/task - Task Planning Agent
Workflow
User Request
↓
0. Read CLAUDE.md + LEARNINGS.md — get full context before anything else
1. Discuss & clarify requirements
1.5. Determine recommended implementation model (haiku vs sonnet)
2. Research codebase for context (targeted, embed findings)
3. Generate Task ID (next available number)
4. Create docs/task/{ID}-{task-name}.md
5. Add to TASKS.md under "## Planned"
↓
Ready for /implement {ID}Step 0: Read Project Knowledge (Before Anything Else)
Read both files before talking to the user or touching the codebase:
- CLAUDE.md — stack, conventions, key file locations, "Do Not" rules, architecture decisions already made
- LEARNINGS.md — common mistakes to avoid, established patterns to follow, past decisions to honor, test cycle counts
- Together these replace most codebase exploration for planning — read before asking clarifying questions and before any Glob/Grep calls
Step 1: Requirements Gathering
- Ask: What is the expected behavior? Any UI/UX preferences? Priority level?
- Version Impact:
feature→minor,bugfix/enhancement/chore/documentation→patch. Override tomajorfor breaking API changes, schema migrations requiring migration, removing deprecated features, or any change requiring user action.
Step 1.5: Determine Recommended Implementation Model
Default: haiku — use for the majority of tasks.
Escalate to sonnet when:
| Signal | Examples |
|---|---|
| New architecture or system design | New auth system, new data layer, introducing a new pattern |
| Cross-cutting concerns | Changes affecting 5+ unrelated files, or spanning multiple layers (DB + API + UI) |
| Security-sensitive logic | Auth, permissions, RLS policies, token handling |
| Complex business logic | Multi-step workflows, state machines, non-obvious edge cases |
| Database schema changes | Migrations, new tables, RLS, schema refactors |
| Ambiguous or contradictory requirements | Conflicting constraints that need judgment calls |
| High-risk refactor | Replacing existing patterns, removing shared utilities |
Stick with haiku for: UI changes, styling, config files, documentation, single-file additions following established patterns, targeted bug fixes, CRUD mirroring existing patterns.
Record in task document header:
> **Recommended Model:** haiku ← most tasks
> **Recommended Model:** sonnet ← complex, architectural, or risky tasksInclude a one-line rationale in ## Notes for Implementation Agent when recommending sonnet.
Step 2: Codebase Research (Targeted — Embed, Don't Just Reference)
- Use specific patterns:
Glob("src/components/auth/**"),Grep("useAuthStore", "*.ts")— not broad sweeps - After finding relevant files, paste key sections into
## Code Contextin the task doc — do NOT just reference file names
What to embed and where:
| Finding | Task doc section |
|---|---|
| File to create/modify | ## File Changes table |
| Current code being changed | ## Code Context — paste it |
| Import patterns needed | ## Code Context — paste them |
| Similar pattern to follow | ## Code Context — paste it |
| Non-obvious architectural decision | ## Notes for Implementation Agent |
If /implement would need to read a file to understand it, paste the relevant part into ## Code Context. The task doc is the single source of truth.
Step 3: Generate Task ID
- Read TASKS.md, find the highest ID across all sections
- Assign next ID = highest + 1; if no tasks exist, start with ID = 1
- Use 3-digit zero-padded format: 001, 002,... 999
Step 4: Create Task Document
Create docs/task/{ID}-{task-name}.md using: docs/templates/task-document.md
Naming: 001-user-dashboard-redesign.md, 002-lead-auto-tagging.md
Step 5: Update TASKS.md
Add to ## Planned. If TASKS.md missing, create from: docs/templates/tasks-tracking.md
Output Checklist
- Task document created in
docs/task/ - All required sections filled
- Implementation steps are clear and actionable
- File paths verified to exist (for modifications)
- Added to TASKS.md "## Planned" section
- User understands and approves the task
Handoff to /implement
Manual Mode
Task created: #{ID} - {Task Title}
Document: docs/task/{ID}-{task-name}.md
Added to TASKS.md under "Planned"
Next:
/implement {ID}
(Optional: /clear first to start fresh session)Auto Mode
When /task auto was invoked and user approves:
- Set
Automation: autoin the task document - Read
Recommended Modelfrom the task document header - Spawn
/implement auto {ID}with that model:Task({subagent_type: "general-purpose", model: "{recommended_model}", prompt: "/implement auto {ID}", run_in_background: true}) - Wait for one final signal: pipeline complete or pipeline stopped
Task approved. Pipeline starting...
Task: #{ID} - {Task Title}
Orchestrator: /implement ({model} per recommendation)
Pipeline: implement → simplify → test → document → ship
Waiting for pipeline to complete...When the final signal arrives, relay to user:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PIPELINE COMPLETE: #{ID} - {Task Title}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PR: {url}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━Or if stopped:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PIPELINE STOPPED: #{ID} - {Task Title}
Reason: {summary}
Details: {reference path}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━