Keep project documentation current

Agents Pack treats documentation as part of implementing a material feature or subsystem change. A future coding agent should be able to read the relevant documentation, code, and tests and understand both how the system works and why it was designed that way.

This behavior starts in the required ap-core-instructions; you do not need to repeat it in every prompt. The recommended ap-refresh-repo-docs skill provides a deeper workflow for feature documentation and repository-wide drift repair.

Ask your coding agent

For normal feature work, describe the outcome:

Add organization-level API keys with creation, revocation, and audit history.

The core instructions tell the agent to read the task-relevant documentation together with the actual code and tests, include documentation in the success criteria, and update the canonical documentation before finishing.

To request an explicit reconciliation:

Use ap-refresh-repo-docs to inspect this feature and its current diff. Update
the canonical documentation for every material behavior or design change.
Follow the project's existing documentation structure. Keep important
decisions and their rationale with the feature or subsystem they govern, and
report what documentation changed or why none was needed.

Follow the project before the fallback

If the repository already has a documentation structure, follow it. Do not introduce a parallel hierarchy merely because Agents Pack suggests one.

When no clear structure exists, use this small fallback:

docs/
├── README.md        # Documentation map and canonical sources
├── features/        # Features and user-visible behavior
├── architecture/    # Subsystems and cross-cutting architecture
└── operations/      # Deployment, recovery, monitoring, and runbooks

Use docs/internal/ only when the project already uses it or needs a clear boundary between public and developer-only documentation.

Keep decisions with the feature or subsystem

Record important decisions in the document whose subject they govern:

a feature-specific decision belongs in that feature’s document;
a subsystem decision belongs in the subsystem’s architecture document; and
a cross-cutting decision belongs in the architecture document that owns the shared concern.

Include the choice, why it was selected, alternatives considered, tradeoffs, consequences, and when it should be reconsidered. Link to the canonical explanation from other documents instead of duplicating it.

If the repository already uses architecture decision records or another decision convention, continue using it. The Agents Pack fallback does not add a separate decision folder because separating rationale from its subject forces a future agent to reconstruct the context from several files.

Comment for reasons, not narration

Readable names, cohesive modules, and explicit boundaries should explain what the code does. Comments and docstrings should explain information the code cannot express cleanly:

intent and business rationale;
invariants and non-obvious constraints;
surprising tradeoffs or compatibility requirements;
failure, concurrency, security, and lifecycle behavior; and
public contracts when the language or framework expects documentation.

Update or remove comments that a change makes inaccurate. More comments are not automatically better; trustworthy comments are.

Create a new document only when it will last

A new feature is material by default, but it may belong in an existing canonical document. Create a new document when the subject has durable behavior, boundaries, invariants, extension points, operational concerns, or design rationale with value beyond the current task.

A small refactor, obvious implementation detail, test-only change, or one-off fix may require no documentation edit. The agent should verify that conclusion and report the concrete reason rather than creating documentation churn.

Repair drift

Ask for a focused check:

Use ap-refresh-repo-docs to verify the billing subsystem documentation against
the current code, configuration, tests, and public contracts. Correct material
drift, preserve intentional future plans, and report anything whose authority
is ambiguous.

Or ask for a repository-wide audit when the scope genuinely calls for it. The skill distinguishes implemented behavior, intended product direction, public contracts, and accepted design intent instead of treating code as the authority for every claim.

Review before shipping

The recommended ap-code-reviewer subagent checks for concrete documentation problems introduced by a change: stale behavior, contracts, architecture, security assumptions, operations guidance, or comments. It does not demand a new file or more comments without a durable reason.

Ask:

Review this change before I commit it. Include concrete documentation drift or
missing rationale in the findings, but do not request documentation churn when
the change has no durable documentation impact.