Skill v1.0.1
currentAutomated scan100/100+5 new
version: "1.0.1" name: task-generation description: "Reference material with the canonical task-format grammar and decomposition rules for plan-to-tasks expansion. Loaded on demand by generate-tasks; not directly invokable."
Task Generation Guide
Task Format (REQUIRED)
Every task MUST strictly follow this format:
- [ ] T### [P?] [US#|OBJ#?] {(FR|TR|OR|RR)-###?} [COMPLETES (FR|TR|OR|RR)-###?] Description with file path [after:T###?] [← T###:Symbol?] [→ exports: Symbol?] [VERIFY: <command>]?*
[VERIFY: <command>] is optional and repeatable (zero or more; typically 0–3). It appends after → exports: (and after [COMPLETES ...]). The command text runs from [VERIFY: to the next ] and MUST NOT contain a literal ] — move such checks into a verify script and reference it when needed.
Format Components
- Checkbox: Always
- [ ](markdown checkbox) - Task ID: Sequential (T001, T002...) in execution order
- `[P]` marker: Only if parallelizable (different files, no dependencies)
- `[US#|OBJ#]` label: Required for delivery phases only
- Product specs use
[US#]for user story phases - Technical and operational specs use
[OBJ#]for objective phases - Setup/Foundational phases: NO work-item label
- Polish phase: NO story label
- `{(FR|TR|OR|RR)-###}` tag: Links task to the requirement(s) it implements
- Use
{FR-001}or{TR-001}for a single requirement,{FR-001,FR-003}for multiple - Required for tasks that directly implement a requirement
- Setup/infrastructure tasks with no direct requirement mapping may omit this tag
- Description: Clear action with exact file path
- `after:T###` clause (optional): Explicit task-level dependency when a task depends on artifacts from a different phase or a non-adjacent task within the same phase. Omit when sequential T### ordering within a phase already implies the dependency.
- `← T###:Symbol` import hint (optional): Lists specific symbols consumed from another task's output file, by source task ID. Use when
data-model.md,contracts/, or the Requirement Coverage MapFunction(s)/Symbol(s)column provide enough detail to name the symbols. Omit for leaf tasks with no cross-file coupling. - `→ exports: Symbol(params)` export hint (optional): Lists the 1–3 most important symbols this task's file will export, with key parameter or field hints. Source from
data-model.mdentities,contracts/schemas, or the Requirement Coverage MapFunction(s)/Symbol(s)column. Omit when no downstream task depends on this file. - `[COMPLETES (FR|TR|OR|RR)-###]` marker (optional): Placed on the last task implementing a requirement that spans 3+ tasks. Signals the implementing agent to verify the full requirement chain at this task's completion.
- `[VERIFY: <command>]` annotation (optional, repeatable): A machine-checkable acceptance assertion the Developer MUST run from the repo root before marking the task
[X]. Non-zero exit (for commands) or no match (forgreppatterns) is FAILURE — the task stays[ ]and routes into the error-recovery loop. Emit when a deterministic check is derivable: prefer aplan.md## Testing Strategytest command scoped to the task's file/requirement; else agrepfor a→ exports:symbol declaration; else a build/typecheck command targeting the task's file. Omit when no deterministic check is derivable. Commands MUST NOT contain a literal].
Annotation Constraints
- Only emit
← T###:and→ exports:annotations when at least one annotation source is available:data-model.md,contracts/, or a Requirement Coverage Map row with a populatedFunction(s)/Symbol(s)column. When none are available, fall back to description-only tasks. - The full task line (checkbox + ID + markers + description + all annotations) must stay under 200 characters. Lines carrying one or more
[VERIFY:]annotations may extend to 300 characters; when a VERIFY line would exceed 300, keep only the single most-decisive assertion (prefer a## Testing Strategytest command, else agrepfor the primary→ exports:symbol) and drop the rest. - When a task has >3 imports: replace inline
← T###:Symbolwith← contracts/[endpoint].yaml. - When a task has >3 exports: replace inline list with
→ see data-model.md#EntityName. - When both overflow: keep only
after:T###and omit symbol-level detail. - A
[VERIFY:]command MUST be non-empty and MUST NOT contain a literal]. Prefer a## Testing Strategytest command scoped to the task's file/requirement, agrepfor an exported symbol, or a build/typecheck command targeting the task's file. Avoid ambient commands (npm testwith no filter) — every assertion must be scoped to what this task produces.
Examples
- ✅
- [ ] T001 Update workspace scripts in package.json - ✅
- [ ] T005 [P] {FR-002} Implement auth middleware in src/middleware/auth.py [VERIFY: grep "authMiddleware" src/middleware/auth.py] - ✅
- [ ] T012 [P] [US1] {FR-005} Create User model in src/models/user.py → exports: UserModel(id,email,role) [VERIFY: grep "class UserModel" src/models/user.py] - ✅
- [ ] T013 [US1] {FR-006} Implement user service in src/services/user.py ← T012:UserModel → exports: UserService.register() [VERIFY: npm test -- --testPathPattern="user"] - ✅
- [ ] T014 [OBJ1] {TR-003,TR-004} Implement migration orchestration in src/services/migrations.py - ✅
- [ ] T018 [US2] {FR-003} [COMPLETES FR-003] Add order endpoint in src/api/orders.py after:T015 ← T015:OrderService [VERIFY: npm test -- --testPathPattern="orders"] - ❌
- [ ] Create User model(missing ID) - ❌
T001 [US1] Create model(missing checkbox) - ❌
- [ ] T005 {FR-002} Implement auth middleware in src/middleware/auth.py [VERIFY: ](empty VERIFY command)
Phase Structure
Optional preamble sections (Project Mode, Epic / Capability Map, Brownfield Notes) may precede the first phase header — see the template for details.
Optional Phase 1: Setup (Repository / Workspace Delta)
- Include only when the feature changes repository-root tooling, workspace config, shared project wiring, or other repo-level scaffolding
- Omit when empty
- No story labels
Optional Phase 2: Foundational (Cross-Work-Item Blockers)
- Include only for true blockers shared by multiple work items
- Omit when empty
- If present, complete before dependent work items
- No story labels
Phase 3+: Delivery Work Items (One Phase Per Story or Objective, by Priority)
- Each phase = one complete user story or objective
- Within each: Acceptance Test Stubs (when
plan.mdhas## Acceptance Test Stubsfor this work item's P1 requirements) → Tests (if requested) → Models → Services → Endpoints → Integration - Each phase independently testable
- Work-item-local setup, integration, compatibility, migration, and rollout tasks stay in-phase unless they truly block multiple work items
- Product phases use
[US#]; technical and operational phases use[OBJ#] - Mark the first P1 work-item phase with
🎯 MVP. If multiple work items share P1 priority, apply the emoji to each P1 phase.
Optional Final Phase: Polish & Cross-Cutting Concerns
- Documentation, refactoring, optimization, security hardening, and other work spanning multiple work items
- Omit when empty
- No story labels
Project Mode
Infer the task-generation mode from the plan and repository context:
- Greenfield: Initial project/workspace setup is part of this feature
- Brownfield: The feature extends an existing codebase and should avoid generic bootstrap tasks
- Mixed: The feature adds targeted repo/workspace changes plus enhancement work in existing code
Record the mode in tasks.md when helpful. Use it to guide whether Setup/Foundational phases are warranted.
Number phases sequentially based on the phases that are actually present. If Setup and/or Foundational are omitted, the first included delivery phase should use the next sequential phase number.
Organization Rules
- From Requirement Coverage Map (PRIMARY): If
plan.mdhas a## Requirement Coverage Maptable, use it as the authoritative source for mapping requirements to components, file paths, and exported symbols. Each row providesReq ID → Component(s) → File Path(s) → Function(s)/Symbol(s)— use the file paths to assign tasks to the correct work-item phases and theFunction(s)/Symbol(s)column to populate→ exports:annotations. - From Product User Stories or Non-Product Objectives: Each P1/P2/P3 work item gets its own phase
- From Contracts (if generated): Map each endpoint to the relevant story or objective
- From Data Model (if generated): Map entities to work items; lift entities into Setup/Foundational only when they truly block multiple work items
- From Infrastructure:
- Repo/workspace delta → Setup
- Cross-work-item blockers → Foundational
- Work-item-specific setup/integration/migration/rollout → in-phase
- Brownfield Heuristics: Prefer integration, compatibility, migration/backfill, feature-flag, rollout, and regression-verification tasks over generic project initialization in mature repositories
- Just-in-Time Shared Work: Create shared structures in the earliest work item that needs them unless they are true cross-work-item blockers
- Requirement Completion Point: When a requirement
{FR-###}(orTR-###/OR-###/RR-###) is implemented across 3+ tasks, the LAST task carrying that tag MUST include the suffix[COMPLETES (FR|TR|OR|RR)-###]. This signals the implementing agent to verify the full requirement at that task's completion rather than deferring to QC.
Dependency Rules
- Setup has no dependencies when present
- Foundational depends on Setup when both are present
- Delivery work items depend on any present shared phases; if no shared phases exist, they can start immediately
- Within work items: tests before implementation, models before services, services before endpoints
- Polish depends on all desired stories being complete when present
- Cross-phase task edges: When a task in one work-item phase depends on artifacts from a prior work-item phase, add
after:T###referencing the producing task. This makes the dependency explicit for resume and parallel-safety checks. - Parallel safety: A task with
after:T###or← T###:SymbolMUST NOT be marked[P]in the same batch as the referenced task. The WBS Generator must validate this in its self-correction step.
Tests
Tests are OPTIONAL — only include if explicitly requested in the spec or user asks for TDD. If included, tests MUST be written and FAIL before implementation.
Acceptance Test Stubs
When plan.md has a populated ## Acceptance Test Stubs section (not N/A — no P1 requirements), stub-creation tasks are MANDATORY for every listed P1 requirement and MUST precede that requirement's implementation tasks within the same work-item phase. A stub task creates the framework-native describe/it (or equivalent) blocks named in the plan row for one P1 reqID; the stub MUST be RED (pending/skip/failing-assertion) at creation. Implementation tasks tagged with a stubbed reqID MUST make their linked stub block GREEN before they can be marked [X].
Stub task format: - [ ] T### [US#|OBJ#] {FR-###|TR-###|OR-###|RR-###} Create acceptance test stub in <test file path> ← plan:AcceptanceTestStubs — the ← plan:AcceptanceTestStubs import hint points the Developer at the plan row to read the block names. Use one stub task per P1 requirement unless the plan groups multiple reqIDs into a single test file (then one stub task carrying {FR-001,FR-002} covering that file is acceptable). Stub tasks are never [P]-batched with the implementation tasks that satisfy them.
Artifact Conventions
Preservation rules: see .github/skills/artifact-conventions/SKILL.md (read during edit/remediation phases).
Template
Use the template at assets/tasks-template.md.
Use the fixture at assets/tasks-annotation-fixture.md to dry-run parser behavior, dependency edges, and completion-point examples before changing task format rules.
When generating tasks.md, omit empty optional sections rather than leaving placeholder phases with filler tasks.
Size budget: Keep tasks.md at or below 6KB. Target 5–10 tasks per work-item phase; if total tasks exceed 40, split the feature into sub-features.