From spec-first
Creates structured plans for multi-step tasks like software features, research workflows, events, or study plans. Deepens existing plans with interactive sub-agent reviews.
npx claudepluginhub sunrain520/spec-firstThis skill uses the workspace's default tool permissions.
**Note: The current year is 2026.** Use this when dating plans and searching for recent documentation.
Creates structured plans for multi-step tasks including software features, implementations, research, or projects. Deepens plans via interactive sub-agent reviews.
Generates structured implementation plans from feature descriptions or requirements, grounded in repo patterns and research. Deepens existing plans via interactive sub-agent review.
Transforms research findings into actionable implementation plans with granular tasks, verification criteria, and stakes classification. Use before coding to ensure alignment.
Share bugs, ideas, or general feedback.
Note: The current year is 2026. Use this when dating plans and searching for recent documentation.
spec-brainstorm defines WHAT to build. spec-plan defines HOW to build it. spec-work executes the plan. A prior brainstorm is useful context but never required — spec-plan works from any input: a 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.
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.
When a CRG graph is available, start planning with spec-first crg hook before-plan --task="<task>" --repo=<repo>. If opened at a parent workspace root, run spec-first crg workspace context --root=<workspace> --task="<task>" first, treat its candidates as advisory, let the LLM/user choose the child repo boundary, then run the repo-local before-plan hook for that child. Treat the hook envelope, locate / path / explain recommendations, repo topology, evidence, and limitations as decision inputs only; the LLM still selects the candidate change surface. If a workspace task spans multiple child repos, decompose it into explicit sequential repo-local plans/runs instead of one combined workspace run. If the hook reports unavailable or degraded graph state, continue with direct repo reads instead of falling back to Stage-0 docs.
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) or 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> #$ARGUMENTS </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.
spec-brainstorm produced a requirements document, planning should build from it rather than re-inventing behavior.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.Every plan should contain:
A plan is ready when an implementer can start confidently without needing the plan to write the code for them.
If the user references an existing plan file or there is an obvious recent matching plan in docs/plans/:
spec-work, so there is no progress to preserve across editsDeepen intent: The word "deepen" (or "deepening") in reference to a plan is the primary trigger for the deepening fast path. When the user says "deepen the plan", "deepen my plan", "run a deepening pass", or similar, the target document is a plan in docs/plans/, not a requirements document. Use any path, keyword, or context the user provides to identify the right plan. If a path is provided, verify it is actually a plan document. If the match is not obvious, confirm with the user before proceeding.
Words like "strengthen", "confidence", "gaps", and "rigor" are NOT sufficient on their own to trigger deepening. These words appear in normal editing requests ("strengthen that section about the diagram", "there are gaps in the test scenarios") and should not cause a holistic deepening pass. Only treat them as deepening intent when the request clearly targets the plan as a whole and does not name a specific section or content area to change — and even then, prefer to confirm with the user before entering the deepening flow.
Once the plan is identified and appears complete (all major sections present, implementation units defined, status: active):
# Title heading with Created: date instead of frontmatter), route to references/universal-planning.md for editing or deepening instead of Phase 5.3. Non-software plans do not use the software confidence-first check.Normal editing requests (e.g., "update the test scenarios", "add a new implementation unit", "strengthen the risk section") should NOT trigger the fast path — they follow the standard resume flow.
If the plan already has a deepened: YYYY-MM-DD frontmatter field and there is no explicit user request to re-deepen, the fast path still applies the same confidence-gap evaluation — it does not force deepening.
If the task involves building, modifying, or architecting software (references code, repos, APIs, databases, or asks to build/modify/deploy), continue to Phase 0.2.
If the domain is genuinely ambiguous (e.g., "plan a migration" with no other context), ask the user before routing.
Otherwise, read references/universal-planning.md and follow that workflow instead. Skip all subsequent phases. Named tools or source links don't change this routing — they're inputs, handled per Core Principle 8.
Before asking planning questions, search docs/brainstorms/ for files matching *-requirements.md.
Relevance criteria: A requirements document is relevant if:
If multiple source documents match, ask which one to use using the platform's blocking question tool when available (see Interaction Method). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
If a relevant requirements document exists:
spec_id when the origin frontmatter contains one. Preserve it exactly in the plan frontmatter; it is the cross-artifact identity for this spec chain.(see origin: <source-path>)If the origin requirements document is a legacy document without spec_id, do not edit the origin by default. Generate a new plan-local spec_id, note in the plan that origin identity was not inherited, and treat the requirements-to-plan link as weak trace. If the user explicitly asks to backfill the origin requirements document, handle that as a separate scoped edit.
If no relevant requirements document exists, planning may proceed from the user's request directly.
If no relevant requirements document exists, or the input needs more structure:
spec-brainstorm as a suggestion — but always offer to continue planning here as wellThe planning bootstrap should establish:
Keep this bootstrap brief. It exists to preserve direct-entry convenience, not to replace a full brainstorm.
If the bootstrap uncovers major unresolved product questions:
spec-brainstorm againIf the bootstrap reveals that a different workflow would serve the user better:
spec-debug skill. A plan requires a known problem to solve; debugging identifies what that problem is. Announce the routing clearly: "This needs investigation before planning — switching to spec-debug to find the root cause."spec-work as a faster alternative alongside continuing with planning. The user decides.If the origin document contains Resolve Before Planning or similar blocking questions:
If true product blockers remain:
spec-brainstorm to resolve themClassify the work into one of these plan depths:
If depth is unclear, ask one targeted question and then continue.
Prepare a concise planning context summary (a paragraph or two) to pass as input to the research agents:
Run these agents in parallel:
docs/solutions/Slack context (opt-in) — never auto-dispatch. Route by condition:
spec-slack-researcher with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation.Decide whether the plan should carry a lightweight execution posture signal.
Look for signals such as:
When the signal is clear, carry it forward silently in the relevant implementation units.
Ask the user only if the posture would materially change sequencing or risk and cannot be responsibly inferred.
Based on the origin document, user signals, and local findings, decide whether external research adds value.
Read between the lines. Pay attention to signals from the conversation so far:
Leverage spec-repo-research-analyst's technology context:
The spec-repo-research-analyst output includes a structured Technology & Infrastructure summary. Use it to make sharper external research decisions:
Always lean toward external research when:
Skip external research when:
Announce the decision briefly before continuing. Examples:
If Step 1.2 indicates external research is useful, run these agents in parallel:
Summarize:
If the current classification is Lightweight and Phase 1 research found that the work touches any of these external contract surfaces, reclassify to Standard:
.github/workflows/, Dockerfile, deployment scripts)This ensures flow analysis (Phase 1.5) runs and the confidence-first check (Phase 5.3) applies critical-section bonuses. Announce the reclassification briefly: "Reclassifying to Standard — this change touches [environment variables / exported APIs / CI config] with external consumers."
For Standard or Deep plans, or when user flow completeness is still unclear, run:
Use the output to:
Build a planning question list from:
For each question, decide whether it should be:
Ask the user only when the answer materially affects architecture, scope, sequencing, or risk and cannot be responsibly inferred. Use the platform's blocking question tool when available (see Interaction Method).
Do not run tests, build the app, or probe runtime behavior in this phase. The goal is a strong plan, not partial execution.
feat: Add user authentication or fix: Prevent checkout double-submitfeat, fix, or refactordocs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
docs/plans/ if it does not exist2026-01-15-001-feat-user-authentication-flow-plan.md, 2026-02-03-002-fix-checkout-race-condition-plan.mdspec_id:
spec_id, inherit that value exactly, even though the plan filename also contains <type>.spec_id, generate a plan-local spec_id from the plan filename sequence and slug, and state in the Problem Frame or Context & Research that origin identity was not inherited.spec_id from the plan filename sequence and slug.spec_id, scan docs/brainstorms/, docs/plans/, and docs/tasks/ frontmatter. If the same spec_id already exists and origin / source_plan links do not prove it belongs to the same spec chain, increment the local sequence or ask the user to confirm.spec_id across ordinary edits, plan deepening, task-pack rebuilds, and work/review handoffs. For alternative implementation plans, independent delivery chains, or abandon-and-replace work from the same origin, decide whether to inherit or create a new spec chain and record the reason in the plan.For Standard or Deep plans, briefly consider who is affected by this change — end users, developers, operations, other teams — and how that should shape the plan. For cross-cutting work, note affected parties in the System-Wide Impact section.
Break the work into logical implementation units. Each unit should represent one meaningful change that an implementer could typically land as an atomic commit.
Good units are:
Avoid:
Each unit carries a stable plan-local U-ID assigned in Phase 3.5 (U1, U2, …). U-IDs survive reordering, splitting, and deletion: new units take the next unused number, gaps are fine, and existing IDs are never renumbered. This lets spec-work reference units unambiguously across plan edits.
Before detailing implementation units, decide whether an overview would help a reviewer validate the intended approach. This section communicates the shape of the solution — how pieces fit together — without dictating implementation.
When to include it:
| Work involves... | Best overview form |
|---|---|
| DSL or API surface design | Pseudo-code grammar or contract sketch |
| Multi-component integration | Mermaid sequence or component diagram |
| Data pipeline or transformation | Data flow sketch |
| State-heavy lifecycle | State diagram |
| Complex branching logic | Flowchart |
| Mode/flag combinations or multi-input behavior | Decision matrix (inputs -> outcomes) |
| Single-component with non-obvious shape | Pseudo-code sketch |
When to skip it:
Choose the medium that fits the work. Do not default to pseudo-code when a diagram communicates better, and vice versa.
Frame every sketch with: "This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce."
Keep sketches concise — enough to validate direction, not enough to copy-paste into production.
For greenfield plans that create a new directory structure (new plugin, service, package, or module), include an ## Output Structure section with a file tree showing the expected layout. This gives reviewers the overall shape before diving into per-unit details.
When to include it:
When to skip it:
The tree is a scope declaration showing the expected output shape. It is not a constraint — the implementer may adjust the structure if implementation reveals a better layout. The per-unit **Files:** sections remain authoritative for what each unit creates or modifies.
Each unit's heading carries a stable U-ID prefix matching the format used for R/A/F/AE in requirements docs: - U1. **[Name]**. The prefix is plain text, not bolded — the bold is reserved for the unit name. Number sequentially within the plan starting at U1. Do not prefix units with - [ ] / - [x] checkbox markers; the plan is a decision artifact, and execution progress is derived from git by spec-work rather than stored in the plan body.
Stability rule. Once assigned, a U-ID is never renumbered. Reordering units leaves their IDs in place (e.g., U1, U3, U5 in their new order is correct; renumbering to U1, U2, U3 is not). Splitting a unit keeps the original U-ID on the original concept and assigns the next unused number to the new unit. Deletion leaves a gap; gaps are fine. This rule matters most during deepening (Phase 5.3), which is the most likely accidental-renumber vector.
For each unit, include:
Test expectation: none -- [reason] instead of leaving the field blank. AE-link convention: when a test scenario directly enforces an origin Acceptance Example, prefix it with Covers AE<N>. (or Covers F<N> / AE<N>.). This is sparse-by-design — most test scenarios are finer-grained than AEs and do not link. Do not force AE links onto tests that only cover lower-level implementation details.
Every feature-bearing unit should include the test file path in **Files:**.
Use Execution note sparingly. Good uses include:
Execution note: Start with a failing integration test for the request/response contract.Execution note: Add characterization coverage before modifying this legacy parser.Execution note: Implement new domain behavior test-first.Do not expand units into literal RED/GREEN/REFACTOR substeps.
If something is important but not knowable yet, record it explicitly under deferred implementation notes rather than pretending to resolve it in the plan.
Examples:
NEVER CODE during this skill. Research, decide, and write the plan — do not start implementation.
Use one planning philosophy across all depths. Change the amount of detail, not the boundary between planning and execution.
Lightweight
Standard
Deep
For sufficiently large, risky, or cross-cutting work, add the sections that genuinely help:
Do not add these as boilerplate. Include them only when they improve execution quality or stakeholder alignment.
Alternatives Considered — what to vary. When this section is included, alternatives must differ on how the work is built: architecture, sequencing, boundaries, integration pattern, rollout strategy. Tiny implementation variants (which hash function, which serialization format) belong in Key Technical Decisions, not Alternatives. Product-shape alternatives (different actors, different core outcome, different positioning) belong in spec-brainstorm, not here — surface them back upstream rather than re-litigating product questions during planning.
Omit clearly inapplicable optional sections, especially for Lightweight plans.
---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
spec_id: YYYY-MM-DD-NNN-<slug>
origin: docs/brainstorms/YYYY-MM-DD-NNN-<slug>-requirements.md # include when planning from a requirements doc
deepened: YYYY-MM-DD # optional, set when the confidence-first check substantively strengthens the plan
---
# [Plan Title]
## Overview
[What is changing and why]
---
## Problem Frame
[Summarize the user/business problem and context. Reference the origin doc when present.]
---
## Requirements Trace
- R1. [Requirement or success criterion this plan must satisfy]
- R2. [Requirement or success criterion this plan must satisfy]
<!-- Origin trace sub-blocks: include only when the upstream requirements doc supplies the
corresponding section. Each sub-block is independent — include only the ones that apply.
Omit cleanly (no header, no empty line) when no origin doc exists or the origin had no
Actors / Key Flows / Acceptance Examples sections. -->
**Origin actors:** [A1 (role/name), A2 (role/name), …]
**Origin flows:** [F1 (flow name), F2 (flow name), …]
**Origin acceptance examples:** [AE1 (covers R1, R4), AE2 (covers R3), …]
---
## Scope Boundaries
<!-- Default structure (no origin doc, or origin was Lightweight / Standard / Deep-feature):
a single bulleted list of explicit non-goals. The optional `### Deferred to Follow-Up Work`
subsection below may still be included when this plan's implementation is intentionally
split across other PRs/issues/repos. -->
- [Explicit non-goal or exclusion]
<!-- Optional plan-local subsection — include when this plan's implementation is intentionally
split across other PRs, issues, or repos. Distinct from origin-carried "Deferred for later"
(product sequencing) and "Outside this product's identity" (positioning). -->
### Deferred to Follow-Up Work
- [Work that will be done separately]: [Where or when -- e.g., "separate PR in repo-x", "future iteration"]
<!-- Triggered structure: replace the single list above with the three subsections below ONLY
when the origin doc is Deep-product (detectable by presence of an "Outside this product's
identity" subsection in the origin's Scope Boundaries). At all other tiers and when no
origin exists, use the single-list structure above. -->
<!--
### Deferred for later
[Carried from origin — product/version sequencing. Work that will be done eventually but not in v1.]
- [Item]
### Outside this product's identity
[Carried from origin — positioning rejection. Adjacent product the plan must not accidentally build.]
- [Item]
### Deferred to Follow-Up Work
[Plan-local — implementation work intentionally split across other PRs/issues/repos. Distinct from origin's "Deferred for later" (product) and "Outside this product's identity" (positioning).]
- [Item]
-->
---
## Context & Research
### Relevant Code and Patterns
- [Existing file, class, component, or pattern to follow]
### Institutional Learnings
- [Relevant `docs/solutions/` insight]
### External References
- [Relevant external docs or best-practice source, if used]
---
## Key Technical Decisions
- [Decision]: [Rationale]
---
## Open Questions
### Resolved During Planning
- [Question]: [Resolution]
### Deferred to Implementation
- [Question or unknown]: [Why it is intentionally deferred]
---
<!-- Optional: Include when the plan creates a new directory structure (greenfield plugin,
new service, new package). Shows the expected output shape at a glance. Omit for plans
that only modify existing files. This is a scope declaration, not a constraint --
the implementer may adjust the structure if implementation reveals a better layout. -->
## Output Structure
[directory tree showing new directories and files]
---
<!-- Optional: Include this section only when the work involves DSL design, multi-component
integration, complex data flow, state-heavy lifecycle, or other cases where prose alone
would leave the approach shape ambiguous. Omit it entirely for well-patterned or
straightforward work. -->
## High-Level Technical Design
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]
---
## Implementation Units
<!-- Each unit carries a stable plan-local U-ID (U1, U2, …) assigned sequentially.
U-IDs are never renumbered: reordering preserves them in place, splitting keeps the
original U-ID and assigns the next unused number to the new unit, deletion leaves
a gap. This anchor is what spec-work references in blockers and verification, so
stability across plan edits is load-bearing. -->
- U1. **[Name]**
**Goal:** [What this unit accomplishes]
**Requirements:** [R1, R2]
**Dependencies:** [None / U1 / external prerequisite]
**Files:**
- Create: `path/to/new_file`
- Modify: `path/to/existing_file`
- Test: `path/to/test_file`
**Approach:**
- [Key design or sequencing decision]
**Execution note:** [Optional test-first, characterization-first, or other execution posture signal]
**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*
**Patterns to follow:**
- [Existing file, class, or pattern]
**Test scenarios:**
<!-- Include only categories that apply to this unit. Omit categories that don't. For units with no behavioral change, use "Test expectation: none -- [reason]" instead of leaving this section blank. -->
- [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]
**Verification:**
- [Outcome that should hold when this unit is complete]
---
## System-Wide Impact
- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
- **Error propagation:** [How failures should travel across layers]
- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
- **API surface parity:** [Other interfaces that may require the same change]
- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
- **Unchanged invariants:** [Existing APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]
---
## Risks & Dependencies
| Risk | Mitigation |
|------|------------|
| [Meaningful risk] | [How it is addressed or accepted] |
---
## Documentation / Operational Notes
- [Docs, rollout, monitoring, or support impacts when relevant]
---
## Sources & References
- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]
For larger Deep plans, extend the core template only when useful with sections such as:
## Alternative Approaches Considered
- [Approach]: [Why rejected or not chosen]
---
## Success Metrics
- [How we will know this solved the intended problem]
---
## Dependencies / Prerequisites
- [Technical, organizational, or rollout dependency]
---
## Risk Analysis & Mitigation
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How addressed] |
---
## Phased Delivery
### Phase 1
- [What lands first and why]
### Phase 2
- [What follows and why]
---
## Documentation Plan
- [Docs or runbooks to update]
---
## Operational / Rollout Notes
- [Monitoring, migration, feature flag, or rollout considerations]
---) between top-level sections in Standard and Deep plans, mirroring the spec-brainstorm requirements doc convention. Improves scannability of dense plans where many H2 sections sit close together. Omit for Lightweight plans where the whole doc fits on a single screen./Users/name/Code/project/src/file.ts. Use src/file.ts instead. Absolute paths make plans non-portable across machines, worktrees, and teammates. When a plan targets a different repo than the document's home, state the target repo once at the top of the plan (e.g., **Target repo:** my-other-project) and use repo-relative paths throughoutRED/GREEN/REFACTOR instructionsWhen the plan contains 4+ implementation units with non-linear dependencies, 3+ interacting surfaces in System-Wide Impact, 3+ behavioral modes/variants in Overview or Problem Frame, or 3+ interacting decisions in Key Technical Decisions or alternatives in Alternative Approaches, read references/visual-communication.md for diagram and table guidance. This covers plan-structure visuals (dependency graphs, interaction diagrams, comparison tables) — not solution-design diagrams, which are covered in Section 3.4.
Before finalizing, check:
spec-brainstormExecution noteTest expectation: none -- [reason] annotation is only valid for non-feature-bearing units (pure config, scaffolding, styling)spec_id is present for software plans, is inherited from origin requirements when available, and is not changed during deepening or ordinary plan editsspec_id, the plan explicitly says it uses a plan-local spec_id and that origin identity was not inheritedspec_id or starts a new spec chain### Deferred to Follow-Up Work rather than mixed with true non-goals?If the plan originated from a requirements document, re-read that document and verify:
spec-brainstormOutside this product's identity subsection): the plan's Scope Boundaries preserves the three-way split — Deferred for later and Outside this product's identity carried verbatim from origin, Deferred to Follow-Up Work reserved for plan-local implementation sequencingREQUIRED: Write the plan file to disk before presenting any options.
Use the Write tool to save the complete plan to:
docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
Confirm:
Plan written to docs/plans/[filename]
Pipeline mode: If invoked from an automated workflow such as LFG, SLFG, or any disable-model-invocation context, skip interactive questions. Make the needed choices automatically and proceed to writing the plan.
After writing the plan file, automatically evaluate whether the plan needs strengthening.
Two deepening modes:
Interactive mode exists because on-demand deepening is a different user posture — the user already has a plan they are invested in and wants to be surgical about what changes. This applies whether the plan was generated by this skill, written by hand, or produced by another tool.
spec-doc-review and this confidence-first check are different:
spec-doc-review skill when the document needs clarity, simplification, completeness, or scope controlPipeline mode: This phase always runs in auto mode in pipeline/disable-model-invocation contexts. No user interaction needed.
Determine the plan depth from the document:
Build a risk profile. Treat these as high-risk signals:
If the plan already appears sufficiently grounded and the thin-grounding override does not apply, report "Confidence-first check passed — no sections need strengthening", then load references/plan-handoff.md now and execute 5.3.8 → 5.3.9 → 5.4 in sequence. Document review is mandatory — do not skip it because the confidence-first check passed. The two tools catch different classes of issues.
When deepening is warranted, read references/deepening-workflow.md for confidence-first scoring checklists, section-to-agent dispatch mapping, execution mode selection, research execution, interactive finding review, and plan synthesis instructions. Execute steps 5.3.3 through 5.3.7 from that file, then return here for 5.3.8.
Load references/plan-handoff.md now. It contains the full instructions for 5.3.8 (document review), 5.3.9 (final checks and cleanup), and 5.4 (post-generation handoff, including the Proof HITL flow, post-HITL re-review, and Issue Creation branching). Document review is mandatory — do not skip it even if the confidence-first check already ran.
After document review and final checks, present this menu using the platform's blocking question tool: AskUserQuestion in Claude Code (call ToolSearch with select:AskUserQuestion first if its schema isn't loaded) or 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.
Question: "Plan ready at docs/plans/YYYY-MM-DD-NNN-<type>-<name>-plan.md. What would you like to do next?"
Options:
/spec:work (recommended) - Begin implementing this plan in the current sessionspec-write-tasks - Use the standalone skill when the plan is large, dependency-heavy, or would benefit from a derived docs/tasks/*-tasks.md execution inputRouting each selection, contextual surfacing of residual spec-doc-review findings, and the post-HITL resync logic all live in references/plan-handoff.md — follow it for every branch.
Completion check: This skill is not complete until the post-generation menu above has been presented and the user has selected an action. If you have written the plan file and have not yet presented the menu, you are not done — go to the load instruction above and continue.
Pipeline mode exception: In LFG, SLFG, or any disable-model-invocation context, skip the interactive menu and return control to the caller after the plan file is written, confidence-first check has run, and spec-doc-review has run in headless mode (per references/plan-handoff.md).