@cleocode/cleo 2026.2.5 → 2026.2.7

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

@@ -0,0 +1,244 @@
+# Migration Epic Example: Database Schema Migration with Rollback
+
+This example demonstrates a multi-phase migration epic with safety checkpoints and rollback capability.
+
+---
+
+## Scenario
+
+Application needs to migrate from single-tenant to multi-tenant schema:
+- Add `tenant_id` to all relevant tables
+- Update all queries to include tenant context
+- Maintain backwards compatibility during rollout
+- Enable rollback at each phase
+
+**Risk Level**: High (production data, requires rollback plan)
+
+---
+
+## Step 1: Create the Migration Epic
+
+```bash
+{{TASK_ADD_CMD}} "EPIC: Multi-Tenant Schema Migration" \
+  --type epic \
+  --size large \
+  --priority high \
+  --phase core \
+  --labels "migration,database,multi-tenant,v2.0" \
+  --description "Migrate from single-tenant to multi-tenant schema. Phases: (1) Schema changes with dual-write, (2) Data backfill, (3) Query migration, (4) Cleanup. Each phase has rollback capability. Zero downtime required." \
+  --acceptance "All tables have tenant_id" \
+  --acceptance "All queries tenant-aware" \
+  --acceptance "Rollback tested at each phase" \
+  --acceptance "Zero data loss" \
+  --acceptance "Zero downtime" \
+  --notes "Migration plan approved by DBA. Target: Q1 2026."
+```
+
+**Annotation**: Migration epics are `large` due to multi-phase nature. Labels include `migration` for filtering. Acceptance criteria emphasize safety (rollback, zero data loss).
+
+---
+
+## Step 2: Create Tasks by Phase
+
+### Phase A: Schema Preparation (Wave 0)
+
+```bash
+# T1: Add nullable tenant_id columns (Wave 0)
+{{TASK_ADD_CMD}} "Add nullable tenant_id columns to tables" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase setup \
+  --labels "migration,schema,phase-a" \
+  --description "Add tenant_id column as NULLABLE to users, projects, tasks tables. Create index. No application changes yet." \
+  --acceptance "Columns added to all tables" \
+  --acceptance "Indexes created" \
+  --acceptance "Existing queries still work" \
+  --files "migrations/001_add_tenant_id.sql"
+```
+
+**Annotation**: First migration task is ADDITIVE ONLY. Never modify existing columns in Wave 0.
+
+### Phase B: Dual-Write Implementation (Wave 1)
+
+```bash
+# T2: Implement dual-write logic (Wave 1 - depends on T1)
+{{TASK_ADD_CMD}} "Implement dual-write for tenant_id" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T1_ID}} \
+  --labels "migration,dual-write,phase-b" \
+  --description "Update write operations to populate tenant_id from context. Existing data unchanged. New records get tenant_id." \
+  --acceptance "New records have tenant_id populated" \
+  --acceptance "Existing records unchanged" \
+  --acceptance "Feature flag controls dual-write" \
+  --files "src/lib/db/tenant-context.ts,src/lib/db/models/*.ts"
+
+# T3: Create rollback procedure for Phase B (Wave 1 - parallel with T2)
+{{TASK_ADD_CMD}} "Create Phase B rollback procedure" \
+  --type task \
+  --size small \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T1_ID}} \
+  --labels "migration,rollback,phase-b" \
+  --description "Document and test rollback: disable dual-write flag, verify system functions without tenant_id writes." \
+  --acceptance "Rollback procedure documented" \
+  --acceptance "Rollback tested in staging" \
+  --files "docs/migration/phase-b-rollback.md"
+```
+
+### Phase C: Data Backfill (Wave 2)
+
+```bash
+# T4: Backfill existing data (Wave 2 - depends on T2, T3)
+{{TASK_ADD_CMD}} "Backfill tenant_id for existing records" \
+  --type task \
+  --size large \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T2_ID}},{{T3_ID}} \
+  --labels "migration,backfill,phase-c" \
+  --description "Batch update existing records to populate tenant_id based on ownership rules. Use batched updates to avoid locks. Verify completeness." \
+  --acceptance "All records have tenant_id" \
+  --acceptance "No NULL tenant_id remaining" \
+  --acceptance "Backfill script idempotent" \
+  --files "scripts/backfill-tenant-id.ts,migrations/002_backfill_tenant.sql"
+
+# T5: Validate backfill completeness (Wave 2 - depends on T4)
+{{TASK_ADD_CMD}} "Validate backfill completeness" \
+  --type task \
+  --size small \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase testing \
+  --depends {{T4_ID}} \
+  --labels "migration,validation,phase-c" \
+  --description "Run validation queries to ensure no NULL tenant_id remains. Compare record counts pre/post migration." \
+  --acceptance "Zero NULL tenant_id records" \
+  --acceptance "Record counts match" \
+  --files "scripts/validate-migration.ts"
+```
+
+### Phase D: Query Migration (Wave 3)
+
+```bash
+# T6: Update read queries to use tenant context (Wave 3 - depends on T5)
+{{TASK_ADD_CMD}} "Update queries to include tenant context" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase core \
+  --depends {{T5_ID}} \
+  --labels "migration,queries,phase-d" \
+  --description "Update all database queries to filter by tenant_id from context. Use repository pattern for consistency." \
+  --acceptance "All queries filter by tenant" \
+  --acceptance "No cross-tenant data leakage" \
+  --acceptance "Query performance acceptable" \
+  --files "src/lib/db/repositories/*.ts"
+
+# T7: Security audit for tenant isolation (Wave 3 - parallel with T6)
+{{TASK_ADD_CMD}} "Audit tenant isolation" \
+  --type task \
+  --size medium \
+  --priority critical \
+  --parent {{EPIC_ID}} \
+  --phase testing \
+  --depends {{T5_ID}} \
+  --labels "migration,security,audit,phase-d" \
+  --description "Security audit: verify no query paths can access cross-tenant data. Test with multiple tenant contexts." \
+  --acceptance "No cross-tenant data access possible" \
+  --acceptance "Security review documented" \
+  --files "docs/security/tenant-isolation-audit.md"
+```
+
+### Phase E: Cleanup (Wave 4 - Final)
+
+```bash
+# T8: Make tenant_id NOT NULL (Wave 4 - depends on T6, T7)
+{{TASK_ADD_CMD}} "Enforce NOT NULL constraint on tenant_id" \
+  --type task \
+  --size small \
+  --priority medium \
+  --parent {{EPIC_ID}} \
+  --phase polish \
+  --depends {{T6_ID}},{{T7_ID}} \
+  --labels "migration,schema,cleanup,phase-e" \
+  --description "After validation, add NOT NULL constraint to tenant_id columns. Point of no easy rollback." \
+  --acceptance "NOT NULL constraint added" \
+  --acceptance "No constraint violations" \
+  --files "migrations/003_enforce_tenant_not_null.sql"
+
+# T9: Remove feature flags and legacy code (Wave 4 - depends on T8)
+{{TASK_ADD_CMD}} "Remove migration feature flags" \
+  --type task \
+  --size small \
+  --priority low \
+  --parent {{EPIC_ID}} \
+  --phase polish \
+  --depends {{T8_ID}} \
+  --labels "migration,cleanup,phase-e" \
+  --description "Remove dual-write feature flags, legacy single-tenant code paths. Document migration completion." \
+  --acceptance "Feature flags removed" \
+  --acceptance "Legacy code removed" \
+  --acceptance "Migration documented as complete" \
+  --files "src/lib/db/models/*.ts,docs/migration/completion.md"
+```
+
+---
+
+## Step 3: Start Session
+
+```bash
+{{TASK_SESSION_START_CMD}} \
+  --scope epic:{{EPIC_ID}} \
+  --name "Multi-Tenant Migration" \
+  --agent ct-epic-architect \
+  --auto-start
+```
+
+---
+
+## Dependency Graph
+
+```
+T1 (Add Columns)
+├──> T2 (Dual-Write)
+│    └──> T4 (Backfill)
+│         └──> T5 (Validate)
+│              ├──> T6 (Update Queries)
+│              │    └──> T8 (NOT NULL)
+│              │         └──> T9 (Cleanup)
+│              └──> T7 (Security Audit)
+│                   └──> T8 (NOT NULL)
+└──> T3 (Rollback Procedure)
+     └──> T4 (Backfill)
+```
+
+---
+
+## Migration Phases Summary
+
+| Phase | Tasks | Rollback | Risk |
+|-------|-------|----------|------|
+| A: Schema | T1 | Drop columns | Low |
+| B: Dual-Write | T2, T3 | Disable flag | Low |
+| C: Backfill | T4, T5 | Restore backup | Medium |
+| D: Queries | T6, T7 | Revert code | Medium |
+| E: Cleanup | T8, T9 | Complex restore | High |
+
+---
+
+## Critical Safety Notes
+
+1. **Each phase has checkpoint**: Don't proceed until validation passes
+2. **Rollback tested before proceeding**: T3 creates rollback before T4 executes
+3. **Security audit before cleanup**: T7 must pass before T8 (NOT NULL)
+4. **Point of no return**: T8 (NOT NULL) is difficult to rollback - ensure confidence

package/packages/ct-skills/skills/ct-epic-architect/references/output-format.md

@@ -0,0 +1,92 @@
+# Epic Output File Format
+
+Template for epic creation output files.
+
+---
+
+## Output File Location
+
+Write to `{{OUTPUT_DIR}}/{{DATE}}_epic-{{FEATURE_SLUG}}.md`
+
+---
+
+## Template
+
+```markdown
+# Epic: {{EPIC_TITLE}}
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| Epic ID | {{EPIC_ID}} |
+| Parent | {{PARENT_ID or "None (root)"}} |
+| Phase | {{PHASE}} |
+| Size | large |
+| Priority | {{PRIORITY}} |
+| Labels | {{LABELS}} |
+
+## Description
+
+{{EPIC_DESCRIPTION}}
+
+## Task Breakdown
+
+| ID | Title | Type | Size | Phase | Depends | Ready |
+|----|-------|------|------|-------|---------|-------|
+| {{EPIC_ID}} | {{EPIC_TITLE}} | epic | large | {{PHASE}} | - | - |
+| {{T1_ID}} | {{T1_TITLE}} | task | {{SIZE}} | {{PHASE}} | - | Yes |
+| {{T2_ID}} | {{T2_TITLE}} | task | {{SIZE}} | {{PHASE}} | {{T1_ID}} | No |
+| {{T3_ID}} | {{T3_TITLE}} | task | {{SIZE}} | {{PHASE}} | {{T1_ID}} | No |
+| {{T4_ID}} | {{T4_TITLE}} | task | {{SIZE}} | {{PHASE}} | {{T2_ID}},{{T3_ID}} | No |
+| {{T5_ID}} | {{T5_TITLE}} | task | {{SIZE}} | {{PHASE}} | {{T4_ID}} | No |
+
+## Dependency Graph
+
+```
+{{T1_ID}}
+├──> {{T2_ID}}
+│    └──> {{T4_ID}}
+└──> {{T3_ID}}
+     └──> {{T4_ID}}
+          └──> {{T5_ID}}
+```
+
+## Critical Path
+
+{{T1_ID}} → {{T2_ID}} → {{T4_ID}} → {{T5_ID}}
+
+(T3 runs parallel to T2, both converge at T4)
+
+## Parallel Opportunities (Wave Analysis)
+
+| Wave | Tasks | Can Parallelize |
+|------|-------|-----------------|
+| 0 | {{T1_ID}} | - |
+| 1 | {{T2_ID}}, {{T3_ID}} | Yes (independent) |
+| 2 | {{T4_ID}} | No (convergence) |
+| 3 | {{T5_ID}} | No (final) |
+
+## Session Started
+
+- Session ID: {{SESSION_ID}}
+- Scope: `epic:{{EPIC_ID}}`
+- First Ready Task: {{T1_ID}}
+
+## Acceptance Criteria
+
+1. All child tasks completed
+2. Integration tests pass
+3. Documentation updated
+4. Code reviewed and merged
+```
+
+---
+
+## Manifest Entry Format
+
+Append ONE line (no pretty-printing) to `{{MANIFEST_PATH}}`:
+
+```json
+{"id":"epic-{{FEATURE_SLUG}}-{{DATE}}","file":"{{DATE}}_epic-{{FEATURE_SLUG}}.md","title":"Epic Created: {{FEATURE_NAME}}","date":"{{DATE}}","status":"complete","topics":["epic","planning","{{DOMAIN}}"],"key_findings":["Created Epic {{EPIC_ID}} with {{N}} child tasks","Dependency chain: {{T1}} -> {{T2}}/{{T3}} -> {{T4}} -> {{T5}}","Wave 0 (parallel start): [{{T1_ID}}]","Wave 1 (parallel): [{{T2_ID}}, {{T3_ID}}]","Critical path: {{T1}} -> {{T2}} -> {{T4}} -> {{T5}}","Session started: {{SESSION_ID}}"],"actionable":true,"needs_followup":["{{FIRST_READY_TASK_ID}}"],"linked_tasks":["{{EPIC_ID}}","{{ALL_TASK_IDS}}"]}
+```

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

@@ -0,0 +1,284 @@
+# Epic Patterns Reference
+
+Detailed patterns for specialized epic types.
+
+---
+
+## Research Epic Pattern
+
+When the work type is classified as research:
+
+### Research Wave Structure
+
+| Wave | Task Type | Purpose |
+|------|-----------|---------|
+| Wave 0 | Scope Definition | Define research questions, boundaries, success criteria |
+| Wave 1+ | Investigation (parallel) | Multiple parallel investigation tasks for sources/aspects |
+| Final Wave | Synthesis | Aggregate findings, create recommendations, link to future work |
+
+### Research Epic Types
+
+| Type | When | Structure |
+|------|------|-----------|
+| Exploratory | Investigating unknowns | Questions -> Literature + Alternatives + Feasibility -> Synthesis -> Recommendations |
+| Decision | Comparing options | Criteria -> Option A + B + C (parallel) -> Matrix -> Recommendation |
+| Codebase Analysis | Understanding existing code | Architecture -> Dependencies + Data Flows -> Pain Points -> Improvements |
+
+### Research-Specific Commands
+
+```bash
+# Initialize research outputs directory
+{{TASK_RESEARCH_INIT_CMD}}
+
+# Create research epic with research-specific labels
+{{TASK_ADD_CMD}} "Research: {{TOPIC}}" \
+  --type epic \
+  --size medium \
+  --labels "research,{{TYPE}},{{DOMAIN}}" \
+  --phase core \
+  --description "Research questions: ..." \
+  --acceptance "Findings documented in research outputs; Recommendations actionable"
+
+# Query prior research before starting
+{{TASK_RESEARCH_LIST_CMD}} --status complete --topic {{DOMAIN}}
+{{TASK_RESEARCH_SHOW_CMD}} {{ID}}              # Key findings only
+{{TASK_RESEARCH_PENDING_CMD}}                  # Incomplete work
+
+# Link research to task after completion
+{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}
+```
+
+### Research Task Atomicity
+
+Each research task SHOULD address exactly ONE research question:
+- **Good**: "What authentication options exist for SvelteKit?"
+- **Bad**: "Research authentication and authorization"
+
+### Research Output Integration
+
+- Subagents write findings to `{{OUTPUT_DIR}}/`
+- Subagents append entry to `{{MANIFEST_PATH}}` with `linked_tasks: ["{{TASK_ID}}"]`
+- Orchestrator reads only manifest summaries (key_findings) for context efficiency
+- Use `{{TASK_RESEARCH_INJECT_CMD}}` to get subagent protocol block
+
+### Synthesis vs Investigation Tasks
+
+| Type | Parallel? | Dependencies | Output |
+|------|-----------|--------------|--------|
+| Investigation | Yes | Scope definition only | Raw findings |
+| Synthesis | No | All investigation tasks | Conclusions, recommendations |
+
+---
+
+## Bug Epic Pattern
+
+When work is classified as bug fix:
+
+### Bug Severity to Priority Mapping
+
+| Severity | Priority | Indicators |
+|----------|----------|------------|
+| Critical | critical | Data loss, security, system down |
+| High | high | Core feature broken, workaround difficult |
+| Medium | medium | Feature degraded, workaround exists |
+| Low | low | Cosmetic, edge case |
+
+### Bug Wave Structure
+
+| Wave | Task Type | Purpose |
+|------|-----------|---------|
+| Wave 0 | Investigation | Root cause analysis |
+| Wave 1 | Fix | Implement solution |
+| Wave 2 | Regression Test | Verify fix, add test coverage |
+
+### Bug-Specific Labels
+
+```bash
+{{TASK_ADD_CMD}} "Fix: {{BUG_DESCRIPTION}}" \
+  --type epic \
+  --labels "bug,severity:{{LEVEL}},{{DOMAIN}}" \
+  --priority {{MAPPED_PRIORITY}}
+```
+
+---
+
+## Brownfield Epic Pattern
+
+When working in existing codebases (refactoring, modernization, migrations):
+
+### Brownfield vs Greenfield Classification
+
+| Indicator | Greenfield | Brownfield |
+|-----------|------------|------------|
+| Code exists | No | Yes |
+| Tests exist | No | May exist |
+| Users exist | No | Yes (production impact) |
+| Rollback needed | No | Yes (critical) |
+| Dependencies | None | Many (existing systems) |
+
+### Brownfield Wave 0: Impact Analysis (MANDATORY)
+
+**Every brownfield epic MUST start with impact analysis:**
+
+```bash
+# T1: Impact analysis task (Wave 0)
+{{TASK_ADD_CMD}} "Analyze impact and dependencies" \
+  --type task \
+  --size medium \
+  --priority critical \
+  --parent {{EPIC_ID}} \
+  --phase setup \
+  --labels "brownfield,analysis,wave-0" \
+  --description "Document all files, functions, and integration points affected. Create dependency graph. Identify external systems." \
+  --acceptance "Dependency map documented" \
+  --acceptance "All integration points identified" \
+  --acceptance "Risk areas flagged"
+```
+
+### Brownfield Wave 0: Regression Baseline (MANDATORY)
+
+**Create tests BEFORE any modifications:**
+
+```bash
+# T2: Regression baseline task (Wave 0)
+{{TASK_ADD_CMD}} "Create regression test baseline" \
+  --type task \
+  --size medium \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --phase setup \
+  --labels "brownfield,testing,wave-0,regression-risk" \
+  --description "Write tests for ALL current behaviors BEFORE changes. These verify no regressions during work." \
+  --acceptance "Current behavior fully tested" \
+  --acceptance "Edge cases covered" \
+  --acceptance "Tests pass against current code"
+```
+
+### Brownfield Safety Patterns
+
+| Pattern | Purpose | Implementation |
+|---------|---------|----------------|
+| **Strangler Fig** | Gradual replacement | New code parallel to legacy, shift traffic gradually |
+| **Feature Flags** | Rollback capability | Gate new behavior, instant rollback |
+| **Dual-Write** | Data migration safety | Write to both old/new, verify consistency |
+| **Shadow Mode** | Risk-free testing | New code runs but doesn't affect users |
+
+### Brownfield-Specific Labels
+
+```bash
+--labels "brownfield,refactor,regression-risk"
+--labels "brownfield,migration,rollback-checkpoint"
+--labels "brownfield,cleanup,tech-debt"
+```
+
+### Rollback Checkpoints
+
+Every brownfield epic MUST document rollback at each wave:
+
+```bash
+# Rollback documentation task (parallel with implementation)
+{{TASK_ADD_CMD}} "Document Wave N rollback procedure" \
+  --type task \
+  --size small \
+  --priority high \
+  --parent {{EPIC_ID}} \
+  --labels "brownfield,rollback" \
+  --description "Document and test rollback procedure for this wave. Must be tested in staging." \
+  --acceptance "Rollback procedure documented" \
+  --acceptance "Tested in staging environment"
+```
+
+### Brownfield Verification Gates
+
+After brownfield task completion:
+
+```bash
+# Regression tests still pass
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate testsPassed
+
+# Cleanup/tech debt addressed
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate cleanupDone
+
+# Security review for auth/data changes
+{{TASK_VERIFY_CMD}} {{TASK_ID}} --gate securityPassed
+```
+
+### Brownfield Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Big-bang cutover** | High risk, no rollback | Gradual migration with feature flags |
+| **No regression tests** | Can't verify no breakage | Baseline tests before any changes |
+| **Undocumented rollback** | Stuck if issues arise | Document rollback at each phase |
+| **Modifying and testing together** | Tests may pass broken code | Tests first, then modifications |
+
+**See [refactor-epic-example.md](refactor-epic-example.md) for complete brownfield refactoring example.**
+
+---
+
+## Refactor Epic Pattern
+
+For code modernization, architectural improvements, and tech debt reduction:
+
+### Refactor Wave Structure
+
+| Wave | Task Type | Purpose |
+|------|-----------|---------|
+| Wave 0 | Impact Analysis + Regression Baseline | Understand scope, create safety net |
+| Wave 1 | New Implementation (parallel) | Build new code alongside legacy |
+| Wave 2 | Adapter/Integration | Create bridge between old and new |
+| Wave 3 | Gradual Migration | Shift traffic/users incrementally |
+| Wave 4 | Validation + Cleanup | Verify migration, remove legacy |
+
+### Refactor Safety Rules
+
+1. **Never modify existing code in Wave 0** - Analysis only
+2. **New code is ADDITIVE in Wave 1** - Don't touch legacy yet
+3. **Feature flags control all behavior changes** - Instant rollback
+4. **Test rollback at every phase** - Before production deployment
+5. **Remove legacy code LAST** - Only after validation complete
+
+### Refactor-Specific Commands
+
+```bash
+# Create refactor epic with lifecycle tracking
+{{TASK_ADD_CMD}} "EPIC: Refactor {{COMPONENT}}" \
+  --type epic \
+  --size large \
+  --priority high \
+  --epic-lifecycle planning \
+  --labels "refactor,brownfield,{{DOMAIN}}" \
+  --description "Modernize {{COMPONENT}}. Strangler fig pattern with feature flags." \
+  --acceptance "New implementation complete" \
+  --acceptance "All users migrated" \
+  --acceptance "Legacy code removed" \
+  --acceptance "Rollback tested at each phase"
+```
+
+**See [refactor-epic-example.md](refactor-epic-example.md) for complete example.**
+
+---
+
+## Task Naming Conventions
+
+### Pattern: "{Verb} {Object} {Qualifier}"
+
+**Good:**
+- "Create user authentication schema"
+- "Implement JWT validation middleware"
+- "Write integration tests for auth flow"
+- "Add error handling to API endpoints"
+
+**Bad:**
+- "Auth stuff"
+- "Part 1"
+- "Fix things"
+- "TODO"
+
+### Numbered Sequences
+
+For clearly sequential work:
+- "1. Define data model"
+- "2. Create API endpoints"
+- "3. Build UI components"
+- "4. Add integration tests"