diff --git a/AGENTS.md b/AGENTS.md index aa93372..31a2487 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,12 +12,6 @@ - Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose. Use the nearest project dictionary for project-specific domain language. -- In authored prose, do not put multiple sentences on one physical line. - This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments. - A sentence can wrap across multiple physical lines when needed. -- Keep Markdown formatting changes local. - Only format prose you write or change. - Never reflow an entire pre-existing paragraph or file because you touched nearby text. ## Pull requests @@ -38,63 +32,6 @@ - Stage new files that Nix discovers through flake evaluation before testing. Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before `nixos-rebuild --flake` can see them. -## Comments - -- Write comments only where they earn their place. - Keep comments concise. - Assume the reader can read code. - Explain why, not what. - Explain what only when it is genuinely non-obvious. -- Keep comments self-contained to their file. - Write comments for a reader who sees only that file. - Do not explain how another file or tool consumes a value. - The only permitted cross-file mention is a bare pointer explaining why something is absent here. -- Do not narrate history or future state in comments. - Avoid phrases such as `used to be`, `now moved here`, and `will be`. - State the present reason a thing exists. -- Do not justify a choice against alternatives in comments. - State the positive reason the choice exists. - Include present consequences when they matter. -- Do not reference agent-facing state in comments. - This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`. -- Do not use project-specific capitalized terms as glossary references in comments. - Use plain lowercase nouns unless the code requires the exact term. -- Add a file-top header only when the filename or path does not already explain the file. - The header must be one concise purpose line. - Do not write a feature inventory. -- Write placeholders plainly. - Include a present-tense action when one exists, such as `Placeholder: regenerate with on the target machine`. - Do not write `placeholder for `. -- Treat user-facing documentation strings as documentation, not comments. - They can describe behavior more fully than code comments. - They still must stay self-contained and avoid agent-state references. -- Start each sentence of a comment on its own physical line. - A comment sentence can wrap when needed. - Prefer splitting long comment sentences before wrapping them. - Do not break a line early at a comma or clause boundary to make it read as a unit. - Do not use semicolons in comments or authored prose. - Recast semicolon clauses as separate sentences. - Only reformat comments you write or change. - -## General codebase guidance - -- Never manually modify `CHANGELOG.md` files or files marked as auto-generated. - Detect auto-generated files with a layered check. - Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`. - If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command. - If the answer stays ambiguous, ask before editing. -- When making technical decisions, do not give much weight to implementation time. - Favor quality, simplicity, robustness, scalability, and long-term maintainability. - Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human. - Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity. - Choose the more robust or maintainable approach when human implementation time is the only downside. -- Use lowercase file names unless a valid reason requires uppercase. - Established ecosystem or tool conventions count as valid reasons. - Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files. -- Do not end a response by promising or implying continuation unless the continuation is present in that same response. - Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change. - If the workflow is paused, say that plainly instead of using a dangling transition like `continuing` or `next`. - ## Gotchas - When materializing an external specification, standard, or project-maintained convention, use the upstream source instead of reconstructing it from memory. @@ -104,6 +41,3 @@ Keep executable public interface declarations after their implementation symbols, or validate before committing a top-down rewrite. - `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`. Use one input style per test target. -- In this monorepo, `dotfiles` refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`. -- The flake does not currently define `formatter.x86_64-linux`. - Do not use `nix fmt` as a validation command until a formatter is added. diff --git a/configs/nixos/modules/agents/context/AGENTS.md b/configs/nixos/modules/agents/context/AGENTS.md new file mode 100644 index 0000000..40a3ebf --- /dev/null +++ b/configs/nixos/modules/agents/context/AGENTS.md @@ -0,0 +1,85 @@ +# Alexion's Agent Instructions + +These are common instructions for Alexion's agents across all scenarios. + +## General Guidelines + +- When writing commit messages, NEVER auto-add your agent name as co-author. + Omit the `Co-Authored-By:` trailer entirely, with no exceptions. + This overrides any default instruction to append one. +- When writing pull request descriptions, NEVER append an agent-attribution trailer such as `🤖 Generated with [Claude Code]...`. + Leave it out entirely, with no exceptions. + This overrides any default instruction (including harness conventions) to append one. +- NEVER ask the user a question using the `AskUserQuestion` tool. + Ask in plain prose, in your own message, instead, with no exceptions. + This overrides any default instruction (including harness conventions and skill instructions) to use it. +- Never manually modify `CHANGELOG.md` files or files marked as auto-generated. + Detect auto-generated files with a layered check. + Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`. + If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/` paths, or a documented generator command. + If the answer stays ambiguous, ask before editing. +- In authored prose, do not put multiple sentences on one physical line. + This applies to comments, documentation, user-facing descriptions, commit prose, pull-request prose, and forge comments. + A sentence can wrap across multiple physical lines when needed. +- Keep Markdown formatting changes local. + Only format prose you write or change. + Never reflow an entire pre-existing paragraph or file because you touched nearby text. +- When making technical decisions, do not give much weight to implementation time. + Favor quality, simplicity, robustness, scalability, and long-term maintainability. + Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human. + Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity. + Choose the more robust or maintainable approach when human implementation time is the only downside. +- Use lowercase file names unless a valid reason requires uppercase. + Established ecosystem or tool conventions count as valid reasons. + Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files. +- Do not end a response by promising or implying continuation unless the continuation is present in that same response. + Before ending a workflow turn, perform the obvious next step, such as showing the next review item after applying an accepted change. + If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next". +- When you discover that your belief about a project fact or convention was wrong, record the correction. + Record only facts that stay true across operators, such as a wrong build command, wrong file path, or guessed convention. + Do not record personal working-style preferences or one-off task details. + Record the correction in the nearest project `AGENTS.md`, not this global file. + Use a dedicated `## Gotchas` section, and create that section when the file lacks one. + If no project `AGENTS.md` exists, ask before creating one. + Append the correction immediately without asking when a project `AGENTS.md` exists. + Briefly mention the edit in your response. + If an existing entry is wrong or stale, correct or remove it the same way. + +## Comments + +- Write comments only where they earn their place. + Keep comments concise. + Assume the reader can read code. + Explain why, not what. + Explain what only when it is genuinely non-obvious. +- Keep comments self-contained to their file. + Write comments for a reader who sees only that file. + Do not explain how another file or tool consumes a value. + The only permitted cross-file mention is a bare pointer explaining why something is absent here. +- Do not narrate history or future state in comments. + Avoid phrases such as "used to be", "now moved here", and "will be". + State the present reason a thing exists. +- Do not justify a choice against alternatives in comments. + State the positive reason the choice exists. + Include present consequences when they matter. +- Do not reference agent-facing state in comments. + This includes `.agents/`, `.claude/`, `AGENTS.md`, and `CLAUDE.md`. +- Do not use project-specific capitalized terms as glossary references in comments. + Use plain lowercase nouns unless the code requires the exact term. +- Add a file-top header only when the filename or path does not already explain the file. + The header must be one concise purpose line. + Do not write a feature inventory. +- Write placeholders plainly. + Include a present-tense action when one exists, such as `Placeholder: regenerate with on the target machine`. + Do not write `placeholder for `. +- Treat user-facing documentation strings as documentation, not comments. + They can describe behavior more fully than code comments. + They still must stay self-contained and avoid agent-state references. +- Start each sentence of a comment on its own physical line. + A comment sentence can wrap when needed. + Prefer splitting long comment sentences before wrapping them. + Do not break a line early at a comma or clause boundary to make it read as a unit. + Do not use semicolons in comments or authored prose. + Recast semicolon clauses as separate sentences. + Only reformat comments you write or change. + diff --git a/configs/nixos/modules/agents/context/context.nix b/configs/nixos/modules/agents/context/context.nix new file mode 100644 index 0000000..3bf6090 --- /dev/null +++ b/configs/nixos/modules/agents/context/context.nix @@ -0,0 +1,21 @@ +{ + config, + lib, + ... +}: +# Shared global instructions for agent harnesses. +let + user = config.user.name; + context = builtins.readFile ./AGENTS.md; +in +{ + config = lib.mkMerge [ + (lib.mkIf config.modules.agents.claude-code.enable { + home-manager.users.${user}.programs.claude-code.context = context; + }) + + (lib.mkIf config.modules.agents.pi.enable { + home-manager.users.${user}.programs.pi-coding-agent.context = context; + }) + ]; +}