| name | planning-and-task-breakdown |
| description | Breaks work into ordered, parallel-dispatchable tasks with an execution DAG. Output format is consumable by CI matrices and parallel agent runners — each task has a stable ID, declared file writes, conflict edges, and branch suffix. Use when you have a spec, brief, or shaper output and need to decompose it into implementable units. Use when a task feels too large, when scope spans multi-repo or multi-week work, or when parallel execution across multiple agents is on the table. |
| when_to_use | Use after a `prompt-shaper` or `marketing-shaper` brief when the work spans multiple repos, multiple weeks, or needs parallel agent execution — specifically when the implementation order is not obvious or tasks can safely be dispatched concurrently. Use when a spec or task feels too large to start in one session.
Not when: the change is single-file with obvious scope — implement it directly. Not when the work has not yet been shaped into a brief — use `prompt-shaper` first. Not when there is no spec yet and requirements are unclear — produce the spec first, then return to decompose it.
|
| compatibility | Requires Bash (Python 3 where scripts are invoked). Works in Claude Code and Codex via install.sh. |
Planning and Task Breakdown
Decompose work into small, verifiable tasks with a parallel-dispatchable structure. The output is a plan document — never code — that downstream runners (CI matrices, single-agent execution sessions) consume to do the work.
When to use
- After a
/shape brief covering multi-repo, multi-week, or multi-slice work
- When a spec or task feels too large to start in one session
- When work needs to parallelize across agents or sessions
- When implementation order isn't obvious
When not to use. Single-file changes with obvious scope, or specs that already contain well-defined tasks.
The planning process
- Plan mode. Read in read-only mode. Map dependencies, note risks. Do not write code during planning.
- Identify the dependency graph. Bottom-up — foundations first.
- Slice vertically. Each task is a feature path through every layer it needs (schema + API + UI), not a horizontal layer of the system. Horizontal slicing produces half-finished branches.
- Write task blocks. Each task is YAML frontmatter (id, depends_on, parallel_safe, conflicts_with, files_write, files_read, branch_suffix, scope) plus prose (description, acceptance, verification). Format and field semantics:
references/task-block-format.md.
- Order and checkpoint. Phases are presentational; the DAG is the execution order. Checkpoints are synchronization barriers — dispatch pauses until they clear.
- Declare the Execution DAG. Top-of-document summary of edges using
→ and ||. Format and dispatcher contract: references/execution-dag.md.
Universal rules
- Stable IDs, never renumbered. Use content-based slugs (
T-auth-schema). Renumbering breaks every reference. Retire dropped IDs rather than reusing them.
files_write is authoritative, not advisory. The dispatcher uses it for conflict detection. Under-declare → parallel collisions; over-declare → false serialization.- The DAG is a summary, not the source of truth. Per-task
depends_on is authoritative. The verification checklist enforces that they agree.
- Day-zero ready set must be non-empty. At least one task has
depends_on: []. If none do, the plan is malformed.
scope: L must be split before dispatch. Agents perform best on XS / S / M.- Plan, do not implement. This skill never writes code. The output is a plan document; execution is a separate step.
- Every plan carries a
**Status:** line. Lifecycle proposed → in-progress → shipped | superseded. A fresh plan starts at proposed; keep it current as the work moves. It is the signal for retiring completed plans (prune shipped/superseded plans manually), so an unmarked plan never gets recognized as done. See assets/plan-document-template.md.
References
Verification
Before starting implementation, confirm:
