Skip to content

plan-template.md

Latest commit

 

History

History
272 lines (211 loc) · 10.7 KB

plan-template.md

File metadata and controls

272 lines (211 loc) · 10.7 KB

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 file system structure or context (web=frontend+backend, mobile=app+API) → Set Structure Decision based on project type
  3. Fill the Constitution Check section based on the content of the constitution document.
  4. Evaluate Constitution Check section below → If violations exist: Document them in Complexity Tracking → If no justification is possible: ERROR "Simplify approach first" → Update Progress Tracking: Initial Constitution Check
  5. Execute Phase 0 → research.md → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
  6. 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, GEMINI.md for Gemini CLI, QWEN.md for Qwen Code or AGENTS.md for opencode).
  7. Re-evaluate Constitution Check section → If new violations: Refactor design, return to Phase 1 → Update Progress Tracking: Post-Design Constitution Check
  8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
  9. 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

Aspect Details
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.

I. Workflow-First Design (NON-NEGOTIABLE)

  • Feature is implemented as reusable GitHub Actions workflow(s)
  • Workflows have clearly defined inputs and outputs
  • Workflows follow single responsibility principle
  • Matrix strategies used for parallel execution where appropriate
  • Workflows are independently testable via CI validation workflow
  • Logic delegated to reusable GitHub Actions (PSModule organization)
  • Inline PowerShell code avoided; action-based scripts used instead
  • Actions referenced by specific versions/tags

II. Test-Driven Development (NON-NEGOTIABLE)

  • Tests will be written before implementation
  • Initial tests will fail (Red phase documented)
  • Implementation plan includes making tests pass (Green phase)
  • Refactoring phase planned while maintaining tests
  • PSScriptAnalyzer validation included
  • Manual testing documented if needed
  • CI validation workflow tests included

III. Platform Independence with Modern PowerShell

  • PowerShell 7.4+ constructs used exclusively
  • Matrix testing across Linux, macOS, Windows included
  • Platform-specific behaviors documented
  • Skip mechanisms justified if platform-specific tests needed
  • No backward compatibility with PowerShell 5.1 required

IV. Quality Gates and Observability

  • Test results captured in structured JSON format
  • Code coverage measurement included
  • Linting results captured and enforced
  • Quality gate thresholds defined
  • Clear error messages planned
  • Debug mode support included

V. Continuous Delivery with Semantic Versioning

  • Version bump strategy documented (labels, SemVer)
  • Release automation compatible with existing workflow
  • Documentation updates included
  • GitHub Pages publishing considered if docs changes

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)

# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
src/
├── models/
├── services/
├── cli/
└── lib/

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

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

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

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

ios/ or android/
└── [platform-specific structure: feature modules, UI flows, platform tests]

Structure Decision: [Document the selected structure and reference the real directories captured above]

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. Generate contract tests from contracts:
    • One test file per endpoint
    • Assert request/response schemas
    • Tests must fail (no implementation yet)
  4. Extract test scenarios from user stories:
    • Each story → integration test scenario
    • Quickstart test = story validation steps
  5. Update agent file incrementally (O(1) operation):
    • Run .specify/scripts/powershell/update-agent-context.ps1 -AgentType copilot IMPORTANT: Execute it exactly as specified above. Do not add or remove any arguments.
    • 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 .specify/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 - See .specify/memory/constitution.md