From 6f92e170edcb22e9735269498089f7ba5a2364f7 Mon Sep 17 00:00:00 2001 From: alexion Date: Wed, 2 Sep 2026 20:03:46 -0400 Subject: [PATCH] refactor(agents): move global context into monorepo instructions --- .../nixos/modules/agents/context/AGENTS.md | 85 ------------------- .../nixos/modules/agents/context/context.nix | 21 ----- 2 files changed, 106 deletions(-) delete mode 100644 configs/nixos/modules/agents/context/AGENTS.md delete mode 100644 configs/nixos/modules/agents/context/context.nix diff --git a/configs/nixos/modules/agents/context/AGENTS.md b/configs/nixos/modules/agents/context/AGENTS.md deleted file mode 100644 index 40a3ebf..0000000 --- a/configs/nixos/modules/agents/context/AGENTS.md +++ /dev/null @@ -1,85 +0,0 @@ -# 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 deleted file mode 100644 index 3bf6090..0000000 --- a/configs/nixos/modules/agents/context/context.nix +++ /dev/null @@ -1,21 +0,0 @@ -{ - 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; - }) - ]; -}