@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/skills/ct-epic-architect/references/bug-epic-example.md

@@ -0,0 +1,172 @@
+# Bug Epic Example: Data Corruption in User Sessions
+
+This example demonstrates a bug fix epic with severity mapping and root cause analysis.
+
+---
+
+## Scenario
+
+Users report intermittent data loss when switching between tabs. Investigation reveals:
+- Session data corrupted when concurrent requests occur
+- Race condition in session update logic
+- Affects ~5% of users during peak hours
+
+**Severity**: High (core feature broken, workaround difficult)
+
+---
+
+## Step 1: Create the Bug Epic
+
+```bash
+{{TASK_ADD_CMD}} "Fix: Session Data Corruption on Concurrent Requests" \
+  --type epic \
+  --size medium \
+  --priority high \
+  --phase maintenance \
+  --labels "bug,severity:high,session,race-condition" \
+  --description "Fix race condition causing session data corruption when multiple requests occur simultaneously. Root cause: non-atomic session updates. Impact: ~5% of users during peak hours experiencing data loss." \
+  --acceptance "Race condition eliminated" \
+  --acceptance "Session updates atomic" \
+  --acceptance "Regression tests added" \
+  --acceptance "No data corruption in stress test" \
+  --notes "Bug report: SUPPORT-1234. First reported 2026-01-15."
+```
+
+**Annotation**: Priority `high` maps from severity `high`. Labels include `severity:high` for filtering. Phase is `maintenance` for bug fixes.
+
+---
+
+## Step 2: Create Tasks
+
+### Wave 0: Investigation
+
+```bash
+# T1: Root cause analysis (Wave 0)
+{{TASK_ADD_CMD}} "Investigate session corruption root cause" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase maintenance \
+  --labels "investigation,root-cause" \
+  --description "Analyze session handling code, identify race condition triggers, document reproduction steps." \
+  --acceptance "Race condition identified in code" \
+  --acceptance "Reproduction steps documented" \
+  --acceptance "Affected code paths mapped" \
+  --files "src/lib/session/manager.ts,src/lib/session/store.ts"
+```
+
+**Annotation**: Bug epics ALWAYS start with investigation. Never jump to fixing without understanding root cause.
+
+### Wave 1: Fix Implementation
+
+```bash
+# T2: Implement atomic session updates (Wave 1 - depends on T1)
+{{TASK_ADD_CMD}} "Implement atomic session update mechanism" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase maintenance \
+  --depends {{T1_ID}} \
+  --labels "fix,atomic,session" \
+  --description "Replace non-atomic session updates with transaction-based approach using optimistic locking or mutex." \
+  --acceptance "Session updates use transactions" \
+  --acceptance "Concurrent writes handled correctly" \
+  --acceptance "No deadlock scenarios" \
+  --files "src/lib/session/manager.ts,src/lib/session/lock.ts"
+
+# T3: Add session versioning (Wave 1 - depends on T1, parallel with T2)
+{{TASK_ADD_CMD}} "Add session version tracking" \
+  --type task \
+  --size small \
+  --priority medium \
+  --parent {{EPIC_ID}} \
+  --phase maintenance \
+  --depends {{T1_ID}} \
+  --labels "versioning,session,integrity" \
+  --description "Add version field to session schema to detect and reject stale updates." \
+  --acceptance "Version field added to session" \
+  --acceptance "Stale updates rejected with retry hint" \
+  --acceptance "Version increment on each update" \
+  --files "src/lib/session/schema.ts,src/lib/session/manager.ts"
+```
+
+### Wave 2: Regression Testing
+
+```bash
+# T4: Add concurrency regression tests (Wave 2 - depends on T2, T3)
+{{TASK_ADD_CMD}} "Write concurrency regression tests" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase testing \
+  --depends {{T2_ID}},{{T3_ID}} \
+  --labels "testing,regression,concurrency" \
+  --description "Write tests that reproduce the original bug and verify fix under concurrent load." \
+  --acceptance "Test reproduces original race condition" \
+  --acceptance "Test passes with fix applied" \
+  --acceptance "Stress test with 100 concurrent requests" \
+  --files "tests/session-concurrency.test.ts"
+
+# T5: Update documentation (Wave 2 - depends on T2, parallel with T4)
+{{TASK_ADD_CMD}} "Document session handling changes" \
+  --type task \
+  --size small \
+  --priority low \
+  --parent {{EPIC_ID}} \
+  --phase polish \
+  --depends {{T2_ID}} \
+  --labels "docs,session" \
+  --description "Update session handling documentation with new atomic update patterns and versioning." \
+  --acceptance "README updated" \
+  --acceptance "Code comments added" \
+  --files "docs/SESSION.md,src/lib/session/README.md"
+```
+
+---
+
+## Step 3: Start Session
+
+```bash
+{{TASK_SESSION_START_CMD}} \
+  --scope epic:{{EPIC_ID}} \
+  --name "Session Bug Fix" \
+  --agent ct-epic-architect \
+  --auto-start
+```
+
+---
+
+## Dependency Graph
+
+```
+T1 (Investigation)
+├──> T2 (Atomic Updates)
+│    ├──> T4 (Regression Tests)
+│    └──> T5 (Documentation)
+└──> T3 (Versioning)
+     └──> T4 (Regression Tests)
+```
+
+---
+
+## Wave Analysis
+
+| Wave | Tasks | Purpose |
+|------|-------|---------|
+| 0 | T1 | Root cause analysis |
+| 1 | T2, T3 | Fix implementation (parallel) |
+| 2 | T4, T5 | Verification and docs (parallel) |
+
+---
+
+## Bug Severity Mapping Reference
+
+| Severity | Priority | Indicators |
+|----------|----------|------------|
+| Critical | critical | Data loss, security breach, system down |
+| High | high | Core feature broken, workaround difficult |
+| Medium | medium | Feature degraded, workaround exists |
+| Low | low | Cosmetic, edge case, annoyance |

package/packages/ct-skills/skills/ct-epic-architect/references/commands.md

@@ -0,0 +1,201 @@
+# Epic Architect Commands Reference
+
+Complete reference of task system commands for epic creation and management.
+
+---
+
+## Core Task Commands
+
+```bash
+# Create epic
+{{TASK_ADD_CMD}} "Epic Title" --type epic --size large --priority high --phase core \
+  --labels "feature,auth" --description "..." --acceptance "..."
+
+# Create tasks under epic
+{{TASK_ADD_CMD}} "Task Title" --type task --parent {{EPIC_ID}} --depends {{DEP_IDS}} \
+  --priority medium --phase core --description "..." --acceptance "..."
+```
+
+---
+
+## Session Lifecycle
+
+```bash
+# Start session scoped to epic
+{{TASK_SESSION_START_CMD}} --scope epic:{{EPIC_ID}} --name "Epic Development" --agent ct-epic-architect --auto-start
+
+# Suspend session (waiting for external dependency)
+{{TASK_SESSION_SUSPEND_CMD}} --note "Waiting for external dependency"
+
+# Resume session
+{{TASK_SESSION_RESUME_CMD}} {{SESSION_ID}}
+
+# End session (work complete for now)
+{{TASK_SESSION_END_CMD}} --note "Epic completed"
+
+# Close session permanently (all tasks must be done)
+{{TASK_SESSION_CLOSE_CMD}} {{SESSION_ID}}
+
+# List active sessions
+{{TASK_SESSION_LIST_CMD}} --status active
+```
+
+---
+
+## Task Lifecycle (Start/Stop/Current)
+
+```bash
+# Start working on task
+{{TASK_START_CMD}} {{TASK_ID}}
+
+# Show current task
+{{TASK_CURRENT_CMD}}
+
+# Add session progress note
+{{TASK_NOTE_CMD}} "Progress: ..."
+
+# Stop working on task
+{{TASK_STOP_CMD}}
+```
+
+---
+
+## Verification Gates Workflow
+
+After task completion, verification gates track quality:
+
+```bash
+# When coder completes implementation
+{{TASK_COMPLETE_CMD}} {{TASK_ID}}              # Auto-sets gates.implemented
+
+# After testing passes
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate testsPassed
+
+# After QA review
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate qaPassed
+
+# After security scan
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate securityPassed
+
+# After documentation
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate documented
+
+# After cleanup/tech debt addressed (optional, excluded from required by default)
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate cleanupDone
+
+# Set all required gates at once
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --all
+```
+
+**Verification Gates Reference:**
+| Gate | Purpose | Auto-set |
+|------|---------|----------|
+| `implemented` | Code complete | Yes (on `complete`) |
+| `testsPassed` | Tests pass | No |
+| `qaPassed` | QA review done | No |
+| `securityPassed` | Security scan clear | No |
+| `documented` | Documentation complete | No |
+| `cleanupDone` | Cleanup/tech debt addressed | No (optional) |
+
+**Epic Lifecycle States** (available in schema 2.6.1+):
+- States: `backlog` -> `planning` -> `active` -> `review` -> `released` -> `archived`
+- Use `--epic-lifecycle` flag when creating/updating epics with `type: epic`
+- Example: `{{TASK_ADD_CMD}} "Epic Title" --type epic --epic-lifecycle planning`
+
+---
+
+## Query Commands
+
+```bash
+# Find related work
+{{TASK_FIND_CMD}} "{{KEYWORDS}}" --status pending
+
+# Link research to epic
+{{TASK_LINK_CMD}} {{EPIC_ID}} {{RESEARCH_ID}}
+
+# Verify existence before operations
+{{TASK_EXISTS_CMD}} {{ID}} --quiet
+
+# Check phase context
+{{TASK_PHASE_CMD}}
+
+# Task triage and planning
+{{TASK_ANALYZE_CMD}}                     # Task triage with leverage scoring
+{{TASK_ANALYZE_CMD}} --parent {{EPIC_ID}}  # Analyze specific epic's tasks
+
+# Visualize hierarchy
+cleo list --tree --parent {{EPIC_ID}}      # Show epic subtree
+
+# Archive completed work
+{{TASK_ARCHIVE_CMD}}                     # Archive all completed tasks (done status)
+{{TASK_ARCHIVE_CMD}} --include-epic      # Include completed epics
+```
+
+---
+
+## Token Reference
+
+### Task Lifecycle Tokens (CLEO defaults)
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_SHOW_CMD}}` | `cleo show` |
+| `{{TASK_START_CMD}}` | `cleo start` |
+| `{{TASK_COMPLETE_CMD}}` | `cleo complete` |
+| `{{TASK_LINK_CMD}}` | `cleo research link` |
+| `{{TASK_LIST_CMD}}` | `cleo list` |
+| `{{TASK_FIND_CMD}}` | `cleo find` |
+| `{{TASK_ADD_CMD}}` | `cleo add` |
+
+### Epic-Specific Tokens
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_EXISTS_CMD}}` | `cleo exists` |
+| `{{TASK_PHASE_CMD}}` | `cleo phase show` |
+| `{{TASK_TREE_CMD}}` | `cleo list --tree` |
+| `{{TASK_ANALYZE_CMD}}` | `cleo analyze` |
+| `{{TASK_ARCHIVE_CMD}}` | `cleo archive` |
+| `{{TASK_VALIDATE_CMD}}` | `cleo validate` |
+
+### Session Tokens
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_SESSION_START_CMD}}` | `cleo session start` |
+| `{{TASK_SESSION_END_CMD}}` | `cleo session end` |
+| `{{TASK_SESSION_SUSPEND_CMD}}` | `cleo session suspend` |
+| `{{TASK_SESSION_RESUME_CMD}}` | `cleo session resume` |
+| `{{TASK_SESSION_CLOSE_CMD}}` | `cleo session close` |
+| `{{TASK_SESSION_LIST_CMD}}` | `cleo session list` |
+
+### Start/Stop/Current Tokens
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_CURRENT_CMD}}` | `cleo current` |
+| `{{TASK_NOTE_CMD}}` | `cleo note` |
+| `{{TASK_STOP_CMD}}` | `cleo stop` |
+
+### Verification Tokens
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_VERIFY_CMD}}` | `cleo verify` |
+
+### Research Tokens
+
+| Token | CLEO Default |
+|-------|--------------|
+| `{{TASK_RESEARCH_INIT_CMD}}` | `cleo research init` |
+| `{{TASK_RESEARCH_LIST_CMD}}` | `cleo research list` |
+| `{{TASK_RESEARCH_SHOW_CMD}}` | `cleo research show` |
+| `{{TASK_RESEARCH_PENDING_CMD}}` | `cleo research pending` |
+| `{{TASK_RESEARCH_INJECT_CMD}}` | `cleo research inject` |
+
+### Output Tokens
+
+| Token | Default |
+|-------|---------|
+| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` |
+| `{{MANIFEST_PATH}}` | `{{OUTPUT_DIR}}/MANIFEST.jsonl` |

package/packages/ct-skills/skills/ct-epic-architect/references/feature-epic-example.md

@@ -0,0 +1,210 @@
+# Feature Epic Example: User Authentication System
+
+This example demonstrates a greenfield feature epic for implementing a new authentication system.
+
+---
+
+## Scenario
+
+A SvelteKit application needs user authentication with:
+- Email/password login
+- JWT token management
+- Protected routes middleware
+- User session handling
+
+---
+
+## Step 1: Create the Epic
+
+```bash
+{{TASK_ADD_CMD}} "EPIC: User Authentication System" \
+  --type epic \
+  --size large \
+  --priority high \
+  --phase core \
+  --labels "feature,auth,security,v1.0" \
+  --description "Implement complete user authentication with email/password login, JWT tokens, protected routes, and session management. Greenfield implementation following security best practices." \
+  --acceptance "All auth endpoints functional" \
+  --acceptance "JWT tokens generated and validated" \
+  --acceptance "Protected routes middleware working" \
+  --acceptance "Integration tests passing" \
+  --notes "Initial planning: Authentication system for SvelteKit app"
+```
+
+**Annotation**: Epic is `large` because it spans multiple systems (API, middleware, frontend). Phase is `core` because this is primary feature work.
+
+---
+
+## Step 2: Create Tasks with Dependencies
+
+### Wave 0: Foundation (No Dependencies)
+
+```bash
+# T1: Schema and types (Wave 0 - no deps)
+{{TASK_ADD_CMD}} "Define auth schema and types" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase setup \
+  --labels "schema,types,foundation" \
+  --description "Create database schema for users, sessions, and tokens. Define TypeScript types for auth payloads." \
+  --acceptance "User table schema defined" \
+  --acceptance "Session/token types exported" \
+  --acceptance "Zod validation schemas created" \
+  --files "src/lib/db/schema/users.ts,src/lib/types/auth.ts"
+```
+
+**Annotation**: First task has NO dependencies, enabling immediate start. Wave 0 tasks are "entry points" into the epic.
+
+### Wave 1: Core Implementation (Depends on T1)
+
+```bash
+# T2: JWT utilities (Wave 1 - depends on T1)
+{{TASK_ADD_CMD}} "Implement JWT token utilities" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T1_ID}} \
+  --labels "jwt,tokens,security" \
+  --description "Create JWT generation, validation, and refresh functions using jose library." \
+  --acceptance "Token generation function works" \
+  --acceptance "Token validation with expiry check" \
+  --acceptance "Refresh token rotation implemented" \
+  --files "src/lib/auth/jwt.ts,src/lib/auth/tokens.ts"
+
+# T3: Password hashing (Wave 1 - depends on T1, parallel with T2)
+{{TASK_ADD_CMD}} "Implement password hashing" \
+  --type task \
+  --size small \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T1_ID}} \
+  --labels "password,security,bcrypt" \
+  --description "Implement secure password hashing using bcrypt with configurable salt rounds." \
+  --acceptance "Hash function produces valid bcrypt hash" \
+  --acceptance "Verify function compares correctly" \
+  --acceptance "Timing-safe comparison used" \
+  --files "src/lib/auth/password.ts"
+```
+
+**Annotation**: T2 and T3 both depend only on T1, so they can run in PARALLEL. This is a "parallel fork" pattern.
+
+### Wave 2: API Layer (Depends on T2 and T3)
+
+```bash
+# T4: Auth API endpoints (Wave 2 - depends on T2, T3)
+{{TASK_ADD_CMD}} "Create auth API endpoints" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T2_ID}},{{T3_ID}} \
+  --labels "api,endpoints,auth" \
+  --description "Implement /api/auth/register, /api/auth/login, /api/auth/logout, /api/auth/refresh endpoints." \
+  --acceptance "Register endpoint creates user" \
+  --acceptance "Login endpoint returns JWT" \
+  --acceptance "Logout invalidates session" \
+  --acceptance "Refresh endpoint rotates token" \
+  --files "src/routes/api/auth/+server.ts,src/routes/api/auth/[action]/+server.ts"
+```
+
+**Annotation**: T4 is a "convergence point" - it depends on BOTH parallel branches (T2 AND T3). Must wait for both to complete.
+
+### Wave 3: Middleware (Depends on T4)
+
+```bash
+# T5: Protected routes middleware (Wave 3 - depends on T4)
+{{TASK_ADD_CMD}} "Implement protected routes middleware" \
+  --type task \
+  --size medium \
+  --priority medium \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T4_ID}} \
+  --labels "middleware,routes,protection" \
+  --description "Create hooks.server.ts middleware to validate JWT on protected routes and inject user into locals." \
+  --acceptance "Middleware validates JWT" \
+  --acceptance "Unauthenticated requests redirected" \
+  --acceptance "User available in locals" \
+  --files "src/hooks.server.ts,src/lib/auth/middleware.ts"
+```
+
+### Wave 4: Testing (Depends on T5)
+
+```bash
+# T6: Integration tests (Wave 4 - depends on T5)
+{{TASK_ADD_CMD}} "Write auth integration tests" \
+  --type task \
+  --size medium \
+  --priority medium \
+  --parent {{EPIC_ID}} \
+  --phase testing \
+  --depends {{T5_ID}} \
+  --labels "testing,integration,auth" \
+  --description "Write integration tests for complete auth flow: register, login, protected access, logout." \
+  --acceptance "Registration flow test passes" \
+  --acceptance "Login/logout flow test passes" \
+  --acceptance "Protected route test passes" \
+  --acceptance "Token refresh test passes" \
+  --files "tests/auth.test.ts"
+```
+
+---
+
+## Step 3: Start Session
+
+```bash
+{{TASK_SESSION_START_CMD}} \
+  --scope epic:{{EPIC_ID}} \
+  --name "Auth System - Development" \
+  --agent ct-epic-architect \
+  --auto-start
+```
+
+---
+
+## Dependency Graph
+
+```
+T1 (Schema)
+├──> T2 (JWT)
+│    └──> T4 (API)
+└──> T3 (Password)
+     └──> T4 (API)
+          └──> T5 (Middleware)
+               └──> T6 (Tests)
+```
+
+---
+
+## Wave Analysis
+
+| Wave | Tasks | Parallel? | Notes |
+|------|-------|-----------|-------|
+| 0 | T1 | - | Entry point |
+| 1 | T2, T3 | Yes | Both depend only on T1 |
+| 2 | T4 | No | Convergence point |
+| 3 | T5 | No | Sequential |
+| 4 | T6 | No | Final validation |
+
+---
+
+## Critical Path
+
+T1 → T2 → T4 → T5 → T6
+
+(T3 runs parallel to T2, both converge at T4)
+
+---
+
+## Key Design Decisions
+
+1. **Schema First**: T1 defines types before implementation - prevents refactoring
+2. **Parallel Security**: JWT (T2) and password (T3) are independent modules
+3. **API Convergence**: Endpoints (T4) need BOTH modules complete
+4. **Test Last**: Integration tests (T6) run after all implementation done