agent-docs-writing

agent-docs

When to use

Use this skill when:

• Navigating the documentation structure to find relevant information
• Creating or updating agent documentation after changes
• Setting up documentation for a new module or package
• Understanding what documentation exists and where

Do NOT use when:

• Creating code or making technical changes (use coding skills)
• Looking for coding guidelines (use guidelines skill)

Documentation hierarchy

The documentation is organized in layers, from cross-project to module-specific:

Layer 1: .augment/ — Cross-project (identical in all repos)

.augment/
├── rules/          ← Always-active rules (coding, docker, scope, language, etc.)
├── commands/       ← Slash commands (fix-ci, create-pr, quality-fix, etc.)
├── skills/         ← Reusable skill definitions (coder, code-refactoring, etc.)
├── contexts/       ← Shared contexts about the agent system itself
├── templates/      ← Templates for features, roadmaps, contexts
└── guidelines/     ← Coding guidelines by language
    └── php/        ← PHP guidelines (controllers, eloquent, patterns, etc.)

Purpose: Universal agent behavior that applies to ALL projects and packages. Language: English. Key rule: This directory is identical across repos. Never add project-specific content here. Templates are the single source of truth for document structure — never store templates in agents/.

Layer 2: AGENTS.md — Project-level entry point

Located in the project root. Contains:

• Project description and tech stack
• Development setup (Docker, env files, Makefile targets)
• Testing conventions
• Quality tool configuration
• Links to ./agents/ for detailed docs

Purpose: First file an agent reads. Provides the full project context. Not every project has this — packages may only have ./agents/.

Layer 3: .github/copilot-instructions.md — Coding standards

Located in .github/. Contains:

• Architecture rules
• PHP coding standards
• Naming conventions
• ORM & database rules (Laravel example: Eloquent)
• API development rules

Purpose: Coding standards shared with GitHub Copilot and other AI tools. Not every project has this — check if it exists before referencing it.

Layer 4: agents/overrides/ — Project-level overrides

agents/overrides/
├── rules/           ← Override .augment/rules/*.md
├── skills/          ← Override .augment/skills/*/SKILL.md
├── commands/        ← Override .augment/commands/*.md
├── guidelines/      ← Override .augment/guidelines/**/*.md
└── templates/       ← Override .augment/templates/*.md

Purpose: Project-specific customizations of shared .augment/ resources (which are delivered as a package). Mechanism: Each override file has a Mode header — extend (additive) or replace (full swap). Key rule: Never modify .augment/ directly — always use overrides for project-specific needs. See: .augment/contexts/override-system.md for naming conventions and format.

Layer 5: ./agents/ — Project-specific documentation

agents/
├── database-setup.md       ← DB architecture, connections, tenancy
├── testing.md              ← Test suites, conventions, seeders
├── dto.md                  ← DTO patterns and base classes
├── services-and-repos.md   ← Service layer conventions
├── overrides/              ← Project-level overrides (see Layer 4)
├── features/               ← Feature plans (project-wide)
│   └── {feature-name}.md
├── roadmaps/               ← Multi-step change plans
│   └── {roadmap-name}.md
│   └── current.md
└── contexts/               ← Context documents (codebase area snapshots)
    └── {context-name}.md

Purpose: Project-specific architecture, conventions, and domain knowledge. Structure rule: Structural docs directly in agents/, features/roadmaps in subdirectories. Templates live in .augment/templates/, NOT in agents/ subdirectories.

Layer 6: {module_root}/{Module}/{agent_folder}/ — Module-specific documentation

{module_root} comes from modules.root_paths and {agent_folder} from modules.agent_folder in .agent-project-settings.yml. Discover via scripts/_lib/agent_settings.ts::enumerate_modules(). Common shapes: Laravel app/Modules/{Module}/agents/, Symfony src/Bundle/{Bundle}/agents/, monorepo packages/{Pkg}/agents/.

{module_root}/{Module}/                  ← e.g. app/Modules/ClientSoftware/
├── {agent_folder}/                      ← e.g. agents/
│   ├── module-description.md
│   ├── features/                        ← Module-scoped feature plans
│   │   └── {feature-name}.md
│   ├── roadmaps/                        ← Module-scoped roadmaps
│   │   └── {roadmap-name}.md
│   └── contexts/                        ← Module-scoped context documents
│       └── {context-name}.md
└── Docs/
    └── technical-docs.md

Purpose: Documentation scoped to a specific module. When to create: When a module has its own conventions, complex domain logic, or active roadmaps.

Layer 7: Docs/ — Technical documentation

Docs/                                    ← Project-level technical docs
{module_root}/{Module}/Docs/             ← Module-level technical docs

Purpose: Technical documentation for humans (setup guides, architecture diagrams, API docs). Difference from agents/: Docs/ is for human readers, agents/ is optimized for AI agents.

Layer 8: Package documentation

{package-root}/
├── agents/
│   ├── package-description.md
│   └── roadmaps/
└── AGENTS.md (optional)

Purpose: Same structure as projects, but for Composer packages.

Reading order

When starting work, read documentation in this order:

1. AGENTS.md (if it exists) — project overview
2. .github/copilot-instructions.md (if it exists) — coding standards
3. agents/overrides/ — check for project-level overrides of skills/rules/commands
4. ./agents/ — project-specific docs relevant to the task
5. {module_root}/{Module}/{agent_folder}/ — if working on a module (resolved via modules.root_paths + modules.agent_folder; Laravel: app/Modules/{Module}/agents/, Symfony: src/Bundle/{Bundle}/agents/, monorepo: packages/{Pkg}/agents/)
6. agents/features/ or module {agent_folder}/features/ — if related feature plan exists
7. agents/roadmaps/ or module {agent_folder}/roadmaps/ — if continuing existing work

Procedure: Create or update agent docs

1. Identify trigger — What changed? (see table below)
2. Locate target — Find the correct file in the documentation hierarchy.
3. Update content — Edit or create the doc. English only in .md files.
4. Verify — Confirm the doc is consistent with surrounding files and cross-references are valid.

When to update documentation

After making changes, check if docs need updating:

• Roadmap step completed → mark [x] in the roadmap file
• Structural changes → update affected docs in ./agents/
• New patterns → update or create guideline docs

Doc-Impact — the mandatory check after every code change

This is the detection procedure the downstream-changes § Doc-Impact obligation points at. Run it after every code change — the detection is non-optional; the human still confirms the actual edit.

Step 1 — did a public surface change? Framework-agnostic surface list:

Step 2 — apply the fire/no-fire test. Drift is a falsifiable-claim contradiction, not incompleteness:

• FIRE (doc is now wrong — a reader would be misled): endpoint no longer exists, wrong return type, renamed key, removed flag, broken code example.
• DO NOT FIRE (completeness / quality only): the doc is high-level and omits a new internal detail it never claimed to list; "could be clearer".

Step 3 — escape hatch. Refactor-only / no public-surface change → no doc obligation. Surface changed but genuinely needs no doc edit → state the one-line reason; never edit a doc just to satisfy the rule (false-positive fatigue is worse than a missed nit).

When a doc edit IS needed but you are unsure of the wording — flag it with numbered options; do NOT auto-rewrite prose without the user's knowledge:

> 1. Yes — update the docs
> 2. No — leave as-is (reason: …)

Rules

• All .md files must be in English.
• Do NOT create docs unless there's a real need.
• Do NOT duplicate content that's already in AGENTS.md or .github/copilot-instructions.md.
• Do NOT write docs just to document what you did — only document things others need to know.
• If unsure whether a doc needs updating, ask the user.
• Sibling-routing sentences are edited as a set, never alone. When a skill's description: carries a routing clause naming an overlapping sibling (Animated → pixar-storyteller), editing it obliges re-reading every sibling it names and every sibling that names it, so no user phrase ends up routed to two skills and none ends up routed to neither. One-sided edits are how a cluster's descriptions drift back into ambiguity between sweeps; lint_skill_descriptions catches a missing clause, not an inconsistent one.

Output format

1. Created or updated documentation file(s) in the correct location
2. Summary of what changed and why

Gotcha

• Don't create documentation files unless explicitly requested — the scope-control rule overrides this skill.
• Always check if a doc already exists before creating a new one — duplicates are worse than gaps.
• AGENTS.md and copilot-instructions.md have different audiences — don't copy content between them.
• Module docs go in {module_root}/{Module}/{agent_folder}/ (per modules.root_paths), NOT in the central agents/ directory.

Frugality Standards

Apply the Frugality Charter to every agent-doc update you author.

Examples in this artifact:

• Per the charter's default-terse rule, doc updates state what changed; no "In this section we will…" frames.
• Per the cheap-question check, AGENTS.md surface offers options only where the project genuinely diverges.
• Per the post-action summary suppression, doc edits append change notes to the existing log entry; no new "Summary of changes" block.

Pre-save self-check:

1. Does the doc open with a narrative intro instead of the actual content?
2. Are paragraphs added that summarize an existing table?
3. Does the doc duplicate the rule index instead of linking the relevant rule?
4. Is German prose present outside DE: / EN: anchor blocks?

User inbox workflow (agents/tmp/)

When a command or skill consumes a file from agents/tmp/ as its INPUT (roadmap created from it, note promoted to knowledge, etc.), move the source file to agents/tmp.old/<original-name> in the same reply as the output.

mv agents/tmp/<filename> agents/tmp.old/<filename>

• Move only files that were explicitly named as input to the command.
• Never sweep or auto-move other files in agents/tmp/.
• No confirmation needed — tmp/ and tmp.old/ are gitignored, local-only.
• Never write agent-generated scratch into agents/tmp/ — use agents/runtime/tmp/.

See docs/contracts/agents-layout.md § User Inbox Workflow.

Transient-reference discipline — mechanics (migrated from the no-roadmap-references rule)

Body of no-roadmap-references (per P4 of road-to-kernel-and-router.md). The Iron Law — never link a specific agents/roadmaps/ or agents/runtime/council/ file from a stable artifact — stays in the rule; the pattern catalog lives here.

Forbidden patterns

These paths must not appear inside a stable artifact:

• agents/roadmaps/<file>.md, agents/roadmaps/archive/<file>.md, agents/roadmaps/skipped/<file>.md
• agents/runtime/council/questions/<file>.md, agents/runtime/council/responses/<file>.json, agents/runtime/council/sessions/<file>.json or <timestamp>/...

Stable artifact = any file under src/{rules,skills,domains}/, src/agent-src/{contexts,templates,personas}/, agents/settings/contexts/, docs/guidelines/, docs/contracts/, docs/architecture.md, docs/customization.md, docs/getting-started.md, docs/catalog.md, AGENTS.md, README.md, copilot-instructions.md.

CI enforcement: scripts/check_no_roadmap_refs.ts (roadmap layer) and scripts/check_council_references.ts (council layer) — both fail the build on any new violation.

Allowed patterns

• agents/roadmaps/ and agents/runtime/council/ subdirs as directory mentions (talking about the layer, not a specific file)
• Roadmap → roadmap references (siblings within the transient layer)
• The ai-council skill and /council:* commands documenting the output path schema
• Inline council convergence summary — e.g. "Council (claude-sonnet-4-5 + gpt-4o, 2026-05-06) converged on …" with date + members, no filepath
• Council sessions, agents/runtime/.agent-chat-history, commit messages, PR descriptions — transient by construction, not part of the package surface

Structural carve-outs (immutable inputs / decision provenance)

Two source/target shapes are exempt from the council-link ban because the target is immutable input or decision provenance, not transient drafting state. The linter implements these directly (STRUCTURAL_CARVEOUTS in scripts/check_council_references.ts); they do not need an inline <!-- council-ref-allowed: ... --> pragma.

Driven by the 2026-05-14 P3.4 council round (claude-sonnet-4-5 + gpt-4o, converged on rule refactor over escape-hatch overuse). Any other source/target combination still needs an inline pragma or inline-summary rewrite.

What to do instead

When a stable artifact needs to cite a transient finding:

1. Identify the durable conclusion — decision, contract, lesson, mechanic.
2. Promote it to a context file under agents/settings/contexts/ (ADR, mechanics doc, locked decision). The roadmap or council session can then point at the context, not the other way around.
3. Reference the context from the stable artifact.
4. For council convergences specifically: inline a convergence-summary block (members, date, cost if relevant — see ai-council § Output format) instead of linking the session JSON.

Failure modes:

• "I'll just link to the roadmap, it's evidence." The roadmap gets archived, then deleted, then the link rots. Promote first, link second.
• "I'll just link to the session JSON, it's evidence." The session is gone in 7 days. Inline first, link never.

Do NOT

• Do NOT create docs unless there's a real need (new module, significant change).
• Do NOT duplicate information already in AGENTS.md or copilot-instructions.md.
• Do NOT write docs just to document what you did — only document things others need to know.
• Do NOT write agent-generated scratch into agents/tmp/ — that is the user's inbox.
• Regen-only outputs (agents/evidence/analysis/*, agents/reports/* generated by a script): commit only together with the work that consumed them. A session that regenerates as a side-effect discards with git checkout -- before ending. See docs/contracts/agents-layout.md § Session-leftover discipline.

Auto-trigger keywords

• agent documentation
• docs structure
• when to read docs
• documentation maintenance