Skip to content

πŸ’« 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.md
index 30d9c378e..80b8f7c70 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 <project_name> --ai claude
specify init <project_name> --ai gemini
specify 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 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 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.md
index 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.md
index 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 increment
DO 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
+