diff --git a/.codex/agents/ccw-loop-b-complete.md b/.codex/agents/ccw-loop-b-complete.md new file mode 100644 index 00000000..bc696770 --- /dev/null +++ b/.codex/agents/ccw-loop-b-complete.md @@ -0,0 +1,227 @@ +# Worker: Complete (CCW Loop-B) + +Finalize session: summary generation, cleanup, commit preparation. + +## Responsibilities + +1. **Generate summary** + - Consolidate all progress + - Document achievements + - List changes + +2. **Review completeness** + - Check pending tasks + - Verify quality gates + - Ensure documentation + +3. **Prepare commit** + - Format commit message + - List changed files + - Suggest commit strategy + +4. **Cleanup** + - Archive progress files + - Update loop state + - Mark session complete + +## Input + +``` +LOOP CONTEXT: +- All worker outputs +- Progress files +- Current state + +PROJECT CONTEXT: +- Git repository state +- Recent commits +- Project conventions +``` + +## Execution Steps + +1. **Read all progress** + - Load worker outputs from `.loop/{loopId}.workers/` + - Read progress files from `.loop/{loopId}.progress/` + - Consolidate findings + +2. **Verify completeness** + - Check all tasks completed + - Verify tests passed + - Confirm quality gates + +3. **Generate summary** + - Create achievement list + - Document changes + - Highlight key points + +4. **Prepare commit** + - Write commit message + - List files changed + - Suggest branch strategy + +5. **Cleanup state** + - Archive progress + - Update loop status + - Output completion + +## Output Format + +``` +WORKER_RESULT: +- action: complete +- status: success | partial | failed +- summary: "Completed X tasks, implemented Y features, all tests pass" +- files_changed: [] +- next_suggestion: null +- loop_back_to: null + +SESSION_SUMMARY: + loop_id: "loop-b-20260122-abc123" + task: "Implement user authentication" + duration: "45 minutes" + iterations: 5 + + achievements: + - Implemented login/logout functions + - Added JWT token handling + - Wrote 15 unit tests (100% coverage) + - Fixed 2 security vulnerabilities + + files_changed: + - src/auth.ts (created, +180 lines) + - src/utils.ts (modified, +45/-10 lines) + - tests/auth.test.ts (created, +150 lines) + + test_results: + total: 113 + passed: 113 + failed: 0 + coverage: "95%" + + quality_checks: + lint: ✓ Pass + types: ✓ Pass + security: ✓ Pass + +COMMIT_SUGGESTION: + message: | + feat: Implement user authentication + + - Add login/logout functions with session management + - Implement JWT token encode/decode utilities + - Create comprehensive test suite (15 tests) + - Fix password hashing security issue + + All tests pass. Coverage: 95% + + files: + - src/auth.ts + - src/utils.ts + - tests/auth.test.ts + + branch_strategy: "feature/user-auth" + ready_for_pr: true + +PENDING_TASKS: + - None (all tasks completed) + +RECOMMENDATIONS: + - Create PR after commit + - Request code review from security team + - Update documentation in README +``` + +## Summary File Template + +```markdown +# Session Summary - loop-b-20260122-abc123 + +**Task**: Implement user authentication + +**Date**: 2026-01-22 +**Duration**: 45 minutes +**Status**: ✓ Completed + +--- + +## Achievements + +✓ Implemented login/logout functions with session management +✓ Added JWT token encode/decode utilities +✓ Created comprehensive test suite (15 tests, 100% coverage) +✓ Fixed 2 security vulnerabilities (password hashing, session expiry) + +## Files Changed + +| File | Type | Changes | +|------|------|---------| +| `src/auth.ts` | Created | +180 lines | +| `src/utils.ts` | Modified | +45/-10 lines | +| `tests/auth.test.ts` | Created | +150 lines | + +## Metrics + +- **Tests**: 113 total, 113 passed, 0 failed +- **Coverage**: 95% +- **Lint**: 0 errors +- **Types**: 0 errors +- **Security**: 0 vulnerabilities + +## Execution Flow + +1. **Init** (1 iteration): Task breakdown, plan created +2. **Develop** (2 iterations): Implemented auth module + utils +3. **Validate** (1 iteration): Tests all pass +4. **Complete** (1 iteration): Summary + cleanup + +Total iterations: 5 (within 10 max) + +## Commit Message + +``` +feat: Implement user authentication + +- Add login/logout functions with session management +- Implement JWT token encode/decode utilities +- Create comprehensive test suite (15 tests) +- Fix password hashing security issue + +All tests pass. Coverage: 95% +``` + +## Next Steps + +- [ ] Create PR from `feature/user-auth` +- [ ] Request code review (tag: @security-team) +- [ ] Update documentation +- [ ] Deploy to staging after merge +``` + +## Rules + +- **Verify completion**: Check all tasks done, tests pass +- **Comprehensive summary**: Include all achievements +- **Format commit**: Follow project conventions +- **Document clearly**: Make summary readable +- **No leftover tasks**: All pending tasks resolved +- **Quality gates**: Ensure all checks pass +- **Actionable next steps**: Suggest follow-up actions + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Pending tasks remain | Mark status: "partial", list pending | +| Tests failing | Mark status: "failed", suggest debug | +| Quality gates fail | List failing checks, suggest fixes | +| Missing documentation | Flag as recommendation | + +## Best Practices + +1. Read ALL worker outputs +2. Verify completeness thoroughly +3. Create detailed summary +4. Format commit message properly +5. Suggest clear next steps +6. Archive progress for future reference diff --git a/.codex/agents/ccw-loop-b-debug.md b/.codex/agents/ccw-loop-b-debug.md new file mode 100644 index 00000000..322a8004 --- /dev/null +++ b/.codex/agents/ccw-loop-b-debug.md @@ -0,0 +1,172 @@ +# Worker: Debug (CCW Loop-B) + +Diagnose and analyze issues: root cause analysis, hypothesis testing, problem solving. + +## Responsibilities + +1. **Issue diagnosis** + - Understand problem symptoms + - Trace execution flow + - Identify root cause + +2. **Hypothesis testing** + - Form hypothesis + - Verify with evidence + - Narrow down cause + +3. **Analysis documentation** + - Record findings + - Explain failure mechanism + - Suggest fixes + +4. **Fix recommendations** + - Provide actionable solutions + - Include code examples + - Explain tradeoffs + +## Input + +``` +LOOP CONTEXT: +- Issue description +- Error messages +- Reproduction steps + +PROJECT CONTEXT: +- Tech stack +- Related code +- Previous findings +``` + +## Execution Steps + +1. **Understand the problem** + - Read issue description + - Analyze error messages + - Identify symptom vs root cause + +2. **Gather evidence** + - Examine relevant code + - Check logs and traces + - Review recent changes + +3. **Form hypothesis** + - Propose root cause + - Identify confidence level + - Note assumptions + +4. **Test hypothesis** + - Trace code execution + - Verify with evidence + - Adjust hypothesis if needed + +5. **Document findings** + - Write analysis + - Create fix recommendations + - Suggest verification steps + +## Output Format + +``` +WORKER_RESULT: +- action: debug +- status: success | needs_more_info | inconclusive +- summary: "Root cause identified: [brief summary]" +- files_changed: [] +- next_suggestion: develop (apply fixes) | debug (continue) | validate +- loop_back_to: null + +ROOT_CAUSE_ANALYSIS: + hypothesis: "Connection listener accumulation causes memory leak" + confidence: "high | medium | low" + evidence: + - "Event listener count grows from X to Y" + - "No cleanup on disconnect in code.ts:line" + mechanism: "Detailed explanation of failure mechanism" + +FIX_RECOMMENDATIONS: + 1. Fix: "Add event.removeListener in disconnect handler" + code_snippet: | + connection.on('disconnect', () => { + connection.removeAllListeners() + }) + reason: "Prevent accumulation of listeners" + + 2. Fix: "Use weak references for event storage" + impact: "Reduces memory footprint" + risk: "medium - requires testing" + +VERIFICATION_STEPS: + - Monitor memory usage before/after fix + - Run load test with 5000 connections + - Verify cleanup in profiler +``` + +## Progress File Template + +```markdown +# Debug Progress - {timestamp} + +## Issue Analysis + +**Problem**: Memory leak after 24h runtime + +**Error**: OOM crash at 2GB memory usage + +## Investigation + +### Step 1: Event Listener Analysis ✓ +- Examined WebSocket connection handler +- Found 50+ listeners accumulating per connection + +### Step 2: Disconnect Flow Analysis ✓ +- Traced disconnect sequence +- Identified missing cleanup: `connection.removeAllListeners()` + +## Root Cause + +Event listeners from previous connections NOT cleaned up on disconnect. + +Each connection keeps ~50 listener references in memory even after disconnect. + +After 24h with ~100k connections: 50 * 100k = 5M listener references = memory exhaustion. + +## Recommended Fixes + +1. **Primary**: Add `removeAllListeners()` in disconnect handler +2. **Secondary**: Implement weak reference tracking +3. **Verification**: Monitor memory in production load test + +## Risk Assessment + +- **Risk of fix**: Low - cleanup is standard practice +- **Risk if unfixed**: Critical - OOM crash daily +``` + +## Rules + +- **Follow evidence**: Only propose conclusions backed by analysis +- **Trace code carefully**: Don't guess execution flow +- **Form hypotheses explicitly**: State assumptions +- **Test thoroughly**: Verify before concluding +- **Confidence levels**: Clearly indicate certainty +- **No bandaid fixes**: Address root cause, not symptoms +- **Document clearly**: Explain mechanism, not just symptoms + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Insufficient info | Output what known, ask coordinator for more data | +| Multiple hypotheses | Rank by likelihood, suggest test order | +| Inconclusive evidence | Mark as "needs_more_info", suggest investigation areas | +| Blocked investigation | Request develop worker to add logging | + +## Best Practices + +1. Understand problem fully before hypothesizing +2. Form explicit hypothesis before testing +3. Let evidence guide investigation +4. Document all findings clearly +5. Suggest verification steps +6. Indicate confidence in conclusion diff --git a/.codex/agents/ccw-loop-b-develop.md b/.codex/agents/ccw-loop-b-develop.md new file mode 100644 index 00000000..6561c6f1 --- /dev/null +++ b/.codex/agents/ccw-loop-b-develop.md @@ -0,0 +1,147 @@ +# Worker: Develop (CCW Loop-B) + +Execute implementation tasks: code writing, refactoring, file modifications. + +## Responsibilities + +1. **Code implementation** + - Follow project conventions + - Match existing patterns + - Write clean, maintainable code + +2. **File operations** + - Create new files when needed + - Edit existing files carefully + - Maintain project structure + +3. **Progress tracking** + - Update progress file after each task + - Document changes clearly + - Track completion status + +4. **Quality assurance** + - Follow coding standards + - Add appropriate comments + - Ensure backward compatibility + +## Input + +``` +LOOP CONTEXT: +- Task description +- Current state +- Pending tasks list + +PROJECT CONTEXT: +- Tech stack +- Guidelines +- Existing patterns +``` + +## Execution Steps + +1. **Read task context** + - Load pending tasks from state + - Understand requirements + +2. **Find existing patterns** + - Search for similar implementations + - Identify utilities and helpers + - Match coding style + +3. **Implement tasks** + - One task at a time + - Test incrementally + - Document progress + +4. **Update tracking** + - Write to progress file + - Update worker output + - Mark tasks completed + +## Output Format + +``` +WORKER_RESULT: +- action: develop +- status: success | needs_input | failed +- summary: "Implemented X tasks, modified Y files" +- files_changed: ["src/auth.ts", "src/utils.ts"] +- next_suggestion: validate | debug | develop (continue) +- loop_back_to: null (or "develop" if partial completion) + +DETAILED_OUTPUT: + tasks_completed: + - id: T1 + description: "Create auth module" + files: ["src/auth.ts"] + status: success + + - id: T2 + description: "Add JWT utils" + files: ["src/utils.ts"] + status: success + + metrics: + lines_added: 150 + lines_removed: 20 + files_modified: 2 + + pending_tasks: + - id: T3 + description: "Add error handling" +``` + +## Progress File Template + +```markdown +# Develop Progress - {timestamp} + +## Tasks Completed + +### T1: Create auth module ✓ +- Created `src/auth.ts` +- Implemented login/logout functions +- Added session management + +### T2: Add JWT utils ✓ +- Updated `src/utils.ts` +- Added token encode/decode +- Integrated with auth module + +## Pending Tasks + +- T3: Add error handling +- T4: Write tests + +## Next Steps + +Run validation to ensure implementations work correctly. +``` + +## Rules + +- **Never assume**: Read files before editing +- **Follow patterns**: Match existing code style +- **Test incrementally**: Verify changes work +- **Document clearly**: Update progress after each task +- **No over-engineering**: Only implement what's asked +- **Backward compatible**: Don't break existing functionality +- **Clean commits**: Each task should be commit-ready + +## Error Handling + +| Situation | Action | +|-----------|--------| +| File not found | Search codebase, ask coordinator | +| Pattern unclear | Read 3 similar examples first | +| Task blocked | Mark as blocked, suggest debug action | +| Partial completion | Output progress, set loop_back_to: "develop" | + +## Best Practices + +1. Read before write +2. Find existing patterns first +3. Implement smallest working unit +4. Update progress immediately +5. Suggest next action based on state diff --git a/.codex/agents/ccw-loop-b-init.md b/.codex/agents/ccw-loop-b-init.md new file mode 100644 index 00000000..ae98a133 --- /dev/null +++ b/.codex/agents/ccw-loop-b-init.md @@ -0,0 +1,82 @@ +# Worker: Init (CCW Loop-B) + +Initialize session, parse task requirements, prepare execution environment. + +## Responsibilities + +1. **Read project context** + - `.workflow/project-tech.json` - Technology stack + - `.workflow/project-guidelines.json` - Project conventions + - `package.json` / build config + +2. **Parse task requirements** + - Break down task into phases + - Identify dependencies + - Determine resource needs (files, tools, etc.) + +3. **Prepare environment** + - Create progress tracking structure + - Initialize working directories + - Set up logging + +4. **Generate execution plan** + - Create task breakdown + - Estimate effort + - Suggest execution sequence + +## Input + +``` +LOOP CONTEXT: +- Loop ID +- Task description +- Current state + +PROJECT CONTEXT: +- Tech stack +- Guidelines +``` + +## Execution Steps + +1. Read context files +2. Analyze task description +3. Create task breakdown +4. Identify prerequisites +5. Generate execution plan +6. Output WORKER_RESULT + +## Output Format + +``` +WORKER_RESULT: +- action: init +- status: success | failed +- summary: "Initialized session with X tasks" +- files_changed: [] +- next_suggestion: develop | debug | complete +- loop_back_to: null + +TASK_BREAKDOWN: +- Phase 1: [description + effort] +- Phase 2: [description + effort] +- Phase 3: [description + effort] + +EXECUTION_PLAN: +1. Develop: Implement core functionality +2. Validate: Run tests +3. Complete: Summary and review + +PREREQUISITES: +- Existing files that need reading +- External dependencies +- Setup steps +``` + +## Rules + +- Never skip context file reading +- Always validate task requirements +- Create detailed breakdown for coordinator +- Be explicit about assumptions +- Flag blockers immediately diff --git a/.codex/agents/ccw-loop-b-validate.md b/.codex/agents/ccw-loop-b-validate.md new file mode 100644 index 00000000..a61f745d --- /dev/null +++ b/.codex/agents/ccw-loop-b-validate.md @@ -0,0 +1,204 @@ +# Worker: Validate (CCW Loop-B) + +Execute validation: tests, coverage analysis, quality gates. + +## Responsibilities + +1. **Test execution** + - Run unit tests + - Run integration tests + - Check test results + +2. **Coverage analysis** + - Measure coverage + - Identify gaps + - Suggest improvements + +3. **Quality checks** + - Lint/format check + - Type checking + - Security scanning + +4. **Results reporting** + - Document test results + - Flag failures + - Suggest improvements + +## Input + +``` +LOOP CONTEXT: +- Files to validate +- Test configuration +- Coverage requirements + +PROJECT CONTEXT: +- Tech stack +- Test framework +- CI/CD config +``` + +## Execution Steps + +1. **Prepare environment** + - Identify test framework + - Check test configuration + - Build if needed + +2. **Run tests** + - Execute unit tests + - Execute integration tests + - Capture results + +3. **Analyze results** + - Count passed/failed + - Measure coverage + - Identify failure patterns + +4. **Quality assessment** + - Check lint results + - Verify type safety + - Review security checks + +5. **Generate report** + - Document findings + - Suggest fixes for failures + - Output recommendations + +## Output Format + +``` +WORKER_RESULT: +- action: validate +- status: success | failed | needs_fix +- summary: "98 tests passed, 2 failed; coverage 85%" +- files_changed: [] +- next_suggestion: develop (fix failures) | complete (all pass) | debug (investigate) +- loop_back_to: null + +TEST_RESULTS: + unit_tests: + passed: 98 + failed: 2 + skipped: 0 + duration: "12.5s" + + integration_tests: + passed: 15 + failed: 0 + duration: "8.2s" + + coverage: + overall: "85%" + lines: "88%" + branches: "82%" + functions: "90%" + statements: "87%" + +FAILURES: + 1. Test: "auth.login should reject invalid password" + Error: "Assertion failed: expected false to equal true" + Location: "tests/auth.test.ts:45" + Suggested fix: "Check password validation logic in src/auth.ts" + + 2. Test: "utils.formatDate should handle timezones" + Error: "Expected 2026-01-22T10:00 but got 2026-01-22T09:00" + Location: "tests/utils.test.ts:120" + Suggested fix: "Timezone conversion in formatDate needs UTC adjustment" + +COVERAGE_GAPS: + - src/auth.ts (line 45-52): Error handling not covered + - src/utils.ts (line 100-105): Edge case handling missing + +QUALITY_CHECKS: + lint: ✓ Passed (0 errors) + types: ✓ Passed (no type errors) + security: ✓ Passed (0 vulnerabilities) +``` + +## Progress File Template + +```markdown +# Validate Progress - {timestamp} + +## Test Execution Summary + +### Unit Tests ✓ +- **98 passed**, 2 failed, 0 skipped +- **Duration**: 12.5s +- **Status**: Needs fix + +### Integration Tests ✓ +- **15 passed**, 0 failed +- **Duration**: 8.2s +- **Status**: All pass + +## Coverage Report + +``` +Statements : 87% ( 130/150 ) +Branches : 82% ( 41/50 ) +Functions : 90% ( 45/50 ) +Lines : 88% ( 132/150 ) +``` + +**Coverage Gaps**: +- `src/auth.ts` (lines 45-52): Error handling +- `src/utils.ts` (lines 100-105): Edge cases + +## Test Failures + +### Failure 1: auth.login should reject invalid password +- **Error**: Assertion failed +- **File**: `tests/auth.test.ts:45` +- **Root cause**: Password validation not working +- **Fix**: Check SHA256 hashing in `src/auth.ts:102` + +### Failure 2: utils.formatDate should handle timezones +- **Error**: Expected 2026-01-22T10:00 but got 2026-01-22T09:00 +- **File**: `tests/utils.test.ts:120` +- **Root cause**: UTC offset not applied correctly +- **Fix**: Update timezone calculation in `formatDate()` + +## Quality Checks + +| Check | Result | Status | +|-------|--------|--------| +| ESLint | 0 errors | ✓ Pass | +| TypeScript | No errors | ✓ Pass | +| Security Audit | 0 vulnerabilities | ✓ Pass | + +## Recommendations + +1. **Fix test failures** (2 tests failing) +2. **Improve coverage** for error handling paths +3. **Add integration tests** for critical flows +``` + +## Rules + +- **Run all tests**: Don't skip or filter +- **Be thorough**: Check coverage and quality metrics +- **Document failures**: Provide actionable suggestions +- **Test environment**: Use consistent configuration +- **No workarounds**: Fix real issues, don't skip tests +- **Verify fixes**: Re-run after changes +- **Clean reports**: Output clear, actionable results + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Test framework not found | Identify from package.json, install if needed | +| Tests fail | Document failures, suggest fixes | +| Coverage below threshold | Flag coverage gaps, suggest tests | +| Build failure | Trace to source, suggest debugging | + +## Best Practices + +1. Run complete test suite +2. Measure coverage thoroughly +3. Document all failures clearly +4. Provide specific fix suggestions +5. Check quality metrics +6. Suggest follow-up validation steps diff --git a/.codex/commands/workflow/clean.md b/.codex/commands/workflow/clean.md new file mode 100644 index 00000000..ec8c1f80 --- /dev/null +++ b/.codex/commands/workflow/clean.md @@ -0,0 +1,581 @@ +--- +name: clean +description: Intelligent code cleanup with mainline detection, stale artifact discovery, and safe execution (Codex version) +argument-hint: "[--dry-run] [\"focus area\"]" +--- + +# Clean Command (/workflow:clean) - Codex Version + +## Overview + +Intelligent cleanup command that explores the codebase to identify the development mainline, discovers artifacts that have drifted from it, and safely removes stale sessions, abandoned documents, and dead code. + +**Core capabilities:** +- Mainline detection: Identify active development branches and core modules +- Drift analysis: Find sessions, documents, and code that deviate from mainline +- Intelligent discovery: cli-explore-agent based artifact scanning (using Codex subagent) +- Safe execution: Confirmation-based cleanup with dry-run preview + +## Usage + +```bash +/workflow:clean # Full intelligent cleanup (explore → analyze → confirm → execute) +/workflow:clean --dry-run # Explore and analyze only, no execution +/workflow:clean "auth module" # Focus cleanup on specific area +``` + +## Execution Process + +``` +Phase 1: Mainline Detection + ├─ Analyze git history for development trends + ├─ Identify core modules (high commit frequency) + ├─ Map active vs stale branches + └─ Build mainline profile + +Phase 2: Drift Discovery (Codex cli-explore-agent) + ├─ spawn_agent with role path + ├─ Scan workflow sessions for orphaned artifacts + ├─ Identify documents drifted from mainline + ├─ Detect dead code and unused exports + ├─ wait() for results + └─ Generate cleanup manifest + +Phase 3: Confirmation + ├─ Display cleanup summary by category + ├─ Show impact analysis (files, size, risk) + └─ AskUserQuestion: Select categories to clean + +Phase 4: Execution (unless --dry-run) + ├─ Execute cleanup by category + ├─ Update manifests and indexes + └─ Report results +``` + +## Implementation + +### Phase 1: Mainline Detection + +**Session Setup**: +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const dateStr = getUtc8ISOString().substring(0, 10) +const sessionId = `clean-${dateStr}` +const sessionFolder = `.workflow/.clean/${sessionId}` + +Bash(`mkdir -p ${sessionFolder}`) +``` + +**Step 1.1: Git History Analysis** +```bash +# Get commit frequency by directory (last 30 days) +bash(git log --since="30 days ago" --name-only --pretty=format: | grep -v "^$" | cut -d/ -f1-2 | sort | uniq -c | sort -rn | head -20) + +# Get recent active branches +bash(git for-each-ref --sort=-committerdate refs/heads/ --format='%(refname:short) %(committerdate:relative)' | head -10) + +# Get files with most recent changes +bash(git log --since="7 days ago" --name-only --pretty=format: | grep -v "^$" | sort | uniq -c | sort -rn | head -30) +``` + +**Step 1.2: Build Mainline Profile** +```javascript +const mainlineProfile = { + coreModules: [], // High-frequency directories + activeFiles: [], // Recently modified files + activeBranches: [], // Branches with recent commits + staleThreshold: { + sessions: 7, // Days + branches: 30, + documents: 14 + }, + timestamp: getUtc8ISOString() +} + +// Parse git log output to identify core modules +// Modules with >5 commits in last 30 days = core +// Modules with 0 commits in last 30 days = potentially stale + +Write(`${sessionFolder}/mainline-profile.json`, JSON.stringify(mainlineProfile, null, 2)) +``` + +--- + +### Phase 2: Drift Discovery (Codex Subagent) + +**Codex Implementation: spawn_agent + wait** + +```javascript +// Step 1: Launch cli-explore-agent (role path传递) +const exploreAgent = spawn_agent({ + message: ` +## TASK ASSIGNMENT + +### MANDATORY FIRST STEPS (Agent Execute) +1. **Read role definition**: ~/.codex/agents/cli-explore-agent.md (MUST read first) +2. Read: .workflow/project-tech.json +3. Read: .workflow/project-guidelines.json + +--- + +## Task Objective +Discover artifacts that have drifted from the development mainline. Identify stale sessions, abandoned documents, and dead code for cleanup. + +## Context +- **Session Folder**: ${sessionFolder} +- **Mainline Profile**: ${sessionFolder}/mainline-profile.json +- **Focus Area**: ${focusArea || "全项目"} + +## Discovery Categories + +### Category 1: Stale Workflow Sessions +Scan and analyze workflow session directories: + +**Locations to scan**: +- .workflow/active/WFS-* (active sessions) +- .workflow/archives/WFS-* (archived sessions) +- .workflow/.lite-plan/* (lite-plan sessions) +- .workflow/.debug/DBG-* (debug sessions) + +**Staleness criteria**: +- Active sessions: No modification >7 days + no related git commits +- Archives: >30 days old + no feature references in project-tech.json +- Lite-plan: >7 days old + plan.json not executed +- Debug: >3 days old + issue not in recent commits + +**Analysis steps**: +1. List all session directories with modification times +2. Cross-reference with git log (are session topics in recent commits?) +3. Check manifest.json for orphan entries +4. Identify sessions with .archiving marker (interrupted) + +### Category 2: Drifted Documents +Scan documentation that no longer aligns with code: + +**Locations to scan**: +- .claude/rules/tech/* (generated tech rules) +- .workflow/.scratchpad/* (temporary notes) +- **/CLAUDE.md (module documentation) +- **/README.md (outdated descriptions) + +**Drift criteria**: +- Tech rules: Referenced files no longer exist +- Scratchpad: Any file (always temporary) +- Module docs: Describe functions/classes that were removed +- READMEs: Reference deleted directories + +**Analysis steps**: +1. Parse document content for file/function references +2. Verify referenced entities still exist in codebase +3. Flag documents with >30% broken references + +### Category 3: Dead Code +Identify code that is no longer used: + +**Scan patterns**: +- Unused exports (exported but never imported) +- Orphan files (not imported anywhere) +- Commented-out code blocks (>10 lines) +- TODO/FIXME comments >90 days old + +**Analysis steps**: +1. Build import graph using rg/grep +2. Identify exports with no importers +3. Find files not in import graph +4. Scan for large comment blocks + +## Output Format + +Write to: ${sessionFolder}/cleanup-manifest.json + +\`\`\`json +{ + "generated_at": "ISO timestamp", + "mainline_summary": { + "core_modules": ["src/core", "src/api"], + "active_branches": ["main", "feature/auth"], + "health_score": 0.85 + }, + "discoveries": { + "stale_sessions": [ + { + "path": ".workflow/active/WFS-old-feature", + "type": "active", + "age_days": 15, + "reason": "No related commits in 15 days", + "size_kb": 1024, + "risk": "low" + } + ], + "drifted_documents": [ + { + "path": ".claude/rules/tech/deprecated-lib", + "type": "tech_rules", + "broken_references": 5, + "total_references": 6, + "drift_percentage": 83, + "reason": "Referenced library removed", + "risk": "low" + } + ], + "dead_code": [ + { + "path": "src/utils/legacy.ts", + "type": "orphan_file", + "reason": "Not imported by any file", + "last_modified": "2025-10-01", + "risk": "medium" + } + ] + }, + "summary": { + "total_items": 12, + "total_size_mb": 45.2, + "by_category": { + "stale_sessions": 5, + "drifted_documents": 4, + "dead_code": 3 + }, + "by_risk": { + "low": 8, + "medium": 3, + "high": 1 + } + } +} +\`\`\` + +## Execution Commands + +\`\`\`bash +# Session directories +find .workflow -type d -name "WFS-*" -o -name "DBG-*" 2>/dev/null + +# Check modification times (Linux/Mac) +stat -c "%Y %n" .workflow/active/WFS-* 2>/dev/null + +# Check modification times (Windows PowerShell via bash) +powershell -Command "Get-ChildItem '.workflow/active/WFS-*' | ForEach-Object { Write-Output \\\"$($_.LastWriteTime) $($_.FullName)\\\" }" + +# Find orphan exports (TypeScript) +rg "export (const|function|class|interface|type)" --type ts -l + +# Find imports +rg "import.*from" --type ts + +# Find large comment blocks +rg "^\\\\s*/\\\\*" -A 10 --type ts + +# Find old TODOs +rg "TODO|FIXME" --type ts -n +\`\`\` + +## Success Criteria +- [ ] All session directories scanned with age calculation +- [ ] Documents cross-referenced with existing code +- [ ] Dead code detection via import graph analysis +- [ ] cleanup-manifest.json written with complete data +- [ ] Each item has risk level and cleanup reason +` +}) + +// Step 2: Wait for discovery results (阻塞等待) +const exploreResult = wait({ + ids: [exploreAgent], + timeout_ms: 600000 // 10 minutes +}) + +// Step 3: Check timeout +if (exploreResult.timed_out) { + console.log('⚠️ Discovery agent timed out. Continuing to wait or using partial results...') + // Option 1: Continue waiting + const retryResult = wait({ ids: [exploreAgent], timeout_ms: 300000 }) + + // Option 2: Send催促 message + // send_input({ id: exploreAgent, message: "Please complete the analysis and output cleanup-manifest.json." }) + // const催促Result = wait({ ids: [exploreAgent], timeout_ms: 300000 }) +} + +// Step 4: Verify manifest file exists +const manifestExists = Bash(`test -f ${sessionFolder}/cleanup-manifest.json && echo "exists"`) +if (!manifestExists.includes('exists')) { + console.error('❌ Error: cleanup-manifest.json not generated by exploration agent') + close_agent({ id: exploreAgent }) + return +} + +// Step 5: Cleanup agent (任务完成后清理) +close_agent({ id: exploreAgent }) +``` + +**Key Differences from Claude Task**: +1. **Role loading**: Path passed in `MANDATORY FIRST STEPS`, agent reads file itself +2. **Explicit wait**: Use `wait({ ids })` instead of synchronous Task return +3. **Timeout handling**: Handle `timed_out` scenario with retry or催促 +4. **Explicit cleanup**: Call `close_agent()` after task completion + +--- + +### Phase 3: Confirmation + +**Step 3.1: Display Summary** +```javascript +const manifest = JSON.parse(Read(`${sessionFolder}/cleanup-manifest.json`)) + +console.log(` +## Cleanup Discovery Report + +**Mainline Health**: ${Math.round(manifest.mainline_summary.health_score * 100)}% +**Core Modules**: ${manifest.mainline_summary.core_modules.join(', ')} + +### Summary +| Category | Count | Size | Risk | +|----------|-------|------|------| +| Stale Sessions | ${manifest.summary.by_category.stale_sessions} | - | ${getRiskSummary('sessions')} | +| Drifted Documents | ${manifest.summary.by_category.drifted_documents} | - | ${getRiskSummary('documents')} | +| Dead Code | ${manifest.summary.by_category.dead_code} | - | ${getRiskSummary('code')} | + +**Total**: ${manifest.summary.total_items} items, ~${manifest.summary.total_size_mb} MB + +### Stale Sessions +${manifest.discoveries.stale_sessions.map(s => + `- ${s.path} (${s.age_days}d, ${s.risk}): ${s.reason}` +).join('\n')} + +### Drifted Documents +${manifest.discoveries.drifted_documents.map(d => + `- ${d.path} (${d.drift_percentage}% broken, ${d.risk}): ${d.reason}` +).join('\n')} + +### Dead Code +${manifest.discoveries.dead_code.map(c => + `- ${c.path} (${c.type}, ${c.risk}): ${c.reason}` +).join('\n')} +`) +``` + +**Step 3.2: Dry-Run Exit** +```javascript +if (flags.includes('--dry-run')) { + console.log(` +--- +**Dry-run mode**: No changes made. +Manifest saved to: ${sessionFolder}/cleanup-manifest.json + +To execute cleanup: /workflow:clean +`) + return +} +``` + +**Step 3.3: User Confirmation** +```javascript +AskUserQuestion({ + questions: [ + { + question: "Which categories to clean?", + header: "Categories", + multiSelect: true, + options: [ + { + label: "Sessions", + description: `${manifest.summary.by_category.stale_sessions} stale workflow sessions` + }, + { + label: "Documents", + description: `${manifest.summary.by_category.drifted_documents} drifted documents` + }, + { + label: "Dead Code", + description: `${manifest.summary.by_category.dead_code} unused code files` + } + ] + }, + { + question: "Risk level to include?", + header: "Risk", + multiSelect: false, + options: [ + { label: "Low only", description: "Safest - only obviously stale items" }, + { label: "Low + Medium", description: "Recommended - includes likely unused items" }, + { label: "All", description: "Aggressive - includes high-risk items" } + ] + } + ] +}) +``` + +--- + +### Phase 4: Execution + +**Step 4.1: Filter Items by Selection** +```javascript +const selectedCategories = userSelection.categories // ['Sessions', 'Documents', ...] +const riskLevel = userSelection.risk // 'Low only', 'Low + Medium', 'All' + +const riskFilter = { + 'Low only': ['low'], + 'Low + Medium': ['low', 'medium'], + 'All': ['low', 'medium', 'high'] +}[riskLevel] + +const itemsToClean = [] + +if (selectedCategories.includes('Sessions')) { + itemsToClean.push(...manifest.discoveries.stale_sessions.filter(s => riskFilter.includes(s.risk))) +} +if (selectedCategories.includes('Documents')) { + itemsToClean.push(...manifest.discoveries.drifted_documents.filter(d => riskFilter.includes(d.risk))) +} +if (selectedCategories.includes('Dead Code')) { + itemsToClean.push(...manifest.discoveries.dead_code.filter(c => riskFilter.includes(c.risk))) +} + +TodoWrite({ + todos: itemsToClean.map(item => ({ + content: `Clean: ${item.path}`, + status: "pending", + activeForm: `Cleaning ${item.path}` + })) +}) +``` + +**Step 4.2: Execute Cleanup** +```javascript +const results = { deleted: [], failed: [], skipped: [] } + +for (const item of itemsToClean) { + TodoWrite({ todos: [...] }) // Mark current as in_progress + + try { + if (item.type === 'orphan_file' || item.type === 'dead_export') { + // Dead code: Delete file or remove export + Bash({ command: `rm -rf "${item.path}"` }) + } else { + // Sessions and documents: Delete directory/file + Bash({ command: `rm -rf "${item.path}"` }) + } + + results.deleted.push(item.path) + TodoWrite({ todos: [...] }) // Mark as completed + } catch (error) { + results.failed.push({ path: item.path, error: error.message }) + } +} +``` + +**Step 4.3: Update Manifests** +```javascript +// Update archives manifest if sessions were deleted +if (selectedCategories.includes('Sessions')) { + const archiveManifestPath = '.workflow/archives/manifest.json' + if (fileExists(archiveManifestPath)) { + const archiveManifest = JSON.parse(Read(archiveManifestPath)) + const deletedSessionIds = results.deleted + .filter(p => p.includes('WFS-')) + .map(p => p.split('/').pop()) + + const updatedManifest = archiveManifest.filter(entry => + !deletedSessionIds.includes(entry.session_id) + ) + + Write(archiveManifestPath, JSON.stringify(updatedManifest, null, 2)) + } +} + +// Update project-tech.json if features referenced deleted sessions +const projectPath = '.workflow/project-tech.json' +if (fileExists(projectPath)) { + const project = JSON.parse(Read(projectPath)) + const deletedPaths = new Set(results.deleted) + + project.features = project.features.filter(f => + !deletedPaths.has(f.traceability?.archive_path) + ) + + project.statistics.total_features = project.features.length + project.statistics.last_updated = getUtc8ISOString() + + Write(projectPath, JSON.stringify(project, null, 2)) +} +``` + +**Step 4.4: Report Results** +```javascript +console.log(` +## Cleanup Complete + +**Deleted**: ${results.deleted.length} items +**Failed**: ${results.failed.length} items +**Skipped**: ${results.skipped.length} items + +### Deleted Items +${results.deleted.map(p => `- ${p}`).join('\n')} + +${results.failed.length > 0 ? ` +### Failed Items +${results.failed.map(f => `- ${f.path}: ${f.error}`).join('\n')} +` : ''} + +Cleanup manifest archived to: ${sessionFolder}/cleanup-manifest.json +`) +``` + +--- + +## Session Folder Structure + +``` +.workflow/.clean/{YYYY-MM-DD}/ +├── mainline-profile.json # Git history analysis +└── cleanup-manifest.json # Discovery results +``` + +## Risk Level Definitions + +| Risk | Description | Examples | +|------|-------------|----------| +| **Low** | Safe to delete, no dependencies | Empty sessions, scratchpad files, 100% broken docs | +| **Medium** | Likely unused, verify before delete | Orphan files, old archives, partially broken docs | +| **High** | May have hidden dependencies | Files with some imports, recent modifications | + +## Error Handling + +| Situation | Action | +|-----------|--------| +| No git repository | Skip mainline detection, use file timestamps only | +| Session in use (.archiving) | Skip with warning | +| Permission denied | Report error, continue with others | +| Manifest parse error | Regenerate from filesystem scan | +| Empty discovery | Report "codebase is clean" | +| Subagent timeout | Continue waiting or催促 with send_input | + +## Codex Conversion Notes + +### Key Changes from Claude Task Version + +1. **Role Loading Pattern**: + - Claude: `Task(subagent_type="cli-explore-agent")` + - Codex: Pass role path in `MANDATORY FIRST STEPS`, agent reads `~/.codex/agents/cli-explore-agent.md` + +2. **Result Retrieval**: + - Claude: Synchronous Task return + - Codex: `wait({ ids: [agent], timeout_ms: 600000 })` + +3. **Timeout Handling**: + - Codex requires explicit handling of `timed_out` with retry or催促 + +4. **Lifecycle Management**: + - Codex requires explicit `close_agent()` after task completion + +5. **Error Recovery**: + - Can use `send_input()` to催促 agent if taking too long + - Can verify output file existence before closing agent + +## Related Commands + +- `/workflow:session:complete` - Properly archive active sessions +- `/memory:compact` - Save session memory before cleanup +- `/workflow:status` - View current workflow state diff --git a/.codex/skills/ccw-loop-b/README.md b/.codex/skills/ccw-loop-b/README.md index 971dc70d..f09e3297 100644 --- a/.codex/skills/ccw-loop-b/README.md +++ b/.codex/skills/ccw-loop-b/README.md @@ -1,102 +1,301 @@ -# CCW Loop-B (Hybrid Orchestrator Pattern) +# CCW Loop-B: Hybrid Orchestrator Pattern -协调器 + 专用 worker 的迭代开发工作流。 +Iterative development workflow using coordinator + specialized workers architecture. ## Overview -CCW Loop-B 采用混合模式设计: -- **Coordinator**: 状态管理、worker 调度、结果汇聚 -- **Workers**: 专注各自领域(develop/debug/validate) +CCW Loop-B implements a flexible orchestration pattern: +- **Coordinator**: Main agent managing state, user interaction, worker scheduling +- **Workers**: Specialized agents (init, develop, debug, validate, complete) +- **Modes**: Interactive / Auto / Parallel execution -## Installation +## Architecture ``` -.codex/skills/ccw-loop-b/ -+-- SKILL.md # Main skill definition -+-- README.md # This file -+-- phases/ -| +-- orchestrator.md # Coordinator logic -| +-- state-schema.md # State structure -+-- specs/ - +-- action-catalog.md # Action catalog - -.codex/agents/ -+-- ccw-loop-b-init.md # Init worker -+-- ccw-loop-b-develop.md # Develop worker -+-- ccw-loop-b-debug.md # Debug worker -+-- ccw-loop-b-validate.md # Validate worker -+-- ccw-loop-b-complete.md # Complete worker +Coordinator (Main Agent) + | + +-- Spawns Workers + | - ccw-loop-b-init.md + | - ccw-loop-b-develop.md + | - ccw-loop-b-debug.md + | - ccw-loop-b-validate.md + | - ccw-loop-b-complete.md + | + +-- Batch Wait (parallel mode) + +-- Sequential Wait (auto/interactive) + +-- State Management + +-- User Interaction ``` +## Subagent API + +Core APIs for worker orchestration: + +| API | 作用 | +|-----|------| +| `spawn_agent({ message })` | 创建 worker,返回 `agent_id` | +| `wait({ ids, timeout_ms })` | 等待结果(唯一取结果入口) | +| `send_input({ id, message })` | 继续交互 | +| `close_agent({ id })` | 关闭回收 | + +**可用模式**: 单 agent 深度交互 / 多 agent 并行 / 混合模式 + ## Execution Modes -| Mode | Description | Use Case | -|------|-------------|----------| -| `interactive` | 用户选择 action | 复杂任务,需要人工决策 | -| `auto` | 自动顺序执行 | 标准开发流程 | -| `parallel` | 并行多维度分析 | 需要快速全面评估 | +### Interactive Mode (default) -## Usage +Coordinator displays menu, user selects action, spawns corresponding worker. ```bash -# Interactive (default) /ccw-loop-b TASK="Implement feature X" - -# Auto mode -/ccw-loop-b --mode=auto TASK="Fix bug Y" - -# Parallel analysis -/ccw-loop-b --mode=parallel TASK="Analyze module Z" - -# Resume -/ccw-loop-b --loop-id=loop-b-xxx ``` -## Session Files +**Flow**: +1. Init: Parse task, create breakdown +2. Menu: Show options to user +3. User selects action (develop/debug/validate) +4. Spawn worker for selected action +5. Wait for result +6. Display result, back to menu +7. Repeat until complete + +### Auto Mode + +Automated sequential execution following predefined workflow. + +```bash +/ccw-loop-b --mode=auto TASK="Fix bug Y" +``` + +**Flow**: +1. Init → 2. Develop → 3. Validate → 4. Complete + +If issues found: loop back to Debug → Develop → Validate + +### Parallel Mode + +Spawn multiple workers simultaneously, batch wait for results. + +```bash +/ccw-loop-b --mode=parallel TASK="Analyze module Z" +``` + +**Flow**: +1. Init: Create analysis plan +2. Spawn workers in parallel: [develop, debug, validate] +3. Batch wait: `wait({ ids: [w1, w2, w3] })` +4. Merge results +5. Coordinator decides next action +6. Complete + +## Session Structure ``` .loop/ -+-- {loopId}.json # Master state -+-- {loopId}.workers/ # Worker outputs (JSON) -+-- {loopId}.progress/ # Human-readable progress (MD) ++-- {loopId}.json # Master state ++-- {loopId}.workers/ # Worker outputs +| +-- init.output.json +| +-- develop.output.json +| +-- debug.output.json +| +-- validate.output.json +| +-- complete.output.json ++-- {loopId}.progress/ # Human-readable logs + +-- develop.md + +-- debug.md + +-- validate.md + +-- summary.md ``` -## Core Pattern +## Worker Responsibilities -### Coordinator + Worker +| Worker | Role | Specialization | +|--------|------|----------------| +| **init** | Session initialization | Task parsing, breakdown, planning | +| **develop** | Code implementation | File operations, pattern matching, incremental development | +| **debug** | Problem diagnosis | Root cause analysis, hypothesis testing, fix recommendations | +| **validate** | Testing & verification | Test execution, coverage analysis, quality gates | +| **complete** | Session finalization | Summary generation, commit preparation, cleanup | -```javascript -// Coordinator spawns specialized worker -const worker = spawn_agent({ message: buildWorkerPrompt(action) }) +## Usage Examples -// Wait for completion -const result = wait({ ids: [worker], timeout_ms: 600000 }) +### Example 1: Simple Feature Implementation -// Process result -const output = result.status[worker].completed -updateState(output) - -// Cleanup -close_agent({ id: worker }) +```bash +/ccw-loop-b TASK="Add user logout function" ``` -### Batch Wait (Parallel Mode) +**Auto flow**: +- Init: Parse requirements +- Develop: Implement logout in `src/auth.ts` +- Validate: Run tests +- Complete: Generate commit message + +### Example 2: Bug Investigation + +```bash +/ccw-loop-b TASK="Fix memory leak in WebSocket handler" +``` + +**Interactive flow**: +1. Init: Parse issue +2. User selects "debug" → Spawn debug worker +3. Debug: Root cause analysis → recommends fix +4. User selects "develop" → Apply fix +5. User selects "validate" → Verify fix works +6. User selects "complete" → Generate summary + +### Example 3: Comprehensive Analysis + +```bash +/ccw-loop-b --mode=parallel TASK="Analyze payment module for improvements" +``` + +**Parallel flow**: +- Spawn [develop, debug, validate] workers simultaneously +- Develop: Analyze code quality and patterns +- Debug: Identify potential issues +- Validate: Check test coverage +- Wait for all three to complete +- Merge findings into comprehensive report + +### Example 4: Resume Existing Loop + +```bash +/ccw-loop-b --loop-id=loop-b-20260122-abc123 +``` + +Continues from previous state, respects status (running/paused). + +## Key Features + +### 1. Worker Specialization + +Each worker focuses on one domain: +- **No overlap**: Clear boundaries between workers +- **Reusable**: Same worker for different tasks +- **Composable**: Combine workers for complex workflows + +### 2. Flexible Coordination + +Coordinator adapts to mode: +- **Interactive**: Menu-driven, user controls flow +- **Auto**: Predetermined sequence +- **Parallel**: Concurrent execution with batch wait + +### 3. State Management + +Unified state at `.loop/{loopId}.json`: +- **API compatible**: Works with CCW API +- **Extension fields**: Skill-specific data in `skill_state` +- **Worker outputs**: Structured JSON for each action + +### 4. Progress Tracking + +Human-readable logs: +- **Per-worker progress**: `{action}.md` files +- **Summary**: Consolidated achievements +- **Commit-ready**: Formatted commit messages + +## Best Practices + +1. **Start with Init**: Always initialize before execution +2. **Use appropriate mode**: + - Interactive: Complex tasks needing user decisions + - Auto: Well-defined workflows + - Parallel: Independent analysis tasks +3. **Clean up workers**: `close_agent()` after each worker completes +4. **Batch wait wisely**: Use in parallel mode for efficiency +5. **Track progress**: Document in progress files +6. **Validate often**: After each develop phase + +## Implementation Patterns + +### Pattern 1: Single Worker Deep Interaction ```javascript -// Spawn multiple workers -const workers = [ - spawn_agent({ message: developPrompt }), - spawn_agent({ message: debugPrompt }), - spawn_agent({ message: validatePrompt }) -] +const workerId = spawn_agent({ message: workerPrompt }) +const result1 = wait({ ids: [workerId] }) + +// Continue with same worker +send_input({ id: workerId, message: "Continue with next task" }) +const result2 = wait({ ids: [workerId] }) + +close_agent({ id: workerId }) +``` + +### Pattern 2: Multi-Worker Parallel + +```javascript +const workers = { + develop: spawn_agent({ message: developPrompt }), + debug: spawn_agent({ message: debugPrompt }), + validate: spawn_agent({ message: validatePrompt }) +} // Batch wait -const results = wait({ ids: workers, timeout_ms: 900000 }) +const results = wait({ ids: Object.values(workers), timeout_ms: 900000 }) -// Merge results -const merged = mergeOutputs(results) +// Process all results +Object.values(workers).forEach(id => close_agent({ id })) ``` -## License +### Pattern 3: Sequential Worker Chain -MIT +```javascript +const actions = ['init', 'develop', 'validate', 'complete'] + +for (const action of actions) { + const workerId = spawn_agent({ message: buildPrompt(action) }) + const result = wait({ ids: [workerId] }) + + updateState(action, result) + close_agent({ id: workerId }) +} +``` + +## Error Handling + +| Error | Recovery | +|-------|----------| +| Worker timeout | `send_input` request convergence | +| Worker fails | Log error, coordinator decides retry strategy | +| Partial results | Use completed workers, mark incomplete | +| State corruption | Rebuild from progress files | + +## File Structure + +``` +.codex/skills/ccw-loop-b/ ++-- SKILL.md # Entry point ++-- README.md # This file ++-- phases/ +| +-- state-schema.md # State structure definition ++-- specs/ + +-- action-catalog.md # Action reference + +.codex/agents/ ++-- ccw-loop-b-init.md # Worker: Init ++-- ccw-loop-b-develop.md # Worker: Develop ++-- ccw-loop-b-debug.md # Worker: Debug ++-- ccw-loop-b-validate.md # Worker: Validate ++-- ccw-loop-b-complete.md # Worker: Complete +``` + +## Comparison: ccw-loop vs ccw-loop-b + +| Aspect | ccw-loop | ccw-loop-b | +|--------|----------|------------| +| Pattern | Single agent, multi-phase | Coordinator + workers | +| Worker model | Single agent handles all | Specialized workers per action | +| Parallelization | Sequential only | Supports parallel mode | +| Flexibility | Fixed sequence | Mode-based (interactive/auto/parallel) | +| Best for | Simple linear workflows | Complex tasks needing specialization | + +## Contributing + +To add new workers: +1. Create worker role file in `.codex/agents/` +2. Define clear responsibilities +3. Update `action-catalog.md` +4. Add worker to coordinator spawn logic +5. Test integration with existing workers diff --git a/.codex/skills/ccw-loop-b/specs/action-catalog.md b/.codex/skills/ccw-loop-b/specs/action-catalog.md new file mode 100644 index 00000000..1d628d91 --- /dev/null +++ b/.codex/skills/ccw-loop-b/specs/action-catalog.md @@ -0,0 +1,383 @@ +# Action Catalog (CCW Loop-B) + +Complete reference of worker actions and their capabilities. + +## Action Matrix + +| Action | Worker Agent | Purpose | Input Requirements | Output | +|--------|--------------|---------|-------------------|--------| +| init | ccw-loop-b-init.md | Session initialization | Task description | Task breakdown + execution plan | +| develop | ccw-loop-b-develop.md | Code implementation | Task list | Code changes + progress update | +| debug | ccw-loop-b-debug.md | Problem diagnosis | Issue description | Root cause analysis + fix suggestions | +| validate | ccw-loop-b-validate.md | Testing and verification | Files to test | Test results + coverage report | +| complete | ccw-loop-b-complete.md | Session finalization | All worker outputs | Summary + commit message | + +## Detailed Action Specifications + +### INIT + +**Purpose**: Parse requirements, create execution plan + +**Preconditions**: +- `status === 'running'` +- `skill_state === null` (first time) + +**Input**: +``` +- Task description (text) +- Project context files +``` + +**Execution**: +1. Read `.workflow/project-tech.json` +2. Read `.workflow/project-guidelines.json` +3. Parse task into phases +4. Create task breakdown +5. Generate execution plan + +**Output**: +``` +WORKER_RESULT: +- action: init +- status: success +- summary: "Initialized with 5 tasks" +- next_suggestion: develop + +TASK_BREAKDOWN: +- T1: Create auth module +- T2: Implement JWT utils +- T3: Write tests +- T4: Validate implementation +- T5: Documentation + +EXECUTION_PLAN: +1. Develop (T1-T2) +2. Validate (T3-T4) +3. Complete (T5) +``` + +**Effects**: +- `skill_state.pending_tasks` populated +- Progress structure created +- Ready for develop phase + +--- + +### DEVELOP + +**Purpose**: Implement code, create/modify files + +**Preconditions**: +- `skill_state.pending_tasks.length > 0` +- `status === 'running'` + +**Input**: +``` +- Task list from state +- Project conventions +- Existing code patterns +``` + +**Execution**: +1. Load pending tasks +2. Find existing patterns +3. Implement tasks one by one +4. Update progress file +5. Mark tasks completed + +**Output**: +``` +WORKER_RESULT: +- action: develop +- status: success +- summary: "Implemented 3 tasks" +- files_changed: ["src/auth.ts", "src/utils.ts"] +- next_suggestion: validate + +DETAILED_OUTPUT: + tasks_completed: [T1, T2] + metrics: + lines_added: 180 + lines_removed: 15 +``` + +**Effects**: +- Files created/modified +- `skill_state.completed_tasks` updated +- Progress documented + +**Failure Modes**: +- Pattern unclear → suggest debug +- Task blocked → mark blocked, continue +- Partial completion → set `loop_back_to: "develop"` + +--- + +### DEBUG + +**Purpose**: Diagnose issues, root cause analysis + +**Preconditions**: +- Issue exists (test failure, bug report, etc.) +- `status === 'running'` + +**Input**: +``` +- Issue description +- Error messages +- Stack traces +- Reproduction steps +``` + +**Execution**: +1. Understand problem symptoms +2. Gather evidence from code +3. Form hypothesis +4. Test hypothesis +5. Document root cause +6. Suggest fixes + +**Output**: +``` +WORKER_RESULT: +- action: debug +- status: success +- summary: "Root cause: memory leak in event listeners" +- next_suggestion: develop (apply fixes) + +ROOT_CAUSE_ANALYSIS: + hypothesis: "Listener accumulation" + confidence: high + evidence: [...] + mechanism: "Detailed explanation" + +FIX_RECOMMENDATIONS: + 1. Add removeAllListeners() on disconnect + 2. Verification: Monitor memory usage +``` + +**Effects**: +- `skill_state.findings` updated +- Fix recommendations documented +- Ready for develop to apply fixes + +**Failure Modes**: +- Insufficient info → request more data +- Multiple hypotheses → rank by likelihood +- Inconclusive → suggest investigation areas + +--- + +### VALIDATE + +**Purpose**: Run tests, check coverage, quality gates + +**Preconditions**: +- Code exists to validate +- `status === 'running'` + +**Input**: +``` +- Files to test +- Test configuration +- Coverage requirements +``` + +**Execution**: +1. Identify test framework +2. Run unit tests +3. Run integration tests +4. Measure coverage +5. Check quality (lint, types, security) +6. Generate report + +**Output**: +``` +WORKER_RESULT: +- action: validate +- status: success +- summary: "113 tests pass, coverage 95%" +- next_suggestion: complete (all pass) | develop (fix failures) + +TEST_RESULTS: + unit_tests: { passed: 98, failed: 0 } + integration_tests: { passed: 15, failed: 0 } + coverage: "95%" + +QUALITY_CHECKS: + lint: ✓ Pass + types: ✓ Pass + security: ✓ Pass +``` + +**Effects**: +- Test results documented +- Coverage measured +- Quality gates verified + +**Failure Modes**: +- Tests fail → document failures, suggest fixes +- Coverage low → identify gaps +- Quality issues → flag problems + +--- + +### COMPLETE + +**Purpose**: Finalize session, generate summary, commit + +**Preconditions**: +- All tasks completed +- Tests passing +- `status === 'running'` + +**Input**: +``` +- All worker outputs +- Progress files +- Current state +``` + +**Execution**: +1. Read all worker outputs +2. Consolidate achievements +3. Verify completeness +4. Generate summary +5. Prepare commit message +6. Cleanup and archive + +**Output**: +``` +WORKER_RESULT: +- action: complete +- status: success +- summary: "Session completed successfully" +- next_suggestion: null + +SESSION_SUMMARY: + achievements: [...] + files_changed: [...] + test_results: { ... } + quality_checks: { ... } + +COMMIT_SUGGESTION: + message: "feat: ..." + files: [...] + ready_for_pr: true +``` + +**Effects**: +- `status` → 'completed' +- Summary file created +- Progress archived +- Commit message ready + +**Failure Modes**: +- Pending tasks remain → mark partial +- Quality gates fail → list failures + +--- + +## Action Flow Diagrams + +### Interactive Mode Flow + +``` ++------+ +| INIT | ++------+ + | + v ++------+ user selects +| MENU |-------------+ ++------+ | + ^ v + | +--------------+ + | | spawn worker | + | +--------------+ + | | + | v + | +------+-------+ + +---------| wait result | + +------+-------+ + | + v + +------+-------+ + | update state | + +--------------+ + | + v + [completed?] --no--> [back to MENU] + | + yes + v + +----------+ + | COMPLETE | + +----------+ +``` + +### Auto Mode Flow + +``` ++------+ +---------+ +-------+ +----------+ +----------+ +| INIT | ---> | DEVELOP | ---> | DEBUG | ---> | VALIDATE | ---> | COMPLETE | ++------+ +---------+ +-------+ +----------+ +----------+ + ^ | | + | +--- [issues] | + +--------------------------------+ + [tests fail] +``` + +### Parallel Mode Flow + +``` ++------+ +| INIT | ++------+ + | + v ++---------------------+ +| spawn all workers | +| [develop, debug, | +| validate] | ++---------------------+ + | + v ++---------------------+ +| wait({ ids: all }) | ++---------------------+ + | + v ++---------------------+ +| merge results | ++---------------------+ + | + v ++---------------------+ +| coordinator decides | ++---------------------+ + | + v ++----------+ +| COMPLETE | ++----------+ +``` + +## Worker Coordination + +| Scenario | Worker Sequence | Mode | +|----------|-----------------|------| +| Simple task | init → develop → validate → complete | Auto | +| Complex task | init → develop → debug → develop → validate → complete | Auto | +| Bug fix | init → debug → develop → validate → complete | Auto | +| Analysis | init → [develop \|\| debug \|\| validate] → complete | Parallel | +| Interactive | init → menu → user selects → worker → menu → ... | Interactive | + +## Best Practices + +1. **Init always first**: Parse requirements before execution +2. **Validate often**: After each develop phase +3. **Debug when needed**: Don't skip diagnosis +4. **Complete always last**: Ensure proper cleanup +5. **Use parallel wisely**: For independent analysis tasks +6. **Follow sequence**: In auto mode, respect dependencies