Speckit 03 Plan

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:

   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
   
   Cannot proceed without constitution.
   Run: /speckit-00-constitution
   

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

4. Extract Enforcement Rules:

   • Find all lines containing "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED", "NON-NEGOTIABLE"
   • Build an enforcement checklist from these rules
   • 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
     

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

6. 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:

   .claude/skills/speckit-core/scripts/bash/setup-plan.sh --json
   

   Windows (PowerShell):

   pwsh .claude/skills/speckit-core/scripts/powershell/setup-plan.ps1 -Json
   

2. Parse JSON for:

   • FEATURE_SPEC - path to spec.md
   • IMPL_PLAN - path to plan.md
   • SPECS_DIR - feature directory
   • BRANCH - current branch name

3. If error or missing spec.md:

   ERROR: spec.md not found in feature directory.
   
   Run: /speckit-01-specify <feature description>
   

Smart Validation

BEFORE proceeding to planning, perform semantic validation:

Spec Quality Gate

Read the spec.md and validate:

1. Requirement Count Check:

   • Count functional requirements (FR-XXX patterns)
   • If fewer than 3 requirements:

     WARNING: Spec may be underspecified (found X requirements, recommend 3+).
     

   • If 0 requirements:

     ERROR: Cannot plan without requirements.
     
     The spec.md has no functional requirements (FR-XXX).
     Run: /speckit-01-specify to add requirements, or manually add FR-XXX items to spec.md
     

2. Measurable Success Criteria Check:

   • Scan Success Criteria section for numeric values, percentages, or time measurements
   • If no measurable criteria found:

     WARNING: No measurable success criteria found.
     
     Recommendation: Add metrics like "under 3 seconds", "95% uptime", "10,000 users".
     

3. Unresolved Clarification Check:

   • Search for [NEEDS CLARIFICATION] markers
   • If found, list each one and ask: "Resolve these before planning, or proceed with assumptions?"
   • If user says proceed, document assumptions explicitly in plan.md

4. User Story Coverage Check:

   • Verify each user story has at least one acceptance scenario
   • If any story lacks scenarios:

     WARNING: User Story X has no acceptance criteria.
     
     Recommendation: Add acceptance scenarios to validate the story is complete.
     

5. Cross-Reference Validation:

   • Check that requirements reference user stories (or vice versa)
   • If orphan requirements exist:

     WARNING: Orphan requirement detected (FR-XXX not linked to any user story).
     
     Recommendation: Link requirements to user stories for traceability.
     

Quality Score Report

Calculate and display:

╭─────────────────────────────────────────────╮
│  SPEC QUALITY REPORT                        │
├─────────────────────────────────────────────┤
│  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"):

   • Language/Version
   • Primary Dependencies
   • Storage
   • Testing
   • Target Platform
   • Project Type
   • Performance Goals
   • Constraints
   • Scale/Scope

2. Fill Constitution Check section from constitution principles

3. Evaluate gates - ERROR if violations cannot be justified

3. Tessl Tile Discovery (MANDATORY if Tessl installed)

Purpose: Discover, install, and catalog Tessl tiles for all technologies in the Technical Context. Tiles provide documentation, rules, and skills that improve implementation quality.

3.1 Check Tessl Availability

Platform Detection:

• Unix/Linux/macOS: command -v tessl >/dev/null 2>&1
• Windows PowerShell: Get-Command tessl -ErrorAction SilentlyContinue

If Tessl NOT Available: Display once and continue without tile operations:

ℹ️ Tessl not installed. Tile-based documentation unavailable.
   Install Tessl for enhanced library documentation: https://tessl.io

If Tessl Available: Proceed with tile discovery.

3.2 Check Tessl Status

mcp__tessl__status()

This shows authentication status and any existing tiles.

3.3 Extract Technologies from Technical Context

From the drafted Technical Context, extract:

• Language/Version (e.g., "Python 3.12", "TypeScript 5.x")
• Primary Dependencies (e.g., "Click", "Express", "React")
• Storage (e.g., "SQLite", "PostgreSQL", "MongoDB")
• Testing (e.g., "pytest", "Jest", "Vitest")
• Any other frameworks/libraries mentioned

3.4 Search and Install Tiles for Each Technology

For each technology identified:

1. Search for tiles:

   mcp__tessl__search(query="<technology>")
   

2. For each tile found, identify type:

   • Documentation tile: Contains library usage specs (has describes field)
   • Rules tile: Contains behavioral guidelines (has rules section)
   • Skills tile: Contains invocable AI commands (has skill section)

3. Install relevant tiles:

   mcp__tessl__install(packageName="<workspace/tile-name>")
   

4. Document in research.md (Tessl Tiles section):

   ## Tessl Tiles
   
   ### Installed Tiles
   
   | Technology | Tile | Type | Version |
   |------------|------|------|---------|
   | Python | tessl/python | Documentation | 1.2.0 |
   | Click | tessl/click | Documentation | 0.8.0 |
   | pytest | tessl/pytest | Documentation + Rules | 1.0.0 |
   
   ### Available Skills
   
   The following skills are available from installed tiles:
   - `/<skill-name>` - Description of what the skill does
   
   ### Technologies Without Tiles
   
   - <technology>: No tile found in registry
   

5. If no tiles found for a technology:

   • Note in research.md: "No Tessl tile available for "
   • Continue without tile for that technology

3.5 Query Installed Documentation Tiles for Best Practices

For each installed documentation tile, query for best practices:

mcp__tessl__query_library_docs(query="best practices for <library>")

Incorporate findings into research.md decisions section.

3.6 Catalog Installed Skill Tiles

List all available skills from installed tiles:

• Record skill name and purpose
• Note in research.md: "Available skills: /, /, ..."
• Skills become available for use in subsequent phases (especially /speckit-08-implement)

3.7 Handle Failures Gracefully

• Network issues: Log warning, continue without affected tiles
• Registry unavailable: Log warning, continue without tiles
• Authentication required: Prompt user to run tessl login, continue without tiles
• Search returns no results: Note in research.md, continue

4. Phase 0: Outline & Research (includes Tessl findings)

1. Extract unknowns from Technical Context:

   • For each NEEDS CLARIFICATION -> research task
   • For each dependency -> best practices task
   • For each integration -> patterns task

2. Research each unknown and document findings

3. Consolidate findings in research.md:

   • Decision: [what was chosen]
   • Rationale: [why chosen]
   • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved (includes Tessl Tiles section if Tessl available)

5. Phase 1: Design & Contracts

Prerequisites: research.md complete

1. Extract entities from feature spec -> data-model.md:

   • Entity name, fields, relationships
   • Validation rules from requirements
   • State transitions if applicable

2. Generate API contracts from functional requirements:

   • For each user action -> endpoint
   • Use standard REST/GraphQL patterns
   • Output OpenAPI/GraphQL schema to /contracts/

3. Create quickstart.md with test scenarios

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

   Unix/macOS/Linux:

   .claude/skills/speckit-core/scripts/bash/update-agent-context.sh claude
   

   Windows (PowerShell):

   pwsh .claude/skills/speckit-core/scripts/powershell/update-agent-context.ps1 -AgentType claude
   

   This updates CLAUDE.md with the new technology stack using the agent-file-template.md.

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

6. 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

7. 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:
   • STOP immediately
   • State: "CONSTITUTION VIOLATION: [Principle Name]"
   • Explain: What specifically violates the principle
   • Suggest: Compliant alternative approach
3. 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 (includes Tessl Tiles section if Tessl available)
  • data-model.md
  • contracts/*
  • quickstart.md
• Agent file update status
• Tessl integration status:
  • Tiles installed (with versions)
  • Skills available for implementation phase
  • Technologies without tiles

Semantic Diff on Re-run

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:

   • Language/Version
   • Primary Dependencies
   • Storage choice
   • Project structure decisions

2. 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 (arch change)       │
   │  ⚠ contracts/ need updates (API change)             │
   │  ⚠ data-model.md may need updates                   │
   ╰─────────────────────────────────────────────────────╯
   

3. Flag breaking changes:

   • Language change → ALL tasks affected
   • Framework change → Most tasks affected
   • 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-06-tasks (REQUIRED - architecture changed)
- /speckit-07-analyze (RECOMMENDED - verify consistency)

Next Steps

After completing the plan:

1. Recommended: Run /speckit-04-checklist to create domain-specific quality checklists

   • Generates "unit tests for English" to validate requirements quality
   • Helps catch requirement gaps before implementation
   • Required to reach 100% before /speckit-08-implement

2. Required: Run /speckit-06-tasks to generate the task breakdown

Suggest to user:

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