sunrain520/spec-first/spec-plan

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 user has been asked: "Plan ready at <absolute path to plan>. What would you like to do next?" If the menu fits the platform's blocking-question tool, ask it there; otherwise render the numbered handoff options in chat and wait. If the user selects an action, execute the Phase 5.4 routing for that selection before treating the skill as complete.

Interaction Method

When asking the user a question, use the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded), request_user_input in Codex. Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question.

Ask one question at a time. Prefer a concise single-select choice when natural options exist.

Feature Description

<feature_description> #<invocation arguments supplied by the current host> </feature_description>

If the feature description above is empty, ask the user: "What would you like to plan? Describe the task, goal, or project you have in mind." Then wait for their response before continuing.

If the input is present but unclear or underspecified, do not abandon — ask one or two clarifying questions, or proceed to Phase 0.4's planning bootstrap to establish enough context. The goal is always to help the user plan, never to exit the workflow.

IMPORTANT: All file references in the plan document must use repo-relative paths (e.g., `src/models/user.rb`), never absolute paths (e.g., `/Users/name/Code/project/src/models/user.rb`). This applies everywhere — implementation unit file lists, pattern references, origin document links, and prose mentions. Absolute paths break portability across machines, worktrees, and teammates.

Core Principles

1. Use the Product Contract as the source of truth - If spec-brainstorm produced a requirements-only unified plan, planning should enrich it in place rather than re-inventing behavior or creating a second artifact.
2. Decisions, not code - Capture approach, boundaries, files, dependencies, risks, and test scenarios. Do not pre-write implementation code or shell command choreography. Pseudo-code sketches or DSL grammars that communicate high-level technical design are welcome when they help a reviewer validate direction — but they must be explicitly framed as directional guidance, not implementation specification.
3. Research before structuring - Explore the codebase, institutional learnings, and external guidance when warranted before finalizing the plan.
4. Right-size the artifact - Small work gets a compact plan. Large work gets more structure. The philosophy stays the same at every depth.
5. Separate planning from execution discovery - Resolve planning-time questions here. Explicitly defer execution-time unknowns to implementation.
6. Keep the plan portable - The plan should work as a living document, review artifact, or issue body without embedding tool-specific executor instructions.
7. Carry execution direction lightly when it matters - If the request, origin document, or repo context clearly implies test-first proof, characterization coverage, smoke-first verification, or another non-default execution direction, reflect that in the plan as a lightweight natural-language signal. Do not encode it as a finite enum or turn the plan into step-by-step execution choreography.
8. Honor user-named resources - When the user names a specific resource — a CLI, MCP server, URL, file, doc link, or prior artifact — treat it as authoritative input, not a suggestion. Discover it if unknown (command -v, fetch, read) before assuming it's unavailable. Use it in place of generic alternatives. If it fails or doesn't exist, say so explicitly rather than silently substituting.
9. Inventory before invention - Before proposing a new abstraction, durable source surface, adapter or wrapper, orchestrator, or integration pipeline, inspect existing capabilities, owners, and extension points. Prefer reuse, focused extension, or composition through thin glue; introduce a new boundary only when existing owners cannot absorb the change without mixing concerns, duplicating truth, or creating a misleading abstraction.

Plan Quality Bar

Every plan should contain:

• A clear problem frame and scope boundary
• A first-screen Goal Capsule that names the objective, recommended approach, decision focus, verification focus, and largest risk or boundary
• Concrete requirements traceability back to the request or origin document
• Repo-relative file paths for the work being proposed (never absolute paths — see Planning Rules)
• Explicit test file paths for feature-bearing implementation units
• Decisions with rationale, not just tasks
• Existing patterns or code references to follow
• Evidence provenance and limitations when source, provider, history, or cross-repo facts materially shape the plan
• A reuse / extend / compose / new architecture posture when the plan proposes a new abstraction, durable source surface, adapter or orchestrator, or integration seam
• Conditional coverage of every materially-considered client, service/backend, API/schema/event contract, data, operational/rollout, verification/test, and agent/tool surface on multi-surface work
• Concrete invariant, failure, rollback, compatibility, and verification decisions when a high-risk lens applies
• Enumerated test scenarios for each feature-bearing unit, specific enough that an implementer knows exactly what to test without inventing coverage themselves
• Clear dependencies and sequencing

A plan is ready when an implementer can start confidently without needing the plan to write the code for them.

STOP. Before Phase 0 source intake or Phase 1 research, read `references/planning-evidence-boundaries.md`. It owns source/runtime exclusion, advisory evidence trust, cross-repo scope, evidence landing, summary-first intake, and the conditional reuse / extend / compose / new capability, composition, and ownership lens. Do not reconstruct those rules from memory.

Workflow

Phase 0: Resume, Source, and Scope