agent-documentation

---
name: agent-documentation
description: |-
    Use for editing, reviewing, auditing, or maintaining project-authored agent documentation, including `AGENTS.md`, `.agents/PROJECT.md`, skill documentation, relay assets, canonical public-surface assets, and public skill READMEs. Also use for documentation authority, ownership, composition, routing, redundancy, and token efficiency.

    Defer to a more specific project agent documentation workflow when one exists.

    Do not use for ordinary project source, script-only work without documentation changes, other consumer documentation, public API documentation, release notes, or source comments alone.

metadata:
    internal: true
---

# Project Agent Documentation

## Apply the Documentation Principles

- Apply the global **Explicit user direction** policy to this workflow’s procedural requirements and conventions, including its routed references. Preserve requested scope and every applicable approval, mutation, security, and submission boundary. Findings alone never authorize edits.
- Write instructions that require no conversational context. Define non-obvious terms, and keep consuming project documentation independent of this skill, its canonical repository, and its installation path.
- Apply `human-facing-writing` whenever authoring, reviewing, auditing, or maintaining any project-authored agent documentation writing surface or any human-facing writing in an asset owned by that documentation. Preserve the agent documentation contract and exact machine-readable, externally owned, and quoted content. Treat this as source authoring composition rather than an installed runtime dependency. When maintaining `human-facing-writing` itself, apply the composition once without routing recursively.
- Optimize the complete context path loaded for a task rather than an individual file’s size. Treat applicable `AGENTS.md` files, skill descriptions, and `SKILL.md` entrypoints as direct-path context. Keep wording there only when most invocations need it, and move coherent conditional detail into a conditional reference in the existing skill when the saved direct-path context exceeds the navigation cost.
- Before deferring a section, separate and rehome the rules that only look domain-specific. Ensure the destination skill’s description states every applicability condition supported clients must recognize, including conditions encountered during a task, and keep any prerequisite needed to recognize those conditions on the surface that always loads. Retain an explicit route only for deliberate skill composition or when the description cannot carry the required condition.
- Weigh a deferral against its own overhead. A new skill’s description loads in every session, so deferring content that does not clearly exceed the description it requires costs more than it saves. Move smaller conditional detail into a reference of an existing skill instead.
- Give each proposition one canonical definition and classify every secondary occurrence as routing, surface-specific application, rationale, example, or required standalone context. Remove a secondary occurrence when it merely paraphrases the definition. Keep it only when its distinct role requires wording at that surface, using the smallest wording that preserves that role. When a secondary occurrence contains a more complete rule than its expected owner, promote the complete rule to the canonical owner before removing or reducing the secondary copy.
- Give any identifier scheme referenced from code or documentation, such as numbered checks or requirement labels, one canonical definition in the same repository. Drop the identifiers when no such definition exists, because a reader cannot resolve the reference or tell which members are missing.

## Resolve the Local Documentation Model

1. Read every applicable `AGENTS.md` file before evaluating other project documentation.
2. Identify the project’s agent documentation surfaces, authority model, project-specific documentation skills, and skill management metadata.
3. Use a locally defined authority or ownership model when one exists. When an ownership decision is required and the project has not defined a model, read the [default authority model](references/default-agent-documentation-authority-model.md).
4. Treat managed, vendored, generated, or third-party skills as outside project-authored documentation unless the user explicitly includes them and applicable project instructions permit the work.

## Choose the Workflow

- When the task affects a project-authored skill’s documentation, metadata, assets, category, or supported installation, apply `skill-development` for the skill-specific contracts before the affected work. Also apply it when a global instruction changes or is evaluated and supplies a public skill mirror, even when the request names only the global source. Compose once, then continue the shared workflow here rather than restarting either skill.
- When a task creates, revises, reviews, audits, or maintains a relay or decision capture prompt, load `agent-task-relay` before resolving its canonical owner or composing it.
- For a documentation-only review or audit, inspect implementation and adjacent tests only as bounded evidence for a specific observable contract, then stop once the claim is established. Do not assess algorithms, internal structure, language idioms, performance, dead code, duplication, or general test quality unless the user explicitly includes implementation. Evaluation criteria such as security, maintainability, or project values apply within the resolved scope and do not expand it.
- When the resolved scope explicitly includes implementation, follow applicable project, domain, and language implementation and validation workflows for internal concerns. Keep the agent documentation pass focused on contract consequences, and update agent documentation only when the contract, routing, or documented invocation changes.
- For an explicit change, including a request that also uses review or audit language, use the change workflow. Treat inspection as the evidence gathering phase, then resolve the canonical owner, compose the change, and validate the final contents.
- For a standalone ordinary review, keep the task read-only. Resolve the canonical owner and validate the existing contents, but skip composition, formatting, and every mutation.
- For a standalone audit, keep the task read-only. Follow an applicable model-invocable project audit workflow when one exists. Otherwise start from Git-tracked paths, add only explicitly named untracked documentation when local policy permits it, inspect the resolved documentation scope, report findings, and stop without formatting or mutation.
- Treat naming and prose punctuation policies as file-scoped unless a narrower surface contract defines another scope.
- Resolve each pass’s scope before applying project and domain skills. Let supported clients discover them from their descriptions, and do not preload skills for later passes.

## Resolve the Canonical Owner

1. State the durable detail being changed or evaluated in one sentence.
2. Use the selected local or fallback authority model to identify its expected owner.
3. Search applicable project-authored agent documentation for existing definitions, rationale, inventories, and links concerning that detail.
4. Name one canonical owner and identify every other document that should link to it or remove a stale paraphrase.
5. Do not edit until one owner can be named. Do not choose an owner merely because the detail already appears there.

## Compose the Change

- Update the selected canonical owner before adjusting secondary documents.
- When a set’s order encodes information a reader must recover, such as precedence, priority, complexity, or containment, state its ordering principle beside the set or in the rule that governs it, so every new entry has a determinable position. This applies to table rows, category sequences, and section sequences alike. Agent documentation authority tables use one canonical principle instead, listing instruction surfaces before reference surfaces, each from the most general to the most specific, with a client bridge following the surface it imports.
- Preserve exact user terminology only when the terminology itself is required or established.
- Before compressing a rule or introducing a case beside it, identify what carries its scope. Labels, unqualified quantifiers, and the range of cases that existed when it was written all bind meaning without reading as conditions. State the scope explicitly whenever the edit changes any of them.
- Phrase reusable guidance against the subject’s declared contract rather than a presumed success model. Do not assume that “completion” means failure-free execution, that a stable identifier proves unchanged state, or that a wrapper must reproduce an underlying tool’s automatic behavior. Before adding a named exception, determine whether an evidence-backed decision criterion explains the case and comparable cases. Prefer that criterion when it preserves the intended behavior and boundaries. Retain a named exception when its identity carries information the general rule cannot express.
- Let rationale explain why a policy exists and link to its owner without repeating maintenance steps or exact inventory.
- Keep `PROJECT.md` declarative and organized under broad second-level sections. Order second-level sections topically, appending a new section when no topical position is evident, and alphabetize third-level sections within each. Move agent actions, reporting exclusions, and workflows to the applicable `AGENTS.md` or domain skill, leaving facts, constraints, maintenance decisions, and rationale in `PROJECT.md`.
- For agent documentation about a versioned tool, runtime, or language, establish one authoritative behavioral baseline before editing. Use its most recent stable release unless direct user instruction or authoritative target environment evidence establishes another version. For newly authored or materially revised security boundary claims, verify behavior against the selected upstream baseline and retain the exact revision and supporting source paths in the conversation or task artifacts. Record verification evidence in the source project’s reference documentation, outside skill directories, only when the user explicitly requests a durable audit trail. Version requirements and explanatory source links remain ordinary documentation, not verification records. Evaluate conflicting evidence against the selected baseline before changing documentation. Do not combine current documentation, pinned source, and upstream `main` as if they describe one implementation. Write only the interfaces, semantics, and syntax of the selected baseline. Do not add compatibility branches, historical caveats, legacy forms, version detection, or version migration guidance. Report when the baseline cannot be verified rather than guessing.
- For a new, renamed, or rewritten project-authored Markdown document without a required filename, let its content and scope determine the top-level title, then derive the filename as `<lower-kebab-case>.md`. Never choose or rewrite a title to preserve an existing filename. If the current filename does not match the resulting title, rename the file and update every inbound link in the same change. A filename required by a client, tool, ecosystem, document format, or more specific contract takes precedence.
- Before composing a change across routed or layered surfaces, use the [documentation boundary checks](references/documentation-boundary-checks.md) to identify the canonical side of each boundary.

## Validate the Documentation

### Run the Complete-Scope Checks

For every change, review, or audit:

1. Reread every applicable `AGENTS.md` file and each in-scope documentation file that the current task has not already loaded unchanged. Use Git status and diff to identify what changed since it was loaded.
2. Search the complete applicable documentation family for each proposition being changed or evaluated, its distinctive wording, and close semantic variants. Apply the [documentation boundary checks](references/documentation-boundary-checks.md) to routed or layered surfaces. When a global instruction changes or is evaluated, identify every affected public skill mirror, including rephrased variants, and apply `skill-development` to each for public mirror alignment. Confirm that one normative definition remains and that every secondary occurrence has a distinct required role or links to the canonical owner.
3. For every in-scope change to a direct-path surface, compare its before-and-after context footprint. In a review or audit, report unjustified growth without editing.
4. When an in-scope change moved guidance from a `SKILL.md` into references, map every removed proposition to its destination and confirm that every task that previously received it still deterministically loads that destination. Treat a missing behavioral distinction, condition, exception, or route as a contract regression.

For a review or audit, use only read-only diagnostics and identify anything that could not be verified.

### Complete Change Validation

After capturing all task-authorized documentation updates intended for the current change:

1. Resolve every unjustified direct-path increase found by the complete-scope footprint check. Move conditional guidance into a reference in the existing skill, and remove obsolete direct-path wording in the same change.
2. Resolve every missing behavioral distinction, condition, exception, or route found by the complete-scope moved guidance check.
3. Run targeted diagnostics and `git diff --check` for the changed documentation without formatting unrelated files. Inspect task-owned untracked documentation directly because Git diff checks do not include it. Do not stage files solely for validation.
4. Perform one bounded final alignment pass over the changed documentation against the [documentation principles](#apply-the-documentation-principles), the resolved local authority model, applicable project values, and explicit user decisions. Include [workflow compatibility](#workflow-compatibility) in that pass. Correct concrete discrepancies within the authorized scope before delivery. Treat this as a completion check rather than a drafting gate: do not withhold useful documentation, reopen settled decisions, repeatedly rewrite compliant content, or expand scope for speculative improvements. If a correction requires new authorization, preserve the completed changes and report that boundary.

#### Workflow Compatibility

Before finalizing new or materially changed operational guidance, identify the failure it is meant to prevent and the supported work it must still permit. Derive expected outcomes from governing instructions, explicit user decisions, and verified behavior, not from the proposed wording alone.

Within the existing bounded alignment pass, trace concrete cases through the applicable inherited rules and routed workflows. When a change alters how a workflow is entered, revisit the assumptions that depended on the previous entry point. Verify the default path and how each remaining branch is selected. Cover the permitted path, the relevant stop or approval boundary, and any affected exception, recovery, or continuation. Check that prerequisites are available at the phase that requires them and that valid authorization remains effective through composition. For commands, verify effective configuration and implicit effects in the supported invocation context, not merely accepted syntax.

Reuse established evidence and choose only cases needed for the changed behavior and its direct integration boundaries. Preserve existing complete-scope checks and approval requirements. Report uncertainty or conflicts rather than inventing a workaround.

## Report the Result

- For a change, identify the canonical owner and any redundant definitions removed or replaced with links. Follow the applicable communication policy for validation reporting.
- For a review or audit, lead with concrete findings, their evidence, the canonical owner, and the suggested fix.
- Report any ownership decision that remains unresolved instead of distributing the detail across multiple documents.