Decompose into Tasks
Break a project down into concrete, dependency-linked tasks.
Decompose into Tasks
Decomposition transforms a project description into a structured task graph. Each task should be independently implementable once its dependencies are met.
From your agent
Decomposition runs inside your coding agent, after brainstorming produces a brief. The /piyaz flow proposes a task breakdown, or you can ask for it directly. On Claude Code you can also jump straight to it with /piyaz:decompose.
break this into tasks with the dependenciesReview the proposed tasks
Each task carries:
- Title: verb plus noun (for example, "Add auth middleware", "Build CLI parser").
- Description: two to four sentences covering what, why, and how.
- Acceptance criteria: two to four testable conditions that define done.
- Tags: for grouping and search.
- Category: the drawer group (for example, "backend", "frontend").
Check the dependencies
Tasks are wired with depends_on and relates_to edges. Confirm that:
- Hard dependencies use
depends_on(the source cannot start until the target is done). - Informational links use
relates_to(shared context, no blocking). - Every edge has a note explaining why the relationship exists.
- There are no cycles. Piyaz rejects those automatically.
Approve
You approve the breakdown before anything is written. New tasks land as drafts, ready to plan.
Check the result at any time:
show me the project overviewThe tasks also appear in the web app, under the task workspace and Graph mode, so you can watch the graph fill in.
Decomposition Principles
Good decomposition follows these guidelines:
- Right granularity: Each task should take an agent 1-3 tool calls to plan and a focused session to implement. Too small = overhead. Too big = hard to track.
- Clear boundaries: A task's description should make it clear where the work starts and ends.
- Explicit dependencies: If task A needs something from task B, add the edge. Don't rely on implicit ordering.
- Edge notes matter: Notes propagate to agent context. "Needs the auth middleware endpoint URL" is better than no note.
Missing dependencies are the most common decomposition mistake. If an agent starts a task and discovers it needs code that doesn't exist yet, the dependency was missed. Run /piyaz:manage to audit the graph for blockers and missing edges.