223 lines
11 KiB
Markdown
223 lines
11 KiB
Markdown
# Task Generation Rules
|
|
|
|
## Core Principles
|
|
|
|
### 1. Natural Language Descriptions
|
|
Focus on capabilities and outcomes, not code structure.
|
|
|
|
**Describe**:
|
|
- What functionality to achieve
|
|
- Business logic and behavior
|
|
- Features and capabilities
|
|
- Domain language and concepts
|
|
- Data relationships and workflows
|
|
|
|
**Avoid**:
|
|
- File paths and directory structure
|
|
- Function/method names and signatures
|
|
- Type definitions and interfaces
|
|
- Class names and API contracts
|
|
- Specific data structures
|
|
|
|
**Rationale**: Implementation details (files, methods, types) are defined in design.md. Tasks describe the functional work to be done.
|
|
|
|
### 2. Task Ordering Principle
|
|
|
|
**Order implies dependency**: Task N implicitly depends on all tasks before it. This is the primary dependency mechanism.
|
|
|
|
**Tasks must follow this phase order**:
|
|
1. **Foundation**: Environment setup, test infrastructure, shared utilities, database schema, configuration
|
|
2. **Core**: Primary feature implementation (parallel-capable tasks grouped here)
|
|
3. **Integration**: Wiring components together, cross-boundary connections
|
|
4. **Validation**: E2E tests, edge cases, regression checks
|
|
|
|
**Rationale**: Foundation work unblocks everything else. Placing setup tasks early prevents downstream blocking. Core tasks can often run in parallel because foundation is already complete.
|
|
|
|
### 3. Task Integration & Progression
|
|
|
|
**Every task must**:
|
|
- Build on previous outputs (no orphaned code)
|
|
- Connect to the overall system (no hanging features)
|
|
- Progress incrementally (no big jumps in complexity)
|
|
- Respect architecture boundaries defined in design.md (Architecture Pattern & Boundary Map)
|
|
- Honor interface contracts documented in design.md
|
|
- Use major task summaries sparingly—omit detail bullets if the work is fully captured by child tasks.
|
|
|
|
**End with integration tasks** to wire everything together.
|
|
|
|
### 4. Dependency Declaration
|
|
|
|
**Default**: Sequential ordering handles most dependencies (task N depends on tasks before it).
|
|
|
|
**Explicit declaration required when**:
|
|
- A task depends on a specific task in a different major-task group (cross-boundary)
|
|
- The dependency is non-obvious from ordering alone
|
|
- A task can skip ahead of its position (declared via `(P)`) but still needs specific prior work
|
|
|
|
**Format**: `_Depends: 1.2, 2.3_` — placed alongside `_Requirements:_` in task detail sections.
|
|
|
|
**Do not over-annotate**: If a task simply depends on the task directly before it, ordering alone is sufficient.
|
|
|
|
### 5. Boundary Scope
|
|
|
|
**Each task should declare its component boundary** using design.md component/module names:
|
|
- `_Boundary: AuthService_` or `_Boundary: API Layer, UserRepository_`
|
|
- Helps validate parallel safety: tasks with non-overlapping boundaries are parallel candidates
|
|
- Helps agents understand scope: what to touch and what not to touch
|
|
|
|
**When to use**: Required for tasks marked `(P)` to validate parallel safety. Omit for sequential tasks where scope is obvious from the description.
|
|
|
|
**Boundary rule**:
|
|
- Each executable task should stay within a single responsibility boundary
|
|
- If work must cross boundaries, make it an explicit integration task rather than a normal implementation task
|
|
- Do not hide cross-boundary coordination inside a task that appears local
|
|
|
|
### 6. Flexible Task Sizing
|
|
|
|
**Guidelines**:
|
|
- **Major tasks**: As many sub-tasks as logically needed (group by cohesion)
|
|
- **Sub-tasks**: 1-3 hours each, 3-10 details per sub-task
|
|
- Balance between too granular and too broad
|
|
|
|
**Don't force arbitrary numbers** - let logical grouping determine structure.
|
|
|
|
### 7. Requirements Mapping
|
|
|
|
**End each task detail section with**:
|
|
- `_Requirements: X.X, Y.Y_` listing **only numeric requirement IDs** (comma-separated). Never append descriptive text, parentheses, translations, or free-form labels.
|
|
- For cross-cutting requirements, list every relevant requirement ID. All requirements MUST have numeric IDs in requirements.md. If an ID is missing, stop and correct requirements.md before generating tasks.
|
|
- Reference components/interfaces from design.md when helpful (e.g., `_Contracts: AuthService API`)
|
|
|
|
### 7.5 Observable Completion
|
|
|
|
**Each executable task must include at least one detail bullet that describes the observable completed state**:
|
|
- Phrase it as a deliverable, runtime behavior, persisted state, UI state, endpoint behavior, test result, or integration outcome
|
|
- Avoid vague bullets like "implement support", "wire things up", or "handle logic" unless paired with a concrete observable result
|
|
- Prefer making one detail bullet clearly answer: "What will be true when this task is done?"
|
|
- Keep this within the existing task body; do not add extra bookkeeping fields
|
|
|
|
### 8. Code-Only Focus
|
|
|
|
**Include ONLY**:
|
|
- Coding tasks (implementation)
|
|
- Testing tasks (unit, integration, E2E)
|
|
- Technical setup tasks (infrastructure, configuration)
|
|
|
|
**Exclude**:
|
|
- Deployment tasks
|
|
- Documentation tasks
|
|
- User testing
|
|
- Marketing/business activities
|
|
|
|
## Task Plan Review Gate
|
|
|
|
Before writing `tasks.md`, review the draft task plan and repair local issues until the plan passes or a true spec gap is discovered.
|
|
|
|
### Coverage Review
|
|
|
|
- Every requirement ID from `requirements.md` must appear in at least one task.
|
|
- Every design component, interface/contract, integration point, runtime prerequisite, and validation concern from `design.md` must be represented by at least one task.
|
|
- If coverage is missing because the task plan is incomplete, repair the draft tasks and review again.
|
|
- If coverage cannot be added cleanly because requirements or design are ambiguous, contradictory, or underspecified, stop and return to the requirements/design phase instead of papering over the gap in `tasks.md`.
|
|
|
|
### Executability Review
|
|
|
|
- Every sub-task must be executable as written, usually within 1-3 hours.
|
|
- Every sub-task must produce a verifiable deliverable (behavior, artifact, endpoint, UI state, config, migration, test, or integration result).
|
|
- Every executable sub-task must include at least one detail bullet that states the observable completion condition.
|
|
- Split tasks that combine multiple independently verifiable outcomes.
|
|
- Split tasks that combine multiple responsibility boundaries unless they are explicit integration tasks.
|
|
- If many tasks require broad `_Boundary:_` scopes or repeated cross-boundary coordination, stop and return to design or roadmap decomposition instead of forcing the spec through task generation.
|
|
- Merge or collapse tasks that are too small, bookkeeping-only, or not meaningful execution units.
|
|
- Make implicit prerequisites explicit as preceding tasks.
|
|
- Re-check `_Depends:_`, `_Boundary:_`, and `(P)` markers after edits so concurrency claims still match the design boundaries and dependency graph.
|
|
|
|
### Review Loop
|
|
|
|
- Run the review gate on the draft task plan before writing `tasks.md`.
|
|
- If issues are task-plan-local, repair the draft and re-run the review gate.
|
|
- Keep the loop bounded: no more than 2 review-and-repair passes before escalating a real spec gap.
|
|
- Write `tasks.md` only after the review gate passes.
|
|
|
|
### Optional Test Coverage Tasks
|
|
|
|
- When the design already guarantees functional coverage and rapid MVP delivery is prioritized, mark purely test-oriented follow-up work (e.g., baseline rendering/unit tests) as **optional** using the `- [ ]*` checkbox form.
|
|
- Only apply the optional marker when the sub-task directly references acceptance criteria from requirements.md in its detail bullets.
|
|
- Never mark implementation work or integration-critical verification as optional—reserve `*` for auxiliary/deferrable test coverage that can be revisited post-MVP.
|
|
|
|
## Task Hierarchy Rules
|
|
|
|
### Maximum 2 Levels
|
|
- **Level 1**: Major tasks (1, 2, 3, 4...)
|
|
- **Level 2**: Sub-tasks (1.1, 1.2, 2.1, 2.2...)
|
|
- **No deeper nesting** (no 1.1.1)
|
|
- If a major task would contain only a single actionable item, collapse the structure and promote the sub-task to the major level (e.g., replace `1.1` with `1.`).
|
|
- When a major task exists purely as a container, keep the checkbox description concise and avoid duplicating detailed bullets—reserve specifics for its sub-tasks.
|
|
|
|
### Sequential Numbering
|
|
- Major tasks MUST increment: 1, 2, 3, 4, 5...
|
|
- Sub-tasks reset per major task: 1.1, 1.2, then 2.1, 2.2...
|
|
- Never repeat major task numbers
|
|
|
|
### Parallel Analysis (default)
|
|
- Assume parallel analysis is enabled unless explicitly disabled (e.g. `--sequential` flag).
|
|
- `(P)` means: this task has no dependency on its immediately preceding peers and can run concurrently with them.
|
|
- Identify tasks that can run concurrently when **all** conditions hold:
|
|
- No data dependency on other pending tasks
|
|
- No shared file or resource contention
|
|
- No prerequisite review/approval from another task
|
|
- `_Boundary:_` annotations confirm non-overlapping component scopes
|
|
- Foundation-phase tasks (see Task Ordering Principle) are rarely `(P)` — they establish shared prerequisites.
|
|
- Core-phase tasks are the primary candidates for `(P)` since foundation is already complete.
|
|
- Validate that identified parallel tasks operate within separate boundaries defined in the Architecture Pattern & Boundary Map.
|
|
- Confirm API/event contracts from design.md do not overlap in ways that cause conflicts.
|
|
- `(P)` tasks with cross-boundary dependencies must declare `_Depends: X.X_` explicitly.
|
|
- Append `(P)` immediately after the task number for each parallel-capable task:
|
|
- Example: `- [ ] 2.1 (P) Build background worker`
|
|
- Apply to both major tasks and sub-tasks when appropriate.
|
|
- If sequential mode is requested, omit `(P)` markers entirely.
|
|
- Group parallel tasks logically (same parent when possible) and highlight any ordering caveats in detail bullets.
|
|
- Explicitly call out dependencies that prevent `(P)` even when tasks look similar.
|
|
|
|
### Checkbox Format
|
|
```markdown
|
|
- [ ] 1. Foundation: environment and test infrastructure setup
|
|
- [ ] 1.1 Sub-task description
|
|
- Detail item 1
|
|
- Detail item 2
|
|
- Observable completion condition
|
|
- _Requirements: X.X_
|
|
|
|
- [ ] 2. Core feature A
|
|
- [ ] 2.1 (P) Sub-task description
|
|
- Detail items...
|
|
- Observable completion condition
|
|
- _Requirements: Y.Y_
|
|
- _Boundary: AuthService_
|
|
|
|
- [ ] 2.2 (P) Sub-task description
|
|
- Detail items...
|
|
- Observable completion condition
|
|
- _Requirements: Z.Z_
|
|
- _Boundary: UserRepository_
|
|
|
|
- [ ] 3. Integration and wiring
|
|
- [ ] 3.1 Sub-task description
|
|
- Detail items...
|
|
- Observable completion condition
|
|
- _Depends: 2.1, 2.2_
|
|
- _Requirements: W.W_
|
|
```
|
|
|
|
## Requirements Coverage
|
|
|
|
**Mandatory Check**:
|
|
- ALL requirements from requirements.md MUST be covered
|
|
- Cross-reference every requirement ID with task mappings
|
|
- If gaps found: Return to requirements or design phase
|
|
- No requirement should be left without corresponding tasks
|
|
|
|
Use `N.M`-style numeric requirement IDs where `N` is the top-level requirement number from requirements.md (for example, Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2), and `M` is a local index within that requirement group.
|
|
|
|
Document any intentionally deferred requirements with rationale.
|