From 0037a3f48468bb7979c284a905121a258e9d3026 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Mon, 6 Oct 2025 21:11:52 -0700 Subject: [PATCH] Update template and docs --- README.md | 26 ++- templates/commands/tasks.md | 104 ++++++++---- templates/spec-template.md | 60 ++++++- templates/tasks-template.md | 318 ++++++++++++++++++++++++++++++------ 4 files changed, 413 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 30d9c378..80b8f7c7 100644 --- a/README.md +++ b/README.md @@ -207,16 +207,28 @@ specify check After 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 proactiv specify init --ai claude specify init --ai gemini specify init --ai copilot -specify init --ai cursor -specify init --ai qwen -specify init --ai opencode -specify init --ai codex -specify init --ai windsurf -specify init --ai q + # Or in current directory: specify init . --ai claude specify init . --ai codex + # or use --here flag specify init --here --ai claude specify init --here --ai codex + # Force merge into a non-empty current directory specify init . --force --ai claude + # or specify init --here --force --ai claude ``` diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index d6beea73..f2bafadc 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 - -2. **From Data Model**: - - Each entity → model creation task [P] - - Relationships → service layer tasks - -3. **From User Stories**: - - Each story → implementation tasks - - If tests requested: Each story → integration test [P] - - If quickstart.md exists: Validation tasks +**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 + +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 + +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 -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 diff --git a/templates/spec-template.md b/templates/spec-template.md index db1d1878..c67d9149 100644 --- a/templates/spec-template.md +++ b/templates/spec-template.md @@ -7,20 +7,64 @@ ## User Scenarios & Testing *(mandatory)* -### Primary User Story - -[Describe the main user journey in plain language] - -### Acceptance Scenarios - +### User Story 1 - [Brief Title] (Priority: P1) + +[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 - 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 -## 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 2: Foundational (Blocking Prerequisites) -## Phase 3.4: Integration -- [ ] T015 Connect UserService to DB -- [ ] T016 Auth middleware -- [ ] T017 Request/response logging -- [ ] T018 CORS and security headers +**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented -## 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 +**⚠️ CRITICAL**: No user story work can begin until this phase is complete -## Dependencies -- Tests (T004-T007) before implementation (T008-T014) -- T008 blocks T009, T015 -- T016 blocks T018 -- Implementation before polish (T019-T023) +Examples of foundational tasks (adjust based on your project): -## 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" +- [ ] 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 -- Verify tests fail before implementing -- Commit after each task -- Avoid: vague tasks, same file conflicts + +- [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 +