speckit-plan
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Pre-Execution Checks
Check for extension hooks (before planning):
- Check if
.specify/extensions.yml exists in the project root.
- If it exists, read it and look for entries under the
hooks.before_plan key
- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
.specify/extensions.yml could not be read (include the parser error) and that no hooks were checked, including any mandatory (optional: false) hooks registered there, then continue normally
- Filter out hooks where
enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
- For each remaining hook, do not attempt to interpret or evaluate hook
condition expressions:
- If the hook has no
condition field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
condition, skip the hook and leave condition evaluation to the HookExecutor implementation
- For each executable hook, output the following based on its
optional flag:
- Optional hook (
optional: true):## Extension Hooks
**Optional Pre-Hook**: {extension}
Command: `/{command}`
Description: {description}
Prompt: {prompt}
To execute: `/{command}`
- Mandatory hook (
optional: false):## Extension Hooks
**Automatic Pre-Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
Wait for the result of the hook command before proceeding to the Outline.
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal {command} id shown above, e.g. a skills-mode agent runs it as /skill:speckit-... or $speckit-...). Emitting the block alone does not run the hook.
- If no hooks are registered or
.specify/extensions.yml does not exist, skip silently
Outline
Setup: Run .specify/scripts/bash/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, FEATURE_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
Load context: Read FEATURE_SPEC and /memory/constitution.md. Load IMPL_PLAN template (already copied).
Execute plan workflow: Follow the structure in IMPL_PLAN template to:
- Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
- Fill Constitution Check section from constitution
- Evaluate gates (ERROR if violations unjustified)
- Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
- Phase 1: Generate data-model.md, contracts/, quickstart.md
- Re-evaluate Constitution Check post-design
Mandatory Post-Execution Hooks
You MUST complete this section before reporting completion to the user.
Check if .specify/extensions.yml exists in the project root.
- If it does not exist, or no hooks are registered under
hooks.after_plan, skip to the Completion Report.
- If it exists, read it and look for entries under the
hooks.after_plan key.
- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that
.specify/extensions.yml could not be read (include the parser error) and that no hooks were checked, including any mandatory (optional: false) hooks registered there, then continue to the Completion Report.
- Filter out hooks where
enabled is explicitly false. Treat hooks without an enabled field as enabled by default.
- For each remaining hook, do not attempt to interpret or evaluate hook
condition expressions:
- If the hook has no
condition field, or it is null/empty, treat the hook as executable
- If the hook defines a non-empty
condition, skip the hook and leave condition evaluation to the HookExecutor implementation
- For each executable hook, output the following based on its
optional flag:
- Mandatory hook (
optional: false) — You MUST emit EXECUTE_COMMAND: for each mandatory hook:## Extension Hooks
**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal {command} id shown above, e.g. a skills-mode agent runs it as /skill:speckit-... or $speckit-...). Emitting the block alone does not run the hook.
- Optional hook (
optional: true):## Extension Hooks
**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}
Prompt: {prompt}
To execute: `/{command}`
Completion Report
Command ends after Phase 1 design. Report branch, IMPL_PLAN path, and generated artifacts.
Phases
Phase 0: Outline & Research
Extract unknowns from Technical Context above:
- For each NEEDS CLARIFICATION → research task
- For each dependency → best practices task
- For each integration → patterns task
Generate and dispatch research agents:
For each unknown in Technical Context:
Task: "Research {unknown} for {feature context}"
For each technology choice:
Task: "Find best practices for {tech} in {domain}"
Consolidate findings in research.md using format:
- Decision: [what was chosen]
- Rationale: [why chosen]
- Alternatives considered: [what else evaluated]
Output: research.md with all NEEDS CLARIFICATION resolved
Phase 1: Design & Contracts
Prerequisites: research.md complete
Extract entities from feature spec → data-model.md:
- Entity name, fields, relationships
- Validation rules from requirements
- State transitions if applicable
Define interface contracts (if project has external interfaces) → /contracts/:
- Identify what interfaces the project exposes to users or other systems
- Document the contract format appropriate for the project type
- Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
- Skip if project is purely internal (build scripts, one-off tools, etc.)
Create quickstart validation guide → quickstart.md:
- Document runnable validation scenarios that prove the feature works end-to-end
- Include prerequisites, setup commands, test/run commands, and expected outcomes
- Use links or references to contracts and data model details instead of duplicating them
- Do not include full implementation code, model/service/controller bodies, migrations, or complete test suites
- Keep this artifact as a validation/run guide; implementation details belong in
tasks.md and the implementation phase
Output: data-model.md, /contracts/*, quickstart.md
Key rules
- Use absolute paths for filesystem operations; use project-relative paths for references in documentation
- ERROR on gate failures or unresolved clarifications
Done When
Plan sections
plan.md follows .specify/templates/plan-template.md: Summary, Technical Context, Constitution Check (pass, or justify each failure under Complexity Tracking), Project Structure, Phase 0 to 2, Build contract, Production caller chain and Cross-repo seams. Name the existing components and wiring to reuse, the interfaces and data flows, migration and failure handling, and the cross-repository contracts. Add research.md, data-model.md, contracts/ and quickstart.md where the plan calls for them.
Workspace conventions
- Feature artifacts live in tracked repository-root
specs/<stable-id>/, never under .specify/specs/ or agent_data/. .specify/ holds only project configuration, templates and .specify/memory/constitution.md.
- Route the feature first with the ecosystem boundaries standard (https://github.com/Knuckles-Team/pipelines/blob/main/reference/ecosystem-boundaries.md). Each behavior has one normative owner. Look up the owning spec and extend it before you add a new one.
- Keep every requirement row ID (
<PREFIX>-<AREA>-R012.4), every Spec: commit trailer and every test binding intact. The delivery state (SPECIFIED, LANDED, VERIFIED, RETIRED) is computed by pipelines-hook spec-status; never write a Status: line or status.json.
- Specs and prompts name no private repository, internal host, homelab inventory or local workspace path. A contributor with only public GitHub access must be able to complete the work.
- When
.specify/scripts/ is absent, derive the feature directory from the repository root and the stable ID instead of running a script.
Optional artifacts
Add each optional artifact only where it carries content, and the analysis check requires it there: contracts/ holds one human-written .md contract per cross-repo seam (wire shape, refusal codes, and Provider: and Consumer: lines that name the row IDs on both sides; no generated contract); data-model.md when a row names new types, ontology classes or tables; quickstart.md when a row is a served behaviour row, naming the scenario or test command that runs its proof; research.md only when Phase 0 lists unknowns. File and directory names are lower-case kebab-case; plans live only in specs/<family>/plan.md, templates only in .specify/templates/, the constitution only in .specify/memory/. checklists/requirements.md is filled before landing.
1---2name: speckit-plan3domain: development4skill_type: skill5description: "Execute the implementation planning workflow using the plan template to generate design artifacts. Use when a clarified spec needs plan.md and its design artifacts."6license: MIT7tags: [spec-kit, sdd, upstream]8metadata:9 source: https://skillmd.com/skills/knuckles-team/speckit-plan10 version: '1.6.0'11 author: GitHub Spec Kit contributors12 upstream: https://github.com/github/spec-kit13---1415# speckit-plan1617## User Input1819```text20$ARGUMENTS21```2223You **MUST** consider the user input before proceeding (if not empty).2425## Pre-Execution Checks2627**Check for extension hooks (before planning)**:28- Check if `.specify/extensions.yml` exists in the project root.29- If it exists, read it and look for entries under the `hooks.before_plan` key30- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.specify/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue normally31- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.32- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:33 - If the hook has no `condition` field, or it is null/empty, treat the hook as executable34 - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation35- For each executable hook, output the following based on its `optional` flag:36 - **Optional hook** (`optional: true`):37 ```38 ## Extension Hooks3940 **Optional Pre-Hook**: {extension}41 Command: `/{command}`42 Description: {description}4344 Prompt: {prompt}45 To execute: `/{command}`46 ```47 - **Mandatory hook** (`optional: false`):48 ```49 ## Extension Hooks5051 **Automatic Pre-Hook**: {extension}52 Executing: `/{command}`53 EXECUTE_COMMAND: {command}5455 Wait for the result of the hook command before proceeding to the Outline.56 ```57 After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.58- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently5960## Outline61621. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, FEATURE_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").63642. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied).65663. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:67 - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")68 - Fill Constitution Check section from constitution69 - Evaluate gates (ERROR if violations unjustified)70 - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)71 - Phase 1: Generate data-model.md, contracts/, quickstart.md72 - Re-evaluate Constitution Check post-design7374## Mandatory Post-Execution Hooks7576**You MUST complete this section before reporting completion to the user.**7778Check if `.specify/extensions.yml` exists in the project root.79- If it does not exist, or no hooks are registered under `hooks.after_plan`, skip to the Completion Report.80- If it exists, read it and look for entries under the `hooks.after_plan` key.81- If the YAML cannot be parsed or is invalid, do not skip silently: tell the user that `.specify/extensions.yml` could not be read (include the parser error) and that no hooks were checked, including any mandatory (`optional: false`) hooks registered there, then continue to the Completion Report.82- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default.83- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions:84 - If the hook has no `condition` field, or it is null/empty, treat the hook as executable85 - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation86- For each executable hook, output the following based on its `optional` flag:87 - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**:88 ```89 ## Extension Hooks9091 **Automatic Hook**: {extension}92 Executing: `/{command}`93 EXECUTE_COMMAND: {command}94 ```95 After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.96 - **Optional hook** (`optional: true`):97 ```98 ## Extension Hooks99100 **Optional Hook**: {extension}101 Command: `/{command}`102 Description: {description}103104 Prompt: {prompt}105 To execute: `/{command}`106 ```107108## Completion Report109110Command ends after Phase 1 design. Report branch, IMPL_PLAN path, and generated artifacts.111112## Phases113114### Phase 0: Outline & Research1151161. **Extract unknowns from Technical Context** above:117 - For each NEEDS CLARIFICATION → research task118 - For each dependency → best practices task119 - For each integration → patterns task1201212. **Generate and dispatch research agents**:122123 ```text124 For each unknown in Technical Context:125 Task: "Research {unknown} for {feature context}"126 For each technology choice:127 Task: "Find best practices for {tech} in {domain}"128 ```1291303. **Consolidate findings** in `research.md` using format:131 - Decision: [what was chosen]132 - Rationale: [why chosen]133 - Alternatives considered: [what else evaluated]134135**Output**: research.md with all NEEDS CLARIFICATION resolved136137### Phase 1: Design & Contracts138139**Prerequisites:** `research.md` complete1401411. **Extract entities from feature spec** → `data-model.md`:142 - Entity name, fields, relationships143 - Validation rules from requirements144 - State transitions if applicable1451462. **Define interface contracts** (if project has external interfaces) → `/contracts/`:147 - Identify what interfaces the project exposes to users or other systems148 - Document the contract format appropriate for the project type149 - Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications150 - Skip if project is purely internal (build scripts, one-off tools, etc.)1511523. **Create quickstart validation guide** → `quickstart.md`:153 - Document runnable validation scenarios that prove the feature works end-to-end154 - Include prerequisites, setup commands, test/run commands, and expected outcomes155 - Use links or references to contracts and data model details instead of duplicating them156 - Do not include full implementation code, model/service/controller bodies, migrations, or complete test suites157 - Keep this artifact as a validation/run guide; implementation details belong in `tasks.md` and the implementation phase158159**Output**: data-model.md, /contracts/*, quickstart.md160161## Key rules162163- Use absolute paths for filesystem operations; use project-relative paths for references in documentation164- ERROR on gate failures or unresolved clarifications165166## Done When167168- [ ] Plan workflow executed and design artifacts generated169- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above170- [ ] Completion reported to user with branch, plan path, and generated artifacts171172## Plan sections173174`plan.md` follows `.specify/templates/plan-template.md`: Summary, Technical Context, Constitution Check (pass, or justify each failure under Complexity Tracking), Project Structure, Phase 0 to 2, Build contract, Production caller chain and Cross-repo seams. Name the existing components and wiring to reuse, the interfaces and data flows, migration and failure handling, and the cross-repository contracts. Add `research.md`, `data-model.md`, `contracts/` and `quickstart.md` where the plan calls for them.175176## Workspace conventions177178- Feature artifacts live in tracked repository-root `specs/<stable-id>/`, never under `.specify/specs/` or `agent_data/`. `.specify/` holds only project configuration, templates and `.specify/memory/constitution.md`.179- Route the feature first with the ecosystem boundaries standard (https://github.com/Knuckles-Team/pipelines/blob/main/reference/ecosystem-boundaries.md). Each behavior has one normative owner. Look up the owning spec and extend it before you add a new one.180- Keep every requirement row ID (`<PREFIX>-<AREA>-R012.4`), every `Spec:` commit trailer and every test binding intact. The delivery state (`SPECIFIED`, `LANDED`, `VERIFIED`, `RETIRED`) is computed by `pipelines-hook spec-status`; never write a `Status:` line or `status.json`.181- Specs and prompts name no private repository, internal host, homelab inventory or local workspace path. A contributor with only public GitHub access must be able to complete the work.182- When `.specify/scripts/` is absent, derive the feature directory from the repository root and the stable ID instead of running a script.183184### Optional artifacts185186Add each optional artifact only where it carries content, and the analysis check requires it there: `contracts/` holds one human-written `.md` contract per cross-repo seam (wire shape, refusal codes, and `Provider:` and `Consumer:` lines that name the row IDs on both sides; no generated contract); `data-model.md` when a row names new types, ontology classes or tables; `quickstart.md` when a row is a `served` behaviour row, naming the scenario or test command that runs its proof; `research.md` only when Phase 0 lists unknowns. File and directory names are lower-case kebab-case; plans live only in `specs/<family>/plan.md`, templates only in `.specify/templates/`, the constitution only in `.specify/memory/`. `checklists/requirements.md` is filled before landing.