kryptobaseddev/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]

Size Guidelines (NOT Time)

| Type | Size | Scope | |------|------|-------| | Epic | large | 8+ files, multiple features | | Task | medium | 3-7 files, single feature | | Subtask | small | 1-2 files, single function |

---

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 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. See MANIFEST.jsonl for summary."
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.