mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-10 02:24:35 +08:00
feat: Add ccw-loop-b hybrid orchestrator skill with specialized workers
Create new ccw-loop-b skill implementing coordinator + workers architecture: **Skill Structure**: - SKILL.md: Entry point with three execution modes (interactive/auto/parallel) - phases/state-schema.md: Unified state structure - specs/action-catalog.md: Complete action reference **Worker Agents**: - ccw-loop-b-init.md: Session initialization and task breakdown - ccw-loop-b-develop.md: Code implementation and file operations - ccw-loop-b-debug.md: Root cause analysis and problem diagnosis - ccw-loop-b-validate.md: Testing, coverage, and quality checks - ccw-loop-b-complete.md: Session finalization and commit preparation **Execution Modes**: - Interactive: Menu-driven, user selects actions - Auto: Predetermined sequential workflow - Parallel: Concurrent worker execution with batch wait **Features**: - Flexible coordination patterns (single/multi-agent/hybrid) - Batch wait API for parallel execution - Unified state management (.loop/ directory) - Per-worker progress tracking - No Claude/Codex comparison content (follows new guidelines) Follows updated design principles: - Content independence (no framework comparisons) - Mode flexibility (no over-constraining) - Coordinator pattern with specialized workers
This commit is contained in:
catlog22
227
.codex/agents/ccw-loop-b-complete.md
Normal file
227
.codex/agents/ccw-loop-b-complete.md
Normal file
@@ -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
|
||||||
172
.codex/agents/ccw-loop-b-debug.md
Normal file
172
.codex/agents/ccw-loop-b-debug.md
Normal file
@@ -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
|
||||||
147
.codex/agents/ccw-loop-b-develop.md
Normal file
147
.codex/agents/ccw-loop-b-develop.md
Normal file
@@ -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
|
||||||
82
.codex/agents/ccw-loop-b-init.md
Normal file
82
.codex/agents/ccw-loop-b-init.md
Normal file
@@ -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
|
||||||
204
.codex/agents/ccw-loop-b-validate.md
Normal file
204
.codex/agents/ccw-loop-b-validate.md
Normal file
@@ -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
|
||||||
581
.codex/commands/workflow/clean.md
Normal file
581
.codex/commands/workflow/clean.md
Normal file
@@ -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
|
||||||
@@ -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
|
## Overview
|
||||||
|
|
||||||
CCW Loop-B 采用混合模式设计：
|
CCW Loop-B implements a flexible orchestration pattern:
|
||||||
- **Coordinator**: 状态管理、worker 调度、结果汇聚
|
- **Coordinator**: Main agent managing state, user interaction, worker scheduling
|
||||||
- **Workers**: 专注各自领域（develop/debug/validate）
|
- **Workers**: Specialized agents (init, develop, debug, validate, complete)
|
||||||
|
- **Modes**: Interactive / Auto / Parallel execution
|
||||||
|
|
||||||
## Installation
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
.codex/skills/ccw-loop-b/
|
Coordinator (Main Agent)
|
||||||
+-- SKILL.md # Main skill definition
|
|
|
||||||
+-- README.md # This file
|
+-- Spawns Workers
|
||||||
+-- phases/
|
| - ccw-loop-b-init.md
|
||||||
| +-- orchestrator.md # Coordinator logic
|
| - ccw-loop-b-develop.md
|
||||||
| +-- state-schema.md # State structure
|
| - ccw-loop-b-debug.md
|
||||||
+-- specs/
|
| - ccw-loop-b-validate.md
|
||||||
+-- action-catalog.md # Action catalog
|
| - ccw-loop-b-complete.md
|
||||||
|
|
|
||||||
.codex/agents/
|
+-- Batch Wait (parallel mode)
|
||||||
+-- ccw-loop-b-init.md # Init worker
|
+-- Sequential Wait (auto/interactive)
|
||||||
+-- ccw-loop-b-develop.md # Develop worker
|
+-- State Management
|
||||||
+-- ccw-loop-b-debug.md # Debug worker
|
+-- User Interaction
|
||||||
+-- ccw-loop-b-validate.md # Validate worker
|
|
||||||
+-- ccw-loop-b-complete.md # Complete worker
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## 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
|
## Execution Modes
|
||||||
|
|
||||||
| Mode | Description | Use Case |
|
### Interactive Mode (default)
|
||||||
|------|-------------|----------|
|
|
||||||
| `interactive` | 用户选择 action | 复杂任务，需要人工决策 |
|
|
||||||
| `auto` | 自动顺序执行 | 标准开发流程 |
|
|
||||||
| `parallel` | 并行多维度分析 | 需要快速全面评估 |
|
|
||||||
|
|
||||||
## Usage
|
Coordinator displays menu, user selects action, spawns corresponding worker.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Interactive (default)
|
|
||||||
/ccw-loop-b TASK="Implement feature X"
|
/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/
|
.loop/
|
||||||
+-- {loopId}.json # Master state
|
+-- {loopId}.json # Master state
|
||||||
+-- {loopId}.workers/ # Worker outputs (JSON)
|
+-- {loopId}.workers/ # Worker outputs
|
||||||
+-- {loopId}.progress/ # Human-readable progress (MD)
|
| +-- 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
|
## Usage Examples
|
||||||
// Coordinator spawns specialized worker
|
|
||||||
const worker = spawn_agent({ message: buildWorkerPrompt(action) })
|
|
||||||
|
|
||||||
// Wait for completion
|
### Example 1: Simple Feature Implementation
|
||||||
const result = wait({ ids: [worker], timeout_ms: 600000 })
|
|
||||||
|
|
||||||
// Process result
|
```bash
|
||||||
const output = result.status[worker].completed
|
/ccw-loop-b TASK="Add user logout function"
|
||||||
updateState(output)
|
|
||||||
|
|
||||||
// Cleanup
|
|
||||||
close_agent({ id: worker })
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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
|
```javascript
|
||||||
// Spawn multiple workers
|
const workerId = spawn_agent({ message: workerPrompt })
|
||||||
const workers = [
|
const result1 = wait({ ids: [workerId] })
|
||||||
spawn_agent({ message: developPrompt }),
|
|
||||||
spawn_agent({ message: debugPrompt }),
|
// Continue with same worker
|
||||||
spawn_agent({ message: validatePrompt })
|
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
|
// Batch wait
|
||||||
const results = wait({ ids: workers, timeout_ms: 900000 })
|
const results = wait({ ids: Object.values(workers), timeout_ms: 900000 })
|
||||||
|
|
||||||
// Merge results
|
// Process all results
|
||||||
const merged = mergeOutputs(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
|
||||||
|
|||||||
383
.codex/skills/ccw-loop-b/specs/action-catalog.md
Normal file
383
.codex/skills/ccw-loop-b/specs/action-catalog.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user