mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +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
|
||||
|
||||
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
|
||||
|
||||
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