# 🛞 UPDATE AGENTS MODE Start all UPDATE AGENTS MODE responses with '🛞' ``` ⋅ ╭───╮ │ ● │ │ ◡ │ Time to level up AGENTS.md! ╰───╯ ``` Interactive Q&A flow to update an existing `AGENTS.md` with new learnings and project knowledge. --- ## Awareness Context Before making any updates, orient yourself to current project state: read `AGENTS.md` and `README.md`, list `src/` directory, run `ls specs/` (not Glob — gitignored) to read any active spec overview, and locate the human-docs tree (`docs/` or equivalent — don't assume). --- ## Step 1: Pre-flight Check Check if `AGENTS.md` exists in project root. **If missing:** "No AGENTS.md found. Create one from scratch? I can analyze the codebase and generate an initial file." Stop and wait. If yes, use `plan2code-init.md` workflow. **If exists:** Read and summarize: - Main sections (bullets) - Current line count Check for `.agents-docs/` directory: **If `.agents-docs/` exists:** ``` Structure: Progressive discovery (index + N section files) Section files: - .agents-docs/AGENTS-architecture.md - .agents-docs/AGENTS-development.md [etc.] ``` **If `.agents-docs/` does not exist:** Note: `Structure: Single-file (no .agents-docs/ directory)` **IMPORTANT — you MUST offer restructuring.** Stop and ask: > "Your AGENTS.md uses a single-file format. Want to restructure for progressive discovery? This splits detailed sections into `.agents-docs/` files and converts AGENTS.md to a lightweight index with summaries and links." Wait for user response before continuing. If user accepts, restructure existing content: create `.agents-docs/` directory with section files, convert AGENTS.md to index with summaries and links. Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) stay in AGENTS.md. If user declines, continue with single-file editing. Proceed to Step 2. --- ## Step 2: Context Detection Check for recent conversation context. **If recent work exists:** "I noticed we just worked on [description]. Worth documenting:" - [Insight #1] - [Insight #2] - [Insight #3 if applicable] "Add any of these to AGENTS.md?" **If no context:** Skip to Step 3. --- ## Step 3: Update Menu Present the user with update options: > ``` > ⋅ > ╭───╮ > │ ● │ > │ ~ │ What should we update? > ╰───╯ > ``` > > "What would you like to add or update in AGENTS.md?" > > **Options:** > - **1. Commands** - Build, test, run, lint, or other CLI commands > - **2. Architecture** - How components interact, data flow, key patterns > - **3. Gotchas/Pitfalls** - Traps to avoid, non-obvious behaviors > - **4. Testing** - Test patterns, how to run specific tests, fixtures > - **5. Environment/Config** - Setup quirks, env variables, configuration > - **6. General Rules** - Coding conventions, style rules, project-specific practices > - **7. Git Commit Messages** - Commit message conventions, AI attribution rules > - **8. Something else** - Tell me what you'd like to add > - **9. Sync & Maintain** - Audit & sync all doc surfaces — AGENTS.md, `.agents-docs/`, `specs/`, README, human docs: fix stale/wrong/missing, cut redundancy > > You can also ask me to: > - **Review for corrections** - Check if any existing content is outdated or wrong > - **Prune/consolidate** - Trim redundant or verbose sections > > "Which would you like to do? (You can pick multiple, e.g., '1 and 3')" --- ## Step 4: Gather Details | Category | Questions | |----------|-----------| | Commands | Purpose? Flags? Prerequisites? | | Architecture | Components? Interactions? Pattern? | | Gotchas | What was unexpected? Workaround? | | Testing | Commands? Fixtures? Mocking? | | Environment | Local/CI/deploy? Env vars/files? | | Rules | Project-wide or specific? Why? | | Git Commit Messages | Format? Attribution? Conventions? | | Other | "Tell me what to add." | | Sync & Maintain | Scope: all surfaces or specific? Then follow the Sync & Maintain section. | | Review | Per section: "Still accurate?" | | Prune | Suggest trims, confirm before applying | --- ## Sync & Maintain Keep every doc surface accurate and in sync. **Deep-audit surfaces this session touched; staleness-scan the rest.** Verify against actual code — never assume or fabricate. | Surface | Tier | Voice | |---------|------|-------| | `AGENTS.md` + ALL applicable `.agents-docs/*` | Persistent | Agent — how/where, exact commands, paths, gotchas | | `README.md` + human docs | Persistent | Human — what/why, scannable | | Active `specs//` | Transient | Session knowledge — status, decisions, next steps. No bloat | **Adaptive:** `AGENTS.md`/`.agents-docs/`/`specs/` are plan2code conventions — expected, but verify. `README.md` is standard. Human-docs tree varies (`docs/` or other) — detect, don't assume. **Fix everywhere:** stale paths/commands, missing/outdated info, mistakes, redundancy. **Never duplicate across tiers:** route each fact to its surfaces in that surface's voice — different phrasings of one truth, never copied text. --- ## Step 5: Confirm & Apply Before changes, route edits to the correct file when `.agents-docs/` exists: - Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) → edit AGENTS.md directly - All other sections → edit the corresponding `.agents-docs/AGENTS-.md` file - Sync & Maintain: human-voice facts → README/human docs; session knowledge → active spec's `overview.md` Preview format: > **File:** `.agents-docs/AGENTS-architecture.md` (or `AGENTS.md` for inline sections) > **Section:** [name] > **Change:** [description] > ``` > [Preview text] > ``` > "Does this look right? (yes/no/adjust)" - "adjust" -> ask what to change, repeat - "yes" -> apply edit, insert in appropriate section (create if needed), preserve structure ### Section File Lifecycle (when `.agents-docs/` exists) - **New section (>~10 lines):** Create `.agents-docs/AGENTS-.md` with breadcrumb header, add summary + link in AGENTS.md - **New section (<~10 lines):** Keep inline in AGENTS.md - **Delete section:** Remove the `.agents-docs/` file and its summary + link from AGENTS.md - **Orphan cleanup:** After all edits, check for `.agents-docs/` files with no corresponding AGENTS.md section — offer to remove them --- ## Step 6: Summary & Next After applying: > "Done! Changed:" > - [Summary] If `.agents-docs/` exists: > Structure: AGENTS.md (index) + N section files in .agents-docs/ > Index line count: X/500 Otherwise: > Line count: X/500 > "Add anything else?" If yes, return to Step 3. If done, proceed to Step 7. --- ## Step 7: AI Agent File Sync Check for other AI agent config files and offer to replace with AGENTS.md references. ### Files to Detect | File | Reference Path | |------|----------------| | `CLAUDE.md` (root) | `./AGENTS.md` | | `GEMINI.md` (root) | `./AGENTS.md` | | `.cursorrules` (root) | `./AGENTS.md` | | `.github/copilot-instructions.md` | `../AGENTS.md` | | `.cursor/rules/*.md` | `../../AGENTS.md` | | `.windsurf/rules/*.md` | `../../AGENTS.md` | **No files found:** Skip silently, end workflow. ### If Files Found ``` o o \ / +---+ | o | | ~ | Found other AI agent configs! +---+ ``` > Found AI config files that could reference AGENTS.md: > > | File | Size | > |------|------| > | `CLAUDE.md` | 45 lines | > > Replace with AGENTS.md references? > - **Yes** - Update all > - **Select** - Choose specific (numbered list) > - **No** - Keep as-is **Warning** for files >10 lines: "[file] has custom content that will be replaced." ### CLAUDE.md Template CLAUDE.md gets a special template because Claude Code auto-loads it — the `CRITICAL — MANDATORY FIRST STEP` directive ensures AGENTS.md is always read: ```markdown # CLAUDE.md **CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.** See AGENTS.md for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details. This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md. ``` ### Reference Template (all other files) Use title and path from the detection table: ```markdown # [Title] See [AGENTS.md]([Path]) for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details. ``` **For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete existing `.md` files, create single `reference.md`. --- ## Update Rules 1. **Surgical edits** - Don't rewrite unchanged sections 2. **Preserve style** - Match existing formatting/tone 3. **Actionable only** - Every entry helps agents do something 4. **Under 500 lines** - Warn if approaching limit 5. **No generic advice** - Must be project-specific 6. **No duplication** - Check for similar content first 7. **Group logically** - Place near related content 8. **Be specific** - Include exact commands, paths, names 9. **Route edits to correct file** - Inline sections edit AGENTS.md directly, detailed sections edit the corresponding .agents-docs/ file --- ## Example Session ``` Agent: Found AGENTS.md (127 lines, single-file). Restructure for progressive discovery? User: No, just update it. Agent: Recent work on auth flow. Worth documenting: - Auth tests require TEST_SECRET env var Add it? User: Yes Agent: **Section:** Testing "- Auth tests require TEST_SECRET env variable" Look right? User: Yes Agent: Done! Line count: 128/500. Add anything else? User: No Agent: Found CLAUDE.md (23 lines). Replace with AGENTS.md reference? User: Yes Agent: Updated CLAUDE.md. AGENTS.md is your single source of truth now! ``` ## Session End Work summary — tell user: sections updated, entries added/changed, files modified (`AGENTS.md` or `.agents-docs/` files). Suggested commit: ``` git commit -m "docs: update AGENTS.md with new learnings" -m "" -m "AI Assisted" ``` Returning context: Run `/plan2code-init-update` again to make additional updates.