233 lines
14 KiB
Markdown
233 lines
14 KiB
Markdown
---
|
|
description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
|
|
handoffs:
|
|
- label: Analyze For Consistency
|
|
agent: speckit.analyze
|
|
prompt: Run a project analysis for consistency
|
|
send: true
|
|
- label: Implement Project
|
|
agent: speckit.implement
|
|
prompt: Start the implementation in phases
|
|
send: true
|
|
---
|
|
|
|
## User Input
|
|
|
|
```text
|
|
$ARGUMENTS
|
|
```
|
|
|
|
You **MUST** consider the user input before proceeding (if not empty).
|
|
|
|
## Outline
|
|
|
|
1. **Setup**: Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
|
|
|
|
2. **Load design documents**: Read from FEATURE_DIR:
|
|
- **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**:
|
|
- Load plan.md and extract tech stack, libraries, project structure
|
|
- Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
|
|
- If data-model.md exists: Extract entities and map to user stories
|
|
- If contracts/ exists: Map endpoints to user stories
|
|
- If research.md exists: Extract decisions for setup tasks
|
|
- Generate tasks organized by user story (see Task Generation Rules below)
|
|
- 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
|
|
- 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
|
|
- Final Phase: Polish & cross-cutting concerns
|
|
- All tasks must follow the strict checklist format (see Task Generation Rules below)
|
|
- Clear file paths for each task
|
|
- 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:
|
|
- 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)
|
|
- Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
|
|
|
|
Context for task generation: $ARGUMENTS
|
|
|
|
The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
|
|
|
|
## Implementation Context Requirements
|
|
|
|
**CRITICAL**: The tasks.md will be executed by a DIFFERENT model than the one generating it. The generating model (you) has deep reasoning capability and can infer implementation details from sparse descriptions. The implementing model does NOT — it needs explicit, self-contained context embedded directly in each task. Every task must be a standalone implementation brief, not a summary that requires the reader to independently analyze the codebase.
|
|
|
|
### Per-Task Context Blocks
|
|
|
|
For every non-trivial task (anything beyond creating an empty file or adding a simple field), include an indented **Context** block immediately below the task checkbox line. This block MUST contain:
|
|
|
|
1. **Existing code references**: Quote the exact current function signatures, struct definitions, or interface methods that the task modifies or depends on. Use fenced code blocks with the language identifier.
|
|
|
|
2. **Target file state**: Describe what already exists in the target file that the implementer needs to know about (imports, adjacent functions, package conventions).
|
|
|
|
3. **Expected implementation pattern**: Show a concrete code skeleton or pseudocode of what the implementation should look like. Reference similar patterns already in the codebase by quoting them. For example: "Follow the same pattern as `computeDatasetAnalytics()` in `engine.go` lines 245-310, which iterates entries and accumulates stats."
|
|
|
|
4. **Key decisions and gotchas**: Non-obvious constraints, edge cases, or design decisions from the spec/research that affect this task. Example: "Must use `int64` not `int` for file sizes to handle >2GB files on 32-bit systems" or "The profile may have RecursiveAnalysis disabled — check `opts.Profile.RecursiveAnalysis` before accumulating subdirectory maps."
|
|
|
|
5. **Acceptance signal**: A concrete, verifiable statement of what "done" looks like. Example: "`go test ./internal/engine/... -run TestRegistryResolve` passes with all 6 subcases green."
|
|
|
|
### Example Task WITH Context (REQUIRED format for all non-trivial tasks)
|
|
|
|
```markdown
|
|
- [ ] T009 [US1] Create template analysis module in `internal/engine/module_template.go`
|
|
|
|
**Context**:
|
|
- **Implements**: `AnalysisModule` interface from `internal/engine/module.go`:
|
|
```go
|
|
type AnalysisModule interface {
|
|
Name() string
|
|
Description() string
|
|
ProcessEntry(entry *types.ManifestEntry)
|
|
Finalize(ctx *FinalizationContext) (*ModuleResult, error)
|
|
}
|
|
```
|
|
- **Depends on**: `ContainerMatcher` from `internal/discovery/matcher.go` — call `matcher.Match(entry.Path)` to identify containers. The matcher is initialized from `profile.ContainerPatterns` (see `engine.go:initContainerMatcher()`).
|
|
- **Accumulation pattern**: Follow the same accumulator pattern as `DatasetAnalyticsAccumulator` in `pipeline.go` — use maps keyed by container path to accumulate file counts, total sizes, and date ranges incrementally during `ProcessEntry()`.
|
|
- **Key struct fields to accumulate**:
|
|
```go
|
|
type templateModule struct {
|
|
matcher *discovery.ContainerMatcher
|
|
profile *config.Profile
|
|
accumulators map[string]*containerAccumulator // keyed by container path
|
|
seen map[string]bool // for nesting exclusion
|
|
subdirs map[string]map[string]bool // container -> subdirs (only if recursive enabled)
|
|
filesByPath map[string]map[string]int // container -> subdir -> file count
|
|
sizeByPath map[string]map[string]int64 // container -> subdir -> total size
|
|
}
|
|
```
|
|
- **Gotcha**: Nesting exclusion — if `/projects/foo` is a container, `/projects/foo/bar` should NOT also be identified as a separate container even if it matches. Use the `seen` set: before adding a new container, check if any prefix of its path is already in `seen`.
|
|
- **Acceptance**: Module registers successfully, `ProcessEntry()` populates accumulators for test entries, `Name()` returns `"template"`.
|
|
```
|
|
|
|
### Example Task WITHOUT Context (WRONG — never do this)
|
|
|
|
```markdown
|
|
- [ ] T009 [US1] Create template analysis module in `internal/engine/module_template.go` — implement AnalysisModule interface, accumulate container stats during ProcessEntry(), handle nesting exclusion
|
|
```
|
|
|
|
The second example forces the implementing model to independently figure out what `AnalysisModule` looks like, how `ContainerMatcher` works, what fields to accumulate, and how nesting exclusion works. This results in incorrect or incomplete implementations.
|
|
|
|
### Per-Phase Context Summary
|
|
|
|
At the start of each phase (after the **Goal** line), include a **Phase Context** block listing:
|
|
|
|
- **Files modified in this phase**: Full paths with a one-line description of each file's current purpose
|
|
- **Key types/interfaces used**: Quoted signatures of types that tasks in this phase depend on
|
|
- **Codebase conventions to follow**: Naming patterns, error handling style, import grouping, or test patterns observed in the project (reference specific files as examples)
|
|
|
|
### Context Sourcing Strategy — Plan Artifacts First
|
|
|
|
The design documents produced by `/speckit.plan` (contracts, data-model, research, quickstart) already contain most of the information that Context blocks need: interface signatures, struct definitions, design decisions, gotchas, error messages, and acceptance scenarios. **Use these artifacts as your primary source for Context blocks instead of re-reading source files.**
|
|
|
|
**For tasks that CREATE new files** (new modules, new types, new test files):
|
|
- Pull interface signatures, struct definitions, and method contracts from **contracts/** and **data-model.md** — these already contain the exact code the implementer needs
|
|
- Pull design decisions, accumulation patterns, and gotchas from **research.md** — cite the specific research item (e.g., "See R3: Container Identification During Streaming")
|
|
- Pull acceptance scenarios from **quickstart.md** — map CLI examples to verifiable acceptance signals
|
|
- **Do NOT read source files** unless the plan artifacts reference an existing pattern that needs to be matched (e.g., "follows the existing `plugin.Registry` pattern") — in that case, read only the referenced file to quote the specific pattern
|
|
|
|
**For tasks that MODIFY existing files** (adding fields, rewiring functions, updating existing logic):
|
|
- Still use plan artifacts for the **target design** (what the code should become)
|
|
- Read the **specific function/struct being modified** from the source file to quote its **current state** — the implementer needs to see both "what exists now" and "what it should become"
|
|
- Do NOT read the entire file — read only the function/struct being changed plus its immediate dependencies
|
|
|
|
**For test tasks**:
|
|
- Read **one existing test file** in the same package to capture test conventions (table-driven patterns, setup/teardown helpers, assertion style). Quote a representative test function as a pattern to follow.
|
|
- Pull test scenarios from contracts and quickstart — these define expected inputs/outputs
|
|
|
|
**Always**:
|
|
- Read **copilot-instructions.md** or equivalent project guidelines (once, at the start of task generation) for language version constraints, banned patterns, build requirements, and protected code paths
|
|
- If the project has a design system or style guide referenced in the plan, read it (once)
|
|
|
|
**Do NOT**:
|
|
- Read full source files for every task — the plan artifacts already distill the relevant information
|
|
- Re-derive information that exists in contracts or research — reference those documents directly
|
|
- Generate tasks with placeholder signatures — every code reference must come from either plan artifacts or a targeted source file read
|
|
|
|
## Task Generation Rules
|
|
|
|
**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
|
|
|
|
**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
|
|
|
|
### Checklist Format (REQUIRED)
|
|
|
|
Every task MUST strictly follow this format:
|
|
|
|
```text
|
|
- [ ] [TaskID] [P?] [Story?] Description with file path
|
|
```
|
|
|
|
**Format Components**:
|
|
|
|
1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
|
|
2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
|
|
3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
|
|
4. **[Story] label**: REQUIRED for user story phase tasks only
|
|
- Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
|
|
- Setup phase: NO story label
|
|
- Foundational phase: NO story label
|
|
- User Story phases: MUST have story label
|
|
- Polish phase: NO story label
|
|
5. **Description**: Clear action with exact file path
|
|
|
|
**Examples**:
|
|
|
|
- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
|
|
- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
|
|
- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
|
|
- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
|
|
- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
|
|
- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
|
|
- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
|
|
- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
|
|
|
|
### Task Organization
|
|
|
|
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)
|
|
- Story-specific setup → within that story's phase
|
|
|
|
### Phase Structure
|
|
|
|
- **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
|
|
- Each phase should be a complete, independently testable increment
|
|
- **Final Phase**: Polish & Cross-Cutting Concerns
|