Decompose

Decompose — Task Breakdown

Break a phase into atomic beads and sub-beads for agent execution.

Design rationale: This skill uses the orchestrator-subagent pattern because decomposition involves substantial cognitive work: understanding the phase, creating a lossless manifest, generating beads, setting dependencies, and validation. The "Create Beads" phase is especially critical—when an agent reads a 1000-line phase doc directly, it summarizes. With subagents, the manifest captures everything first, preventing information loss.

When This Applies

Tool Reference

File Operations

Beads (Task Tracking)

BV (Graph Intelligence)

Sub-Bead Suffix Convention

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    DECOMPOSE ORCHESTRATOR                        │
│  - Creates session: sessions/decompose-{timestamp}/              │
│  - Manages TodoWrite state                                       │
│  - Spawns subagents with minimal context                         │
│  - Passes manifest (not phase doc) to Create Beads phase         │
└─────────────────────────────────────────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Understand     │  │    Manifest     │  │  Create Beads   │
│  agents/        │  │  agents/        │  │  agents/        │
│  understand.md  │  │  manifest.md    │  │  create-beads.md│
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
    01_understanding     02_manifest.md      03_beads_created
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         ▼                    ▼
┌─────────────────┐  ┌─────────────────┐
│  Dependencies   │  │    Validate     │ → Ready for execution
│  agents/        │  │  agents/        │
│  dependencies.md│  │  validate.md    │
└────────┬────────┘  └────────┬────────┘
         │                    │
    04_dependencies      05_validation

Subagents

Why Subagents for Decomposition

The "Create Beads" phase is the most lossy. When an agent reads a 1000-line phase doc directly, it summarizes. With subagents:

Key insight: The manifest becomes the source of truth. Create Beads never reads the original phase doc—it reads the manifest.

Execution Flow

1. Setup (Orchestrator)

1. Create session directory:
   mkdir -p sessions/decompose-{timestamp}

2. Initialize TodoWrite with phases:
   - [ ] Phase 1: Understand
   - [ ] Phase 2: Manifest
   - [ ] Phase 3: Create Beads
   - [ ] Phase 4: Dependencies
   - [ ] Phase 5: Validate

3. Gather inputs:
   - phase_doc_path: Path to phase document
   - north_star_path: Path to North Star Card

2. Phase 1: Understand

Spawn: agents/understand.md

Input:

{
  "phase_doc_path": "PLAN/phase-2.md",
  "session_dir": "sessions/decompose-{timestamp}",
  "north_star_path": "PLAN/00_north_star.md"
}

Output: understanding_path + goals + ambiguities

3. Phase 2: Manifest

Spawn: agents/manifest.md

Input:

{
  "session_dir": "sessions/decompose-{timestamp}",
  "understanding_path": "<from Phase 1>",
  "phase_doc_path": "PLAN/phase-2.md"
}

Output: manifest_path + item counts + gaps

4. Phase 3: Create Beads (CRITICAL)

Spawn: agents/create-beads.md

Input:

{
  "session_dir": "sessions/decompose-{timestamp}",
  "manifest_path": "<from Phase 2>",
  "north_star_path": "PLAN/00_north_star.md",
  "phase_name": "Phase 2: User Auth"
}

CRITICAL: Input is manifest_path, NOT phase_doc_path. The manifest is the lossless source of truth.

Output: beads_created_path + bead IDs

5. Phase 4: Dependencies

Spawn: agents/dependencies.md

Input:

{
  "session_dir": "sessions/decompose-{timestamp}",
  "beads_created_path": "<from Phase 3>"
}

Output: dependencies_path + execution order

6. Phase 5: Validate

Spawn: agents/validate.md

Input:

{
  "session_dir": "sessions/decompose-{timestamp}",
  "dependencies_path": "<from Phase 4>",
  "manifest_path": "<from Phase 2>"
}

Output: validation_path + ready_for_execution

7. Finalize (Orchestrator)

1. Update TodoWrite (all phases complete)
2. If validation failed, report issues
3. Output summary to user

Templates

Located in .claude/templates/planning/:

• content-manifest.md — Pre-decomposition checklist
• sub-bead-structure.md — Standard suffix pattern
• decompose-output.md — Output summary format

1. Understand

Read the phase. Identify:

• Goal
• Components/files
• Dependencies (what must exist first)
• Deliverables (how we know it's done)

If vague → ask for clarification before decomposing.

2. Manifest

Use content-manifest template. List everything:

• Components
• Files to create/modify
• Tests required
• Dependencies
• Acceptance criteria

3. Create Beads

Terminology Clarification

Phase/Epic bead (container for the phase):

bd create "Phase N: <Title>" -t epic -p 1 -d '<description>'

Task beads (the actual work items):

bd create "<Task title>" --parent <phase-id> --priority 1 -d '<Full description>'

Note: Task beads use suffixes .1, .2, etc. for organization. This is DIFFERENT from ADaPT sub-beads which are created when execution fails. See templates/planning/sub-bead-structure.md for ADaPT.

Critical Rules — Bounded. Complete. Verified.

4. Set Dependencies

bd dep add <child-id> <blocker-id> --type blocks

Common pattern:

• Schema (.1) → blocks → Implementation (.2, .3)
• Implementation → blocks → Tests (.4-.8)
• All sub-beads → block → Parent completion

5. Validate

bv --robot-suggest   # Duplicates, missing deps, cycle breaks
bv --robot-plan      # Can work proceed in order?
bv --robot-alerts    # Stale, cascades, drift signals

Fix issues before agents start executing.

Sizing Guidelines

The goal is semantic coherence, not fixed line counts. Can an agent hold the full context without losing track?

If you'd have to guess → the bead isn't ready. If an agent would ask "what should I do here?" → keep decomposing.

When to STOP and Ask

1. Phase too vague — Can't identify concrete deliverables
2. Phase too large — Would result in 20+ sub-beads (split phase)
3. Unclear dependencies — Don't know what must exist first
4. Multiple valid approaches — Need architectural decision first

Task Bead Suffix Convention (Planning-Time)

IMPORTANT DISTINCTION:

• Planning-time task beads (this section): Created upfront when decomposing phases
• ADaPT sub-beads: Created ONLY when execution fails after 3 iterations

Both use the same .1, .2 naming, but serve different purposes. See .claude/templates/planning/sub-bead-structure.md for ADaPT sub-beads.

Example: For epic user-auth (Phase bead):

• user-auth.1 → User model schema (task bead)
• user-auth.2 → JWT validation logic (task bead)
• user-auth.3 → Session management (task bead)
• user-auth.4 → Unit tests for JWT (task bead)
• user-auth.5 → Integration tests (task bead)

If user-auth.2 fails after 3 iterations during execution:

• user-auth.2.1 → ADaPT sub-bead for specific failing component

Anti-Patterns

Output Format

Use decompose-output template. Include:

• Parent bead ID
• Sub-beads table with IDs, titles, estimates, dependencies
• Verification checklist
• Next steps

See Also

• docs/workflow/DISCOVERY.md — Pre-pipeline discovery (where plans come from)
• docs/workflow/DECOMPOSITION.md — Full decomposition guide
• advance/ — Bead lifecycle
• .claude/templates/planning/ — Templates