name: speckit-03-plan
description: Create technical implementation plan from feature specification

Spec-Kit Plan

Execute the implementation planning workflow using the plan template to generate design artifacts.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Constitution Loading (REQUIRED)

Before ANY action, load and internalize the project constitution:

1. Read constitution:
   bash cat .specify/memory/constitution.md 2>/dev/null || echo "NO_CONSTITUTION"

2. If file doesn't exist:
   ```
   ERROR: Project constitution not found at .specify/memory/constitution.md

STOP - Cannot proceed without constitution.
Run /speckit-00-constitution first to define project principles.
```

1. Parse all principles, constraints, and governance rules.

2. Extract Enforcement Rules (Skills Advantage - Hard Gate):

3. Find all lines containing "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED", "NON-NEGOTIABLE"
4. Build an enforcement checklist from these rules

5. Example extraction:
   CONSTITUTION ENFORCEMENT RULES: [MUST] Use TDD - write tests before implementation [MUST NOT] Use external dependencies without justification [REQUIRED] All code must have error handling

6. Validation commitment: Every output will be validated against each principle before being written.

7. Hard Gate Declaration: State explicitly:
   CONSTITUTION GATE ACTIVE Extracted X enforcement rules ANY violation will HALT planning with explanation

Prerequisites Check

1. Run setup script (choose based on platform):

Unix/macOS/Linux:
bash .specify/scripts/bash/setup-plan.sh --json

Windows (PowerShell):
powershell pwsh .specify/scripts/powershell/setup-plan.ps1 -Json

1. Parse JSON for:
2. FEATURE_SPEC - path to spec.md
3. IMPL_PLAN - path to plan.md
4. SPECS_DIR - feature directory

5. BRANCH - current branch name

6. If error or missing spec.md:
   ERROR: spec.md not found in feature directory. Run /speckit-01-specify first to create the feature specification.

Smart Validation (Skills Advantage)

BEFORE proceeding to planning, perform AI-powered semantic validation that vanilla commands cannot do:

Spec Quality Gate

Read the spec.md and validate:

1. Requirement Count Check:
2. Count functional requirements (FR-XXX patterns)
3. WARN if fewer than 3 requirements: "Spec may be underspecified"

4. HALT if 0 requirements: "Cannot plan without requirements"

5. Measurable Success Criteria Check:

6. Scan Success Criteria section for numeric values, percentages, or time measurements

7. WARN if no measurable criteria found: "Success criteria should include metrics (e.g., 'under 3 seconds', '95% uptime')"

8. Unresolved Clarification Check:

9. Search for [NEEDS CLARIFICATION] markers
10. If found, list each one and ask: "Resolve these before planning, or proceed with assumptions?"

11. If user says proceed, document assumptions explicitly in plan.md

12. User Story Coverage Check:

13. Verify each user story has at least one acceptance scenario

14. WARN if any story lacks scenarios: "User Story X has no acceptance criteria"

15. Cross-Reference Validation:

16. Check that requirements reference user stories (or vice versa)
17. WARN if orphan requirements exist: "FR-XXX not linked to any user story"

Quality Score Report

Calculate and display:

╭─────────────────────────────────────────────╮
│  SPEC QUALITY REPORT (Skills Advantage)     │
├─────────────────────────────────────────────┤
│  Requirements:     X found (min: 3)    [✓/✗]│
│  Success Criteria: X found (min: 3)    [✓/✗]│
│  User Stories:     X found (min: 1)    [✓/✗]│
│  Measurable:       X criteria have metrics  │
│  Clarifications:   X unresolved             │
│  Coverage:         X% requirements linked   │
├─────────────────────────────────────────────┤
│  OVERALL SCORE: X/10                        │
│  STATUS: [READY/NEEDS WORK]                 │
╰─────────────────────────────────────────────╯

If score < 6: Recommend running /speckit-02-clarify first
If score >= 6: Proceed with planning

Execution Flow

1. Setup

• Run setup script to get paths and copy plan template
• Read FEATURE_SPEC and constitution
• Load IMPL_PLAN template

2. Execute Plan Workflow

Follow the structure in IMPL_PLAN template to:

1. Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION"):
2. Language/Version
3. Primary Dependencies
4. Storage
5. Testing
6. Target Platform
7. Project Type
8. Performance Goals
9. Constraints

10. Scale/Scope

11. Fill Constitution Check section from constitution principles

12. Evaluate gates - ERROR if violations cannot be justified

3. Phase 0: Outline & Research

1. Extract unknowns from Technical Context:
2. For each NEEDS CLARIFICATION -> research task
3. For each dependency -> best practices task

4. For each integration -> patterns task

5. Research each unknown and document findings

6. Consolidate findings in research.md:

7. Decision: [what was chosen]
8. Rationale: [why chosen]
9. Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

4. Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from feature spec -> data-model.md:
2. Entity name, fields, relationships
3. Validation rules from requirements

4. State transitions if applicable

5. Generate API contracts from functional requirements:

6. For each user action -> endpoint
7. Use standard REST/GraphQL patterns

8. Output OpenAPI/GraphQL schema to /contracts/

9. Create quickstart.md with test scenarios

10. Agent context update (choose based on platform):

Unix/macOS/Linux:
bash .specify/scripts/bash/update-agent-context.sh claude

Windows (PowerShell):
powershell pwsh .specify/scripts/powershell/update-agent-context.ps1 -AgentType claude

This updates CLAUDE.md with the new technology stack.

Output: data-model.md, /contracts/*, quickstart.md, updated agent file

5. Constitution Check (Post-Design)

Re-evaluate the Constitution Check after design phase:

• Verify all technical decisions align with principles
• If ANY violation detected:
• STOP immediately
• State: "CONSTITUTION VIOLATION: [Principle Name]"
• Explain what specifically violates the principle
• Suggest compliant alternative approach
• DO NOT proceed with "best effort" or workarounds

6. Phase Separation Validation (REQUIRED)

Before finalizing, scan the draft plan for governance content that belongs in /speckit-00-constitution:

Check for violations - plan MUST NOT contain:
- Project governance principles or "laws"
- Non-negotiable development rules (e.g., "always use TDD", "code review required")
- Quality standards that apply project-wide (e.g., "100% test coverage")
- Amendment procedures or versioning policies
- Compliance or audit requirements
- Team workflow rules (e.g., "PRs must be approved by 2 reviewers")
- Coding standards that aren't technology-specific

Plan SHOULD contain (these are appropriate here):
- Technology stack decisions (languages, frameworks, databases)
- Architecture patterns for THIS feature
- Implementation approach and rationale
- Data models and API contracts
- Performance targets for THIS feature
- Technology-specific best practices

If violations found:

╭─────────────────────────────────────────────────────────────────╮
│  PHASE SEPARATION VIOLATION DETECTED                           │
├─────────────────────────────────────────────────────────────────┤
│  Plan contains governance content:                             │
│  - [list each violation]                                       │
│                                                                 │
│  Governance principles belong in /speckit-00-constitution.     │
│  Plan defines HOW to implement THIS feature, not project laws. │
├─────────────────────────────────────────────────────────────────┤
│  ACTION: Moving governance content to constitution reference...│
╰─────────────────────────────────────────────────────────────────╯

Auto-fix: Replace governance statements with constitution references:
- "Always use TDD" → "Per constitution: [reference TDD principle]"
- "Code must have 100% coverage" → "Coverage target per constitution"
- "All PRs require review" → (remove - this is workflow, not implementation)

Re-validate after fixes until no violations remain.

Output Validation (REQUIRED)

Before writing ANY artifact:

1. Review output against EACH constitutional principle
2. If ANY violation detected:
3. STOP immediately
4. State: "CONSTITUTION VIOLATION: [Principle Name]"
5. Explain: What specifically violates the principle
6. Suggest: Compliant alternative approach
7. If compliant, proceed and note: "Validated against constitution v[VERSION]"

Key Rules

• Use absolute paths
• ERROR on gate failures or unresolved clarifications
• Command ends after Phase 1 design is complete

Report

Output:
- Branch name
- IMPL_PLAN path
- Generated artifacts list:
- research.md
- data-model.md
- contracts/*
- quickstart.md
- Agent file update status

Semantic Diff on Re-run (Skills Advantage)

If plan.md already exists with content, perform semantic diff before overwriting:

1. Detect and Parse Existing Plan

If plan.md exists and has Technical Context filled in:

1. Extract semantic elements:
2. Language/Version
3. Primary Dependencies
4. Storage choice

5. Project structure decisions

6. Compare with new content:
   ╭─────────────────────────────────────────────────────╮ │ SEMANTIC DIFF: plan.md │ ├─────────────────────────────────────────────────────┤ │ Tech Stack: │ │ ~ Language: Python 3.11 → Python 3.12 │ │ + Added: Redis for caching │ │ - Removed: None │ │ │ │ Architecture: │ │ ~ Changed: Switched from REST to GraphQL │ │ + Added: Event sourcing pattern │ ├─────────────────────────────────────────────────────┤ │ DOWNSTREAM IMPACT: │ │ ⚠ tasks.md MUST be regenerated (architecture change)│ │ ⚠ contracts/ need updates (API change) │ │ ⚠ data-model.md may need updates │ ╰─────────────────────────────────────────────────────╯

7. Flag breaking changes:

8. Language change → ALL tasks affected
9. Framework change → Most tasks affected
10. Storage change → Data layer tasks affected

2. Automatic Downstream Invalidation

If significant changes detected:

WARNING: Plan changes detected that invalidate downstream artifacts.
Recommend re-running:
- /speckit-05-tasks (REQUIRED - architecture changed)
- /speckit-06-analyze (RECOMMENDED - verify consistency)

Next Steps

After completing the plan:

1. Recommended: Run /speckit-04-checklist to create domain-specific quality checklists
2. Generates "unit tests for English" to validate requirements quality
3. Helps catch requirement gaps before implementation

4. Required to reach 100% before /speckit-07-implement

5. Required: Run /speckit-05-tasks to generate the task breakdown

Suggest to user:

Plan complete! Next steps:
- /speckit-04-checklist - (Recommended) Generate quality checklists for requirements validation
- /speckit-05-tasks - Generate task breakdown from plan