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

Read(phase_doc_path)

Read(north_star_path)

Write(file_path, content)

Beads (Task Tracking)

bd create --title "..." --body "..."

bd create --parent <id> --title "..."

bd dep add <child> <blocker>

bd list --json

BV (Graph Intelligence)

bv --robot-suggest

bv --robot-plan

bv --robot-alerts

Sub-Bead Suffix Convention

.1

.2-.3

.4-.8

.9

.10

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

agents/understand.md

agents/manifest.md

agents/create-beads.md

agents/dependencies.md

agents/validate.md

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

phase_doc_path

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.

.1

.2-.3

.4-.8

.9

.10

Example: For epic

user-auth

• 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

• 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