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 dependencies

Check the state of the project at any time:

show me the project overview

The tasks also appear in the web app, under the task workspace and Graph mode, so you can watch the graph fill in.

decompose, decompose-feature, decompose-task

Piyaz has three decomposition commands for three situations. The /piyaz skill routes to the right one on its own; the explicit commands (Claude Code) let you call it directly.

• /piyaz:decompose turns a project that has a description but few or no tasks into its initial graph. Use it once, at the start, after brainstorming produces a brief.
• /piyaz:decompose-feature adds a new feature or capability to a project that is already active. It reuses the project's existing categories and tag vocabulary, creates a cluster of roughly 5 to 20 tasks, and wires edges both inside the cluster and into the tasks already in the graph. It does not change the project's status.
• /piyaz:decompose-task splits a single task that grew too big, larger than about 13 points of work. It breaks the parent into two or more children, rewires every dependency edge that touched the parent, and cancels the parent with a rationale that points to its children. Composer also calls this on its own when its research flags a task as oversize.

When in doubt, describe what you want to /piyaz and let it pick. For a wider audit of an existing graph rather than a new decomposition, use /piyaz:manage.

Decomposition Principles

Good decomposition follows these guidelines:

• Right granularity: Each task should take roughly 1 to 4 hours, a focused session, to implement. Smaller than about 30 minutes adds overhead; much larger is hard to track and should be split.
• 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.

Useful prompts

Decompose a feature, edges first, so it wires into what already exists:

/piyaz:decompose-feature add password reset by email. Design the tasks and their
edges first, including edges into existing tasks. Explore the codebase so the tasks
match how the app actually works, and write a clear note on every edge.

Connect new work to the graph instead of duplicating it:

do not decompose this. Connect it to the existing DEMO task if a relation already
exists. Use /piyaz:manage if the graph needs a wider look.

Split a task that grew too big:

/piyaz:decompose-task DEMO-7 is too big. Split it into smaller tasks, rewire the
edges into the children, and cancel the original with a note pointing to them.

Re-ground a task that may have drifted, then plan it:

refine DEMO-12. Re-check the plan against what shipped and re-plan if it no longer
reflects the codebase. Then write the implementation plan and save it to the task.