@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/protocols/decomposition.md

@@ -0,0 +1,352 @@
+# Decomposition Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Epic Planning | "epic", "project", "initiative" | Large scope work |
+| Breakdown | "decompose", "break down", "split" | Task subdivision |
+| Planning | "plan", "roadmap", "phases" | Work organization |
+| Analysis | "scope", "estimate complexity" | Size assessment |
+
+**Explicit Override**: `--protocol decomposition` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| DCMP-001 | MUST follow MECE principle (Mutually Exclusive, Collectively Exhaustive) |
+| DCMP-002 | MUST map dependencies between tasks |
+| DCMP-003 | MUST respect maximum depth (3 levels: epic > task > subtask) |
+| DCMP-004 | MUST verify atomicity for leaf tasks |
+| DCMP-005 | MUST NOT include time estimates (use size: small/medium/large) |
+| DCMP-006 | MUST include acceptance criteria for each task |
+| DCMP-007 | MUST set `agent_type: "analysis"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| DCMP-010 | SHOULD identify parallel execution opportunities |
+| DCMP-011 | SHOULD flag unclear requirements for HITL |
+| DCMP-012 | SHOULD consider existing task overlap |
+| DCMP-013 | SHOULD assign phase to each task |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| DCMP-020 | MAY propose multiple decomposition options |
+| DCMP-021 | MAY identify risks and mitigations |
+| DCMP-022 | MAY suggest task consolidation |
+
+---
+
+## Output Format
+
+### Hierarchy Structure
+
+```
+EPIC (T001) - Large initiative
+├── TASK (T002) - Coherent unit of work
+│   ├── SUBTASK (T003) - Atomic task (MUST be atomic)
+│   └── SUBTASK (T004) - Atomic task
+├── TASK (T005) - Another unit
+│   └── SUBTASK (T006)
+└── TASK (T007) - Independent task
+```
+
+### Size Definitions
+
+| Size | Scope | Atomicity |
+|------|-------|-----------|
+| `small` | 1-2 files, single concern | MUST be atomic |
+| `medium` | 3-7 files, related concerns | SHOULD be atomic |
+| `large` | 8+ files, multiple concerns | MUST decompose further |
+
+### Atomicity Criteria (6-Point Test)
+
+| # | Criterion | Pass Condition |
+|---|-----------|----------------|
+| 1 | Single File Scope | Affects ≤3 tightly-coupled files |
+| 2 | Single Cognitive Concern | One "thing" to understand |
+| 3 | Clear Acceptance Criteria | Testable completion condition |
+| 4 | No Context Switching | Can complete in one session |
+| 5 | No Hidden Sub-Decisions | All choices made at decomposition |
+| 6 | Programmatic Validation | Result verifiable by code/test |
+
+### Dependency Graph
+
+```json
+{
+  "tasks": [
+    {"id": "T001", "type": "epic", "children": ["T002", "T005", "T007"]},
+    {"id": "T002", "type": "task", "parent": "T001", "children": ["T003", "T004"], "depends": []},
+    {"id": "T003", "type": "subtask", "parent": "T002", "depends": []},
+    {"id": "T004", "type": "subtask", "parent": "T002", "depends": ["T003"]},
+    {"id": "T005", "type": "task", "parent": "T001", "depends": ["T002"]},
+    {"id": "T007", "type": "task", "parent": "T001", "depends": []}
+  ],
+  "waves": [
+    {"wave": 0, "tasks": ["T003", "T007"]},
+    {"wave": 1, "tasks": ["T004"]},
+    {"wave": 2, "tasks": ["T002"]},
+    {"wave": 3, "tasks": ["T005"]}
+  ]
+}
+```
+
+### Wave Computation
+
+Tasks are grouped into waves for parallel execution:
+
+| Wave | Condition | Execution |
+|------|-----------|-----------|
+| 0 | No dependencies | Parallel |
+| 1 | Depends only on wave 0 | Parallel after wave 0 |
+| N | Depends on wave N-1 or earlier | Sequential ordering |
+
+### File Output
+
+```markdown
+# Decomposition: {Epic Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: analysis
+
+---
+
+## Epic Summary
+
+{2-3 sentence summary of the epic scope}
+
+## Task Hierarchy
+
+### T001 - {Epic Title} (epic, large)
+
+**Description**: {Epic description}
+**Phase**: {phase}
+
+#### T002 - {Task Title} (task, medium)
+
+**Description**: {Task description}
+**Depends**: none
+**Phase**: {phase}
+**Acceptance Criteria**:
+- {Criterion 1}
+- {Criterion 2}
+
+##### T003 - {Subtask Title} (subtask, small)
+
+**Description**: {Subtask description}
+**Depends**: none
+**Atomicity**: 6/6 (PASS)
+**Acceptance Criteria**:
+- {Testable criterion}
+
+## Dependency Graph
+
+```mermaid
+graph TD
+    T001[Epic] --> T002[Task A]
+    T001 --> T005[Task B]
+    T002 --> T003[Subtask 1]
+    T002 --> T004[Subtask 2]
+    T003 --> T004
+```
+
+## Wave Analysis
+
+| Wave | Tasks | Parallel Opportunities |
+|------|-------|----------------------|
+| 0 | T003, T007 | 2 tasks parallel |
+| 1 | T004 | Sequential |
+| 2 | T002, T005 | 2 tasks parallel |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk} | {Impact} | {Mitigation} |
+
+## Open Questions
+
+- {Questions requiring HITL resolution}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Decomposition: Epic Title" \
+  --file "YYYY-MM-DD_decomposition.md" \
+  --topics "decomposition,planning,epic" \
+  --findings "12 tasks identified,3 wave parallel plan,2 HITL questions" \
+  --status complete \
+  --task T#### \
+  --actionable \
+  --needs-followup T#### \
+  --agent-type analysis
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| research | Research informs scope understanding |
+| specification | Spec defines task boundaries |
+| implementation | Decomposition feeds implementation order |
+
+### CLEO Integration
+
+```bash
+# Create epic and tasks from decomposition
+cleo add "Epic Title" --type epic --size large
+
+# Add tasks with hierarchy
+cleo add "Task A" --parent T001 --type task --size medium --phase core
+
+# Add subtasks
+cleo add "Subtask 1" --parent T002 --type subtask --size small --phase core
+
+# Set dependencies
+cleo update T004 --depends T003
+```
+
+---
+
+## Example
+
+**Task**: Decompose CLEO Universal Subagent Architecture
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Decomposition: Universal Subagent Architecture" \
+  --file "2026-01-26_subagent-decomposition.md" \
+  --topics "subagent,architecture,decomposition" \
+  --findings "14 tasks identified,4 parallel waves,Base protocol + 7 conditional protocols" \
+  --status complete \
+  --task T2392 \
+  --actionable \
+  --needs-followup T2393,T2394 \
+  --agent-type analysis
+```
+
+---
+
+## Atomicity Validation
+
+### Atomicity Checklist
+
+For each leaf task, verify:
+
+- [ ] **Single Responsibility**: One clear objective
+- [ ] **Completable in 1 session**: No multi-day work
+- [ ] **Testable**: Has clear acceptance criteria
+- [ ] **Mergeable**: Can be PR'd independently
+- [ ] **Reversible**: Can be rolled back if needed
+- [ ] **Dependencies Clear**: Blocking tasks explicit
+
+### Validation Command
+
+**Command** (planned): `cleo atomicity check --epic EPIC_ID`
+
+**Current State**: Available via `validate_decomposition_protocol()` in `lib/protocol-validation.sh`
+
+```bash
+# Programmatic validation
+source lib/protocol-validation.sh
+child_tasks=$(cleo list --parent T2000 --format json | jq -c '.tasks')
+result=$(validate_decomposition_protocol "T2000" "T2000" "$child_tasks" "false")
+```
+
+**Checks**:
+- DCMP-002: No circular dependencies (via hierarchy validation)
+- DCMP-003: Max depth 3 (epic→task→subtask)
+- DCMP-004: Atomicity test (6 criteria above)
+- DCMP-006: Max 7 siblings per parent
+
+### Scoring System
+
+Each leaf task scored on 6 criteria (pass/fail per criterion):
+
+| Score | Interpretation | Action |
+|-------|---------------|--------|
+| 6/6 | Atomic | Proceed |
+| 4-5/6 | Mostly atomic | Review failing criteria |
+| 2-3/6 | Needs refinement | Split or clarify |
+| 0-1/6 | Not atomic | Reject, re-decompose |
+
+**Aggregate Epic Score**: Average of leaf task scores
+
+### Orchestrator Integration
+
+**Pre-Decomposition**:
+- Epic architect validates parent epic exists
+- Checks current depth < 3
+- Verifies sibling count < 7
+
+**Post-Decomposition**:
+- Validates all new tasks meet atomicity criteria
+- Blocks spawn of non-atomic tasks
+- Returns refinement suggestions
+
+### Exit Codes
+
+- `EXIT_PROTOCOL_DECOMPOSITION` (63) - Decomposition protocol violation
+- Common violations: Max siblings exceeded, depth limit exceeded, non-atomic tasks
+
+### Auto-Refinement (Future)
+
+**Planned**: If atomicity score <4/6:
+1. Analyze failing criteria
+2. Suggest task splits
+3. Generate refined decomposition
+4. Re-validate until score ≥4/6
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Time estimates | Cannot predict duration accurately |
+| Non-atomic leaf tasks | Create hidden work |
+| Missing dependencies | Incorrect execution order |
+| Violating depth limit | Complexity explosion |
+| Overlapping scopes (not MECE) | Duplicate work |
+| Skipping atomicity check | Quality regression |
+
+---
+
+*Protocol Version 1.0.0 - Decomposition Protocol*

package/packages/ct-skills/protocols/implementation.md

@@ -0,0 +1,344 @@
+# Implementation Protocol
+
+**Provenance**: @task T3155, @epic T3147
+**Version**: 1.0.1
+**Type**: Conditional Protocol
+**Max Active**: 3 protocols (including base)
+
+---
+
+## Trigger Conditions
+
+This protocol activates when the task involves:
+
+| Trigger | Keywords | Context |
+|---------|----------|---------|
+| Building | "implement", "build", "create", "develop" | New functionality |
+| Coding | "code", "write", "program" | Software creation |
+| Fixing | "fix", "bug", "patch", "repair" | Issue resolution |
+| Enhancement | "improve", "enhance", "optimize" | Existing code |
+
+**Explicit Override**: `--protocol implementation` flag on task creation.
+
+---
+
+## Requirements (RFC 2119)
+
+### MUST
+
+| Requirement | Description |
+|-------------|-------------|
+| IMPL-001 | MUST include tests for new functionality |
+| IMPL-002 | MUST follow project code style conventions |
+| IMPL-003 | MUST include JSDoc/docstring provenance tags |
+| IMPL-004 | MUST verify changes pass existing tests |
+| IMPL-005 | MUST document breaking changes |
+| IMPL-006 | MUST write implementation summary to manifest |
+| IMPL-007 | MUST set `agent_type: "implementation"` in manifest |
+
+### SHOULD
+
+| Requirement | Description |
+|-------------|-------------|
+| IMPL-010 | SHOULD add inline comments for complex logic |
+| IMPL-011 | SHOULD refactor duplicated code |
+| IMPL-012 | SHOULD update related documentation |
+| IMPL-013 | SHOULD consider error handling edge cases |
+
+### MAY
+
+| Requirement | Description |
+|-------------|-------------|
+| IMPL-020 | MAY propose architectural improvements |
+| IMPL-021 | MAY add performance benchmarks |
+| IMPL-022 | MAY suggest follow-up enhancements |
+
+---
+
+## Output Format
+
+### Provenance Tags
+
+**JavaScript/TypeScript**:
+```javascript
+/**
+ * @task T####
+ * @session session_YYYYMMDD_HHMMSS_######
+ * @agent opus-1
+ * @date YYYY-MM-DD
+ * @description Brief description of the function
+ */
+function implementedFunction() {
+    // Implementation
+}
+```
+
+**Bash**:
+```bash
+# =============================================================================
+# Function: function_name
+# Task: T####
+# Session: session_YYYYMMDD_HHMMSS_######
+# Agent: opus-1
+# Date: YYYY-MM-DD
+# Description: Brief description
+# =============================================================================
+function_name() {
+    # Implementation
+}
+```
+
+**Python**:
+```python
+def implemented_function():
+    """
+    Brief description.
+
+    Task: T####
+    Session: session_YYYYMMDD_HHMMSS_######
+    Agent: opus-1
+    Date: YYYY-MM-DD
+    """
+    # Implementation
+```
+
+### Test Requirements
+
+| Test Type | When Required | Coverage |
+|-----------|---------------|----------|
+| Unit | New functions | MUST cover happy path |
+| Integration | New workflows | SHOULD cover end-to-end |
+| Edge Case | Complex logic | SHOULD cover boundaries |
+| Regression | Bug fixes | MUST reproduce issue |
+
+### Code Style Checklist
+
+| Language | Style Guide | Enforcement |
+|----------|-------------|-------------|
+| Bash | CLEO style (4 spaces, snake_case) | `shellcheck` |
+| JavaScript | ESLint config | `eslint` |
+| TypeScript | TSConfig strict | `tsc --noEmit` |
+| Python | PEP 8 | `flake8`, `black` |
+
+### File Output
+
+```markdown
+# Implementation: {Feature/Fix Title}
+
+**Task**: T####
+**Date**: YYYY-MM-DD
+**Status**: complete|partial|blocked
+**Agent Type**: implementation
+
+---
+
+## Summary
+
+{2-3 sentence summary of implementation}
+
+## Changes
+
+### Files Modified
+
+| File | Action | Description |
+|------|--------|-------------|
+| `path/to/file.sh` | Modified | Added validation function |
+| `path/to/new.sh` | Created | New utility module |
+
+### Functions Added
+
+| Function | File | Purpose |
+|----------|------|---------|
+| `validate_input()` | file.sh | Input validation |
+
+### Functions Modified
+
+| Function | File | Change |
+|----------|------|--------|
+| `process_data()` | file.sh | Added error handling |
+
+## Tests
+
+### New Tests
+
+| Test | File | Coverage |
+|------|------|----------|
+| `test_validate_input` | tests/unit/file.bats | Input validation |
+
+### Test Results
+
+```
+Running tests/unit/file.bats
+ ✓ validate_input accepts valid input
+ ✓ validate_input rejects empty input
+ ✓ validate_input handles special characters
+
+3 tests, 0 failures
+```
+
+## Validation
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Tests pass | PASS | All 42 tests pass |
+| Lint clean | PASS | No shellcheck warnings |
+| No regressions | PASS | Existing tests unchanged |
+
+## Breaking Changes
+
+{If any, document migration path}
+
+## Follow-up
+
+- {Suggested improvements}
+- {Technical debt items}
+```
+
+### Manifest Entry
+
+@skills/_shared/manifest-operations.md
+
+Use `cleo research add` to create the manifest entry:
+
+```bash
+cleo research add \
+  --title "Implementation: Feature Name" \
+  --file "YYYY-MM-DD_implementation.md" \
+  --topics "implementation,feature" \
+  --findings "3 functions added,Tests passing,No breaking changes" \
+  --status complete \
+  --task T#### \
+  --not-actionable \
+  --agent-type implementation
+```
+
+---
+
+## Integration Points
+
+### Base Protocol
+
+- Inherits task lifecycle (start, execute, complete)
+- Inherits manifest append requirement
+- Inherits error handling patterns
+
+### Protocol Interactions
+
+| Combined With | Behavior |
+|---------------|----------|
+| specification | Spec defines implementation requirements |
+| contribution | Implementation triggers contribution record |
+| release | Implementation changes tracked for release |
+
+### Workflow Sequence
+
+```
+1. Read task requirements (cleo show T####)
+2. Start task (cleo start T####)
+3. Implement changes with provenance tags
+4. Write/update tests
+5. Run validation (tests, lint)
+6. Document changes in output file
+7. Append manifest entry
+8. Complete task (cleo complete T####)
+9. Return completion message
+```
+
+---
+
+## Example
+
+**Task**: Implement session binding for multi-agent support
+
+**Manifest Entry Command**:
+```bash
+cleo research add \
+  --title "Implementation: Session Binding" \
+  --file "2026-01-26_session-binding-impl.md" \
+  --topics "session,binding,multi-agent" \
+  --findings "TTY binding implemented,Env var fallback added,4 new tests passing" \
+  --status complete \
+  --task T2400 \
+  --epic T2392 \
+  --not-actionable \
+  --agent-type implementation
+```
+
+**Return Message**:
+```
+Implementation complete. See MANIFEST.jsonl for summary.
+```
+
+---
+
+## Provenance Validation
+
+### Pre-Commit Hook
+
+**Location**: `.git/hooks/commit-msg` (installed via `git config core.hooksPath .cleo/hooks`)
+
+**Logic**:
+1. Extract @task tags from commit diff
+2. Count new functions/classes
+3. Calculate provenance coverage
+4. Apply thresholds:
+   - **New code**: 100% coverage required
+   - **Existing code**: 80% coverage required
+   - **Legacy code**: 50% coverage required
+5. Block commit if thresholds not met
+
+**Exit Code**: `EXIT_PROTOCOL_IMPLEMENTATION` (64) on violation
+
+### Runtime Validation
+
+**Command** (planned): `cleo provenance validate [--task TASK_ID]`
+
+**Current State**: Validation available via protocol library
+
+```bash
+# Programmatic validation
+source lib/protocol-validation.sh
+result=$(validate_implementation_protocol "T1234" "$manifest_entry" "false")
+```
+
+**Checks**:
+- IMPL-003: `@task T####` tags in new functions
+- Git diff analysis for provenance coverage
+- Agent type = "implementation" (IMPL-007)
+
+### Thresholds
+
+| Code Category | Provenance Requirement | Rationale |
+|---------------|------------------------|-----------|
+| **New code** | 100% | Fresh code must be attributable |
+| **Existing code** | 80% | Modifications should track origin |
+| **Legacy code** | 50% | Gradual attribution improvement |
+
+**Detection**:
+- New code: Lines with `^+` in git diff, no prior history
+- Existing code: Modified files with prior commits
+- Legacy code: Files >6 months old or >100 commits
+
+### Enforcement Points
+
+1. **Pre-commit**: Blocks commits lacking provenance
+2. **Pre-push**: Warns on aggregate provenance score <70%
+3. **Runtime**: `cleo complete` validates IMPL-003 for implementation tasks
+4. **Orchestrator**: Validates before spawning implementation agents
+
+---
+
+## Anti-Patterns
+
+| Pattern | Why Avoid |
+|---------|-----------|
+| Code without tests | Regression risk |
+| Missing provenance | Lost attribution |
+| Skipping validation | Quality regression |
+| Undocumented breaking changes | Surprise failures |
+| No error handling | Silent failures |
+| Hardcoded values | Maintenance burden |
+
+---
+
+*Protocol Version 1.0.0 - Implementation Protocol*