diff --git a/templates/plan-template.md b/templates/plan-template.md index ee57c35656..4b338e4163 100644 --- a/templates/plan-template.md +++ b/templates/plan-template.md @@ -1,104 +1,61 @@ # Implementation Plan: [FEATURE] **Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] -**Input**: Feature specification from `/specs/[###-feature-name]/spec.md` - -**Note**: This template is filled in by the `__SPECKIT_COMMAND_PLAN__` command. See `.specify/templates/plan-template.md` for the execution workflow. +**Input**: `/specs/[###-feature-name]/spec.md` ## Summary -[Extract from feature spec: primary requirement + technical approach from research] +[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**: [e.g., library/cli/web-service/mobile-app/compiler/desktop-app or NEEDS CLARIFICATION] -**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] +- **Language/Version**: [e.g., Python 3.11] · or `NEEDS CLARIFICATION` +- **Primary Dependencies**: [e.g., FastAPI] +- **Storage**: [e.g., PostgreSQL, N/A] +- **Testing**: [e.g., pytest] +- **Target Platform**: [e.g., Linux server] +- **Project Type**: [library / cli / web-service / mobile-app / desktop-app] +- **Performance Goals**: [e.g., 1000 req/s p95 < 200ms] +- **Constraints**: [e.g., <100MB memory, offline-capable] +- **Scale/Scope**: [e.g., 10k users, 1M LOC] ## Constitution Check -*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* - -[Gates determined based on constitution file] +Gates derived from `.specify/memory/constitution.md`. MUST pass before Phase 0 and re-pass after Phase 1 design. ## Project Structure -### Documentation (this feature) - ```text specs/[###-feature]/ -├── plan.md # This file (__SPECKIT_COMMAND_PLAN__ command output) -├── research.md # Phase 0 output (__SPECKIT_COMMAND_PLAN__ command) -├── data-model.md # Phase 1 output (__SPECKIT_COMMAND_PLAN__ command) -├── quickstart.md # Phase 1 output (__SPECKIT_COMMAND_PLAN__ command) -├── contracts/ # Phase 1 output (__SPECKIT_COMMAND_PLAN__ command) -└── tasks.md # Phase 2 output (__SPECKIT_COMMAND_TASKS__ command - NOT created by __SPECKIT_COMMAND_PLAN__) +├── plan.md # this file +├── research.md # Phase 0 +├── data-model.md # Phase 1 +├── quickstart.md # Phase 1 +├── contracts/ # Phase 1 +└── tasks.md # Phase 2 (created by __SPECKIT_COMMAND_TASKS__) ``` -### Source Code (repository root) - +Source layout — pick one, delete the rest, populate with real paths: ```text -# [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] +# Single project +src/{models,services,cli,lib}/ tests/{contract,integration,unit}/ + +# Web app +backend/src/{models,services,api}/ backend/tests/ +frontend/src/{components,pages,services}/ frontend/tests/ + +# Mobile + API +api/{same as backend} +ios/ or android/{feature modules, UI flows, platform tests} ``` -**Structure Decision**: [Document the selected structure and reference the real -directories captured above] +**Structure Decision**: [chosen layout + real paths] ## Complexity Tracking -> **Fill ONLY if Constitution Check has violations that must be justified** +*Fill ONLY if Constitution Check has violations needing justification.* -| Violation | Why Needed | Simpler Alternative Rejected Because | -|-----------|------------|-------------------------------------| +| 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] | diff --git a/templates/spec-template.md b/templates/spec-template.md index 4581e40529..a2bf5ed183 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -1,128 +1,59 @@ # Feature Specification: [FEATURE NAME] -**Feature Branch**: `[###-feature-name]` -**Created**: [DATE] -**Status**: Draft -**Input**: User description: "$ARGUMENTS" +**Feature Branch**: `[###-feature-name]` +**Created**: [DATE] +**Status**: Draft +**Input**: `$ARGUMENTS` -## User Scenarios & Testing *(mandatory)* +## User Scenarios & Testing - +Each story is a standalone slice — can be developed, tested, and shipped independently. Priorities order delivery (P1 = MVP). -### User Story 1 - [Brief Title] (Priority: P1) +### User Story 1 — [Title] (P1) -[Describe this user journey in plain language] +[One sentence describing the journey.] -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] -2. **Given** [initial state], **When** [action], **Then** [expected outcome] +**Acceptance**: +1. **Given** [state], **When** [action], **Then** [outcome] +2. **Given** [state], **When** [action], **Then** [outcome] --- -### User Story 2 - [Brief Title] (Priority: P2) - -[Describe this user journey in plain language] - -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently] +### User Story 2 — [Title] (P2) -**Acceptance Scenarios**: +[One sentence.] -1. **Given** [initial state], **When** [action], **Then** [expected outcome] +**Acceptance**: +1. **Given** [state], **When** [action], **Then** [outcome] --- -### User Story 3 - [Brief Title] (Priority: P3) - -[Describe this user journey in plain language] - -**Why this priority**: [Explain the value and why it has this priority level] - -**Independent Test**: [Describe how this can be tested independently] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -[Add more user stories as needed, each with an assigned priority] - ### Edge Cases - - -- What happens when [boundary condition]? -- How does system handle [error scenario]? +- What happens when [boundary]? +- How does the system handle [error]? -## Requirements *(mandatory)* +## Requirements - +### Functional -### Functional Requirements +- **FR-001**: System MUST [capability] +- **FR-002**: System MUST [capability] +- **FR-003**: Users MUST be able to [interaction] -- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"] -- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"] -- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"] -- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"] -- **FR-005**: System MUST [behavior, e.g., "log all security events"] +Mark unclear items inline: `[NEEDS CLARIFICATION: ]` (max 3). -*Example of marking unclear requirements:* +### Key Entities *(if data is involved)* -- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?] -- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified] +- **[Entity]**: [what it represents, key attributes] -### Key Entities *(include if feature involves data)* +## Success Criteria -- **[Entity 1]**: [What it represents, key attributes without implementation] -- **[Entity 2]**: [What it represents, relationships to other entities] - -## Success Criteria *(mandatory)* - - - -### Measurable Outcomes - -- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"] -- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"] -- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"] -- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"] +- **SC-001**: [Measurable outcome, tech-agnostic — e.g., "Users complete checkout in <3 min"] +- **SC-002**: [Measurable outcome] +- **SC-003**: [User or business metric] ## Assumptions - - -- [Assumption about target users, e.g., "Users have stable internet connectivity"] -- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"] -- [Assumption about data/environment, e.g., "Existing authentication system will be reused"] -- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"] +- [Reasonable default the feature description didn't specify] +- [Scope boundary — e.g., "Mobile out of scope for v1"] diff --git a/templates/tasks-template.md b/templates/tasks-template.md index cc649380b9..c6e6a5d8e2 100644 --- a/templates/tasks-template.md +++ b/templates/tasks-template.md @@ -5,247 +5,80 @@ description: "Task list template for feature implementation" # Tasks: [FEATURE NAME] -**Input**: Design documents from `/specs/[###-feature-name]/` -**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ +**Input**: `/specs/[###-feature-name]/` — plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md (optional) -**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification. +**Tests**: OPTIONAL. Only generate test tasks if explicitly requested. -**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story. +**Organization**: tasks grouped by user story so each story ships independently. -## Format: `[ID] [P?] [Story] Description` +## Format -- **[P]**: Can run in parallel (different files, no dependencies) -- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3) -- Include exact file paths in descriptions +`- [ ] [TaskID] [P?] [Story?] Description with exact file path` -## Path Conventions +- `[P]` — parallelizable (different files, no blocking deps) +- `[US1]|[US2]|…` — required for user-story phase tasks; omit for setup/foundational/polish +- Sequential IDs: T001, T002, … -- **Single project**: `src/`, `tests/` at repository root -- **Web app**: `backend/src/`, `frontend/src/` -- **Mobile**: `api/src/`, `ios/src/` or `android/src/` -- Paths shown below assume single project - adjust based on plan.md structure +## Paths - +- Single project: `src/`, `tests/` at repo root +- Web: `backend/src/`, `frontend/src/` +- Mobile: `api/src/`, `ios/src/` or `android/src/` -## Phase 1: Setup (Shared Infrastructure) +Adjust based on `plan.md`'s Structure Decision. -**Purpose**: Project initialization and basic structure + -- [ ] T001 Create project structure per implementation plan -- [ ] T002 Initialize [language] project with [framework] dependencies -- [ ] T003 [P] Configure linting and formatting tools +## Phase 1: Setup ---- - -## Phase 2: Foundational (Blocking Prerequisites) - -**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented - -**⚠️ CRITICAL**: No user story work can begin until this phase is complete - -Examples of foundational tasks (adjust based on your project): - -- [ ] T004 Setup database schema and migrations framework -- [ ] T005 [P] Implement authentication/authorization framework -- [ ] T006 [P] Setup API routing and middleware structure -- [ ] T007 Create base models/entities that all stories depend on -- [ ] T008 Configure error handling and logging infrastructure -- [ ] T009 Setup environment configuration management - -**Checkpoint**: Foundation ready - user story implementation can now begin in parallel - ---- - -## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP - -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️ - -> **NOTE: Write these tests FIRST, ensure they FAIL before implementation** - -- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 1 - -- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py -- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py -- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013) -- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T016 [US1] Add validation and error handling -- [ ] T017 [US1] Add logging for user story 1 operations - -**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently - ---- - -## Phase 4: User Story 2 - [Title] (Priority: P2) - -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️ - -- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 2 - -- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py -- [ ] T021 [US2] Implement [Service] in src/services/[service].py -- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py -- [ ] T023 [US2] Integrate with User Story 1 components (if needed) - -**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently +- [ ] T001 Create project structure per plan +- [ ] T002 Initialize [language] project with [framework] +- [ ] T003 [P] Configure linting / formatting --- -## Phase 5: User Story 3 - [Title] (Priority: P3) +## Phase 2: Foundational (blocks all stories) -**Goal**: [Brief description of what this story delivers] - -**Independent Test**: [How to verify this story works on its own] - -### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️ - -- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py -- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py - -### Implementation for User Story 3 - -- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py -- [ ] T027 [US3] Implement [Service] in src/services/[service].py -- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py - -**Checkpoint**: All user stories should now be independently functional - ---- - -[Add more user story phases as needed, following the same pattern] - ---- - -## Phase N: Polish & Cross-Cutting Concerns - -**Purpose**: Improvements that affect multiple user stories - -- [ ] TXXX [P] Documentation updates in docs/ -- [ ] TXXX Code cleanup and refactoring -- [ ] TXXX Performance optimization across all stories -- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/ -- [ ] TXXX Security hardening -- [ ] TXXX Run quickstart.md validation +- [ ] T004 Setup database schema + migrations framework +- [ ] T005 [P] Auth/authorization framework +- [ ] T006 [P] API routing + middleware +- [ ] T007 Base models all stories depend on --- -## Dependencies & Execution Order +## Phase 3: User Story 1 — [Title] (P1) — MVP -### Phase Dependencies +**Independent test**: [how to verify this story alone] -- **Setup (Phase 1)**: No dependencies - can start immediately -- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories -- **User Stories (Phase 3+)**: All depend on Foundational phase completion - - User stories can then proceed in parallel (if staffed) - - Or sequentially in priority order (P1 → P2 → P3) -- **Polish (Final Phase)**: Depends on all desired user stories being complete +- [ ] T010 [P] [US1] Tests for US1 *(if requested)* in `tests/.../` +- [ ] T012 [P] [US1] Create `[Entity]` model in `src/models/[entity].py` +- [ ] T014 [US1] Implement `[Service]` in `src/services/[service].py` (depends on T012) +- [ ] T015 [US1] Implement endpoint / feature in `src/[location]/[file].py` +- [ ] T016 [US1] Validation + error handling -### User Story Dependencies - -- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories -- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable -- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable - -### Within Each User Story - -- Tests (if included) MUST be written and FAIL before implementation -- Models before services -- Services before endpoints -- Core implementation before integration -- Story complete before moving to next priority - -### Parallel Opportunities - -- All Setup tasks marked [P] can run in parallel -- All Foundational tasks marked [P] can run in parallel (within Phase 2) -- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows) -- All tests for a user story marked [P] can run in parallel -- Models within a story marked [P] can run in parallel -- Different user stories can be worked on in parallel by different team members - ---- - -## Parallel Example: User Story 1 - -```bash -# Launch all tests for User Story 1 together (if tests requested): -Task: "Contract test for [endpoint] in tests/contract/test_[name].py" -Task: "Integration test for [user journey] in tests/integration/test_[name].py" - -# Launch all models for User Story 1 together: -Task: "Create [Entity1] model in src/models/[entity1].py" -Task: "Create [Entity2] model in src/models/[entity2].py" -``` +**Checkpoint**: US1 fully functional and testable. --- -## Implementation Strategy - -### MVP First (User Story 1 Only) +## Phase 4+: Additional user stories (P2, P3, …) -1. Complete Phase 1: Setup -2. Complete Phase 2: Foundational (CRITICAL - blocks all stories) -3. Complete Phase 3: User Story 1 -4. **STOP and VALIDATE**: Test User Story 1 independently -5. Deploy/demo if ready +Repeat the Phase 3 pattern: one phase per story, each with `[USx]` label, each a self-contained slice. -### Incremental Delivery +## Phase N: Polish -1. Complete Setup + Foundational → Foundation ready -2. Add User Story 1 → Test independently → Deploy/Demo (MVP!) -3. Add User Story 2 → Test independently → Deploy/Demo -4. Add User Story 3 → Test independently → Deploy/Demo -5. Each story adds value without breaking previous stories +- [ ] TXXX [P] Documentation in `docs/` +- [ ] TXXX Performance + security pass +- [ ] TXXX Run `quickstart.md` smoke test -### Parallel Team Strategy +## Dependencies -With multiple developers: - -1. Team completes Setup + Foundational together -2. Once Foundational is done: - - Developer A: User Story 1 - - Developer B: User Story 2 - - Developer C: User Story 3 -3. Stories complete and integrate independently - ---- +- Setup → Foundational → Stories (any order or parallel) → Polish. +- Tests (if included) must FAIL before implementation. +- Models → services → endpoints within a story. ## Notes -- [P] tasks = different files, no dependencies -- [Story] label maps task to specific user story for traceability -- Each user story should be independently completable and testable -- Verify tests fail before implementing -- Commit after each task or logical group -- Stop at any checkpoint to validate story independently -- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence +- `[P]` = different files, no deps. Same-file tasks are serial. +- `[US#]` maps to spec.md story IDs for traceability. +- Commit after each task or logical group. +- Stop at any checkpoint to validate a story independently.