| name | task |
| description | Create well-defined task specifications from plans or user prompts. Use when user wants to define a task, create a work item, break down a plan into actionable work, or write a spec for implementation. Triggers on "create task", "define task", "write spec", "break this down", "make this actionable", or when moving from planning to execution. |
Task Creation
Create well-defined task specifications that provide clear goals while leaving implementation open to interpretation. Output to .work/tasks/backlog/<name>.md.
Task Creation Workflow
1. Understand the Scope
Determine task type and relevant sections:
- Full-stack feature: All sections applicable
- Backend only: Skip UX Guidelines, focus on System Behaviors and Data
- Frontend only: Skip Data & Contracts internals, focus on UX
- Documentation: Summary, Acceptance Criteria only
- Bug fix: Summary, Edge Cases, Acceptance Criteria
- Refactor: Summary, System Behaviors, Acceptance Criteria
2. Gather Context
If working from a plan:
- Read the plan from
.work/plans/ - Extract relevant decisions and constraints
- Link back to the plan
If working from user prompt:
- Ask clarifying questions about scope
- Identify affected files and systems
- Understand success criteria
3. Write the Task Spec
Create .work/tasks/backlog/<descriptive-name>.md using the template below.
Omit sections not relevant to the task type. A backend API task doesn't need UX Guidelines. A docs update doesn't need System Behaviors.
Task Template
See references/spec-template.md for the full template.
Core sections:
- Summary: One paragraph describing the task and why it exists
- User Journey: Entry point, happy path, exit criteria
- UX Guidelines: What user sees, copy tone, accessibility
- System Behaviors: Invariants, state transitions, policies
- Data & Contracts: Storage needs, API/events (high-level)
- Usage/Cost Accounting: What usage to track and how
- Edge Cases: Failure modes and user-visible outcomes
- Acceptance Criteria: Testable outcomes as bullet list
Writing Guidelines
Be Specific About What, Open About How
Good: "User can filter todos by status (all, active, completed)" Bad: "Implement filtering using React state with useMemo optimization"
Define the outcome, not the implementation.
Reference Concrete Touchpoints
Include:
- Files that will likely need changes
- API routes or contracts involved
- Database tables affected
- UI components to modify
Keep It Scannable
- Use bullet points over paragraphs
- Bold key terms
- Keep acceptance criteria atomic and testable
Task Lifecycle
After creating the task:
- Task starts in
.work/tasks/backlog/ - When work begins, move to
.work/tasks/in-progress/ - When complete, move to
.work/tasks/completed/
Update task status in the file header as work progresses.