# Project Documentation Roles

## Recommended files

- `AGENTS.md`: thin agent entrypoint that points to the playbook and nearest local rules.
- `README.md`: public setup and run guide.
- `PROJECT_SPEC.md`: product goal, screens, feature scope, API/data policies when the project uses this file.
- `PLANS.md`: milestones, completion criteria, and verification commands when the project uses this file.
- `FSD.md`: architecture boundary rules only when the repo actually uses FSD.
- `.ai-agent-playbook/README.md`: agent-facing project memory index and source-of-truth rules.
- `.ai-agent-playbook/START_HERE.md`: shortest resume guide for the next agent.
- `.ai-agent-playbook/CURRENT.md`: current baseline, working vocabulary, active risks, and decisions that still matter.
- `.ai-agent-playbook/policy/SKILLS.md`: project-level skill selection policy.
- `.ai-agent-playbook/policy/GIT.md`: short Git, commit, PR, and push policy.
- `.ai-agent-playbook/memory/maps/**`: repository, runtime, API, route, data, risk, and structural evidence maps.
- `.ai-agent-playbook/workflows/runbooks/**`: repeatable commands and operational procedures.
- `.ai-agent-playbook/memory/decisions/**`: durable decisions with rationale and evidence.
- `.ai-agent-playbook/workflows/plans/**`: active execution plans only.
- `.ai-agent-playbook/workflows/worklogs/**`: detailed milestone, blocker, direction-change, and debugging records.
- `.ai-agent-playbook/archive/**`: stale plans, old handoffs, and retired notes.
- Project design docs and local reference material: secondary references.
- `.ai-agent-playbook/knowledge/references/guides/runtime-roadmap.md`: optional guidance for deciding whether runtime hooks should reinforce, but not replace, project docs.

## Source-of-truth priority

1. Latest user instruction.
2. Actual code, config, and command output.
3. Root and nearest agent instruction files.
4. Current project memory in `.ai-agent-playbook/CURRENT.md`, maps, runbooks, and decisions.
5. Project-specific planning/spec docs.
6. Worklogs, old plans, examples, handoffs, and archived notes.

## Cleanup rules

- Keep root agent instructions short enough to be a stable entrypoint.
- Keep current project truth and stable shared terms in `.ai-agent-playbook/CURRENT.md`.
- Keep structural facts in `.ai-agent-playbook/memory/maps/`.
- Keep duplicate or clone signals in maps only when scan range, freshness, and confidence limits are clear.
- Keep repeated commands in `.ai-agent-playbook/workflows/runbooks/`.
- Keep live plans in `.ai-agent-playbook/workflows/plans/`.
- Keep detailed history in `.ai-agent-playbook/workflows/worklogs/`.
- Archive stale plans, prompts, and handoffs.
- Promote current facts from worklogs into `CURRENT.md`, maps, runbooks, or decisions.
- Prefer one index document over scattered repeated instructions.
- Keep hook-specific behavior optional and documented; do not make runtime state the only source of project policy.