| name | refine-project-guidance |
| description | Audit and refine root or nested AGENTS.md guidance into a concise, evidence-backed project operating map after initial seeding, architecture or command changes, repeated agent mistakes, or an explicit request to polish project instructions. Preserve the deterministic managed block, add only durable repository-specific invariants, and reject GEB-style file inventories or mandatory file-header documentation. |
Refine project guidance
Turn a seeded factual baseline into a compact project operating map. Keep source, tests, schemas, manifests, CI, and canonical documentation as the executable truth.
1. Establish ownership and evidence
Read the active root-to-current-directory instruction chain, current AGENTS.md, relevant repository status, and the smallest set of canonical project files needed to understand the active task boundary.
If guidance is absent or the managed block is stale, run the sibling $seed-project-guidance workflow first. Never edit inside its managed markers by hand.
2. Apply the value test
Keep a statement only when all are true:
- it changes a future agent's implementation, review, verification, or safety decision;
- it is durable across ordinary code changes;
- repository evidence supports it;
- it belongs at this directory scope;
- it is not already expressed by a closer source of truth or the managed block.
Delete or avoid personality prose, generic software advice, copied framework documentation, command lists already generated by the seeder, speculative architecture, historical narrative, full file inventories, and blanket rules such as fixed file-length limits.
3. Record only project-specific invariants
Prefer a short ## Project-specific invariants section outside the managed block. Useful facts include:
- module ownership and allowed dependency direction, citing relevant paths;
- public, persisted, security, or compatibility boundaries and their schemas/tests;
- generated-file ownership and the canonical generator;
- canonical architecture, product, migration, verification, or deployment documents;
- a non-obvious domain invariant whose absence has caused or would cause incorrect work.
Write one decision-bearing sentence per bullet. Name the supporting path. Do not claim inferred business rules as fact.
4. Use hierarchy sparingly
Create nested AGENTS.md only for a genuine module boundary with distinct commands, ownership, contracts, or invariants. Place the override as close as practical to the specialized work. Do not mirror every directory and do not add L3 headers to source files.
The useful GEB idea is recursive locality: global guidance summarizes stable operating policy, root guidance maps the repository, and nested guidance captures real local differences. The map should point to terrain, not duplicate it.
5. Verify
Run the seeder validator for every managed guidance file and inspect the effective instruction chain from the relevant working directory. Check for contradiction, duplication, stale paths, broken commands, oversized context, and rules that cannot be verified.
When guidance changes because repository behavior or contracts changed, run the repository's normal documentation and validation checks. Report the exact evidence and any remaining uncertain invariant.
