Plan hygiene — extract, then remove
This is not a plan format. Developers, users, and agents may plan however they like: Superpowers, Cursor plans, engineering-loop, GitHub Issues,
TODO.md, ad-hoc markdown, or no file at all. Skill Steward does not define or require a new planning template.
This page explains why plan artifacts should not stay in the repo as source of truth after work finishes — and where durable knowledge should go instead.
The rule (format-agnostic)
When work is done:
- Extract everything still true into durable homes (table below).
- Remove the plan artifact from the repo (or move it to an explicit archive that agents are told not to execute).
Plans are scratch paper, not documentation. Keeping finished checklists in-tree misleads the next agent (same failure mode as a bloated AGENTS.md).
Where extracted knowledge goes
| Outcome type | Land in |
|---|---|
| Strategic choice, trade-off | ADR |
| Standing why / how | DESIGN_FAQ.md / DX_FAQ.md |
| Behavior, gates, automation | Code, CI, CLI, MCP, plugins/ |
| Repeatable agent procedure | skills/{name}/SKILL.md |
| Charter / scope change | North Star + ADR if significant |
Any planning tool is fine
| You might use… | Guild stance |
|---|---|
| Superpowers / spec-driven programs | OK — use docs/superpowers/ (or equivalent) in your repo; see concept-doc-store skill |
| Cursor / Codex session plans | OK — ephemeral by default |
docs/exec-plans/active/ in this repo | Optional scratch only; not a standard |
| Issues / Projects | OK — tracking outside git truth |
Do not treat this repo’s docs/exec-plans/ as “the Guild plan format.” It exists only as optional short-lived storage for maintainers who want a file in-tree during a PR.
Optional in-repo scratch (docs/exec-plans/)
If you need a file while work is in flight:
docs/exec-plans/active/YYYY-MM-DD-short-title.md(or your own path)- Link it from the PR
- On merge: extract → delete the file (or one-line summary in ADR Notes)
Anti-patterns
- Finished checklists left in
ROADMAP.md,docs/plans/, orTODO.mdas if still current - Duplicate plan + ADR with the same “truth”
- Archived phase plans executed as if they were the live tracker (use tracker/spec + closure in Superpowers-style layouts, or delete/archive)
Agent workflow
- Read North Star before multi-step work.
- Plan with whatever the user or product repo already uses.
- On completion: extract → ADR / FAQ / code / skill → remove the plan file.
- Update docs_map only if navigation changed.
Related
- Skill:
north-star-governance - ADR 0005 — docs.page + ephemeral plans doctrine