@cleocode/cleo 2026.3.4 → 2026.3.7

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

@@ -1,352 +0,0 @@
-# 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

@@ -1,344 +0,0 @@
-# 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*