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 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

Method	Use Case	Storage
--files	Input context (specs, designs, code)	Task .files array
research link	Output artifacts (research findings)	Task .linkedResearch array

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

Constraint	Value	Enforcement
Max depth	3	epic (0) → task (1) → subtask (2)
Max active siblings	8 (default)	hierarchy.maxActiveSiblings
Max siblings	unlimited (default)	hierarchy.maxSiblings=0
Parent must exist	Validated	cleo exists {{PARENT_ID}}

Validation Before Creation:

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

---

Wave Planning

Wave	Description	Execution
Wave 0	No dependencies	Start immediately
Wave 1	Depends on Wave 0	Parallel within wave
Wave N	Depends on prior waves	Convergence points

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

Phase	Purpose
setup	Schema, config, structure
core	Features, components
testing	Tests, validation
polish	Docs, optimization
maintenance	Fixes, updates

cleo phase show                              # Current phase
cleo phase show                              # Current phase (slug)
cleo list --phase <slug>                     # Tasks in that 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 record decomposition with cleo docs add {{TASK_ID}} --content - --type plan --slug {{TOPIC_SLUG}} (never a raw file under .cleo/agent-outputs/)
2. MUST record ONE manifest entry: cleo manifest append --entry '<entry JSON>' (the flat manifest file is retired, ADR-027)
3. MUST return ONLY: "Decomposition complete. Manifest appended to pipeline_manifest."
4. MUST NOT return full decomposition in response

---

Extended References

Reference	Content
patterns.md	Research, Bug, Brownfield, Refactor patterns
commands.md	Complete CLEO command reference
shell-escaping.md	Escape $ as \$ in notes
feature-epic-example.md	Greenfield feature
refactor-epic-example.md	Brownfield modernization

---

Anti-Patterns

Anti-Pattern	Solution
Too large tasks	Atomic (one agent session)
Missing Wave 0	At least one no-dependency task
Circular deps	Analyze data flow
Depth > 3	Flatten hierarchy
Missing acceptance	Add --acceptance
Time estimates	Use size only

---

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

Exit	Meaning	Fix
4	Not found	cleo find to verify
10	Parent missing	cleo exists {{ID}}
11	Depth exceeded	Flatten (epic→task→subtask max)
12	Sibling limit	Split to different parent
6	Validation	Escape $ as \$, check fields

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.