git:20260723.7fc2f3b to git:20260905.f755314

- description: Write an implementation plan of waves, phases, and steps. Use only after the authorizing ADR - or the cluster of ADRs a roll-up plan executes - is approved.

- # Plan writing skill (vaultspec-write)

-

- Use this skill:

-

- - To write the required implementation plan grounded with research and ADRs.

- - To plan **non-trivial work, such as new features, complex auditing, or refactoring**.

- - When the user explicitly asked to "write plan" or "draft Steps".

-

- This skill **MUST always** be called after `vaultspec-adr` concludes with architectural

- approval.

-

- **Announce at start:** "I'm using the `vaultspec-write` skill to write the

- implementation plan."

-

- ## Important

-

- - If part of the `vaultspec-research` -> `vaultspec-adr` flow, this skill **MUST** be

- provided with the relevant Research and ADR documents.

-

- - If invoked standalone, you must locate or request relevant context.

-

- ## CLI usage mandate

-

- Plan documents authored by this skill MUST be manipulated via the

- `vaultspec-core vault plan` CLI rather than by hand-editing the markdown body. The CLI

- is the canonical surface for every identifier-affecting change. The verbs are:

-

- - `vaultspec-core vault plan step add | insert | edit | move | remove`

- - `vaultspec-core vault plan step check | uncheck | toggle` (state)

- - `vaultspec-core vault plan phase add | insert | edit | move | renumber | remove`

- - `vaultspec-core vault plan wave add | insert | edit | move | remove`

- - `vaultspec-core vault plan epic intent show | edit` (L4 only)

- - `vaultspec-core vault plan tier show | promote | demote`

-

- The CLI guarantees canonical-identifier preservation, gap-no-reuse via a hidden

- retirement ledger, and display-path consistency that hand edits cannot. Run

- `vaultspec-core vault plan --help` for the full subcommand surface and

- `vaultspec-core vault plan check` for the validator that backs it.

-

- ## Hierarchy and tiers

-

- The plan hierarchy is `Epic > Wave > Phase > Step`. Plans declare their complexity tier

- (`L1`, `L2`, `L3`, or `L4`) in frontmatter; the tier determines which structural

- containers exist:

-

- - `L1`: Steps only.

- - `L2`: Phases above Steps.

- - `L3`: Waves above Phases above Steps.

- - `L4`: Epic above Waves above Phases above Steps; an external project-management

- association is declared in the Epic intent block.

-

- Full criteria, the row contract, identifier rules, and ordering rules are embedded as

- markdown-comment hint blocks in `.vaultspec/templates/plan.md`. The skill defers to

- those canonical sources rather than restating them.

-

- ## ADR cardinality

-

- A plan executes one ADR or a cluster of them; both are normal. Multi-component work - a

- frontend or backend spanning several components, elements, or libraries, each with its

- own decision record - rolls up into a single epic plan (typically `L3`/`L4`) as the

- tracking document. Every governing ADR is listed in `related:` (`--related` repeats at

- scaffold time), and when several feed the plan, the Description section states which

- Wave or Phase each ADR governs. The inverse is not sanctioned: one ADR spread across

- several concurrent plans fragments tracking - prefer one plan per decision cluster.

-

- ## Rules

-

- - **Ground the plan in real code first.** Map the implementation surface the plan will

- touch before writing Steps - it is what lets Steps name real files and real symbols

- rather than assumed paths. Lead with `vaultspec-rag search "<intent>" --type code` to

- locate the sites (read the epicenter or nearest existing analogue in full, then

- confirm exact symbols and insertion points with grep),

- `vaultspec-rag search "<intent>" --type vault --doc-type adr` to confirm the governing

- decisions, and `vaultspec-core status` and `vaultspec-core vault list` - first-class

- for orientation - to map plans and records. Where `vaultspec-rag` is not installed,

- the `vaultspec-core` discovery verbs and grep carry the same sequence.

-

- - **Must reference research and ADRs**. Read these in full prior to writing the plan.

-

- - Ensure no knowledge gap remains prior to writing the plan. Call the

- `vaultspec-research` skill if more information is needed.

-

- - **Granularity:** Every Step is one Markdown bulleted checkbox row naming exactly one

- file or one cohesive area in inline backticks per the Step row contract embedded in

- the plan template. No per-row reference footers; authorizing documents go once in the

- plan's `related:` frontmatter.

-

- - **Persistence:**

-

- - Plans: scaffold via

- `vaultspec-core vault add plan --feature {feature} --tier <L1..L4> --related <adr-stem> [--related <adr-stem> ...]`

- (one `--related` per authorizing ADR); the CLI owns the filename

- (`.vault/plan/yyyy-mm-dd-{feature}-plan.md`) and the frontmatter; never hand-write

- either. Build the structure with the `vaultspec-core vault plan` verbs above, then

- author the prose sections (Description, Parallelization, Verification) as body

- edits.

-

- - Phase Summaries: tier-conditional `.vault/exec/yyyy-mm-dd-{feature}/...-summary.md`

- filenames (`yyyy-mm-dd-{feature}-{phase}-summary.md` at L2;

- `yyyy-mm-dd-{feature}-{wave}-{phase}-summary.md` at L3/L4).

-

- - Step Records: tier-conditional `.vault/exec/yyyy-mm-dd-{feature}/...md` filenames

- (`yyyy-mm-dd-{feature}-{step}.md` at L1; `yyyy-mm-dd-{feature}-{phase}-{step}.md` at

- L2; `yyyy-mm-dd-{feature}-{wave}-{phase}-{step}.md` at L3/L4).

-

- ## Frontmatter

-

- The scaffold owns the frontmatter; the full schema is defined in the `vaultspec` rule.

- Plan-specific requirements on top of the shared schema:

-

- - **`related`** carries the AUTHORIZING documents (ADR, research, reference, prior plan)

- for every Step in the plan. Steps inherit this chain; per-row reference footers do not

- exist. `related` is required when the plan contains at least one Step row.

- - **`tier`** is an unquoted scalar with value `L1`, `L2`, `L3`, or `L4`, set via the

- `--tier` flag at scaffold time and changed only through

- `vaultspec-core vault plan tier promote | demote`. Pre-existing plans without the

- field default to `L2`.

- Verify after scaffolding with `vaultspec-core vault check all` rather than hand-editing

- frontmatter.

- ## Workflow

- - **Research**: Ensure vaultspec research agents have answered questions.

- - **Linking**: Ensure the Plan uses `[[wiki-links]]` only in the `related:` frontmatter

- field. The plan body must remain free of wiki-links and markdown links per the

- embedded LINK RULES in the plan template.

- - **Drafting**: If working with sub-agents, load the `vaultspec-writer` agent persona.

- Instruct it to "Create an implementation plan for `{feature}` based on the authorizing

- ADR(s) `[[...-adr.md]]`. Use the template at `.vaultspec/templates/plan.md` and

- conform to the embedded HIERARCHY AND TIERS, IDENTIFIERS AND ROW CONTRACT, and NO

- COMPRESSION hint blocks. The plan's tier (`L1`/`L2`/`L3`/`L4`) is already set in

- frontmatter by the `--tier` flag at scaffold time."

- - **Review**: Present the saved Plan summary to the user before executing.

- - **Provide an absolute link** and prompt the user:

- The Plan is ready:

- [[yyyy-mm-dd-{feature}-plan.md]]

-

- - **Approval loop**: The user must explicitly approve the Plan. If changes are

- requested, load the `vaultspec-writer` agent persona again to make changes. If more

- research and grounding is required, use the appropriate vaultspec research skills and

- agents. Instruct them to "Revise the plan based on user feedback: `{feedback}`."