ct-epic-architect

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}}
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}} --auto-start
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:

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 Wave 0
cleo add "Implement JWT middleware" \
  --type task --size medium --priority high \
  --parent T001 --phase core --depends T002 \
  --description "Token generation, validation, refresh" \
  --acceptance "All token operations tested"

# Wave 2: Convergence
cleo add "Integration tests" \
  --type task --size medium --priority high \
  --parent T001 --phase testing --depends T003,T004 \
  --acceptance "E2E auth flow tests pass"

Link Research to Tasks

# Link existing research output to task
cleo research link T001 research-auth-patterns-20260126

# View linked research
cleo show T001  # Shows .linkedResearch array

---

File Attachment Patterns

When to Use --files vs Research Link

Attach Files During Creation

cleo add "Implement auth" --files "spec.md,design.md"

Append Files to Existing Task

cleo update T001 --files "additional-context.md"

---

Hierarchy Constraints

Validation Before Creation:

cleo exists T001 --quiet || echo "ERROR: Parent not found"
cleo list --parent T001 --status pending,active | jq '.tasks | length'

---

Wave Planning

Dependency Rules

1. No circular dependencies (A→B→C→A invalid)
2. Wave siblings are independent (no cross-dependencies)
3. Convergence depends on ALL branches

---

Phase Assignment

cleo phase show                              # Current phase
cleo list --phase $(cleo phase show -q)      # Tasks in phase

---

HITL Clarification

Ask when:

• Requirements ambiguous
• Multiple valid approaches
• Missing context
• Scope unclear

Template:

Before proceeding, I need clarification:
1. [Question about scope]
2. [Question about constraints]

Options:
A. [Option with trade-offs]
B. [Option with trade-offs]

Recommendation: [Your recommendation]

---

Subagent Protocol

@skills/_shared/subagent-protocol-base.md

Output Requirements

1. MUST write decomposition to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
2. MUST append ONE line to: {{MANIFEST_PATH}}
3. MUST return ONLY: "Decomposition complete. Manifest appended to pipeline_manifest."
4. MUST NOT return full decomposition in response

---

Extended References

---

Anti-Patterns

---

Completion Checklist

• Checked existing work (cleo find, cleo list --type epic)
• Phase verified (cleo phase show)
• Epic created with priority, phase, acceptance
• Tasks with dependencies, no circular deps
• Wave 0 exists (at least one no-deps task)
• Hierarchy: depth ≤ 3, siblings ≤ 8 active
• Files attached where relevant
• Session started scoped to epic

---

Error Handling

Shell Escaping: Always \$ in --notes/--description. See shell-escaping.md.

---

See also / References

This skill binds to the decomposition LOOM lifecycle stage. Governing ADRs:

• ADR-066 — task taxonomy consolidation — defines the Type/Kind/Severity axes the decomposer must populate on every leaf task.
• ADR-073 — above-epic naming — defines the Saga/Epic/Task/Subtask hierarchy that decomposition produces.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.