/ct-epic-architect

name: ct-epic-architect
description: Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. Provides dependency analysis, wave-based parallel execution planning, hierarchy management, and research linking. Use when creating epics, decomposing initiatives into task trees, planning parallel workflows, or analyzing task dependencies. Triggers on epic creation, task decomposition requests, or planning phase work.
version: 3.0.4
protocol: decomposition
adrRefs:
  - ADR-066
  - ADR-073
dependencies: []
sharedResources:
  - subagent-protocol-base
  - task-system-integration
compatibility:
  - claude-code
  - cursor
  - windsurf
  - gemini-cli
license: MIT
metadata:
  version: 3.0.4
  tier: on-demand
  install: harness
  covers:
    - packages/core/src/validation/protocols/cant/decomposition.cant
    - packages/core/src/validation/protocols/protocols-markdown/decomposition.md
  loomStage: decomposition
  lastReviewed: 2026-09-30
  stability: stable

Epic Architect Context Injection

**Protocol**: @src/protocols/decomposition.md **Type**: Context Injection (cleo-subagent) **Version**: 3.0.0

---

Purpose

Context injection for epic planning and task decomposition tasks spawned via cleo-subagent. Provides domain expertise for breaking down large initiatives into atomic, executable tasks.

---

Capabilities

1. **Epic Creation** - Parent epic with full metadata and file attachments 2. **Task Decomposition** - Atomic tasks with acceptance criteria 3. **Dependency Analysis** - Wave-based parallel execution planning 4. **Research Linking** - Connect research outputs to tasks 5. **HITL Clarification** - Ask when requirements are ambiguous

---

Task System Integration

@skills/_shared/task-system-integration.md

Execution Sequence

1. Read task: `cleo show {{TASK_ID}}` 2. Start task: `cleo start {{TASK_ID}}`. If `cleo start` fails with `E_SESSION_UNBOUND` (spawned workers and subagents are already bound), run `cleo session start --scope global --name "<name>"` or `cleo session resume <id>` first. 3. Check existing work: `cleo find "keyword"`, `cleo list --type epic` 4. Create epic and child tasks 5. Attach files and link research 6. Start session: `cleo session start --scope epic:{{EPIC_ID}} --name "<what you are doing>"` 7. Complete task: `cleo complete {{TASK_ID}}`

---

Requirements Analysis

**MUST check for related work BEFORE creating:**

cleo find "auth" --status pending       # Related tasks
cleo list --type epic --status pending  # Existing epics
cleo phase show                         # Current phase
cleo list --tree --parent T001          # Hierarchy view

---

Epic Structure

Epic (type: epic, size: large)
├── Task 1 (no deps)           [Wave 0]
├── Task 2 (depends: T1)       [Wave 1]
├── Task 3 (depends: T1)       [Wave 1]  ← Parallel
├── Task 4 (depends: T2,T3)    [Wave 2]  ← Convergence
└── Task 5 (depends: T4)       [Wave 3]

Tier Sizing & Scope (canonical source: ADR-073 §1.1)

**DO NOT redefine here.** The strict definitions live in `.cleo/adrs/ADR-073-above-epic-naming.md` §1.1 (tier table) + §1.2 (8 invariants I1–I8) + §1.3 (lifecycle decision table).

Quick reference for decomposition:

| Tier | Scope-of-change | Sizing | |---------|----------------------------------------------------|----------------------------------------------------| | Saga | Theme grouping ≥2 Epics across ≥2 releases | ≥2 child Epics | | Epic | One releasable slice; ≥1 PR to `main` | 4–10 child Tasks | | Task | One atomic PR-sized change; single wave | 1–7 child Subtasks (or leaf); single PR | | Subtask | One commit; ≤2 files OR one module boundary | 1 commit; contributes to parent Task's single PR |

**I8 (load-bearing):** A Task ships as exactly ONE PR. Multiple Subtasks contribute commits to that single PR. Subtasks never own a PR — if a unit warrants its own PR, it MUST be a Task. When decomposing, ask: "does this unit need its own PR?" → Task. "Is this a commit inside a larger PR?" → Subtask.

Above-Epic: Sagas (PM-Core V2 — ADR-088)

A **Saga** groups multiple Epics into a multi-release theme. Use a Saga when the work spans more than one releasable Epic and you want a stable handle for rollup/reporting. A Saga uses `type='saga'` (NOT `label='saga'`) — it is a peer type discriminator at the top of the parent ladder. All IDs are stored as `T####`; prefixes (`SG-`, `E-`) are display-only. Saga membership uses `parent_id` containment (NOT `task_relations.groups`).

cleo saga create --title "Auth Modernization" --description "..." --acceptance "ac1|ac2|ac3|ac4|ac5"
# returns SG-id (stored as T#### with type=saga)
cleo saga add <sagaId> <epicId>          # sets epic.parent_id = sagaId (containment edge)
cleo saga members <sagaId>               # returns members via parent_id containment
cleo saga rollup <sagaId>                # aggregates child statuses + completionPct

---

Epic Creation

Create Epic with File Attachments

cleo add "Auth System Implementation" \
  --type epic --size large --priority high --phase core \
  --labels "feature,auth,v1.0" \
  --description "Complete authentication with JWT and session management" \
  --acceptance "All child tasks completed" \
  --acceptance "Integration tests pass" \
  --files "docs/auth-spec.md,docs/api-design.md" \
  --notes "Initial planning: JWT chosen for stateless API support"

Create Tasks with Dependencies

# Wave 0: No dependencies
cleo add "Create auth schema" \
  --type task --size medium --priority high \
  --parent T001 --phase setup \
  --description "Define user, session, and token tables" \
  --acceptance "Schema validates against requirements" \
  --files "src/db/schema.ts"

# Wave 1: Depends on W