Refine Project Guidance

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: liyanqing90
• Source: liyanqing90/rootloom
• License: MIT

Install and usage instructions live in the source repository linked above.