Wf Spec Breakdown

---
name: wf-spec-breakdown
description: Split one spec into children — sub-design specs when questions are still open, or implementation-ready leaves when the plan is clear. Picks the mode from the spec's lifecycle state unless told otherwise. Writes new spec files and indexes them on the parent. Use when a spec is too large to build in one pass.
argument-hint: <spec-file.md> [design|tasks]
allowed-tools: Read, Grep, Glob, Edit, Write, Agent, Bash(ls *), Bash(mkdir *)
---

# Break Down Spec

Decompose a spec into smaller child specs. The output is either **design specs**
(sub-design problems that need further iteration) or **implementation tasks**
(leaf specs ready to dispatch to the board).

## Step 0: Parse arguments and determine mode

$ARGUMENTS has the form: `<spec-file.md> [design|tasks]`

- The **first token** is the spec file path.
- The optional **second token** is an explicit mode override: `design` or `tasks`.

If no mode is given, determine it from the spec's lifecycle state:

- `vague` or `drafted` with unresolved open questions → **design** mode.
  The spec's design problems need further exploration before implementation.
- `validated` with a clear implementation plan → **tasks** mode.
  The design is settled; decompose into implementable leaf specs.
- `stale` → warn the user and suggest `/wf-spec-refine` first.
- `complete` → warn the user; completed specs don't normally need breakdown.

If the heuristic is ambiguous (e.g., `drafted` but the spec has a detailed
implementation plan), ask the user which mode to use.

## Step 1: Read the spec and context

1. Read the spec file in full.
2. **Parse YAML frontmatter** — extract `title`, `status`, `depends_on`,
   `affects`, `effort`, `created`, `updated`, `author`, `dispatched_task_id`.
3. **Check dependencies** — for each path in `depends_on`, read that spec's
   frontmatter and confirm its `status` is `complete`. Report any incomplete
   blockers. (In design mode, incomplete dependencies are a warning; in tasks
   mode, they are a stronger signal that the breakdown may be premature.)
4. Read `specs/README.md` to understand track organization and dependency graph.
5. Use the `affects` list to identify the primary code files and packages.
6. Identify the spec's structure: design problems, implementation plan, phases,
   existing breakdown.

## Step 2: Explore the codebase

For each major area the spec touches, explore the codebase to understand:

- What files will be created or modified
- What existing patterns, types, and interfaces are relevant
- What test patterns exist in those packages
- Whether any items are already partially implemented

Use Agent subagents (Explore type) for thorough codebase exploration. Launch up
to 3 in parallel for independent areas.

## Step 3: Design the breakdown

### Design mode

Identify the distinct design problems embedded in the spec. Each child should:

- Focus on **one design problem** — a single architectural decision, interface
  design, data model, protocol, UX flow, or integration concern
- Be **explorable independently** — the user can iterate on this sub-design
  without needing to resolve other sub-designs first (though dependencies are
  allowed)
- Contain **open questions** that need resolution before implementation

Guidelines for identifying design boundaries:
- Separate concerns that touch different subsystems or packages
- Separate decisions that have independent trade-offs
- Separate user-facing design (UX, API surface) from internal design (data
  model, algorithms)
- Separate integration concerns (how components connect) from component design

Order by: (1) dependency flow, (2) risk — uncertain or high-impact decisions
earlier, (3) incremental understanding — earlier designs build foundations for
later ones.

### Tasks mode

Break the spec into discrete, implementable tasks. Each child should:

- Be completable in a single commit
- Leave the project in a working state (tests pass)
- Have clear boundaries (what to change, what NOT to change)
- Include specific test requirements

Sizing guidelines:
- **Small** (~50-100 lines changed): add a type, method, or field
- **Medium** (~100-300 lines): refactor a function, add a new file with tests
- **Large** (~300+ lines): multi-file refactor, complex feature

Prefer smaller tasks. If a task feels large, split it further.

Order so dependencies flow forward (no task depends on a later task). Maximize
parallelism — tasks without mutual dependencies should be independent.

## Step 4: Create the child spec folder and files

Per the spec document model, child specs live in a subdirectory named after the
parent. For example, breaking down `specs/local/desktop-app.md` creates children
in `specs/local/desktop-app/`.

1. Create the subdirectory if it doesn't exist.
2. Create one markdown file per child, using descriptive names (no numeric
   prefixes — execution order comes from `depends_on`, not filenames).

### Design mode child template

````markdown
---
title: <Descriptive title of the design problem>
status: drafted
depends_on:
  - <relative path to sibling spec if ordering matters, or empty list>
affects:
  - <code paths / packages this design will govern>
effort: <small | medium | large | xlarge>
created: <today>
updated: <today>
author: <from parent spec>
dispatched_task_id: null
---

# <Title>

## Design Problem

<Clear statement of the single design problem this spec addresses. What
decision needs to be made? What are the constraints? Why can't this be
resolved trivially?>

## Context

<Relevant codebase context, existing patterns, related specs, prior art.
What does the reader need to know to reason about this problem?>

## Options

<At least two concrete approaches, each with pro/con analysis. Include
enough detail that the user can make an informed decision or direct the
agent to explore further.>

## Open Questions

<Specific questions that need resolution before this design can move to
`validated` and be broken into implementation tasks. Each question should
be answerable — avoid vague "what should we do?" in favor of "should X
use approach A or B, given constraint C?">

## Affects

<Which parts of the codebase this design governs, and how the design
decision will ripple into implementation.>
````

Key properties: status is `drafted` (needs iteration), body has Options and
Open Questions, `dispatched_task_id` is always `null` (non-leaf).

### Tasks mode child template

````markdown
---
title: <Descriptive title>
status: validated
depends_on:
  - <relative path to sibling spec, or empty list>
affects:
  - <files/directories this task will create or modify>
effort: <small | medium | large | xlarge>
created: <today>
updated: <today>
author: <from parent spec>
dispatched_task_id: null
---

# <Title>

## Goal

<1-2 sentences explaining what this task achieves and why>

## What to do

<Numbered list of specific implementation steps with file paths,
function names, and code patterns. Include pseudocode for non-obvious
changes.>

## Tests

<Bulleted list of specific test cases to write, with test function
names and what they verify>

## Boundaries

<Bulleted list of what NOT to change in this task — helps scope the
work and prevents task creep>
````

Key properties: status is `validated` (ready to dispatch), body has Goal,
What to do, Tests, Boundaries.

**Important for both modes:** Use `depends_on` with full relative paths from
the repo root (e.g., `specs/local/desktop-app/sandbox-interface.md`) to express
ordering. Do not use task numbers.

## Step 5: Verify the breakdown

Check that:
- Every item from the spec's plan is covered by at least one child
- No circular dependencies exist in the `depends_on` DAG
- The dependency graph allows parallel execution where possible
- All `depends_on` paths resolve to existing spec files
- Each child's `affects` paths are plausible

Additional checks for tasks mode:
- Each child's "What to do" references real file paths and function names
- Leaf specs are small enough for one agent task (2-5 files, one clear goal)

## Step 6: Index the breakdown on the parent spec

Append or update a breakdown section on the parent spec.

### Design mode: `## Design Breakdown`

````markdown
## Design Breakdown

| # | Sub-design | Design problem | Depends on | Effort | Status |
|---|-----------|---------------|-----------|--------|--------|
| 1 | [Sandbox interface](desktop-app/sandbox-interface.md) | How to abstract container backends | — | medium | drafted |
| 2 | [Window lifecycle](desktop-app/window-lifecycle.md) | Native window create/destroy | — | large | drafted |
| 3 | [IPC protocol](desktop-app/ipc-protocol.md) | Communication between shell and webview | sandbox-interface | medium | drafted |

```mermaid
graph LR
  A[Sandbox interface] --> C[IPC protocol]
  B[Window lifecycle] --> D[Build pipeline]
  C --> D
```

**Recommended iteration order:** Start with #1 and #2 in parallel — they
are independent. Then #3 once the sandbox interface is settled.
````

The `#` column provides a recommended reading/iteration order (suggestion, not
constraint). The `depends_on` DAG is the actual constraint.

### Tasks mode: `## Task Breakdown`

````markdown
## Task Breakdown

| Child spec | Depends on | Effort | Status |
|------------|-----------|--------|--------|
| [Define interface](sandbox-backends/define-interface.md) | — | small | validated |
| [Local backend](sandbox-backends/local-backend.md) | define-interface | medium | validated |
| [Refactor launch](sandbox-backends/refactor-launch.md) | local-backend | small | validated |

```mermaid
graph LR
  A[Define interface] --> B[Local backend]
  B --> C[Refactor launch]
```
````

Use relative links from the parent spec to the child spec files. If the parent
already has a breakdown section, replace its contents.

## Step 7: Commit

Stage the new folder, child spec files, and the updated parent spec. Commit:

- Design mode: `specs: break down <spec-name> into sub-design specs`
- Tasks mode: `specs: break down <spec-name> into implementable tasks`

Do NOT push unless the user explicitly asks.

## Step 8: Summary

Report to the user:
- Mode used (design or tasks) and why
- Total number of child specs created
- The dependency graph and parallelism opportunities
- Any spec items intentionally excluded and why
- Suggested next steps:
  - Design mode: "Iterate on sub-designs, then `/wf-spec-breakdown <child> tasks`
    when each is validated"
  - Tasks mode: "Run `/wf-spec-review-breakdown <spec>` to validate, then dispatch"