Decompose Task

Decompose Task — Orchestrator

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

Pattern: This skill uses the orchestrator-subagent pattern. Each phase runs in a fresh context to prevent "context bombing" on large phases. See docs/guides/ORCHESTRATOR_SUBAGENT_PATTERN.md.

When This Applies

Tool Reference

File Operations

Beads (Task Tracking)

BV (Graph Intelligence)

Sub-Bead Suffix Convention

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                  DECOMPOSE-TASK 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

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

If too large → decompose further.

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

• bead-workflow/ — Bead lifecycle
• .claude/templates/planning/ — Templates
• docs/workflow/DECOMPOSITION.md — Full guide