Skip to content

Commit 0037a3f

Browse files
localdenlocalden
committed
Update template and docs
1 parent a6be9be commit 0037a3f

File tree

4 files changed

+414
-96
lines changed

4 files changed

+414
-96
lines changed

‎README.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -207,16 +207,28 @@ specify check
207207

208208
After running `specify init`, your AI coding agent will have access to these slash commands for structured development:
209209

210+
#### Core Commands
211+
212+
Essential commands for the Spec-Driven Development workflow:
213+
210214
| Command | Description |
211215
|-----------------|-----------------------------------------------------------------------|
212216
| `/constitution` | Create or update project governing principles and development guidelines |
213217
| `/specify` | Define what you want to build (requirements and user stories) |
214-
| `/clarify` | Clarify underspecified areas (must be run before `/plan` unless explicitly skipped; formerly `/quizme`) |
215218
| `/plan` | Create technical implementation plans with your chosen tech stack |
216219
| `/tasks` | Generate actionable task lists for implementation |
217-
| `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) |
218220
| `/implement` | Execute all tasks to build the feature according to the plan |
219221

222+
#### Optional Commands
223+
224+
Additional commands for enhanced quality and validation:
225+
226+
| Command | Description |
227+
|-----------------|-----------------------------------------------------------------------|
228+
| `/clarify` | Clarify underspecified areas (recommended before `/plan`; formerly `/quizme`) |
229+
| `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) |
230+
| `/checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
231+
220232
### Environment Variables
221233

222234
| Variable | Description |
@@ -314,20 +326,18 @@ You will be prompted to select the AI agent you are using. You can also proactiv
314326
specify init <project_name> --ai claude
315327
specify init <project_name> --ai gemini
316328
specify init <project_name> --ai copilot
317-
specify init <project_name> --ai cursor
318-
specify init <project_name> --ai qwen
319-
specify init <project_name> --ai opencode
320-
specify init <project_name> --ai codex
321-
specify init <project_name> --ai windsurf
322-
specify init <project_name> --ai q
329+
323330
# Or in current directory:
324331
specify init . --ai claude
325332
specify init . --ai codex
333+
326334
# or use --here flag
327335
specify init --here --ai claude
328336
specify init --here --ai codex
337+
329338
# Force merge into a non-empty current directory
330339
specify init . --force --ai claude
340+
331341
# or
332342
specify init --here --force --ai claude
333343
```

‎templates/commands/tasks.md‎

Lines changed: 70 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -18,37 +18,57 @@ You **MUST** consider the user input before proceeding (if not empty).
1818
1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
1919

2020
2. **Load design documents**: Read from FEATURE_DIR:
21-
- **Required**: plan.md (tech stack, libraries, structure)
21+
- **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
2222
- **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
2323
- Note: Not all projects have all documents. Generate tasks based on what's available.
2424

2525
3. **Execute task generation workflow** (follow the template structure):
2626
- Load plan.md and extract tech stack, libraries, project structure
27-
- If data-model.md exists: Extract entities → generate model tasks
28-
- If contracts/ exists: Each file → generate endpoint/API tasks
27+
- **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**
28+
- If data-model.md exists: Extract entities → map to user stories
29+
- If contracts/ exists: Each file → map endpoints to user stories
2930
- If research.md exists: Extract decisions → generate setup tasks
30-
- Generate tasks by category: Setup, Core Implementation, Integration, Polish
31+
- **Generate tasks ORGANIZED BY USER STORY**:
32+
- Setup tasks (shared infrastructure needed by all stories)
33+
- **Foundational tasks (prerequisites that must complete before ANY user story can start)**
34+
- For each user story (in priority order P1, P2, P3...):
35+
- Group all tasks needed to complete JUST that story
36+
- Include models, services, endpoints, UI components specific to that story
37+
- Mark which tasks are [P] parallelizable
38+
- If tests requested: Include tests specific to that story
39+
- Polish/Integration tasks (cross-cutting concerns)
3140
- **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach
3241
- Apply task rules:
33-
* Different files = mark [P] for parallel
34-
* Same file = sequential (no [P])
35-
* If tests requested: Tests before implementation (TDD order)
42+
- Different files = mark [P] for parallel
43+
- Same file = sequential (no [P])
44+
- If tests requested: Tests before implementation (TDD order)
3645
- Number tasks sequentially (T001, T002...)
37-
- Generate dependency graph
38-
- Create parallel execution examples
39-
- Validate task completeness (all entities have implementations, all endpoints covered)
46+
- Generate dependency graph showing user story completion order
47+
- Create parallel execution examples per user story
48+
- Validate task completeness (each user story has all needed tasks, independently testable)
4049

4150
4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
4251
- Correct feature name from plan.md
43-
- Numbered tasks (T001, T002...) in dependency order
52+
- Phase 1: Setup tasks (project initialization)
53+
- Phase 2: Foundational tasks (blocking prerequisites for all user stories)
54+
- Phase 3+: One phase per user story (in priority order from spec.md)
55+
- Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
56+
- Clear [Story] labels (US1, US2, US3...) for each task
57+
- [P] markers for parallelizable tasks within each story
58+
- Checkpoint markers after each story phase
59+
- Final Phase: Polish & cross-cutting concerns
60+
- Numbered tasks (T001, T002...) in execution order
4461
- Clear file paths for each task
45-
- [P] markers for parallelizable tasks
46-
- Phase groupings based on what's needed (Setup, Core Implementation, Integration, Polish)
47-
- If tests requested: Include separate "Tests First (TDD)" phase before Core Implementation
48-
- Dependency notes
62+
- Dependencies section showing story completion order
63+
- Parallel execution examples per story
64+
- Implementation strategy section (MVP first, incremental delivery)
4965

50-
5. **Report**: Output path to generated tasks.md and summary of task counts by phase.
51-
- Parallel execution guidance
66+
5. **Report**: Output path to generated tasks.md and summary:
67+
- Total task count
68+
- Task count per user story
69+
- Parallel opportunities identified
70+
- Independent test criteria for each story
71+
- Suggested MVP scope (typically just User Story 1)
5272

5373
Context for task generation: {ARGS}
5474

@@ -58,20 +78,38 @@ The tasks.md should be immediately executable - each task must be specific enoug
5878

5979
**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.
6080

61-
1. **From Contracts**:
62-
- Each contract/endpoint → implementation task
63-
- If tests requested: Each contract → contract test task [P] before implementation
81+
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
82+
83+
1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
84+
- Each user story (P1, P2, P3...) gets its own phase
85+
- Map all related components to their story:
86+
- Models needed for that story
87+
- Services needed for that story
88+
- Endpoints/UI needed for that story
89+
- If tests requested: Tests specific to that story
90+
- Mark story dependencies (most stories should be independent)
91+
92+
2. **From Contracts**:
93+
- Map each contract/endpoint → to the user story it serves
94+
- If tests requested: Each contract → contract test task [P] before implementation in that story's phase
6495

65-
2. **From Data Model**:
66-
- Each entity → model creation task [P]
67-
- Relationships → service layer tasks
96+
3. **From Data Model**:
97+
- Map each entity → to the user story(ies) that need it
98+
- If entity serves multiple stories: Put in earliest story or Setup phase
99+
- Relationships → service layer tasks in appropriate story phase
68100

69-
3. **From User Stories**:
70-
- Each story → implementation tasks
71-
- If tests requested: Each story → integration test [P]
72-
- If quickstart.md exists: Validation tasks
73-
74-
4. **Ordering**:
75-
- Without tests: Setup → Models → Services → Endpoints → Integration → Polish
76-
- With tests (TDD): Setup → Tests → Models → Services → Endpoints → Integration → Polish
77-
- Dependencies block parallel execution
101+
4. **From Setup/Infrastructure**:
102+
- Shared infrastructure → Setup phase (Phase 1)
103+
- Foundational/blocking tasks → Foundational phase (Phase 2)
104+
- Examples: Database schema setup, authentication framework, core libraries, base configurations
105+
- These MUST complete before any user story can be implemented
106+
- Story-specific setup → within that story's phase
107+
108+
5. **Ordering**:
109+
- Phase 1: Setup (project initialization)
110+
- Phase 2: Foundational (blocking prerequisites - must complete before user stories)
111+
- Phase 3+: User Stories in priority order (P1, P2, P3...)
112+
- Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
113+
- Final Phase: Polish & Cross-Cutting Concerns
114+
- Each user story phase should be a complete, independently testable increment
115+

‎templates/spec-template.md‎

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,64 @@
77

88
## User Scenarios & Testing *(mandatory)*
99

10-
### Primary User Story
10+
<!--
11+
IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
12+
Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
13+
you should still have a viable MVP (Minimum Viable Product) that delivers value.
14+
15+
Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
16+
Think of each story as a standalone slice of functionality that can be:
17+
- Developed independently
18+
- Tested independently
19+
- Deployed independently
20+
- Demonstrated to users independently
21+
-->
1122

12-
[Describe the main user journey in plain language]
23+
### User Story 1 - [Brief Title] (Priority: P1)
1324

14-
### Acceptance Scenarios
25+
[Describe this user journey in plain language]
1526

16-
<!--
17-
ACTION REQUIRED: The content in this section represents placeholders.
18-
Fill them out with the right acceptance scenarios.
19-
-->
27+
**Why this priority**: [Explain the value and why it has this priority level]
28+
29+
**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
30+
31+
**Acceptance Scenarios**:
2032

2133
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2234
2. **Given** [initial state], **When** [action], **Then** [expected outcome]
2335

36+
---
37+
38+
### User Story 2 - [Brief Title] (Priority: P2)
39+
40+
[Describe this user journey in plain language]
41+
42+
**Why this priority**: [Explain the value and why it has this priority level]
43+
44+
**Independent Test**: [Describe how this can be tested independently]
45+
46+
**Acceptance Scenarios**:
47+
48+
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
49+
50+
---
51+
52+
### User Story 3 - [Brief Title] (Priority: P3)
53+
54+
[Describe this user journey in plain language]
55+
56+
**Why this priority**: [Explain the value and why it has this priority level]
57+
58+
**Independent Test**: [Describe how this can be tested independently]
59+
60+
**Acceptance Scenarios**:
61+
62+
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
63+
64+
---
65+
66+
[Add more user stories as needed, each with an assigned priority]
67+
2468
### Edge Cases
2569

2670
<!--

0 commit comments

Comments
 (0)