| name | plans |
| description | Use whenever working with maintainer plans under .agents/docs/plans/. Covers reading a plan before implementation, creating or scaffolding a plan, and updating status or body during or after work. Trigger when the user asks to plan, scope deferred work, check what is planned, or record a plan. Also trigger at the start of implementation to see whether a plan already exists. |
Plans
Deferred implementation plans — scoped work not yet (fully) implemented. Each
file is self-contained so an agent can implement without reconstructing intent.
Plans live under .agents/docs/plans/ (active) and plans/archive/
(completed or otherwise terminal). YAML frontmatter follows the
write-plan CONTRACT (id, title, last_updated,
description, tags, status, optional graph keys).
Quick reference
| Action | When |
|---|
| Read a plan | Before starting implementation |
| Create a plan | When scoping work for later |
| Update a plan | When status or blocking questions change |
Reading a plan
- Scan
.agents/docs/plans/index.md (or search under plans/).
- Read YAML frontmatter first:
status, title, last_updated, tags, optional superseded_by / related_plans (qualified plans/<slug> form per CONTRACT).
- Treat the body as authoritative for approach and decisions already recorded.
- Do not relitigate items under Decisions already made (or equivalent).
- Resolve Open questions before driving implementation if they are blocking.
- Check Dependencies / cross-links to other plans (
../other-plan.md, archive/other.md).
Legacy prose: older plan bodies may still mention historical status words
(ready, in-progress, done). Prefer the frontmatter status field; map
roughly: ready / in-progress → treat as in-flight initiative; done →
completed work (often the file is under archive/).
Creating a plan
Prefer scaffolding with valid CONTRACT metadata:
python3 .agents/skills/write-plan/scripts/write-plan.py --help
Otherwise create .agents/docs/plans/<id>.md where id matches the
filename stem (lowercase [a-z0-9_-] only). Then run
bash .agents/skills/docs-compile/scripts/docs-compile.sh so plans/index.md
and docs-search stay aligned.
Template (body after CONTRACT frontmatter)
Use write-plan CONTRACT for the YAML header. After
the closing ---, start with # title, then sections such as:
## Summary
## Context
## Approach
## Decisions already made
## Open questions
## Out of scope
## Dependencies
## References
Link to durable decisions or troubleshooting from the body using a
## Related decisions section and relative links (for example
../decisions/<slug>.md); do not use a related_decisions YAML list.
Updating a plan
| Situation | Action |
|---|
| Status / scope change | Bump last_updated; set status per CONTRACT vocabulary |
| Open question resolved | Move answer into Decisions already made; trim Open questions |
| Work finished | Set status: completed (or cancelled / superseded as appropriate); git mv to plans/archive/ when retiring from the active set; bump last_updated |
| Superseded by another plan | Set status: superseded and superseded_by: [plans/<other-id>, ...] |
Do not delete archived plans; they keep history. See CONTRACT Archive
section for the git mv convention.
Status values (write-plan)
Use only CONTRACT status values in frontmatter: draft, active, paused,
completed, cancelled, superseded, archived (all lowercase). These
replace older informal labels such as ready / in-progress / done /
abandoned over time as plans are edited.
