Speckit.Plan

---
description: Execute the implementation planning workflow using the plan template to generate design artifacts.
handoffs: 
  - label: Create Tasks
    agent: speckit.tasks
    prompt: Break the plan into tasks
    send: true
  - label: Create Checklist
    agent: speckit.checklist
    prompt: Create a checklist for the following domain...
---

## User Input

```text
$ARGUMENTS

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

Outline

1. Setup: Run pwsh -ExecutionPolicy Bypass -File .specify/scripts/powershell/setup-plan.ps1 -Json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use PowerShell escape syntax: double the quote inside single-quoted strings (e.g., 'I''m Groot') or use double quotes (e.g., "I'm Groot").

2. Load context: Read FEATURE_SPEC and .specify/memory/constitution.md. Load IMPL_PLAN template (already copied by Setup step).

3. 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
   • Phase 1: Update agent context by running the agent script
   • Re-evaluate Constitution Check post-design

4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

1. Extract unknowns from Technical Context above:

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

2. 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}"
   

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

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. Agent context update:

   • Run .specify/scripts/powershell/update-agent-context.ps1 -AgentType qwen
   • These scripts detect which AI agent is in use
   • Update the appropriate agent-specific context file
   • Add only new technology from current plan
   • Preserve manual additions between markers

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

Patterns: Best Practices for Implementation Planning

Pattern 1: Explicit Clarification Tracking

Objective: Prevent proceeding with incomplete or ambiguous information that could lead to implementation failures.

Context of application: Apply during Technical Context gathering (Step 3) and throughout all phases when encountering undefined requirements, unclear dependencies, or ambiguous specifications.

Key characteristics:

• Unknowns are explicitly marked with "NEEDS CLARIFICATION" rather than making assumptions
• Each clarification item is tracked through to resolution in Phase 0
• Gate evaluation blocks progress until all clarifications are resolved

Operational guidance:

1. During Technical Context analysis, flag every uncertainty with "NEEDS CLARIFICATION" tag
2. Document the specific question or unknown (not just "unclear")
3. Convert each flagged item into a discrete research task in Phase 0
4. Verify in research.md that each clarification has a documented decision and rationale
5. Re-check Technical Context to ensure all "NEEDS CLARIFICATION" markers are removed before Phase 1

Pattern 2: Constitution-Driven Design Gates

Objective: Ensure architectural and design decisions align with project principles and constraints before committing to implementation.

Context of application: Use at constitution check evaluation (Step 3), after initial design, and post-design re-evaluation.

Key characteristics:

• Constitution is loaded as authoritative source for project constraints
• Violations trigger ERROR state rather than warnings
• Gates require justification for any deviations
• Post-design re-evaluation catches drift introduced during artifact generation

Operational guidance:

1. Load .specify/memory/constitution.md at workflow start
2. Document each constitution principle that applies to current feature
3. For each design decision in Technical Context, explicitly check against applicable principles
4. If violation is necessary, document justification before proceeding
5. After Phase 1 artifact generation, re-run constitution check to catch emergent violations
6. Treat unjustified violations as blocking errors that halt the workflow

Pattern 3: Research-First Design Approach

Objective: Ground all design decisions in researched alternatives and documented rationale rather than assumptions or defaults.

Context of application: Apply in Phase 0 before any artifact generation, especially when selecting technologies, patterns, or architectural approaches.

Key characteristics:

• Every "NEEDS CLARIFICATION" generates a research task
• Research tasks explicitly evaluate alternatives
• Decisions are documented with rationale and rejected alternatives
• Technology choices include best practices research

Operational guidance:

1. Extr