π« Toolkit to help you get started with SDD or any other process!
Update template and docs
den (work)0037a3f48468
diff --git a/README.md b/README.mdindex 30d9c378e..80b8f7c70 100644--- a/README.md+++ b/README.md@@ -207,16 +207,28 @@ specify checkAfter running `specify init`, your AI coding agent will have access to these slash commands for structured development:+#### Core Commands++Essential commands for the Spec-Driven Development workflow:+| Command | Description ||-----------------|-----------------------------------------------------------------------|| `/constitution` | Create or update project governing principles and development guidelines || `/specify` | Define what you want to build (requirements and user stories) |-| `/clarify` | Clarify underspecified areas (must be run before `/plan` unless explicitly skipped; formerly `/quizme`) || `/plan` | Create technical implementation plans with your chosen tech stack || `/tasks` | Generate actionable task lists for implementation |-| `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) || `/implement` | Execute all tasks to build the feature according to the plan |+#### Optional Commands++Additional commands for enhanced quality and validation:++| Command | Description |+|-----------------|-----------------------------------------------------------------------|+| `/clarify` | Clarify underspecified areas (recommended before `/plan`; formerly `/quizme`) |+| `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) |+| `/checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |+### Environment Variables| Variable | Description |@@ -314,20 +326,18 @@ You will be prompted to select the AI agent you are using. You can also proactivspecify init <project_name> --ai claudespecify init <project_name> --ai geminispecify init <project_name> --ai copilot-specify init <project_name> --ai cursor-specify init <project_name> --ai qwen-specify init <project_name> --ai opencode-specify init <project_name> --ai codex-specify init <project_name> --ai windsurf-specify init <project_name> --ai q+# Or in current directory:specify init . --ai claudespecify init . --ai codex+# or use --here flagspecify init --here --ai claudespecify init --here --ai codex+# Force merge into a non-empty current directoryspecify init . --force --ai claude+# orspecify init --here --force --ai claude```diff --git a/templates/commands/tasks.md b/templates/commands/tasks.mdindex d6beea739..f2bafadcd 100644--- a/templates/commands/tasks.md+++ b/templates/commands/tasks.md@@ -18,37 +18,57 @@ You **MUST** consider the user input before proceeding (if not empty).1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.2. **Load design documents**: Read from FEATURE_DIR:- - **Required**: plan.md (tech stack, libraries, structure)+ - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)- **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)- Note: Not all projects have all documents. Generate tasks based on what's available.3. **Execute task generation workflow** (follow the template structure):- Load plan.md and extract tech stack, libraries, project structure- - If data-model.md exists: Extract entities β generate model tasks- - If contracts/ exists: Each file β generate endpoint/API tasks+ - **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**+ - If data-model.md exists: Extract entities β map to user stories+ - If contracts/ exists: Each file β map endpoints to user stories- If research.md exists: Extract decisions β generate setup tasks- - Generate tasks by category: Setup, Core Implementation, Integration, Polish+ - **Generate tasks ORGANIZED BY USER STORY**:+ - Setup tasks (shared infrastructure needed by all stories)+ - **Foundational tasks (prerequisites that must complete before ANY user story can start)**+ - For each user story (in priority order P1, P2, P3...):+ - Group all tasks needed to complete JUST that story+ - Include models, services, endpoints, UI components specific to that story+ - Mark which tasks are [P] parallelizable+ - If tests requested: Include tests specific to that story+ - Polish/Integration tasks (cross-cutting concerns)- **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach- Apply task rules:- * Different files = mark [P] for parallel- * Same file = sequential (no [P])- * If tests requested: Tests before implementation (TDD order)+ - Different files = mark [P] for parallel+ - Same file = sequential (no [P])+ - If tests requested: Tests before implementation (TDD order)- Number tasks sequentially (T001, T002...)- - Generate dependency graph- - Create parallel execution examples- - Validate task completeness (all entities have implementations, all endpoints covered)+ - Generate dependency graph showing user story completion order+ - Create parallel execution examples per user story+ - Validate task completeness (each user story has all needed tasks, independently testable)4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:- Correct feature name from plan.md- - Numbered tasks (T001, T002...) in dependency order+ - Phase 1: Setup tasks (project initialization)+ - Phase 2: Foundational tasks (blocking prerequisites for all user stories)+ - Phase 3+: One phase per user story (in priority order from spec.md)+ - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks+ - Clear [Story] labels (US1, US2, US3...) for each task+ - [P] markers for parallelizable tasks within each story+ - Checkpoint markers after each story phase+ - Final Phase: Polish & cross-cutting concerns+ - Numbered tasks (T001, T002...) in execution order- Clear file paths for each task- - [P] markers for parallelizable tasks- - Phase groupings based on what's needed (Setup, Core Implementation, Integration, Polish)- - If tests requested: Include separate "Tests First (TDD)" phase before Core Implementation- - Dependency notes+ - Dependencies section showing story completion order+ - Parallel execution examples per story+ - Implementation strategy section (MVP first, incremental delivery)-5. **Report**: Output path to generated tasks.md and summary of task counts by phase.- - Parallel execution guidance+5. **Report**: Output path to generated tasks.md and summary:+ - Total task count+ - Task count per user story+ - Parallel opportunities identified+ - Independent test criteria for each story+ - Suggested MVP scope (typically just User Story 1)Context for task generation: {ARGS}@@ -58,20 +78,38 @@ The tasks.md should be immediately executable - each task must be specific enoug**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.-1. **From Contracts**:- - Each contract/endpoint β implementation task- - If tests requested: Each contract β contract test task [P] before implementation+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.++1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:+ - Each user story (P1, P2, P3...) gets its own phase+ - Map all related components to their story:+ - Models needed for that story+ - Services needed for that story+ - Endpoints/UI needed for that story+ - If tests requested: Tests specific to that story+ - Mark story dependencies (most stories should be independent)++2. **From Contracts**:+ - Map each contract/endpoint β to the user story it serves+ - If tests requested: Each contract β contract test task [P] before implementation in that story's phase-2. **From Data Model**:- - Each entity β model creation task [P]- - Relationships β service layer tasks+3. **From Data Model**:+ - Map each entity β to the user story(ies) that need it+ - If entity serves multiple stories: Put in earliest story or Setup phase+ - Relationships β service layer tasks in appropriate story phase-3. **From User Stories**:- - Each story β implementation tasks- - If tests requested: Each story β integration test [P]- - If quickstart.md exists: Validation tasks--4. **Ordering**:- - Without tests: Setup β Models β Services β Endpoints β Integration β Polish- - With tests (TDD): Setup β Tests β Models β Services β Endpoints β Integration β Polish- - Dependencies block parallel execution\ No newline at end of file+4. **From Setup/Infrastructure**:+ - Shared infrastructure β Setup phase (Phase 1)+ - Foundational/blocking tasks β Foundational phase (Phase 2)+ - Examples: Database schema setup, authentication framework, core libraries, base configurations+ - These MUST complete before any user story can be implemented+ - Story-specific setup β within that story's phase++5. **Ordering**:+ - Phase 1: Setup (project initialization)+ - Phase 2: Foundational (blocking prerequisites - must complete before user stories)+ - Phase 3+: User Stories in priority order (P1, P2, P3...)+ - Within each story: Tests (if requested) β Models β Services β Endpoints β Integration+ - Final Phase: Polish & Cross-Cutting Concerns+ - Each user story phase should be a complete, independently testable increment+diff --git a/templates/spec-template.md b/templates/spec-template.mdindex db1d1878d..c67d91498 100644--- a/templates/spec-template.md+++ b/templates/spec-template.md@@ -7,20 +7,64 @@## User Scenarios & Testing *(mandatory)*-### Primary User Story+<!--+ IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.+ Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,+ you should still have a viable MVP (Minimum Viable Product) that delivers value.++ Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.+ Think of each story as a standalone slice of functionality that can be:+ - Developed independently+ - Tested independently+ - Deployed independently+ - Demonstrated to users independently+-->-[Describe the main user journey in plain language]+### User Story 1 - [Brief Title] (Priority: P1)-### Acceptance Scenarios+[Describe this user journey in plain language]-<!--- ACTION REQUIRED: The content in this section represents placeholders.- Fill them out with the right acceptance scenarios.--->+**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]+---++### 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]++**Acceptance Scenarios**:++1. **Given** [initial state], **When** [action], **Then** [expected 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<!--diff --git a/templates/tasks-template.md b/templates/tasks-template.mdindex 855335c5b..0e11d78a1 100644--- a/templates/tasks-template.md+++ b/templates/tasks-template.md@@ -5,12 +5,15 @@ description: "Task list template for feature implementation"# Tasks: [FEATURE NAME]**Input**: Design documents from `/specs/[###-feature-name]/`-**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.-## Format: `[ID] [P?] Description`+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.++## Format: `[ID] [P?] [Story] Description`- **[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## Path Conventions@@ -24,68 +27,291 @@ description: "Task list template for feature implementation"IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.The /tasks command MUST replace these with actual tasks based on:+ - User stories from spec.md (with their priorities P1, P2, P3...)- Feature requirements from plan.md- Entities from data-model.md- Endpoints from contracts/- - User stories from the feature spec++ Tasks MUST be organized by user story so each story can be:+ - Implemented independently+ - Tested independently+ - Delivered as an MVP incrementDO NOT keep these sample tasks in the generated tasks.md file.============================================================================-->-## Phase 3.1: Setup+## Phase 1: Setup (Shared Infrastructure)++**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 3.2: Tests First (TDD) - OPTIONAL β οΈ-**NOTE: This phase is only included if tests are explicitly requested**-**If included: These tests MUST be written and MUST FAIL before ANY implementation**-- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py-- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py-- [ ] T006 [P] Integration test user registration in tests/integration/test_registration.py-- [ ] T007 [P] Integration test auth flow in tests/integration/test_auth.py--## Phase 3.3: Core Implementation-- [ ] T008 [P] User model in src/models/user.py-- [ ] T009 [P] UserService CRUD in src/services/user_service.py-- [ ] T010 [P] CLI --create-user in src/cli/user_commands.py-- [ ] T011 POST /api/users endpoint-- [ ] T012 GET /api/users/{id} endpoint-- [ ] T013 Input validation-- [ ] T014 Error handling and logging--## Phase 3.4: Integration-- [ ] T015 Connect UserService to DB-- [ ] T016 Auth middleware-- [ ] T017 Request/response logging-- [ ] T018 CORS and security headers--## Phase 3.5: Polish-- [ ] T019 [P] Documentation updates in docs/-- [ ] T020 Code cleanup and refactoring-- [ ] T021 Performance optimization-- [ ] T022 [P] Unit tests (if requested) in tests/unit/-- [ ] T023 Run quickstart.md validation--## Dependencies-- Tests (T004-T007) before implementation (T008-T014)-- T008 blocks T009, T015-- T016 blocks T018-- Implementation before polish (T019-T023)--## Parallel Example-```-# Launch T004-T007 together:-Task: "Contract test POST /api/users in tests/contract/test_users_post.py"-Task: "Contract test GET /api/users/{id} in tests/contract/test_users_get.py"-Task: "Integration test registration in tests/integration/test_registration.py"-Task: "Integration test auth in tests/integration/test_auth.py"+---++## 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++---++## Phase 5: User Story 3 - [Title] (Priority: P3)++**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++---++## 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**++- [ ] T005 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py+- [ ] T006 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py++### Implementation for User Story 1++- [ ] T007 [P] [US1] Create [Entity1] model in src/models/[entity1].py+- [ ] T008 [P] [US1] Create [Entity2] model in src/models/[entity2].py+- [ ] T009 [US1] Implement [Service] in src/services/[service].py (depends on T007, T008)+- [ ] T010 [US1] Implement [endpoint/feature] in src/[location]/[file].py+- [ ] T011 [US1] Add validation and error handling+- [ ] T012 [US1] Add logging for user story 1 operations++**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently++---++## Phase 3: 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) β οΈ++- [ ] T013 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py+- [ ] T014 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py++### Implementation for User Story 2++- [ ] T015 [P] [US2] Create [Entity] model in src/models/[entity].py+- [ ] T016 [US2] Implement [Service] in src/services/[service].py+- [ ] T017 [US2] Implement [endpoint/feature] in src/[location]/[file].py+- [ ] T018 [US2] Integrate with User Story 1 components (if needed)++**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently++---++## Phase 4: User Story 3 - [Title] (Priority: P3)++**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) β οΈ++- [ ] T019 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py+- [ ] T020 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py++### Implementation for User Story 3++- [ ] T021 [P] [US3] Create [Entity] model in src/models/[entity].py+- [ ] T022 [US3] Implement [Service] in src/services/[service].py+- [ ] T023 [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++---++## Dependencies & Execution Order++### Phase Dependencies++- **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++### 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"```+---++## Implementation Strategy++### MVP First (User Story 1 Only)++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++### Incremental Delivery++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++### Parallel Team Strategy++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++---+## 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-- Avoid: vague tasks, same file conflicts+- 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+