/spec-plan

name: spec-plan
description: "Create or deepen evidence-grounded plans for multi-step software and non-software work, including plans derived from requirements and answer-seeking research plans. Use when the outcome is clear enough to plan but HOW is unsettled. Prefer spec-brainstorm for unresolved WHAT, spec-debug for active failures, spec-work for implementation or tests, spec-doc-review for independent document critique, and runtime-maintenance for generated runtime mirrors."
argument-hint: "[optional: feature description, requirements doc path, plan path to deepen, or any task to plan] [output:html]"

Create Technical Plan

Note: Use the current date from the active host context. Use this when weighting external sources and dating artifacts.

`spec-brainstorm` defines **WHAT** to build by creating a requirements-only unified plan. `spec-plan` enriches that same artifact with **HOW** to build it. `spec-work` executes implementation-ready plans. A prior brainstorm is useful context but never required — `spec-plan` works from any input: a requirements-only unified plan, a legacy requirements doc, a bug report, a feature idea, or a rough description.

**When directly invoked, always plan.** Never classify a direct invocation as "not a planning task" and abandon the workflow. If the input is unclear, ask clarifying questions or use the planning bootstrap (Phase 0.4) to establish enough context — but always stay in the planning workflow. Here, "always plan" means entering and remaining in planning evaluation; entering planning evaluation does not promise an `implementation-ready` output. A blocked checkpoint or producer handoff is a valid outcome while product blockers remain.

This workflow produces a durable implementation plan. It does **not** implement code, run tests, or learn from execution-time results. If the answer depends on changing code and seeing what happens, that belongs in `spec-work`, not here.

Workflow Contract Summary

• **Input:** A requirements-only unified plan, legacy requirements, a bug or feature description, an existing plan, or an explicit answer-seeking objective.
• **Output:** An implementation-ready unified plan, the corresponding non-code or answer-seeking artifact, or a blocked checkpoint / producer handoff that preserves unresolved product questions.
• **Hard exits:** While WHAT is unsettled, the target repo or source owner is unclear, a load-bearing architecture or acceptance decision is unconfirmed, artifact metadata is invalid, or the user has not selected the owning handoff, do not modify the artifact to promote it to `implementation-ready`, generate Implementation Units or an implementation handoff, or enter implementation. When WHAT is unsettled at 0-1 depth (no shape, no audience, no success criterion), name `spec-brainstorm` explicitly as the upstream route in the options you offer — folding the gap into "explicit assumptions" and promising an executable plan anyway is not a legal substitute for routing.
• **Authority:** The Product Contract owns WHAT; current source and evidence constrain HOW; the LLM makes architecture judgments while scripts only prepare facts. Planning does not authorize code mutation, tests, commits, or landing.
• **Consumers:** `spec-write-tasks`, `spec-work`, `spec-doc-review`, human reviewers, and caller-owned pipelines.

Planning-Only Safety Contract

• **Before handoff selection, planning is the only authorized effect.** Research, ask planning questions, and write or revise the plan artifact; do not edit implementation code/config, run implementation tests/builds, start implementation workflows, or mutate generated runtime.
• **User pressure is not a write gate.** A user request to "just implement it too", "change the code while you're at it", "do it in one step", or an explicit go-ahead inside the planning run does not grant implementation authority here. Decline the implementation part, name `spec-work` as the owning route for execution, and finish the planning deliverable. Being asked directly by the user is exactly the case this contract exists for — it is not an exception to it.
• **Handoff stays blocking.** Writing a plan or finding an obvious implementation path does not authorize execution. Wait for the owning handoff question, then act only on the user's selected branch.
• **Enforcement is honest.** These rules are workflow-level attention hardening unless the host exposes a real Plan Mode or equivalent write gate. Do not claim a hard write guarantee from prose alone.

Mandatory Completion Contract

Every normal interactive `spec-plan` branch that produces a plan artifact or checkpoint is incomplete until its owning handoff question is presented. For software implementation-plan runs that continue past Phase 0.1b, that boundary is Phase 5.4's post-generation handoff menu. Non-software plan-seeking and approach-altitude branches use the terminal handoff in the reference workflow they route to; do not force those branches through Phase 5.4 after they have been told to skip subsequent phases. Answer-seeking is the exception: it may end after delivering the answer unless the universal-planning reference says to offer save/share.

For software implementation-plan runs, writing the plan file, running the confidence check, and running headless `spec-doc-review` are intermediate milestones, not completion. This producer invokes Markdown review with explicit `mutation:apply-fixes`; HTML review is report-only. This remains true when the user's prompt says only "create a plan", "write the doc", "run `spec-doc-review`", or similar. The only exception is pipeline mode (LFG or any `disable-model-invocation` context), where the caller owns the next step after the plan file, confidence check, and headless document review are complete.

Before any response that could end a software implementation-plan run, verify that the plan path is known, the headless review state and mutation policy are summarized, and the