plan-template.md Raw History Folder

Implementation Plan: [FEATURE]

Branch: [###-feature-name] | Date: [DATE] | Spec: [link] Input: Feature specification from /specs/[###-feature-name]/spec.md

Execution Flow (/plan command scope)

1. Load feature spec from Input path
   → If not found: ERROR "No feature spec at {path}"
2. Fill Technical Context (scan for NEEDS CLARIFICATION)
   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
   → Set Structure Decision based on project type
3. Evaluate Constitution Check section below
   → If violations exist: Document in Complexity Tracking
   → If no justification possible: ERROR "Simplify approach first"
   → Update Progress Tracking: Initial Constitution Check
4. Execute Phase 0 → research.md
   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
5. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
6. Re-evaluate Constitution Check section
   → If new violations: Refactor design, return to Phase 1
   → Update Progress Tracking: Post-Design Constitution Check
7. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
8. STOP - Ready for /tasks command

IMPORTANT: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:

Phase 2: /tasks command creates tasks.md
Phase 3-4: Implementation execution (manual or via tools)

Summary

[Extract from feature spec: primary requirement + technical approach from research]

Technical Context

Language/Version: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
Primary Dependencies: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
Storage: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
Testing: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
Target Platform: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION] Project Type: [single/web/mobile - determines source structure]
Performance Goals: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
Constraints: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
Scale/Scope: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Simplicity:

Projects: [#] (max 3 - e.g., api, cli, tests)
Using framework directly? (no wrapper classes)
Single data model? (no DTOs unless serialization differs)
Avoiding patterns? (no Repository/UoW without proven need)

Architecture:

EVERY feature as library? (no direct app code)
Libraries listed: [name + purpose for each]
CLI per library: [commands with --help/--version/--format]
Library docs: llms.txt format planned?

Testing (NON-NEGOTIABLE):

RED-GREEN-Refactor cycle enforced? (test MUST fail first)
Git commits show tests before implementation?
Order: Contract→Integration→E2E→Unit strictly followed?
Real dependencies used? (actual DBs, not mocks)
Integration tests for: new libraries, contract changes, shared schemas?
FORBIDDEN: Implementation before test, skipping RED phase

Observability:

Structured logging included?
Frontend logs → backend? (unified stream)
Error context sufficient?

Versioning:

Version number assigned? (MAJOR.MINOR.BUILD)
BUILD increments on every change?
Breaking changes handled? (parallel tests, migration plan)

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/plan command output)
├── research.md          # Phase 0 output (/plan command)
├── data-model.md        # Phase 1 output (/plan command)
├── quickstart.md        # Phase 1 output (/plan command)
├── contracts/           # Phase 1 output (/plan command)
└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)

Source Code (repository root)

# Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

tests/
├── contract/
├── integration/
└── unit/

# Option 2: Web application (when "frontend" + "backend" detected)
backend/
├── src/
│   ├── models/
│   ├── services/
│   └── api/
└── tests/

frontend/
├── src/
│   ├── components/
│   ├── pages/
│   └── services/
└── tests/

# Option 3: Mobile + API (when "iOS/Android" detected)
api/
└── [same as backend above]

ios/ or android/
└── [platform-specific structure]

Structure Decision: [DEFAULT to Option 1 unless Technical Context indicates web/mobile app]

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
Generate API contracts from functional requirements:
- For each user action → endpoint
- Use standard REST/GraphQL patterns
- Output OpenAPI/GraphQL schema to /contracts/
Generate contract tests from contracts:
- One test file per endpoint
- Assert request/response schemas
- Tests must fail (no implementation yet)
Extract test scenarios from user stories:
- Each story → integration test scenario
- Quickstart test = story validation steps
Update agent file incrementally (O(1) operation):
- Run /scripts/update-agent-context.sh [claude|gemini|copilot] for your AI assistant
- If exists: Add only NEW tech from current plan
- Preserve manual additions between markers
- Update recent changes (keep last 3)
- Keep under 150 lines for token efficiency
- Output to repository root

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

Phase 2: Task Planning Approach

This section describes what the /tasks command will do - DO NOT execute during /plan

Task Generation Strategy:

Load /templates/tasks-template.md as base
Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
Each contract → contract test task [P]
Each entity → model creation task [P]
Each user story → integration test task
Implementation tasks to make tests pass

Ordering Strategy:

TDD order: Tests before implementation
Dependency order: Models before services before UI
Mark [P] for parallel execution (independent files)

Estimated Output: 25-30 numbered, ordered tasks in tasks.md

IMPORTANT: This phase is executed by the /tasks command, NOT by /plan

Phase 3+: Future Implementation

These phases are beyond the scope of the /plan command

Phase 3: Task execution (/tasks command creates tasks.md)
Phase 4: Implementation (execute tasks.md following constitutional principles)
Phase 5: Validation (run tests, execute quickstart.md, performance validation)

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

Progress Tracking

This checklist is updated during execution flow

Phase Status:

Phase 0: Research complete (/plan command)
Phase 1: Design complete (/plan command)
Phase 2: Task planning complete (/plan command - describe approach only)
Phase 3: Tasks generated (/tasks command)
Phase 4: Implementation complete
Phase 5: Validation passed

Gate Status:

Initial Constitution Check: PASS
Post-Design Constitution Check: PASS
All NEEDS CLARIFICATION resolved
Complexity deviations documented

Based on Constitution v2.1.1 - See /memory/constitution.md

source

1# Implementation Plan: [FEATURE]
2
3**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
4**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
5
6## Execution Flow (/plan command scope)
7```
81. Load feature spec from Input path
9   → If not found: ERROR "No feature spec at {path}"
102. Fill Technical Context (scan for NEEDS CLARIFICATION)
11   → Detect Project Type from context (web=frontend+backend, mobile=app+api)
12   → Set Structure Decision based on project type
133. Evaluate Constitution Check section below
14   → If violations exist: Document in Complexity Tracking
15   → If no justification possible: ERROR "Simplify approach first"
16   → Update Progress Tracking: Initial Constitution Check
174. Execute Phase 0 → research.md
18   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
195. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, or `GEMINI.md` for Gemini CLI).
206. Re-evaluate Constitution Check section
21   → If new violations: Refactor design, return to Phase 1
22   → Update Progress Tracking: Post-Design Constitution Check
237. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
248. STOP - Ready for /tasks command
25```
26
27**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
28- Phase 2: /tasks command creates tasks.md
29- Phase 3-4: Implementation execution (manual or via tools)
30
31## Summary
32[Extract from feature spec: primary requirement + technical approach from research]
33
34## Technical Context
35**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
36**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
37**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
38**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
39**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
40**Project Type**: [single/web/mobile - determines source structure]  
41**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
42**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
43**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
44
45## Constitution Check
46*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
47
48**Simplicity**:
49- Projects: [#] (max 3 - e.g., api, cli, tests)
50- Using framework directly? (no wrapper classes)
51- Single data model? (no DTOs unless serialization differs)
52- Avoiding patterns? (no Repository/UoW without proven need)
53
54**Architecture**:
55- EVERY feature as library? (no direct app code)
56- Libraries listed: [name + purpose for each]
57- CLI per library: [commands with --help/--version/--format]
58- Library docs: llms.txt format planned?
59
60**Testing (NON-NEGOTIABLE)**:
61- RED-GREEN-Refactor cycle enforced? (test MUST fail first)
62- Git commits show tests before implementation?
63- Order: Contract→Integration→E2E→Unit strictly followed?
64- Real dependencies used? (actual DBs, not mocks)
65- Integration tests for: new libraries, contract changes, shared schemas?
66- FORBIDDEN: Implementation before test, skipping RED phase
67
68**Observability**:
69- Structured logging included?
70- Frontend logs → backend? (unified stream)
71- Error context sufficient?
72
73**Versioning**:
74- Version number assigned? (MAJOR.MINOR.BUILD)
75- BUILD increments on every change?
76- Breaking changes handled? (parallel tests, migration plan)
77
78## Project Structure
79
80### Documentation (this feature)
81```
82specs/[###-feature]/
83├── plan.md              # This file (/plan command output)
84├── research.md          # Phase 0 output (/plan command)
85├── data-model.md        # Phase 1 output (/plan command)
86├── quickstart.md        # Phase 1 output (/plan command)
87├── contracts/           # Phase 1 output (/plan command)
88└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
89```
90
91### Source Code (repository root)
92```
93# Option 1: Single project (DEFAULT)
94src/
95├── models/
96├── services/
97├── cli/
98└── lib/
99
100tests/
101├── contract/
102├── integration/
103└── unit/
104
105# Option 2: Web application (when "frontend" + "backend" detected)
106backend/
107├── src/
108│   ├── models/
109│   ├── services/
110│   └── api/
111└── tests/
112
113frontend/
114├── src/
115│   ├── components/
116│   ├── pages/
117│   └── services/
118└── tests/
119
120# Option 3: Mobile + API (when "iOS/Android" detected)
121api/
122└── [same as backend above]
123
124ios/ or android/
125└── [platform-specific structure]
126```
127
128**Structure Decision**: [DEFAULT to Option 1 unless Technical Context indicates web/mobile app]
129
130## Phase 0: Outline & Research
1311. **Extract unknowns from Technical Context** above:
132   - For each NEEDS CLARIFICATION → research task
133   - For each dependency → best practices task
134   - For each integration → patterns task
135
1362. **Generate and dispatch research agents**:
137   ```
138   For each unknown in Technical Context:
139     Task: "Research {unknown} for {feature context}"
140   For each technology choice:
141     Task: "Find best practices for {tech} in {domain}"
142   ```
143
1443. **Consolidate findings** in `research.md` using format:
145   - Decision: [what was chosen]
146   - Rationale: [why chosen]
147   - Alternatives considered: [what else evaluated]
148
149**Output**: research.md with all NEEDS CLARIFICATION resolved
150
151## Phase 1: Design & Contracts
152*Prerequisites: research.md complete*
153
1541. **Extract entities from feature spec** → `data-model.md`:
155   - Entity name, fields, relationships
156   - Validation rules from requirements
157   - State transitions if applicable
158
1592. **Generate API contracts** from functional requirements:
160   - For each user action → endpoint
161   - Use standard REST/GraphQL patterns
162   - Output OpenAPI/GraphQL schema to `/contracts/`
163
1643. **Generate contract tests** from contracts:
165   - One test file per endpoint
166   - Assert request/response schemas
167   - Tests must fail (no implementation yet)
168
1694. **Extract test scenarios** from user stories:
170   - Each story → integration test scenario
171   - Quickstart test = story validation steps
172
1735. **Update agent file incrementally** (O(1) operation):
174   - Run `/scripts/update-agent-context.sh [claude|gemini|copilot]` for your AI assistant
175   - If exists: Add only NEW tech from current plan
176   - Preserve manual additions between markers
177   - Update recent changes (keep last 3)
178   - Keep under 150 lines for token efficiency
179   - Output to repository root
180
181**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
182
183## Phase 2: Task Planning Approach
184*This section describes what the /tasks command will do - DO NOT execute during /plan*
185
186**Task Generation Strategy**:
187- Load `/templates/tasks-template.md` as base
188- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
189- Each contract → contract test task [P]
190- Each entity → model creation task [P] 
191- Each user story → integration test task
192- Implementation tasks to make tests pass
193
194**Ordering Strategy**:
195- TDD order: Tests before implementation 
196- Dependency order: Models before services before UI
197- Mark [P] for parallel execution (independent files)
198
199**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
200
201**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
202
203## Phase 3+: Future Implementation
204*These phases are beyond the scope of the /plan command*
205
206**Phase 3**: Task execution (/tasks command creates tasks.md)  
207**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
208**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
209
210## Complexity Tracking
211*Fill ONLY if Constitution Check has violations that must be justified*
212
213| Violation | Why Needed | Simpler Alternative Rejected Because |
214|-----------|------------|-------------------------------------|
215| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
216| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
217
218
219## Progress Tracking
220*This checklist is updated during execution flow*
221
222**Phase Status**:
223- [ ] Phase 0: Research complete (/plan command)
224- [ ] Phase 1: Design complete (/plan command)
225- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
226- [ ] Phase 3: Tasks generated (/tasks command)
227- [ ] Phase 4: Implementation complete
228- [ ] Phase 5: Validation passed
229
230**Gate Status**:
231- [ ] Initial Constitution Check: PASS
232- [ ] Post-Design Constitution Check: PASS
233- [ ] All NEEDS CLARIFICATION resolved
234- [ ] Complexity deviations documented
235
236---
237*Based on Constitution v2.1.1 - See `/memory/constitution.md`*

plan-template.md RawHistoryFolder