zhongwei/gh-michael-harris-claude-code-multi-agent-dev-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:40:21 +08:00
commit 17a685e3a6
89 changed files with 43606 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
commands/feature.md Normal file
View File

@@ -0,0 +1,350 @@
# Feature Command
You are implementing a **complete feature workflow** from description to delivery.
## Command Usage
`/multi-agent:feature [feature description]` - Complete workflow: PRD → Planning → Implementation
`/multi-agent:feature [feature description] --tracks N` - Same workflow with N parallel development tracks
Examples:
- `/multi-agent:feature Add user authentication with OAuth and 2FA`
- `/multi-agent:feature Implement real-time notifications using WebSockets`
- `/multi-agent:feature Create analytics dashboard with charts and exports --tracks 2`
- `/multi-agent:feature Build ML recommendation engine --tracks 3`
The `--tracks` parameter is optional. If not specified, single-track mode is used.
## Your Process
### Step 0: Parse Parameters
Extract parameters from the command:
- Feature description (required)
- Number of tracks (optional, from `--tracks N`, default: 1)
This is a **macro command** that orchestrates the complete development lifecycle.
### Phase 1: PRD Generation
**Launch PRD Generator:**
```javascript
Task(
subagent_type="multi-agent:planning:prd-generator",
model="sonnet",
description="Generate PRD for feature",
prompt=`Create a Product Requirements Document for this feature:
FEATURE: ${featureDescription}
Conduct interactive interview to gather:
1. Technology stack needed (or use existing project stack)
2. User stories and use cases
3. Acceptance criteria
4. Technical requirements
5. Integration points with existing system
6. Security requirements
7. Performance requirements
Generate PRD at: docs/planning/FEATURE_${featureId}_PRD.yaml
If this is adding to an existing project:
- Review existing code structure
- Maintain consistency with existing tech stack
- Consider integration with existing features
`
)
```
### Phase 2: Planning & Task Breakdown
**Launch Planning Workflow:**
```javascript
// Task Graph Analyzer
Task(
subagent_type="multi-agent:planning:task-graph-analyzer",
model="sonnet",
description="Break feature into tasks",
prompt=`Analyze PRD and create task breakdown:
PRD: docs/planning/FEATURE_${featureId}_PRD.yaml
Create tasks in: docs/planning/tasks/
Prefix task IDs with FEATURE-${featureId}-
Identify dependencies and create dependency graph.
Calculate maximum possible parallel development tracks.
Keep tasks small (1-2 days each).
`
)
// Sprint Planner
Task(
subagent_type="multi-agent:planning:sprint-planner",
model="sonnet",
description="Organize tasks into sprints",
prompt=`Organize feature tasks into sprints:
Tasks: docs/planning/tasks/FEATURE-${featureId}-*
Dependencies: docs/planning/task-dependency-graph.md
Requested parallel tracks: ${requestedTracks}
If tracks > 1:
Create sprints: docs/sprints/FEATURE_${featureId}_SPRINT-XXX-YY.yaml
Initialize state file: docs/planning/.feature-${featureId}-state.yaml
If tracks = 1:
Create sprints: docs/sprints/FEATURE_${featureId}_SPRINT-XXX.yaml
Initialize state file: docs/planning/.feature-${featureId}-state.yaml
Balance sprint capacity and respect dependencies.
If requested tracks > max possible, use max possible and warn user.
`
)
```
### Phase 3: Execute All Sprints
**Launch Sprint Execution:**
```javascript
Task(
subagent_type="multi-agent:orchestration:sprint-orchestrator",
model="sonnet",
description="Execute all feature sprints",
prompt=`Execute ALL sprints for feature ${featureId} sequentially:
Sprint files: docs/sprints/FEATURE_${featureId}_SPRINT-*.yaml
State file: docs/planning/.feature-${featureId}-state.yaml
IMPORTANT - Progress Tracking:
1. Load state file at start
2. Check for resume point (skip completed sprints)
3. Update state after each sprint/task completion
4. Enable resumption if interrupted
For each sprint:
1. Check state file - skip if already completed
2. Execute all tasks with task-orchestrator
3. Update task status in state file after each completion
4. Run final code review (code, security, performance)
5. Update documentation
6. Mark sprint as completed in state file
7. Generate sprint report
After all sprints:
5. Run comprehensive feature review
6. Verify integration with existing system
7. Update project documentation
8. Generate feature completion report
9. Mark feature as complete in state file
Do NOT proceed to next sprint unless current sprint passes all quality gates.
`
)
```
### Phase 4: Feature Integration Verification
**After implementation, verify integration:**
```
1. Run all existing tests (ensure no regressions)
2. Test feature in isolation
3. Test feature integrated with existing features
4. Verify API compatibility
5. Check database migrations applied correctly
6. Verify configuration changes documented
```
### Phase 5: Documentation Update
**Update project documentation:**
- Add feature to README
- Update API documentation
- Add feature guide
- Update changelog
### User Communication
**Starting:**
```
🚀 Feature Implementation Workflow Started
Feature: ${featureDescription}
Phase 1/3: Generating PRD...
Conducting interactive interview to gather requirements...
```
**Progress Updates:**
```
✅ Phase 1 Complete: PRD Generated
docs/planning/FEATURE_001_PRD.yaml
📋 Phase 2/3: Planning...
Breaking down into tasks...
✅ Created 8 tasks
✅ Organized into 2 sprints
🔨 Phase 3/3: Implementation...
Sprint 1/2: Core functionality
Task 1/4: Database schema
Task 2/4: API endpoints
...
✅ Sprint 1 complete
Sprint 2/2: Integration & polish
Task 1/4: Frontend components
...
✅ Sprint 2 complete
🎯 Running final feature review...
✅ Code review passed
✅ Security audit passed
✅ Performance audit passed
✅ Integration tests passed
✅ Documentation updated
```
**Completion:**
```
╔══════════════════════════════════════════╗
║ ✅ FEATURE COMPLETE ✅ ║
╚══════════════════════════════════════════╝
Feature: ${featureDescription}
Implementation Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Tasks Completed: 8/8
Sprints: 2/2
Quality: All checks passed ✅
Files Changed:
• 12 files modified
• 847 lines added
• 45 lines removed
Testing:
• Unit tests: 23 added, all passing
• Integration tests: 5 added, all passing
• Coverage: 87%
Documentation:
• API docs updated
• README updated
• Feature guide created
Ready for review and deployment! 🚀
Next steps:
1. Review changes: git diff main
2. Test feature manually
3. Deploy to staging
4. Create pull request
```
## Error Handling
**Invalid feature description:**
```
Error: Feature description too vague
Please provide more details. Examples:
✅ "Add OAuth login with Google and GitHub"
❌ "Add login"
✅ "Implement WebSocket notifications for task updates"
❌ "Add notifications"
```
**Feature too large:**
```
⚠️ Warning: Feature spans 6 sprints (12+ tasks)
Recommendation: Break into smaller features
Consider splitting into:
1. /multi-agent:feature User authentication (OAuth only)
2. /multi-agent:feature Two-factor authentication
3. /multi-agent:feature Social login integration
```
**Integration conflicts:**
```
❌ Integration test failed
Conflict: New auth system incompatible with existing session handling
Pausing for resolution.
Recommend:
1. Review existing auth code: backend/auth/
2. Decide on migration strategy
3. Update or revert changes
```
## Advanced Usage
**Add to existing project:**
```
/multi-agent:feature Add GraphQL API alongside existing REST API
(System detects existing project structure and integrates)
```
**Specify technical details:**
```
/multi-agent:feature Implement caching layer using Redis with 5-minute TTL for user queries
```
**Complex features:**
```
/multi-agent:feature Build ML-powered recommendation engine using scikit-learn, with API endpoints and admin dashboard
```
## Workflow Diagram
```
User: /multi-agent:feature Add real-time chat
↓
1. PRD Generation (interactive)
↓
2. Task Breakdown + Sprint Planning
↓
3. Sprint Execution (all sprints)
├── Sprint 1: Database + API
├── Sprint 2: WebSocket server
└── Sprint 3: Frontend UI
↓
4. Feature Integration
├── Code review
├── Security audit
├── Performance audit
└── Integration tests
↓
5. Documentation Update
↓
✅ Feature Complete
```
## Cost Estimation
**Small feature (1 sprint, 3-5 tasks):**
- PRD: ~$0.50
- Planning: ~$0.30
- Implementation: ~$2-4
- **Total: ~$3-5**
**Medium feature (2-3 sprints, 8-12 tasks):**
- PRD: ~$0.70
- Planning: ~$0.50
- Implementation: ~$8-15
- **Total: ~$10-20**
**Large feature (4-6 sprints, 15-25 tasks):**
- PRD: ~$1.00
- Planning: ~$1.00
- Implementation: ~$25-50
- **Total: ~$30-60**
Time saved: **90-95% vs manual development**

468
commands/issue.md Normal file
View File

@@ -0,0 +1,468 @@
# Issue Command
You are implementing a **complete issue resolution workflow** from bug report to fix.
## Command Usage
`/multi-agent:issue [issue description or GitHub issue URL]` - Complete bug fix workflow
`/multi-agent:issue [issue description] --tracks N` - Same workflow with N parallel tracks (rare for small issues)
Examples:
- `/multi-agent:issue https://github.com/user/repo/issues/123`
- `/multi-agent:issue Fix memory leak in WebSocket handler`
- `/multi-agent:issue Users can't login after password reset`
- `/multi-agent:issue API returns 500 error for /users endpoint with pagination`
- `/multi-agent:issue Refactor authentication system for better performance --tracks 2`
Note: Most issues are small enough that tracks=1 (default) is sufficient. Parallel tracks are useful only for large, complex issues that span multiple independent components.
## Your Process
This is a **macro command** for rapid issue resolution.
### Phase 1: Issue Analysis
**Gather Information:**
If GitHub URL provided:
```javascript
// Use gh CLI to fetch issue details
Task(
subagent_type="general-purpose",
model="sonnet",
description="Fetch GitHub issue details",
prompt=`Fetch issue details:
gh issue view ${issueNumber} --json title,body,labels,comments
Extract:
- Issue title
- Description
- Steps to reproduce
- Expected vs actual behavior
- Labels/tags
- Related code references
`
)
```
If description provided:
- Analyze issue description
- Identify affected components
- Determine severity (critical/high/medium/low)
- Identify issue type (bug/performance/security/enhancement)
### Phase 2: Create Lightweight PRD
**Generate focused PRD:**
```javascript
Task(
subagent_type="multi-agent:planning:prd-generator",
model="sonnet",
description="Create issue PRD",
prompt=`Create focused PRD for issue resolution:
ISSUE: ${issueDescription}
Create lightweight PRD:
- Problem statement
- Root cause (if known)
- Solution approach
- Acceptance criteria:
* Issue is resolved
* No regressions introduced
* Tests added to prevent recurrence
- Testing requirements
- Affected components
Output: docs/planning/ISSUE_${issueId}_PRD.yaml
Keep it concise - this is a bug fix, not a feature.
`
)
```
### Phase 3: Task Creation & Sprint Planning
**Create tasks and organize into sprint:**
```javascript
// First, create tasks
Task(
subagent_type="multi-agent:planning:task-graph-analyzer",
model="sonnet",
description="Create issue resolution tasks",
prompt=`Create tasks for issue resolution:
Issue PRD: docs/planning/ISSUE_${issueId}_PRD.yaml
Create tasks in: docs/planning/tasks/
Prefix task IDs with ISSUE-${issueId}-
Task breakdown should include:
- Investigate and identify root cause
- Implement fix
- Add/update tests
- Verify no regressions
Most issues will be 1 task, but complex issues may require multiple tasks with dependencies.
Identify all dependencies between tasks.
`
)
// Then, organize into sprint
Task(
subagent_type="multi-agent:planning:sprint-planner",
model="sonnet",
description="Organize issue tasks into sprint",
prompt=`Organize issue resolution tasks into a sprint:
Tasks: docs/planning/tasks/ISSUE-${issueId}-*
Dependencies: Check task files for dependencies
Requested parallel tracks: 1 (single-track for issues)
Create sprint: docs/sprints/ISSUE_${issueId}_SPRINT-001.yaml
Initialize state file: docs/planning/.issue-${issueId}-state.yaml
Even if there's only 1 task, create a proper sprint structure to ensure consistent workflow.
Balance sprint capacity and respect dependencies.
`
)
```
### Phase 4: Execute Sprint
**Launch sprint orchestrator:**
```javascript
Task(
subagent_type="multi-agent:orchestration:sprint-orchestrator",
model="sonnet",
description="Execute issue resolution sprint",
prompt=`Execute sprint for issue ${issueId}:
Sprint file: docs/sprints/ISSUE_${issueId}_SPRINT-001.yaml
State file: docs/planning/.issue-${issueId}-state.yaml
Technology stack: docs/planning/PROJECT_PRD.yaml or ISSUE_${issueId}_PRD.yaml
CRITICAL - Autonomous Execution:
You MUST execute autonomously without stopping or requesting permission. Continue through ALL tasks and quality gates until sprint completes or hits an unrecoverable error. DO NOT pause, DO NOT ask for confirmation, DO NOT wait for user input.
IMPORTANT - State Tracking & Resume:
1. Load state file at start
2. Check sprint status (skip if completed, resume if in_progress)
3. Update state after EACH task completion
4. Save state regularly to enable resumption
Workflow for each task:
1. Investigate root cause (use appropriate language developer)
2. Implement fix (T1 first, escalate to T2 if needed)
3. Run code reviewer
4. Run security auditor (if security issue)
5. Run performance auditor (if performance issue)
6. Add tests to prevent regression
7. Verify fix with requirements validator
8. Run workflow compliance check
Use T2 agents directly if:
- Critical severity
- Security vulnerability
- Complex root cause
Execute autonomously until sprint completes.
`
)
```
### Phase 5: Verification & Documentation
**Comprehensive verification:**
```
1. Run all existing tests (no regressions)
2. Verify specific issue is resolved
3. Check related functionality still works
4. Security scan if relevant
5. Performance check if relevant
```
**Update documentation:**
- Add to changelog
- Update relevant docs if behavior changed
- Add comments in code if complex fix
**GitHub integration (if issue from GitHub):**
```bash
# Comment on issue with fix details
gh issue comment ${issueNumber} --body "Fixed in commit ${commitHash}
Changes:
- [describe fix]
Testing:
- [tests added]
Verification:
- [how to verify]"
# Close issue
gh issue close ${issueNumber}
```
### User Communication
**Starting:**
```
🔍 Issue Resolution Workflow Started
Issue: ${issueDescription}
Phase 1/5: Analyzing issue...
Identifying affected components...
Determining severity: ${severity}
```
**Progress:**
```
✅ Phase 1/5: Analysis complete
Root cause: Memory leak in event handler (handlers/websocket.py)
Severity: High
📋 Phase 2/5: Creating resolution plan...
✅ Generated focused PRD
📋 Phase 3/5: Planning sprint...
✅ Created 2 resolution tasks
✅ Organized into sprint ISSUE_001_SPRINT-001
🔨 Phase 4/5: Executing sprint...
Sprint 1/1: ISSUE_001_SPRINT-001
Task 1/2: Investigate and fix root cause
Investigating root cause...
✅ Found: Goroutine leak, missing context cancellation
Implementing fix (T1 agent)...
✅ Added context.WithCancel()
✅ Added proper cleanup
Running code review...
✅ Code review passed
Task 2/2: Add regression tests
Adding tests...
✅ Added regression test
✅ Test confirms fix works
Running workflow compliance check...
✅ Workflow compliance verified
✅ Sprint complete
✅ Phase 5/5: Verification...
✅ All existing tests pass
✅ Issue resolved
✅ No regressions
```
**Completion:**
```
╔══════════════════════════════════════════╗
║ ✅ ISSUE RESOLVED ✅ ║
╚══════════════════════════════════════════╝
Issue: Memory leak in WebSocket handler
Resolution Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Root Cause: Goroutine leak - missing cancellation
Fix: Added context.WithCancel() and cleanup
Impact: Prevents memory leak under load
Changes:
• handlers/websocket.go (modified)
• handlers/websocket_test.go (added tests)
Testing:
• Added regression test
• Verified fix with load test
• All existing tests passing
Documentation:
• Changelog updated
• Code comments added
Ready to commit and deploy! 🚀
${githubIssueUrl ? `GitHub issue #${issueNumber} will be closed automatically.` : ''}
Next steps:
1. Review changes
2. Run additional manual tests if needed
3. Deploy to staging
4. Monitor for any issues
```
## Issue Type Handling
### Bug Fix (standard)
```
Workflow: Analyze → Plan → Create Sprint → Execute Sprint → Verify
Agents: sprint-orchestrator → task-orchestrator → Developer (T1/T2) → Reviewer → Validator
Sprint: Usually 1 sprint with 1-2 tasks
```
### Security Vulnerability (critical)
```
Workflow: Analyze → Plan → Create Sprint → Execute Sprint (T2) → Security audit → Verify
Agents: sprint-orchestrator → Developer T2 → Security auditor → Validator
Priority: IMMEDIATE
Sprint: 1 sprint, T2 agents used immediately
```
### Performance Issue
```
Workflow: Analyze → Profile → Plan → Create Sprint → Execute Sprint → Benchmark → Verify
Agents: sprint-orchestrator → Developer → Performance auditor → Validator
Include: Before/after benchmarks
Sprint: 1 sprint with profiling + optimization tasks
```
### Enhancement/Small Feature
```
(Consider using /multi-agent:feature instead for larger enhancements)
This command better for: Quick fixes, small improvements, single-component changes
Sprint: 1 sprint with 1-3 tasks
```
## Error Handling
**Cannot reproduce:**
```
⚠️ Could not reproduce issue
Steps taken:
1. Followed reproduction steps
2. Checked with multiple scenarios
3. Reviewed recent changes
Possible reasons:
- Issue may be environment-specific
- May require specific data/state
- May have been fixed in another change
Recommendation:
- Provide more details on reproduction
- Share logs/error messages
- Specify environment details
```
**Fix introduces regression:**
```
❌ Verification failed: Regression detected
Fix resolved original issue ✅
BUT broke existing functionality ❌
Failed test: test_user_authentication
Error: Login fails after fix
Rolling back and retrying with different approach...
```
**Complex issue needs decomposition:**
```
⚠️ Issue is complex, may require multiple changes
Issue affects:
- WebSocket handler (backend)
- React component (frontend)
- Database queries (performance)
Recommendation:
1. Use /multi-agent:issue for WebSocket fix (blocking)
2. Use /multi-agent:issue for React component separately
3. Use /multi-agent:feature for query optimization (larger scope)
Or proceed as single complex issue? (y/n)
```
## Advanced Usage
**With GitHub CLI:**
```
/multi-agent:issue https://github.com/myorg/myrepo/issues/456
(Automatically fetches details, closes issue when fixed)
```
**Security issue:**
```
/multi-agent:issue CRITICAL: SQL injection in /api/users endpoint
(System prioritizes, uses T2 agents, runs security audit)
```
**Performance issue:**
```
/multi-agent:issue API response time degraded from 200ms to 3000ms
(System profiles, identifies bottleneck, optimizes)
```
## Workflow Diagram
```
User: /multi-agent:issue Fix login timeout
↓
1. Analyze Issue
├── Identify affected code
├── Determine severity
└── Find root cause
↓
2. Create Fix Plan (lightweight PRD)
↓
3. Create Tasks & Sprint
├── Break into tasks (task-graph-analyzer)
├── Organize into sprint (sprint-planner)
└── Create state file for tracking
↓
4. Execute Sprint
├── Sprint orchestrator manages execution
├── For each task:
│ ├── Developer (T1 or T2)
│ ├── Code review
│ ├── Security audit (if needed)
│ ├── Performance audit (if needed)
│ ├── Tests added
│ └── Requirements validation
├── Workflow compliance check
└── Runtime verification
↓
5. Verify
├── No regressions
├── Issue resolved
└── All tests pass
↓
✅ Issue Resolved
└── (Close GitHub issue if applicable)
```
## Cost Estimation
**Simple bug fix:**
- Analysis + plan: ~$0.30
- Implementation: ~$0.50-1.50
- Testing + review: ~$0.40
- **Total: ~$1-2**
**Complex bug fix:**
- Analysis + plan: ~$0.50
- Implementation: ~$2-5
- Testing + review: ~$1
- **Total: ~$4-7**
**Critical security fix:**
- Analysis: ~$0.70
- Implementation (T2): ~$3-6
- Security audit: ~$1.50
- Testing: ~$1
- **Total: ~$6-10**
Time saved: **80-90% vs manual debugging and fixing**

317
commands/merge-tracks.md Normal file
View File

@@ -0,0 +1,317 @@
# Merge Tracks Command
You are orchestrating the **parallel development tracks merging phase** to combine all completed tracks back into the main branch.
## Command Usage
```bash
/multi-agent:merge-tracks # Merge all tracks, create PR, cleanup worktrees (default)
/multi-agent:merge-tracks --manual-merge # Merge all tracks, skip PR, cleanup worktrees
/multi-agent:merge-tracks --keep-worktrees # Merge, create PR, keep worktrees
/multi-agent:merge-tracks --delete-branches # Merge, create PR, cleanup worktrees & branches
/multi-agent:merge-tracks --dry-run # Show what would be merged without doing it
```
**Flags:**
- `--manual-merge`: Skip automatic PR creation after merge, allow manual PR creation
- `--keep-worktrees`: Keep worktrees after merge (default: delete)
- `--delete-branches`: Delete track branches after merge (default: keep)
- `--dry-run`: Preview merge plan without executing
## Prerequisites
This command only works for projects planned with git worktrees (`--use-worktrees` flag).
**Pre-flight checks:**
1. State file must exist with worktree mode enabled
2. All tracks must be complete (all sprints in all tracks marked "completed")
3. No uncommitted changes in any worktree
4. All worktrees should have pushed to remote (optional but recommended)
## Your Process
### Step 0: Parse Parameters
Extract flags from command:
- `--manual-merge`: Skip PR creation after merge (default: false)
- `--keep-worktrees`: Do not delete worktrees after merge (default: false)
- `--delete-branches`: Delete track branches after merge (default: false)
- `--dry-run`: Show merge plan without executing (default: false)
### Step 1: Load State and Validate
1. **Load state file** (`docs/planning/.project-state.yaml`)
2. **Verify worktree mode:**
```python
if state.parallel_tracks.mode != "worktrees":
error("This project was not planned with worktrees. Nothing to merge.")
suggest("/multi-agent:sprint all # All work already in main branch")
exit(1)
```
3. **Verify all tracks complete:**
```python
incomplete_tracks = []
for track_id, track_info in state.parallel_tracks.track_info.items():
track_sprints = filter(s for s in state.sprints if s.track == track_id)
if any(sprint.status != "completed" for sprint in track_sprints):
incomplete_tracks.append(track_id)
if incomplete_tracks:
error(f"Cannot merge: Tracks {incomplete_tracks} not complete")
suggest(f"/multi-agent:sprint all {incomplete_tracks[0]:02d} # Complete remaining tracks")
exit(1)
```
4. **Check for uncommitted changes:**
```bash
for track in tracks:
cd $worktree_path
if [ -n "$(git status --porcelain)" ]; then
error("Uncommitted changes in $worktree_path")
suggest("Commit or stash changes before merging")
exit(1)
fi
```
5. **Check remote push status (warning only):**
```bash
for track in tracks:
cd $worktree_path
if git status | grep "Your branch is ahead"; then
warn("Track $track has unpushed commits - recommend pushing for backup")
fi
```
### Step 2: Create Pre-Merge Backup
**Safety measure:**
```bash
# Return to main directory
cd $MAIN_REPO
# Create backup tag
git tag pre-merge-backup-$(date +%Y%m%d-%H%M%S)
echo "✓ Created backup tag: pre-merge-backup-YYYYMMDD-HHMMSS"
echo " (To restore: git reset --hard <tag-name>)"
```
### Step 3: Show Merge Plan (Dry-Run)
If `--dry-run` flag:
```markdown
Merge Plan
═══════════════════════════════════════
Tracks to merge: 3
- Track 1 (dev-track-01): 7 commits, 15 files changed
- Track 2 (dev-track-02): 5 commits, 12 files changed
- Track 3 (dev-track-03): 4 commits, 8 files changed
Merge strategy: Sequential merge (track-01 → track-02 → track-03)
Target branch: main (or current branch)
Potential conflicts: 2 files
- src/config.yaml (modified in tracks 01 and 02)
- package.json (modified in tracks 01 and 03)
After merge:
- Delete worktrees: YES (default)
- Delete branches: NO (use --delete-branches to enable)
To proceed with merge:
/multi-agent:merge-tracks
```
Exit without merging.
### Step 4: Launch Track Merger Agent
If not dry-run, launch the **track-merger** agent:
```javascript
Task(
subagent_type="multi-agent:orchestration:track-merger",
model="sonnet",
description="Merge all development tracks intelligently",
prompt=`Merge all development tracks back to main branch.
State file: docs/planning/.project-state.yaml
Your responsibilities:
1. Verify all pre-flight checks passed
2. Ensure we're on the correct base branch (main or specified)
3. Merge each track branch sequentially:
- Track 1: dev-track-01
- Track 2: dev-track-02
- Track 3: dev-track-03
4. Handle merge conflicts intelligently (use context from PRD and tasks)
5. Run integration tests after each merge
6. Create merge commit messages that reference track work
7. Tag the final merged state
8. Create pull request (unless --manual-merge)
9. Clean up worktrees (unless --keep-worktrees)
10. Optionally delete track branches (if --delete-branches)
11. Update state file to mark merge complete
12. Generate merge completion report
Flags:
- manual_merge: ${manual_merge}
- keep_worktrees: ${keep_worktrees}
- delete_branches: ${delete_branches}
Provide detailed progress updates and final summary.`
)
```
### Step 5: Post-Merge Verification
After track-merger completes:
1. **Run final project review** (same as sprint-all completion):
- Comprehensive code review across all languages
- Security audit
- Performance audit
- Integration testing
- Documentation review
2. **Update state file:**
```yaml
merge_info:
merged_at: "2025-11-03T15:30:00Z"
tracks_merged: [1, 2, 3]
merge_commit: "abc123def456"
conflicts_resolved: 2
worktrees_cleaned: true
branches_deleted: false
```
3. **Generate completion report** in `docs/merge-completion-report.md`
## Report Formats
### Successful Merge
```markdown
╔═══════════════════════════════════════════╗
║ 🎉 TRACK MERGE SUCCESSFUL 🎉 ║
╚═══════════════════════════════════════════╝
Parallel Development Complete!
Tracks Merged: 3
- Track 1 (Backend): dev-track-01 → main
- Track 2 (Frontend): dev-track-02 → main
- Track 3 (Infrastructure): dev-track-03 → main
Merge Statistics:
- Total commits merged: 16
- Files changed: 35
- Conflicts resolved: 2
- Merge strategy: Sequential
- Merge commit: abc123def456
Quality Checks:
✅ Code review: PASS
✅ Security audit: PASS
✅ Performance audit: PASS
✅ Integration tests: PASS
✅ Documentation: Complete
Cleanup:
✅ Worktrees removed: .multi-agent/track-01/, track-02/, track-03/
⚠️ Branches kept: dev-track-01, dev-track-02, dev-track-03
(Use --delete-branches to remove)
Final state:
- Working branch: main
- All parallel work now integrated
- Backup tag: pre-merge-backup-20251103-153000
Ready for deployment! 🚀
Full report: docs/merge-completion-report.md
```
### Merge with Conflicts
```markdown
⚠️ MERGE COMPLETED WITH MANUAL RESOLUTION REQUIRED
Tracks Merged: 2/3
- ✅ Track 1 (Backend): Merged successfully
- ✅ Track 2 (Frontend): Merged successfully
- ⚠️ Track 3 (Infrastructure): Conflicts detected
Conflicts in Track 3:
1. src/config.yaml (lines 45-52)
- Track 01 changes: Database connection settings
- Track 03 changes: Deployment configuration
- Resolution needed: Combine both changes
2. package.json (line 23)
- Track 01 changes: Added express dependency
- Track 03 changes: Added docker dependency
- Resolution needed: Include both dependencies
To resolve:
1. Edit the conflicted files manually
2. Run tests to verify
3. Commit the resolution: git commit
4. Re-run: /multi-agent:merge-tracks
Backup available: pre-merge-backup-20251103-153000
```
## Error Handling
**Incomplete tracks:**
```
Error: Cannot merge - incomplete tracks detected
Track 2 status: 1/2 sprints complete
Track 3 status: 0/2 sprints complete
Complete all tracks before merging:
/multi-agent:sprint all 02
/multi-agent:sprint all 03
Then retry: /multi-agent:merge-tracks
```
**Not worktree mode:**
```
Error: This project was not planned with git worktrees
Your project uses state-only mode for track separation.
All work is already in the main branch - no merge needed.
Project is complete! Run final review if needed:
/multi-agent:sprint all
```
**Uncommitted changes:**
```
Error: Uncommitted changes in worktree .multi-agent/track-02/
Please commit or stash changes before merging:
cd .multi-agent/track-02/
git status
git add .
git commit -m "Final changes before merge"
Then retry: /multi-agent:merge-tracks
```
## Important Notes
- Always creates backup tag before merge (safety)
- Merges tracks sequentially (not all at once)
- Intelligently resolves conflicts using PRD/task context
- Runs full quality checks after merge
- Default: deletes worktrees, keeps branches
- Use --delete-branches carefully (branches are lightweight and provide history)
- Can be re-run if interrupted (idempotent after conflicts resolved)

303
commands/planning.md Normal file
View File

@@ -0,0 +1,303 @@
# Planning Command
You are orchestrating the **project planning phase** using the pragmatic approach. This involves two sequential agent invocations with optional parallel development track support.
## Command Usage
```bash
/multi-agent:planning # Single track (default)
/multi-agent:planning 3 # Request 3 parallel development tracks (state-only mode)
/multi-agent:planning 3 --use-worktrees # Request 3 tracks with git worktrees for isolation
/multi-agent:planning 5 # Request 5 parallel tracks (will use max possible if less)
```
## Your Process
### Step 0: Parse Parameters
Extract the number of requested parallel tracks and worktree mode from the command:
- If no parameter provided: tracks = 1 (single track mode), use_worktrees = false
- If parameter provided: tracks = requested number
- If `--use-worktrees` flag present: use_worktrees = true, otherwise use_worktrees = false
- Pass both tracks and use_worktrees to sprint-planner in Step 2
**Worktree Mode:**
- `false` (default): State-only mode - tracks use logical separation via state files
- `true`: Git worktrees mode - each track gets isolated directory and branch
### Step 1: Task Analysis
1. Read `docs/planning/PROJECT_PRD.yaml`
2. Launch the **task-graph-analyzer** agent using the Task tool:
- Pass the PRD content
- Ask it to break down requirements into tasks
- Ask it to identify dependencies between tasks
- **NEW:** Ask it to calculate maximum possible parallel development tracks
3. Have the agent create individual task files: `docs/planning/tasks/TASK-001.yaml`, `TASK-002.yaml`, etc.
4. Have the agent create `docs/planning/task-dependency-graph.md` showing relationships
5. **NEW:** Agent should report the max possible parallel tracks in its summary
### Step 2: Sprint Planning
1. After task analysis completes, launch the **sprint-planner** agent using the Task tool:
- Pass all task definitions
- Pass the dependency graph
- Pass number of requested tracks (from Step 0)
- Pass max possible tracks (from Step 1)
- **NEW:** Pass use_worktrees flag (from Step 0)
- Ask it to organize tasks into sprints
2. If tracks > 1:
- Have agent create sprint files with track suffix: `docs/sprints/SPRINT-XXX-YY.yaml`
- Have agent initialize state file: `docs/planning/.project-state.yaml`
- Example: `SPRINT-001-01.yaml`, `SPRINT-001-02.yaml` for 2 tracks
- **NEW:** If use_worktrees = true:
- Have agent create git worktrees: `.multi-agent/track-01/`, `.multi-agent/track-02/`, etc.
- Have agent create branches: `dev-track-01`, `dev-track-02`, etc.
- Have agent copy planning artifacts to each worktree
- State file should include worktree paths and branch names
3. If tracks = 1 (default):
- Have agent create traditional sprint files: `docs/sprints/SPRINT-001.yaml`, `SPRINT-002.yaml`, etc.
- Still initialize state file for progress tracking
- No worktrees needed for single track
## Special Pattern: API-First Full-Stack Applications
**Use this pattern when building applications with separate backend and frontend that communicate via API.**
### When to Use API-First Pattern
Use this when your PRD indicates:
- Full-stack application (backend + frontend)
- REST API or GraphQL API
- Mobile app + backend
- Microservices architecture
- Any scenario with API contract between components
### How API-First Works
1. **First Task = API Design**: Create OpenAPI specification BEFORE any code
2. **Backend implements FROM spec**: Exact schemas, no deviations
3. **Frontend generates FROM spec**: Auto-generated type-safe client
4. **Result**: Perfect alignment, compile-time safety
### Task Structure Template
When you detect a full-stack project, ensure tasks follow this order:
```
TASK-001: Design API Specification (NO dependencies)
├── Agent: backend:api-designer
├── Output: docs/api/openapi.yaml
└── Critical: This runs FIRST
TASK-002: Design Database Schema (depends on TASK-001)
└── Agent: database:designer
TASK-003: Implement Database Models (depends on TASK-002)
└── Agent: database:developer-{language}-t1
TASK-004: Implement Backend API (depends on TASK-001, TASK-003)
├── Agent: backend:api-developer-{language}-t1
├── Input: docs/api/openapi.yaml
└── Must match spec EXACTLY
TASK-005: Generate Frontend API Client (depends on TASK-001 ONLY)
├── Agent: frontend:developer-t1
├── Input: docs/api/openapi.yaml
├── Tool: openapi-typescript-codegen
└── Output: Auto-generated type-safe client
TASK-006: Implement Frontend UI (depends on TASK-005)
└── Agent: frontend:developer-t1
└── Uses ONLY generated client
```
### Important Dependencies
- **Backend depends on**: API spec + Database models
- **Frontend client depends on**: API spec ONLY (not backend implementation!)
- **Frontend UI depends on**: Generated client
This allows frontend and backend to develop in parallel after the API spec is complete.
### Validation Requirements
When creating tasks for API-first projects, include these acceptance criteria:
**For TASK-001 (API Design):**
- OpenAPI 3.0 specification at docs/api/openapi.yaml
- Passes openapi-spec-validator
- All endpoints, schemas, errors documented
**For TASK-004 (Backend):**
- Implements ONLY endpoints in spec
- Schemas match spec EXACTLY
- Passes openapi-spec-validator
- /docs endpoint serves the specification
**For TASK-005 (Frontend Client):**
- Client auto-generated from spec
- NO manual endpoint definitions
- TypeScript types from spec
- CI verifies client is up-to-date
**For TASK-006 (Frontend UI):**
- Uses ONLY generated client
- NO fetch/axios outside generated code
- TypeScript compilation enforces correctness
### Example Detection
If PRD contains:
- "backend API" + "frontend application"
- "REST API" + "React/Vue/Angular"
- "mobile app" + "API server"
- "microservices" with communication
Then recommend API-first pattern and structure tasks accordingly.
### Reference
See complete example: `examples/api-first-fullstack-workflow.md`
See task templates: `docs/templates/api-first-tasks.yaml`
---
## Agent References
- Task Graph Analyzer: `.claude/agents/multi-agent:planning/task-graph-analyzer.md`
- Sprint Planner: `.claude/agents/multi-agent:planning/multi-agent:sprint-planner.md`
## After Completion
### Report Format - Single Track Mode
```
Planning complete!
Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)
Sprint Planning:
- Created 3 sprints in docs/sprints/
- SPRINT-001: Foundation (5 tasks, 40 hours)
- SPRINT-002: Core Features (6 tasks, 52 hours)
- SPRINT-003: Polish (4 tasks, 36 hours)
Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml
Ready to start development:
/multi-agent:sprint all # Execute all sprints
/multi-agent:sprint SPRINT-001 # Execute specific sprint
Tip: For parallel development, try:
/multi-agent:planning 3 # Re-run with 3 tracks for faster execution
/multi-agent:planning 3 --use-worktrees # Use worktrees for physical isolation
```
### Report Format - Parallel Track Mode (State-Only)
```
Planning complete!
Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)
Sprint Planning:
- Requested tracks: 5
- Max possible: 3
- Using: 3 tracks
- Mode: State-only (logical separation)
Track Distribution:
- Track 1: 5 tasks, 42 hours (SPRINT-001-01, SPRINT-002-01)
- Track 2: 6 tasks, 48 hours (SPRINT-001-02, SPRINT-002-02)
- Track 3: 4 tasks, 38 hours (SPRINT-001-03, SPRINT-002-03)
Total: 15 tasks, ~128 hours development time
Parallel execution time: ~48 hours (62% faster)
Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/ (6 sprint files across 3 tracks)
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml
Ready to start development:
/multi-agent:sprint all # Execute all tracks sequentially
/multi-agent:sprint all 01 # Execute track 1 only
/multi-agent:sprint all 02 # Execute track 2 only
/multi-agent:sprint all 03 # Execute track 3 only
Or run in parallel (multiple terminals):
Terminal 1: /multi-agent:sprint all 01
Terminal 2: /multi-agent:sprint all 02
Terminal 3: /multi-agent:sprint all 03
Tip: For stronger isolation, try:
/multi-agent:planning 3 --use-worktrees # Use git worktrees for physical separation
```
### Report Format - Parallel Track Mode (With Worktrees)
```
Planning complete!
Task Analysis:
- Created 15 tasks in docs/planning/tasks/
- Max possible parallel tracks: 3
- Critical path: 5 tasks (20 hours)
Sprint Planning:
- Requested tracks: 5
- Max possible: 3
- Using: 3 tracks
- Mode: Git worktrees (physical isolation)
Worktree Configuration:
✓ Track 1: .multi-agent/track-01/ (branch: dev-track-01)
✓ Track 2: .multi-agent/track-02/ (branch: dev-track-02)
✓ Track 3: .multi-agent/track-03/ (branch: dev-track-03)
Track Distribution:
- Track 1: 5 tasks, 42 hours (SPRINT-001-01, SPRINT-002-01)
- Track 2: 6 tasks, 48 hours (SPRINT-001-02, SPRINT-002-02)
- Track 3: 4 tasks, 38 hours (SPRINT-001-03, SPRINT-002-03)
Total: 15 tasks, ~128 hours development time
Parallel execution time: ~48 hours (62% faster)
Artifacts:
- Tasks: docs/planning/tasks/
- Sprints: docs/sprints/ (6 sprint files across 3 tracks)
- Dependency graph: docs/planning/task-dependency-graph.md
- State file: docs/planning/.project-state.yaml
- Worktrees: .multi-agent/track-01/, track-02/, track-03/
Ready to start development:
/multi-agent:sprint all # Execute all tracks sequentially
/multi-agent:sprint all 01 # Execute track 1 (auto-switches to worktree)
/multi-agent:sprint all 02 # Execute track 2 (auto-switches to worktree)
/multi-agent:sprint all 03 # Execute track 3 (auto-switches to worktree)
Or run in parallel (multiple terminals):
Terminal 1: /multi-agent:sprint all 01
Terminal 2: /multi-agent:sprint all 02
Terminal 3: /multi-agent:sprint all 03
After all tracks complete, merge them:
/multi-agent:merge-tracks # Merges all tracks, cleans up worktrees
```
## Important Notes
- Use the Task tool to launch each agent
- Wait for each agent to complete before moving to the next
- Agents should reference the PRD's technology stack for language-specific tasks
- Ensure dependency order is preserved in sprint plans

70
commands/prd.md Normal file
View File

@@ -0,0 +1,70 @@
# PRD Generator Command
You are the **PRD Generator agent** using the pragmatic orchestration approach. Your job is to conduct an interactive interview and create a comprehensive Product Requirements Document.
## Your Instructions
Follow the agent definition in `.claude/agents/multi-agent:planning/multi-agent:prd-generator.md` exactly.
## Process Overview
1. **Technology Stack Selection (REQUIRED FIRST)**
- Ask: "What external services, libraries, or APIs will you integrate with?"
- Based on answer, recommend Python or TypeScript stack with reasoning
- Confirm with user
- Document their choice
2. **Problem and Solution**
- Ask about the problem they're solving
- Understand the proposed solution
- Document value proposition
3. **Users and Use Cases**
- Identify primary users
- Document user journeys
- List must-have vs nice-to-have features
4. **Technical Context**
- Integration requirements
- Performance requirements
- Scale considerations
5. **Success Criteria**
- How to measure success
- Acceptance criteria
- Definition of done
6. **Constraints**
- Timeline, budget, security
- Compliance requirements
7. **Additional Details (if needed)**
- Only ask clarifying questions if necessary
## Output
Generate `docs/planning/PROJECT_PRD.yaml` using the format specified in the agent definition.
## After Completion
Tell the user:
```
PRD saved to docs/planning/PROJECT_PRD.yaml
Your technology stack:
- Backend: [Language + Framework]
- Frontend: [Framework]
- Database: [Database + ORM]
Next steps:
1. Review the PRD: docs/planning/PROJECT_PRD.yaml
2. Run /multi-agent:planning to break into tasks and create sprints
```
## Important
- Ask ONE question at a time
- Be conversational but efficient
- Start with integrations to determine stack
- Provide reasoning for technology recommendations
- Don't generate the PRD until you have all required information

449
commands/sprint-all.md Normal file
View File

@@ -0,0 +1,449 @@
# Sprint All Command
You are orchestrating **multi-sprint execution** using the agent-based approach.
## Command Usage
```bash
/multi-agent:sprint all # Execute all sprints, create PRs (default)
/multi-agent:sprint all --manual-merge # Execute all sprints, skip PR creation
/multi-agent:sprint all 01 # Execute track 1, create PRs
/multi-agent:sprint all 01 --manual-merge # Execute track 1, skip PRs
/multi-agent:sprint all 02 # Execute track 2, create PRs
/multi-agent:sprint all 03 # Execute track 3, create PRs
```
Executes all sprints sequentially until completion. Supports track filtering for parallel development workflows.
**Flags:**
- `--manual-merge`: Skip automatic PR creation after each sprint, allow manual merge/PR creation
## Your Process
### Step 0: Parse Parameters
**Extract track number** from command (if specified):
- If no parameter: execute all tracks sequentially
- If parameter (e.g., "01", "02"): execute only that track
**Extract flags:**
- Check for `--manual-merge` flag
- If present: manual_merge = true (skip PR creation after each sprint)
- If absent: manual_merge = false (create PR after each sprint)
### Step 1: Load State File
**Determine state file location:**
- Check `docs/planning/.project-state.yaml`
- Check `docs/planning/.feature-*-state.yaml`
- Check `docs/planning/.issue-*-state.yaml`
**If state file doesn't exist:**
- Create initial state file with all sprints marked "pending"
- Initialize track configuration from sprint files
**If state file exists:**
- Load current progress
- Identify completed vs pending sprints
- Determine resume point
- **NEW:** Check if worktree mode is enabled (`parallel_tracks.mode = "worktrees"`)
### Step 1.5: Determine Working Directory (NEW)
**If worktree mode is enabled AND track is specified:**
1. Get worktree path from state file:
```python
worktree_path = state.parallel_tracks.track_info[track_number].worktree_path
# Example: ".multi-agent/track-01"
```
2. Verify worktree exists:
```bash
if [ -d "$worktree_path" ]; then
echo "Working in worktree: $worktree_path"
cd "$worktree_path"
else
echo "ERROR: Worktree not found at $worktree_path"
echo "Run /multi-agent:planning again with --use-worktrees"
exit 1
fi
```
3. Verify we're on the correct branch:
```bash
expected_branch = state.parallel_tracks.track_info[track_number].branch
current_branch = git rev-parse --abbrev-ref HEAD
if current_branch != expected_branch:
echo "WARNING: Worktree is on branch $current_branch, expected $expected_branch"
```
4. All subsequent file operations (reading sprints, tasks, creating files) happen in this worktree directory
**If state-only mode OR no track specified:**
- Work in current directory (main repo)
- No directory switching needed
### Step 2: Project State Analysis
**Check Sprint Files:**
```bash
# In worktree directory if applicable, otherwise main directory
ls docs/sprints/
```
**Filter by track (if specified):**
- If track specified: filter to only sprints matching that track
- Example: track=01 → only `SPRINT-*-01.yaml` files
**Determine Sprint Status from State File:**
- For each sprint in scope:
- Check state.sprints[sprintId].status
- "completed" → skip
- "in_progress" → resume from last completed task
- "pending" → execute normally
- Count total sprints to execute vs already completed
**Check PRD Exists:**
- Verify `docs/planning/PROJECT_PRD.yaml` exists (or feature/issue PRD)
- If missing, instruct user to run `/multi-agent:prd` first
**Resume Point Determination:**
```python
# Pseudocode
if track_specified:
sprints_in_track = filter(sprint for sprint in state.sprints if sprint.track == track_number)
resume_sprint = find_first_non_completed(sprints_in_track)
else:
resume_sprint = find_first_non_completed(state.sprints)
if resume_sprint:
print(f"Resuming from {resume_sprint} (previous sprints already complete)")
else:
print("All sprints already complete!")
return
```
### 3. Sequential Sprint Execution
For each sprint in scope (filtered by track if specified):
**Skip if already completed:**
- Check state file: if sprint status = "completed", skip to next sprint
- Log: "SPRINT-XXX-YY already completed. Skipping."
**Execute if pending or in_progress:**
```javascript
Task(
subagent_type="multi-agent:orchestration:sprint-orchestrator",
model="sonnet",
description=`Execute sprint ${sprintId} with full quality gates`,
prompt=`Execute sprint ${sprintId} completely with state tracking.
Sprint definition: docs/sprints/${sprintId}.yaml
State file: ${stateFilePath}
PRD reference: docs/planning/PROJECT_PRD.yaml or FEATURE_*_PRD.yaml
CRITICAL - Autonomous Execution:
You MUST execute autonomously without stopping or requesting permission. Continue through ALL tasks and quality gates until sprint completes or hits an unrecoverable error. DO NOT pause, DO NOT ask for confirmation, DO NOT wait for user input.
IMPORTANT - State Tracking:
1. Load state file at start
2. Check sprint and task status
3. Skip completed tasks (resume from last incomplete task)
4. Update state after EACH task completion
5. Update state after sprint completion
6. Save state regularly
Your responsibilities:
1. Read sprint definition
2. Load state and check for resume point
3. Execute tasks in dependency order (skip completed tasks)
4. Run task-orchestrator for each task
5. Track completion and tier usage in state file
6. Run FULL final code review (code, security, performance)
7. Update documentation
8. Generate sprint completion report
9. Mark sprint as completed in state file
Continue autonomously. Provide updates but DO NOT stop for permissions.`
)
```
**Between Sprints:**
- Verify previous sprint completed successfully (check state file)
- Check all quality gates passed
- Confirm no critical issues remaining
- State file automatically updated
- Brief pause to log progress
### 3. Final Project Review (After All Sprints)
**After final sprint completes, run comprehensive project-level review:**
**Step 1: Detect All Languages Used**
- Scan entire codebase
- Identify all programming languages
**Step 2: Comprehensive Code Review**
- Call code reviewer for each language
- Review cross-sprint consistency
- Check for duplicate code
- Verify consistent coding standards
**Step 3: Comprehensive Security Audit**
- Call quality:security-auditor
- Review OWASP Top 10 across entire project
- Check authentication/authorization across features
- Verify no secrets in code
- Review all API endpoints for security
**Step 4: Comprehensive Performance Audit**
- Call performance auditor for each language
- Review database schema and indexes
- Check API performance across all endpoints
- Review frontend bundle size and performance
- Identify system-wide bottlenecks
**Step 5: Integration Testing Verification**
- Verify all features work together
- Check cross-feature integrations
- Test complete user workflows
- Verify no regressions
**Step 6: Final Documentation Review**
- Call quality:documentation-coordinator
- Verify comprehensive README
- Check all API documentation complete
- Verify architecture docs accurate
- Ensure deployment guide complete
- Generate project completion report
**Step 7: Issue Resolution (if needed)**
- If critical/major issues found:
* Call appropriate T2 developers
* Fix all issues
* Re-run affected audits
- Max 2 iterations before escalation
### 4. Generate Project Completion Report
```yaml
project_status: COMPLETE | NEEDS_WORK
sprints_completed: 5/5
overall_statistics:
total_tasks: 47
tasks_completed: 47
t1_tasks: 35 (74%)
t2_tasks: 12 (26%)
total_iterations: 89
quality_metrics:
code_reviews: PASS
security_audit: PASS
performance_audit: PASS
documentation: COMPLETE
issues_summary:
critical_fixed: 3
major_fixed: 8
minor_documented: 12
languages_used:
- Python (FastAPI backend)
- TypeScript (React frontend)
- PostgreSQL (database)
features_delivered:
- User authentication
- Task management
- Real-time notifications
- Analytics dashboard
- API integrations
documentation_updated:
- README.md (comprehensive)
- API documentation (OpenAPI)
- Architecture diagrams
- Deployment guide
- User guide
estimated_cost: $45.30
estimated_time_saved: 800 hours vs manual development
recommendations:
- Consider adding rate limiting for API
- Monitor database query performance under load
- Schedule security audit for production deployment
next_steps:
- Review completion report
- Run integration tests
- Deploy to staging environment
- Schedule production deployment
```
### 5. User Communication
**During Execution (State-Only Mode):**
```
Starting multi-sprint execution...
Found 5 sprints in docs/sprints/
Mode: State-only (logical separation)
Starting from SPRINT-001
═══════════════════════════════════════
Sprint 1/5: SPRINT-001 (Foundation)
═══════════════════════════════════════
Launching sprint-orchestrator...
[sprint-orchestrator executes with updates]
✅ SPRINT-001 complete (8 tasks, 45 min)
═══════════════════════════════════════
Sprint 2/5: SPRINT-002 (Core Features)
═══════════════════════════════════════
Launching sprint-orchestrator...
...
═══════════════════════════════════════
All Sprints Complete! Running final review...
═══════════════════════════════════════
Running comprehensive code review...
Running security audit...
Running performance audit...
Updating final documentation...
✅ PROJECT COMPLETE!
```
**During Execution (Worktree Mode):**
```
Starting multi-sprint execution for Track 01...
Mode: Git worktrees (physical isolation)
Working directory: .multi-agent/track-01/
Branch: dev-track-01
Found 2 sprints for track 01
Starting from SPRINT-001-01
═══════════════════════════════════════
Track 1: Backend (Worktree Mode)
═══════════════════════════════════════
Location: .multi-agent/track-01/
Branch: dev-track-01
Status: 0/2 sprints complete
═══════════════════════════════════════
Sprint 1/2: SPRINT-001-01 (Foundation)
═══════════════════════════════════════
Launching sprint-orchestrator...
[sprint-orchestrator executes in worktree]
Committing to branch: dev-track-01
✅ SPRINT-001-01 complete (5 tasks, 32 min)
═══════════════════════════════════════
Sprint 2/2: SPRINT-002-01 (Advanced Features)
═══════════════════════════════════════
Launching sprint-orchestrator...
[sprint-orchestrator executes in worktree]
Committing to branch: dev-track-01
✅ SPRINT-002-01 complete (2 tasks, 18 min)
═══════════════════════════════════════
Track 1 Complete!
═══════════════════════════════════════
All sprints in track 01 completed ✅
Commits pushed to branch: dev-track-01
Next steps:
- Wait for other tracks to complete (if running in parallel)
- When all tracks done, run: /multi-agent:merge-tracks
```
**On Completion:**
```
╔═══════════════════════════════════════════╗
║ 🎉 PROJECT COMPLETION SUCCESSFUL 🎉 ║
╚═══════════════════════════════════════════╝
Sprints Completed: 5/5
Tasks Delivered: 47/47
Quality: All checks passed ✅
Documentation: Complete ✅
Cost Estimate: $45.30
Time Saved: ~800 hours
See full report: docs/project-completion-report.md
Ready for deployment! 🚀
```
## Error Handling
**Sprint fails:**
```
❌ SPRINT-003 failed after 3 fix attempts
Issue: Critical security vulnerability in authentication
Location: backend/auth/jwt_handler.py
Pausing multi-sprint execution.
Human intervention required.
To resume after fix: /multi-agent:sprint all
(Will skip completed sprints automatically)
```
**No sprints found:**
```
Error: No sprint files found in docs/sprints/
Have you run /multi-agent:planning to create sprints?
Workflow:
1. /multi-agent:prd - Create PRD
2. /multi-agent:planning - Break into tasks and sprints
3. /multi-agent:sprint all - Execute all sprints
```
**Worktree not found:**
```
Error: Worktree not found at .multi-agent/track-01/
This project was planned with git worktrees, but the worktree is missing.
To recreate worktrees, run:
/multi-agent:planning <tracks> --use-worktrees
Or if you want to switch to state-only mode, update the state file manually.
```
## Important Notes
- Each sprint MUST complete successfully before next sprint starts
- Final project review is MANDATORY after all sprints
- Documentation is updated continuously (per sprint) and finally (project-level)
- All quality gates must pass before marking project complete
- Execution can be paused/resumed (picks up from last completed sprint)
- Detailed logs generated for each sprint and overall project
- Cost tracking across all sprints for transparency
## Comparison to Single Sprint
**`/multi-agent:sprint SPRINT-001`:**
- Executes one sprint
- Final review for that sprint
- Documentation updated for that sprint
**`/multi-agent:sprint all`:**
- Executes ALL sprints sequentially
- Final review for each sprint
- Additional project-level review at the end
- Comprehensive documentation at project completion
- Full integration testing verification

175
commands/sprint.md Normal file
View File

@@ -0,0 +1,175 @@
# Sprint Execution Command
You are initiating a **Sprint Execution** using the agent-based orchestration approach.
## Command Usage
```bash
/multi-agent:sprint SPRINT-001 # Execute sprint, create PR (default)
/multi-agent:sprint SPRINT-001 --manual-merge # Execute sprint, skip PR creation
/multi-agent:sprint SPRINT-001-01 # Execute sprint in track, create PR
/multi-agent:sprint SPRINT-001-01 --manual-merge # Execute sprint in track, skip PR
```
This command executes a single sprint. The sprint ID can be:
- Traditional format: `SPRINT-001` (single-track mode)
- Track format: `SPRINT-001-01` (multi-track mode, sprint 1 track 1)
**Flags:**
- `--manual-merge`: Skip automatic PR creation, allow manual merge/PR creation
## Your Process
### 1. Parse Command Parameters
**Extract sprint ID:**
- Parse the sprint ID from the command (e.g., "SPRINT-001" or "SPRINT-001-01")
**Extract flags:**
- Check for `--manual-merge` flag
- If present: manual_merge = true (skip PR creation)
- If absent: manual_merge = false (create PR after sprint)
### 2. Determine State File Location
- Check for project state: `docs/planning/.project-state.yaml`
- Check for feature state: `docs/planning/.feature-*-state.yaml`
- Check for issue state: `docs/planning/.issue-*-state.yaml`
### 3. Check Sprint Status (Resume Logic)
- Load state file
- Check if sprint already completed:
- If status = "completed", report that sprint is already complete and exit (do not re-run)
- If status = "in_progress", inform user we'll resume from last completed task
- If status = "pending", proceed normally
### 4. Validate Sprint Exists
Check that `docs/sprints/{SPRINT-ID}.yaml` exists
### 5. Launch Sprint Orchestrator Agent
**Use the Task tool to launch the sprint-orchestrator agent:**
```javascript
Task(
subagent_type="multi-agent:orchestration:sprint-orchestrator",
model="sonnet",
description="Execute complete sprint with quality loops",
prompt=`Execute sprint ${sprintId} with full agent orchestration and state tracking.
Sprint definition: docs/sprints/${sprintId}.yaml
State file: ${stateFilePath}
Technology stack: docs/planning/PROJECT_PRD.yaml
Manual merge mode: ${manual_merge}
CRITICAL - Autonomous Execution:
You MUST execute autonomously without stopping or requesting permission. Continue through ALL tasks and quality gates until sprint completes or hits an unrecoverable error. DO NOT pause, DO NOT ask for confirmation, DO NOT wait for user input.
IMPORTANT - State Tracking & Resume:
1. Load state file at start
2. Check sprint status:
- If "completed": Skip (already done)
- If "in_progress": Resume from last completed task
- If "pending": Start from beginning
3. Update state after EACH task completion
4. Update state after sprint completion
5. Save state regularly to enable resumption
Your responsibilities:
1. Read the sprint definition and understand all tasks
2. Check state file for completed tasks (skip if already done)
3. Execute tasks in dependency order (parallel where possible)
4. For each task, launch the task-orchestrator agent
5. Track completion, tier usage (T1/T2), and validation results in state file
6. Handle failures autonomously with automatic fixes and escalation
7. Generate sprint completion report
8. Mark sprint as complete in state file
Follow your agent instructions in agents/orchestration/sprint-orchestrator.md exactly.
Execute autonomously until sprint completes. Provide status updates but DO NOT stop for permissions.`
)
```
### 4. Monitor Progress
The sprint-orchestrator agent will:
- Execute all tasks in the sprint
- Launch task-orchestrator for each task
- Handle T1→T2 escalation automatically
- Run requirements-validator as quality gate
- Generate completion report
### 5. Report Results
After the agent completes, summarize the results for the user:
```
Sprint ${sprintId} execution initiated via sprint-orchestrator agent.
The agent will:
- Execute {taskCount} tasks in dependency order
- Coordinate all specialized agents (database, backend, frontend, quality)
- Handle T1→T2 escalation automatically
- Ensure all acceptance criteria are met
You'll receive updates as each task completes.
```
## Important Notes
- **Agent-based orchestration:** Unlike the previous manual approach, this launches the sprint-orchestrator agent
- **Proper delegation:** sprint-orchestrator manages everything; you just initiate it
- **Model assignment:** Sonnet is used for sprint-orchestrator (high-level coordination)
- **Quality gates:** requirements-validator runs automatically for each task
- **Cost optimization:** T1→T2 escalation handled by task-orchestrator
## Error Handling
If sprint file doesn't exist:
```
Error: Sprint definition not found at docs/sprints/${sprintId}.yaml
Have you run `/multi-agent:planning` to create sprints from your PRD?
```
If PRD doesn't exist:
```
Error: Project PRD not found at docs/planning/PROJECT_PRD.yaml
Please run `/multi-agent:prd` first to create your project requirements document.
```
## Example Flow
```
User: /multi-agent:sprint SPRINT-001
You: Starting execution of SPRINT-001 via sprint-orchestrator agent...
[Launch sprint-orchestrator agent with proper parameters]
You: Sprint orchestrator agent launched. It will execute all tasks and provide updates.
[Agent executes entire sprint workflow]
Sprint orchestrator: ✅ SPRINT-001 complete
- Tasks: 5/5 completed
- Total iterations: 12
- T1→T2 switches: 1 task
- All acceptance criteria met
```
## Comparison to Previous Approach
**Before (Manual Orchestration):**
- Main Claude directly orchestrated all agents
- Manual state tracking
- Manual T1→T2 decisions
- Procedural approach
**Now (Agent-Based Orchestration):**
- sprint-orchestrator agent manages everything
- Proper agent hierarchy
- Automated workflows
- Declarative approach
- Reusable in any project with the plugin

206
commands/worktree-cleanup.md Normal file
View File

@@ -0,0 +1,206 @@
# Worktree Cleanup Command
**Expert Command** - Manually clean up development track worktrees.
## Command Usage
```bash
/multi-agent:worktree cleanup # Clean up all worktrees
/multi-agent:worktree cleanup 01 # Clean up specific track
/multi-agent:worktree cleanup --all # Clean up worktrees AND delete branches
```
## Warning
This command is destructive. Use with caution.
## Your Process
### Step 1: Load State and Validate
1. Load state file
2. Verify worktree mode enabled
3. If specific track, verify track exists
4. Check if tracks are complete (warning if not)
### Step 2: Safety Checks
For each worktree to be removed:
```bash
cd "$worktree_path"
# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
echo "❌ ERROR: Uncommitted changes in $worktree_path"
echo " Please commit or stash changes first"
exit 1
fi
# Check if pushed to remote
if git status | grep "Your branch is ahead"; then
echo "⚠️ WARNING: Unpushed commits in $worktree_path"
echo " Recommend pushing before cleanup"
read -p "Continue anyway? (y/N): " confirm
if [ "$confirm" != "y" ]; then
exit 1
fi
fi
```
### Step 3: Remove Worktrees
For each worktree:
```bash
cd "$MAIN_REPO"
echo "Removing worktree: $worktree_path"
git worktree remove "$worktree_path"
if [ $? -eq 0 ]; then
echo "✓ Removed: $worktree_path"
else
echo "❌ Failed to remove: $worktree_path"
echo " Try: git worktree remove --force $worktree_path"
fi
```
### Step 4: Remove Empty Directory
```bash
if [ -d ".multi-agent" ] && [ -z "$(ls -A .multi-agent)" ]; then
rmdir .multi-agent
echo "✓ Removed empty .multi-agent/ directory"
fi
```
### Step 5: Optionally Delete Branches
If `--all` flag:
```bash
for track in tracks:
branch = "dev-track-${track:02d}"
# Safety: verify branch is merged
if git branch --merged | grep -q "$branch"; then
git branch -d "$branch"
echo "✓ Deleted branch: $branch"
else
echo "⚠️ Branch $branch not fully merged - keeping for safety"
echo " To force delete: git branch -D $branch"
fi
done
```
### Step 6: Update State File
```yaml
# Update docs/planning/.project-state.yaml
cleanup_info:
cleaned_at: "2025-11-03T16:00:00Z"
worktrees_removed: [1, 2, 3]
branches_deleted: true # or false
```
## Output Format
**Success:**
```markdown
═══════════════════════════════════════════
Worktree Cleanup
═══════════════════════════════════════════
Cleaning up worktrees for all tracks...
Track 1:
✓ Verified no uncommitted changes
⚠️ Warning: 3 unpushed commits
✓ Worktree removed: .multi-agent/track-01/
Track 2:
✓ Verified no uncommitted changes
✓ Verified pushed to remote
✓ Worktree removed: .multi-agent/track-02/
Track 3:
✓ Verified no uncommitted changes
✓ Verified pushed to remote
✓ Worktree removed: .multi-agent/track-03/
✓ Removed .multi-agent/ directory
Branches kept (to remove: use --all flag):
- dev-track-01
- dev-track-02
- dev-track-03
Cleanup complete! ✅
```
**With --all flag:**
```markdown
═══════════════════════════════════════════
Worktree Cleanup (Including Branches)
═══════════════════════════════════════════
Cleaning up worktrees and branches...
Worktrees:
✓ Removed: .multi-agent/track-01/
✓ Removed: .multi-agent/track-02/
✓ Removed: .multi-agent/track-03/
✓ Removed: .multi-agent/ directory
Branches:
✓ Deleted: dev-track-01 (was merged)
✓ Deleted: dev-track-02 (was merged)
✓ Deleted: dev-track-03 (was merged)
All worktrees and branches removed! ✅
Note: Development history is still in main branch commits.
```
## Error Handling
**Uncommitted changes:**
```
❌ Cannot clean up worktree: .multi-agent/track-02/
Uncommitted changes detected:
M src/components/Header.tsx
M src/pages/Dashboard.tsx
?? src/components/NewFeature.tsx
Please commit or stash these changes:
cd .multi-agent/track-02/
git add .
git commit -m "Final changes"
Or force removal (WILL LOSE CHANGES):
git worktree remove --force .multi-agent/track-02/
```
**Track not complete:**
```
⚠️ WARNING: Cleaning up incomplete tracks
Track 2 progress: 1/2 sprints complete (4/6 tasks)
Track 3 progress: 0/2 sprints complete (0/5 tasks)
Are you sure you want to remove these worktrees?
Work will be lost unless already committed.
To continue: /multi-agent:worktree cleanup --force
```
## Safety Notes
- Always checks for uncommitted changes
- Warns about unpushed commits
- Won't delete unmerged branches (without -D flag)
- Can be undone if branches kept (recreate worktree)
- Updates state file for audit trail

115
commands/worktree-list.md Normal file
View File

@@ -0,0 +1,115 @@
# Worktree List Command
**Expert Command** - List all git worktrees with development track information.
## Command Usage
```bash
/multi-agent:worktree list # List all worktrees
```
## Your Process
### Step 1: Get Git Worktrees
```bash
# Get all git worktrees
git worktree list --porcelain
```
### Step 2: Load State File
Read `docs/planning/.project-state.yaml` to correlate git worktrees with development tracks.
### Step 3: Display Worktree Information
```markdown
═══════════════════════════════════════════
Git Worktrees
═══════════════════════════════════════════
Mode: Git worktrees enabled
State file: docs/planning/.project-state.yaml
Main Repository:
───────────────────────────────────────────
Path: /home/user/my-project
Branch: main
HEAD: abc123 (2 hours ago)
Development Track Worktrees:
───────────────────────────────────────────
Track 01: Backend API
Path: /home/user/my-project/.multi-agent/track-01
Branch: dev-track-01
HEAD: def456 (30 min ago)
Status: ✅ Complete (2/2 sprints)
Size: 45 MB
Track 02: Frontend
Path: /home/user/my-project/.multi-agent/track-02
Branch: dev-track-02
HEAD: ghi789 (1 hour ago)
Status: 🔄 In Progress (1/2 sprints)
Size: 52 MB
Track 03: Infrastructure
Path: /home/user/my-project/.multi-agent/track-03
Branch: dev-track-03
HEAD: jkl012 (2 hours ago)
Status: ⏸️ Pending (0/2 sprints)
Size: 38 MB
═══════════════════════════════════════════
Summary
═══════════════════════════════════════════
Total worktrees: 4 (1 main + 3 tracks)
Total disk usage: ~135 MB
Tracks complete: 1/3
Commands:
Status: /multi-agent:worktree status
Cleanup: /multi-agent:worktree cleanup
Merge: /multi-agent:merge-tracks
```
## Alternative: Simple Format
```markdown
Worktrees:
main /home/user/my-project (abc123)
track-01 /home/user/my-project/.multi-agent/track-01 (def456) ✅
track-02 /home/user/my-project/.multi-agent/track-02 (ghi789) 🔄
track-03 /home/user/my-project/.multi-agent/track-03 (jkl012) ⏸️
```
## Error Handling
**No worktrees:**
```
No development track worktrees found.
This project is using state-only mode (not git worktrees).
To use worktrees:
/multi-agent:planning <tracks> --use-worktrees
```
**Git command fails:**
```
Error: Could not list git worktrees
Make sure you're in a git repository:
git status
If git is not working, check git installation:
git --version
```
## Notes
- Shows all worktrees (not just multi-agent tracks)
- Correlates with state file for track information
- Displays disk usage per worktree
- Quick reference for expert users

229
commands/worktree-status.md Normal file
View File

@@ -0,0 +1,229 @@
# Worktree Status Command
**Expert Command** - Shows detailed status of all development track worktrees.
## Command Usage
```bash
/multi-agent:worktree status # Show all worktree status
/multi-agent:worktree status 01 # Show status for specific track
```
## Your Process
### Step 1: Load State File
Read `docs/planning/.project-state.yaml` to get worktree configuration.
If not worktree mode:
```
This project is not using git worktrees (mode: state-only)
No worktrees to show status for.
```
### Step 2: Collect Worktree Information
For each track in state file:
```bash
track_num = "01"
worktree_path = ".multi-agent/track-01"
branch_name = "dev-track-01"
# Check if worktree exists
if [ -d "$worktree_path" ]; then
exists = true
cd "$worktree_path"
# Get git status
current_branch = $(git rev-parse --abbrev-ref HEAD)
uncommitted = $(git status --porcelain | wc -l)
ahead = $(git rev-list --count @{u}..HEAD 2>/dev/null || echo "N/A")
behind = $(git rev-list --count HEAD..@{u} 2>/dev/null || echo "N/A")
# Get sprint status from state file
sprints = get_sprints_for_track(track_num)
completed_sprints = count(s for s in sprints if s.status == "completed")
total_sprints = len(sprints)
# Get task status
tasks = get_tasks_for_track(track_num)
completed_tasks = count(t for t in tasks if t.status == "completed")
total_tasks = len(tasks)
else
exists = false
fi
```
### Step 3: Display Status
**For all tracks:**
```markdown
═══════════════════════════════════════════
Development Track Status
═══════════════════════════════════════════
Mode: Git worktrees (physical isolation)
Base path: .multi-agent/
Track 1: Backend API
───────────────────────────────────────────
Status: ✅ ACTIVE
Location: .multi-agent/track-01/
Branch: dev-track-01 (current)
Progress: 2/2 sprints complete (7/7 tasks)
Git status:
Uncommitted changes: 0
Ahead of remote: 3 commits
Behind remote: 0
Action: ⚠️ Push recommended
Track 2: Frontend
───────────────────────────────────────────
Status: 🔄 IN PROGRESS
Location: .multi-agent/track-02/
Branch: dev-track-02 (current)
Progress: 1/2 sprints complete (4/6 tasks)
Git status:
Uncommitted changes: 5 files
Ahead of remote: 2 commits
Behind remote: 0
Action: ⚠️ Commit and push needed
Track 3: Infrastructure
───────────────────────────────────────────
Status: ⏸️ PENDING
Location: .multi-agent/track-03/
Branch: dev-track-03 (current)
Progress: 0/2 sprints complete (0/5 tasks)
Git status:
Uncommitted changes: 0
Ahead of remote: 0
Behind remote: 0
Action: ✓ Clean
═══════════════════════════════════════════
Summary
═══════════════════════════════════════════
Total tracks: 3
Complete: 1
In progress: 1
Pending: 1
Warnings:
⚠️ Track 1: Unpushed commits (backup recommended)
⚠️ Track 2: Uncommitted changes (commit before merge)
Next steps:
Track 2: /multi-agent:sprint all 02
Track 3: /multi-agent:sprint all 03
After all complete: /multi-agent:merge-tracks
```
**For specific track:**
```markdown
═══════════════════════════════════════════
Track 01: Backend API
═══════════════════════════════════════════
Worktree Information:
───────────────────────────────────────────
Location: .multi-agent/track-01/
Branch: dev-track-01 (current: dev-track-01) ✓
Status: Active
Progress:
───────────────────────────────────────────
Sprints: 2/2 complete ✅
✅ SPRINT-001-01: Foundation (5 tasks)
✅ SPRINT-002-01: Advanced Features (2 tasks)
Tasks: 7/7 complete ✅
✅ TASK-001: Database schema design
✅ TASK-004: User authentication API
✅ TASK-008: Product catalog API
✅ TASK-012: Shopping cart API
✅ TASK-016: Payment integration
✅ TASK-006: Email notifications
✅ TASK-018: Admin dashboard API
Git Status:
───────────────────────────────────────────
Uncommitted changes: 0 ✓
Staged files: 0
Commits ahead of remote: 3
Commits behind remote: 0
Recent commits:
abc123 (2 hours ago) Complete TASK-018: Admin dashboard
def456 (3 hours ago) Complete TASK-016: Payment integration
ghi789 (4 hours ago) Complete SPRINT-001-01
Actions Needed:
───────────────────────────────────────────
⚠️ Push commits to remote (backup)
git push origin dev-track-01
Ready for merge:
───────────────────────────────────────────
✅ All sprints complete
✅ All tasks complete
✅ No uncommitted changes
⚠️ Not pushed (recommended before merge)
When ready:
/multi-agent:merge-tracks
```
## Error Handling
**Worktree missing:**
```
═══════════════════════════════════════════
Track 02: Frontend
═══════════════════════════════════════════
Status: ❌ ERROR - Worktree not found
Expected location: .multi-agent/track-02/
Expected branch: dev-track-02
The worktree appears to be missing or was removed.
To recreate:
git worktree add .multi-agent/track-02 -b dev-track-02
Or recreate all with:
/multi-agent:planning 3 --use-worktrees
```
**Wrong branch:**
```
═══════════════════════════════════════════
Track 01: Backend API
═══════════════════════════════════════════
Status: ⚠️ WARNING - Branch mismatch
Location: .multi-agent/track-01/
Expected branch: dev-track-01
Current branch: main ❌
The worktree is on the wrong branch.
To fix:
cd .multi-agent/track-01/
git checkout dev-track-01
```
## Notes
- This command is read-only (no changes made)
- Shows aggregate status for quick health check
- Warns about issues that could block merging
- Useful before running merge-tracks