plan-tree

# Plan Tree

Use this skill to manage a tree of Markdown planning documents. The goal is to keep plans navigable, current, and internally consistent while preserving the user's intent and existing document style.

## Execution Contract

For every plan-tree task:

1. Identify the plan root and user intent before editing.
2. Read the root index plus only the relevant status, topic, decision, question, idea, or history files.
3. Classify the request as an idea, promotion, status update, question, decision, archive, audit, resume, restructure, or consistency repair.
4. Preserve the existing planning entrypoint, registered plan roots, folder names, document style, and authority order unless the task is specifically to reorganize them.
5. Keep active roadmap and handoff files small; move historical evidence out of active state.
6. Update indexes, retrieval headers, and links when adding, moving, promoting, archiving, or splitting durable files.
7. Run the final checks before replying.
8. Report changed files, unresolved questions, and the next useful maintenance action.

## Intent Routing

When the request maps to one of these intents, follow the corresponding behavior. Explicit shortcuts such as `$plan-tree idea` or `$plan-tree resume` are intent hints, not a strict command language; natural-language requests with the same meaning should behave the same way.

- `idea`: add a low-commitment thought to `ideas/inbox.md` or the local equivalent.
- `promote`: move an idea into a roadmap item, topic, open question, or decision, and link the original idea to the promoted artifact.
- `status`: update active implementation or handoff state.
- `question`: add, narrow, or resolve an open question.
- `decision`: create or update a stable decision record.
- `archive`: move superseded evidence, old status detail, or reference-only material out of active files.
- `audit`: run consistency, retrieval, and drift checks without changing structure unless asked.
- `resume`: follow the resume workflow and summarize current phase, TODO, blockers, next target, and last verification before editing.

## Document Model

Prefer this generic shape when creating a new tree, but adapt to existing names and conventions:

```text
<plan-root>/
  README.md
  roadmap.md
  implementation-status.md
  open-questions.md
  indexes/
    <optional-index>.md
  topics/
    repository-cleanup-and-filesystem-plan.md
    <topic>.md
  decisions/
    README.md
    001-<decision>.md
  history/
    <optional-status-or-checkpoint-history>.md
  ideas/
    <optional-idea-or-inbox>.md
```

The tree above defines document roles, not a mandatory directory template. Rules for adapting it:

- The top-level files and the `decisions/` folder are generic roles that most multi-file plans need. Only create the ones the plan actually uses.
- `topics/` is a content container. Its internal organization, such as flat files or role-based subfolders like `contracts/`, `frontend/`, and `operations/`, should follow the project's domain structure, not a fixed template. Let the project's natural groupings emerge before creating subfolders.
- `indexes/`, `history/`, and folder-level README files are maintenance structure. Add them only when a specific navigation or lifecycle problem appears, not preemptively.
- When introducing subfolders inside `topics/`, keep depth to two levels maximum, such as `topics/frontend/interaction-contract.md`. Deeper nesting harms discoverability more than flat listing does.

- `README.md`: purpose, scope, file map, and how to read the tree.
- `roadmap.md`: current state grouped as `Done`, `In Progress`, `Next`, and `Deferred` unless the existing tree uses another state model.
- `implementation-status.md` or equivalent handoff file: optional active execution state for resuming work across sessions. Use it for current phase, active TODO, last completed step, blockers, next commit target, verification, and handoff notes; do not use roadmap as a volatile task board when a separate handoff file exists or would help.
- `indexes/`: optional navigation helpers for large trees. Use when the root README or a folder listing becomes too long to scan.
- `topics/`: working context, options, constraints, implementation notes, and links to related decisions or questions.
- `topics/repository-cleanup-and-filesystem-plan.md` or equivalent: optional repo hygiene and file-structure plan for implementation efforts. Use it when the plan affects project layout, legacy cleanup, generated files, assets, uploads, migrations, tests, or archive/delete rules.
- `decisions/`: stable decision records. Use numbered kebab-case files when no naming scheme exists.
- `decisions/README.md` or equivalent decision index: optional for large decision sets. Group decisions by theme, active/superseded state, and related topics.
- `history/`: optional append-only or low-churn history for accepted checkpoints, old review/job detail, retired status snapshots, or phase logs that no longer belong in active handoff files.
- `ideas/` or equivalent: optional low-commitment inspiration pool for thoughts that are not yet questions, decisions, or roadmap items. Use it for future possibilities, external inspiration, unvalidated improvement directions, or speculative features that may never be built. Keep the barrier to entry minimal; a single `ideas/inbox.md` list is enough until the pool grows large enough to need individual files.
- `open-questions.md`: unresolved questions only. Do not use it as a todo list.

Rules for the ideas area:

- Ideas carry no commitment. They are not requirements, roadmap items, or open questions.
- When an idea matures into real work, promote it by creating a roadmap item, topic, open question, or decision as appropriate, and mark the original idea as promoted with a link. Do not duplicate the content.
- Do not force status labels or metadata on ideas. A one-line description is a valid idea entry. Add source, context, or links only when they help future evalu