name: speckit-plan
description: Execute implementation planning workflow using the plan template to generate design artifacts

Speckit-Plan: Technical Implementation Planning

Purpose

Create technical implementation plan that describes HOW to build the feature defined in the specification, including architecture, technology choices, data models, and API contracts.

Prerequisites

• Completed specification (spec.md exists)
• Project constitution loaded (.specify/memory/constitution.md)

What This Skill Does

1. Loads specification and project context
2. Researches technical approaches and best practices
3. Designs system architecture and technology stack
4. Creates data models and API contracts
5. Documents technology choices with rationale
6. Generates integration scenarios (quickstart)
7. Updates agent context with new technologies

Key Principles

Specification is Immutable

• Don't change WHAT while designing HOW
• Technical decisions must serve specification requirements
• If spec gaps found, note them but don't modify spec

Constitution Authority

• Project constitution principles are non-negotiable
• Validate all choices against constitution
• Document compliance in Constitution Check section

Design Before Tasks

• Complete all design artifacts before task generation
• Data models, contracts, and research must be finished
• Provides foundation for accurate task breakdown

Template Location

IMPORTANT: The plan template is located at:
.github/skills/speckit-plan/plan-template.md

This template MUST be loaded and used as the base structure for all technical planning.

Execution Flow

All execution logic is now contained within this skill. The skill handles:
- Setup script execution
- Context loading
- Planning workflow execution
- Artifact generation

Quick Summary

1. Setup: Run setup-plan.sh to get feature paths
2. Load template from .github/skills/speckit-plan/plan-template.md
3. Load context: Read spec.md and constitution.md
4. Execute planning workflow:
5. Phase 0: Research & Outline
   • Identify unknowns and research needs
   • Dispatch research agents for each unknown
   • Consolidate findings in research.md
6. Phase 1: Design & Contracts
   • Extract entities → data-model.md
   • Generate API contracts → contracts/
   • Create integration scenarios → quickstart.md
   • Update agent context (copilot-specific files)
7. Constitution check: Validate design against principles
8. Report completion: List all generated artifacts

Phase 0: Research & Outline

Goal: Resolve all technical unknowns before design

What Happens

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. Dispatch research agents:

6. "Research {unknown} for {feature context}"

7. "Find best practices for {tech} in {domain}"

8. Consolidate findings in research.md:
   ```markdown
   ## Decision: [what was chosen]

Rationale: [why chosen]

Alternatives Considered:
- Option A: [pros/cons]
- Option B: [pros/cons]

Selected: Option A because...
```

Output: research.md with all unknowns resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

What Happens

1. Data Model (data-model.md):
2. Extract entities from specification
3. Define fields, types, relationships
4. Document validation rules

5. Describe state transitions

6. API Contracts (contracts/):

7. For each user action → endpoint
8. Use standard REST/GraphQL patterns
9. Generate OpenAPI or GraphQL schema

10. Include request/response examples

11. Quickstart (quickstart.md):

12. End-to-end integration scenarios
13. Setup instructions
14. Sample requests/responses

15. Common troubleshooting

16. Agent Context Update:

17. Run update-agent-context.sh copilot
18. Add new technologies from plan
19. Preserve manual additions between markers

Output:
- data-model.md
- contracts/*.yaml (OpenAPI/GraphQL)
- quickstart.md
- Updated agent context files

Constitution Check

Validate design against project principles:

1. Load constitution from .specify/memory/constitution.md
2. Check each principle:
3. Does design violate any MUST rules?
4. Are SHOULD rules followed or justified?
5. Document compliance in Constitution Check section
6. ERROR if violations unjustified

Success Indicators

Plan is ready when:
- ✅ All research decisions documented with rationale
- ✅ Data model covers all entities from specification
- ✅ API contracts map to all user actions
- ✅ Quickstart provides working integration example
- ✅ Constitution check passes (or violations justified)
- ✅ Agent context updated with new technologies
- ✅ No NEEDS CLARIFICATION markers remain

Output

specs/N-feature-name/
├── plan.md                    # Technical implementation plan (HOW)
├── data-model.md              # Entity definitions and relationships
├── research.md                # Technical decisions and rationale
├── quickstart.md              # Integration scenarios
└── contracts/                 # API specifications
    ├── openapi.yaml
    └── schema.graphql

Next Step

After plan is complete:
- Use speckit-tasks to generate task breakdown

Common Mistakes

❌ Changing Specification During Planning

Wrong: "Spec says OAuth2, but I'll use API keys instead" (changing WHAT)
Right: "Spec requires OAuth2, planning OAuth2 implementation" (serving WHAT)

❌ Ignoring Constitution

Wrong: Skip constitution check, violate principles
Right: Validate against constitution, justify any exceptions

❌ Incomplete Research

Wrong: Jump to design with unresolved unknowns
Right: Research all unknowns first, document decisions

❌ Vague Data Models

Wrong: "User entity has some fields"
Right: "User entity: id (UUID), email (string, unique), createdAt (timestamp)"

❌ Missing Contracts

Wrong: "We'll figure out API structure during implementation"
Right: Complete OpenAPI spec with all endpoints, schemas, examples

Related Skills

• speckit-specify - Previous step (create specification)
• speckit-tasks - Next step (generate task breakdown)
• speckit-checklist - Generate domain-specific quality checks