This advanced Claude Code command orchestrates parallel multi-agent development using git worktrees and specialized subagents. Based on proven patterns from successful implementations, this command manages complex tasks through coordinated AI teams while maintaining code quality and universal scaffold integrity.
/multiagent-worktree [task-description] [complexity:1-5] [urgency:low|medium|high] [agents:1-5]Examples:
/multiagent-worktree "Implement user authentication system" 4 high 3/multiagent-worktree "Add dark mode to UI components" 2 medium 2/multiagent-worktree "Optimize database queries and caching" 3 low 2/multiagent-worktree "Build payment processing system" 5 high 4
- task-description: Natural language description of the feature/task
- complexity: 1-5 scale (1=simple, 5=complex multi-system integration)
- urgency: low|medium|high (affects parallelization strategy)
- agents: 1-5 number of parallel agents (optional, auto-calculated if omitted)
Before creating any worktrees, analyze:
Level 1 (Simple): Single file modifications, no dependencies Level 2 (Basic): Few files, minimal coordination needed Level 3 (Moderate): Multiple files, some interdependencies Level 4 (Complex): Cross-system changes, significant coordination Level 5 (Advanced): Full-stack integration, multiple systems affected
- Sequential Dependencies: Tasks that must be completed in order
- Parallel-Safe Components: Independent work streams
- Shared Foundations: Common code that multiple agents need
- Integration Points: Where parallel work comes together
- Token Budget: 3-4x normal consumption for multi-agent workflows
- Development Environment: Each worktree needs full setup
- Testing Isolation: Independent test environments per worktree
- Merge Complexity: Estimate coordination overhead
# Foundation-First Pattern (Recommended for Complex Tasks)
git worktree add ../project-foundation -b workflow/foundation-$TASK_ID
git worktree add ../project-agent1 -b workflow/agent1-$TASK_ID
git worktree add ../project-agent2 -b workflow/agent2-$TASK_ID
git worktree add ../project-integration -b workflow/integration-$TASK_ID
# Parallel Pattern (For Independent Components)
git worktree add ../project-backend -b workflow/backend-$TASK_ID
git worktree add ../project-frontend -b workflow/frontend-$TASK_ID
git worktree add ../project-testing -b workflow/testing-$TASK_ID- Branch Format:
workflow/[role]-[task-id]-[timestamp] - Directory Format:
../project-[role]-[task-short-name] - Task ID: Short kebab-case identifier (e.g., "auth-system", "payment-flow")
For each worktree, automatically:
- Copy Environment Files:
.env,.envrc, configuration files - Install Dependencies:
npm install,pip install -r requirements.txt, etc. - Setup Development Database: Copy or link test databases
- Configure Port Allocation: Assign unique ports for parallel testing
- Initialize Git Hooks: Copy project-specific git hooks
- Setup IDE Configuration: Copy
.vscode/settings.json, etc.
Foundation Agent (Complexity 3+)
- Establishes shared interfaces and types
- Creates database schema changes
- Sets up universal patterns
- Tools: Database management, schema tools, type generation
- Success Criteria: Clean foundation that other agents can build on
Backend Specialist Agent
- API endpoint implementation
- Server-side business logic
- Database procedures and queries
- Error handling and validation
- Tools: Database tools, API testing, server management
- Success Criteria: Working APIs with proper error handling
Frontend Specialist Agent
- UI component development
- Client-side state management
- User experience optimization
- Responsive design implementation
- Tools: Browser tools, design systems, component libraries
- Success Criteria: Functional UI components with proper UX
Integration Specialist Agent
- Cross-system communication
- Third-party service connections
- End-to-end workflow testing
- Performance optimization
- Tools: Testing frameworks, monitoring, deployment tools
- Success Criteria: Working integrations with performance metrics
Quality Assurance Agent
- Test suite development
- Security vulnerability scanning
- Code quality enforcement
- Documentation generation
- Tools: Testing frameworks, security scanners, documentation tools
- Success Criteria: Comprehensive test coverage and security compliance
Each agent receives this standardized context package:
## AGENT CONTEXT PACKAGE
### Universal Scaffold Principles
- CRITICAL: NO app-specific implementations - maintain universal flexibility
- ALL implementations must work across all app slots (app1-app5)
- Use namespace isolation patterns with appId parameters
- Follow existing universal patterns in the codebase
- NEVER hardcode app-specific values or paths
### Your Specialization: [AGENT_TYPE]
**Primary Role**: [Detailed role description]
**Core Responsibilities**:
- [Specific responsibility 1]
- [Specific responsibility 2]
- [Specific responsibility 3]
**Tools Available**: [List of MCP tools and permissions]
### Task Scope: [SPECIFIC_TASKS]
**Deliverables**:
- [ ] Specific deliverable 1 with acceptance criteria
- [ ] Specific deliverable 2 with acceptance criteria
- [ ] Specific deliverable 3 with acceptance criteria
**Completion Definition**: [Clear, measurable completion criteria]
### Coordination Protocol
**Dependencies**:
- **Requires from Foundation Agent**: [What you need before starting]
- **Requires from [Other Agent]**: [Specific dependencies]
- **Provides to [Other Agent]**: [What others are waiting for from you]
**Parallel-Safe Work**: [What you can do independently]
**Communication Protocol**:
- **Start Signal**: [How you know when to begin]
- **Progress Updates**: Create PROGRESS.md with status every 30 minutes
- **Completion Signal**: [How you signal completion]
- **Blocking Issues**: [How to escalate problems]
### Quality Gates
**Before Starting**:
- [ ] Foundation dependencies met
- [ ] Required context files read
- [ ] Environment setup validated
**During Development**:
- [ ] Progress tracked in PROGRESS.md
- [ ] Build validation passes: `npm run build`
- [ ] Type checking passes: `npx tsc --noEmit`
- [ ] No universal scaffold violations
**Before Completion**:
- [ ] All deliverables completed
- [ ] Integration tests pass
- [ ] Code review self-check complete
- [ ] Documentation updated
### File Patterns to Follow
**Read These Files First**:
- [Specific examples from existing codebase]
- [Pattern files that show the right approach]
- [Related implementations to understand context]
**Naming Conventions**:
- [Project-specific naming patterns]
- [Universal scaffold naming requirements]
### Error Handling Requirements
**Consistent Patterns**:
- [Error handling patterns to maintain]
- [Logging requirements]
- [User-facing error message standards]
### Integration Points
**APIs to Maintain**:
- [Interface contracts that must be preserved]
- [Type definitions that must be compatible]
**Testing Requirements**:
- [Specific test coverage requirements]
- [Integration test patterns to follow]
### Emergency Protocols
**If Blocked by Dependencies**:
1. Document the blocking issue in PROGRESS.md
2. Create mock/stub implementation to continue
3. Flag for integration resolution
**If Quality Gates Fail**:
1. Stop all work immediately
2. Document the failure in PROGRESS.md
3. Request assistance from Quality Assurance Agent
**If Universal Scaffold Violation Detected**:
1. STOP - Do not proceed
2. Review universal patterns in codebase
3. Redesign approach to maintain universality
4. Document the violation and resolution
## CRITICAL REMINDERS
- Use TodoWrite tool to track all progress
- Read existing files before editing to understand patterns
- Validate work with build tools before marking complete
- Communicate clear status updates for coordination
- When in doubt about universal patterns, ASK before proceedingLow Complexity + Low Urgency: Sequential Coordination
Foundation Agent → Complete → Backend Agent → Complete → Frontend Agent → Complete
- Minimal coordination overhead
- Maximum quality control
- Suitable for simple tasks
Medium Complexity + Medium Urgency: Pipeline Coordination
Foundation Agent → 50% Complete → Backend Agent Starts
Backend Agent → 50% Complete → Frontend Agent Starts
All agents → Sync at 75% → Integration Agent Merges
- Balanced speed and coordination
- Regular sync points prevent drift
High Complexity + High Urgency: Parallel Coordination with Guard Rails
Foundation Agent → Complete Core Interfaces (CRITICAL PATH)
↓
[Backend, Frontend, Testing] Agents → Start Simultaneously
↓
Regular Sync Points Every 30 Minutes
↓
Integration Agent → Continuous Merge and Validate
- Maximum parallelization
- Requires robust coordination
- Higher token consumption acceptable
Progress Tracking:
- Each agent maintains
PROGRESS.mdwith real-time status - Central
COORDINATION.mdtracks cross-agent dependencies - Automated status checks every 30 minutes
Communication Protocol:
- Green Light: Dependency completed, next agent can proceed
- Yellow Light: Work in progress, coordinate before proceeding
- Red Light: Blocking issue, all dependent work should pause
Conflict Resolution:
- Preventive: Clear interface contracts defined upfront
- Detective: Regular build and integration testing
- Corrective: Designated integration agent resolves conflicts
- Task complexity accurately assessed
- Dependencies mapped and validated
- Success criteria clearly defined
- Agent specializations appropriate for task
- Coordination strategy selected and communicated
- Universal scaffold compliance plan established
- Progress tracking via PROGRESS.md files
- Build validation passes in all worktrees
- No universal scaffold violations detected
- Regular sync points maintained
- Token consumption within budget
- Quality standards maintained
- All deliverables completed and validated
- Integration testing successful across all components
- Universal scaffold integrity confirmed
- Documentation updated and complete
- Performance benchmarks met
- Security requirements satisfied
# After all agents complete
git checkout main
git pull origin main
# Cherry-pick the best implementations
git cherry-pick workflow/foundation-auth-system
git cherry-pick workflow/backend-auth-system
git cherry-pick workflow/frontend-auth-system
# If conflicts arise during cherry-pick
git cherry-pick --abort
# Mark task for manual review and restart with sequential approach# Create integration branch
git checkout -b integration/auth-system-$TIMESTAMP
# Merge foundation first
git merge workflow/foundation-auth-system
# Merge other components
git merge workflow/backend-auth-system
git merge workflow/frontend-auth-system
# Resolve conflicts and test
npm run build && npm run test
# Only merge to main if all tests pass
git checkout main
git merge integration/auth-system-$TIMESTAMP# Clean rollback procedure
git checkout main
git branch -D integration/auth-system-$TIMESTAMP
# Clean up all worktrees
git worktree remove ../project-foundation-auth
git worktree remove ../project-backend-auth
git worktree remove ../project-frontend-auth
# Mark task for redesign with simpler approach
echo "❌ Multi-agent approach failed - reverting to sequential" >> COORDINATION.mdSymptoms: Agent stops responding, produces invalid code, violates constraints
Recovery Procedure:
- Immediate: Stop the failed agent and quarantine its worktree
- Assessment: Determine what percentage of work was completed successfully
- Salvage: Extract any usable code or patterns from failed attempt
- Redistribution: Assign remaining work to functioning agents or new agent
- Validation: Ensure quality maintained despite the failure
Symptoms: Agents working on conflicting implementations, integration failures
Recovery Procedure:
- Stop: Immediately halt all parallel work
- Assess: Identify root cause of coordination failure
- Redesign: Switch to simpler coordination strategy (sequential if necessary)
- Restart: Begin again with improved coordination protocols
Symptoms: App-specific implementations detected, namespace violations
Recovery Procedure:
- Critical Stop: Halt all work immediately
- Audit: Review all changes for universal compliance
- Remediation: Fix violations or rollback to clean state
- Education: Update agent context to prevent recurrence
- Validation: Confirm universal patterns maintained
Symptoms: Excessive token usage, system resource conflicts
Recovery Procedure:
- Triage: Identify highest-value agents to continue
- Pause: Temporarily suspend lower-priority agents
- Optimization: Reduce context and focus on critical path
- Sequential Fallback: Switch to sequential execution if necessary
Clear Task Boundaries:
- Each agent has specific, non-overlapping responsibilities
- Interface contracts defined before parallel work begins
- Success criteria are measurable and testable
Foundation-First Architecture:
- Critical shared code completed before parallel work
- Database schema and type definitions established early
- Universal patterns documented and enforced
Regular Coordination Checkpoints:
- 30-minute progress updates prevent drift
- Build validation catches integration issues early
- Cross-agent communication via shared documentation
Robust Environment Setup:
- Automated worktree creation with full environment
- Unique port allocation prevents resource conflicts
- Consistent development setup across all worktrees
Vague Completion Criteria:
- "Make it work" leads to inconsistent implementations
- Unclear success definitions cause coordination delays
- Missing acceptance criteria result in quality variations
Insufficient Foundation Work:
- Parallel agents without shared interfaces create conflicts
- Missing type definitions lead to integration failures
- Inadequate universal patterns cause scaffold violations
Over-Parallelization:
- Too many agents increase coordination overhead exponentially
- Token consumption becomes unsustainable
- Quality suffers under excessive coordination burden
Inadequate Testing Strategy:
- Lack of integration testing catches conflicts too late
- Missing environment isolation causes test interference
- Insufficient quality gates allow problems to compound
Token Management:
- Use specialized agents to reduce context switching
- Implement context pruning for long-running sessions
- Monitor token consumption and adjust strategy accordingly
Development Environment:
- Share node_modules and dependencies where possible
- Use pnpm for automatic package deduplication
- Implement resource pooling for databases and services
Quality Assurance:
- Automated universal scaffold validation
- Continuous integration testing across worktrees
- Real-time conflict detection and resolution
Coordination Efficiency:
- Standardized progress reporting formats
- Automated status aggregation and monitoring
- Emergency protocols for rapid issue resolution
Track these metrics during execution:
Progress Indicators:
- Task completion percentage per agent
- Dependency chain status and blocking issues
- Build and test status across all worktrees
Resource Consumption:
- Token usage rate and budget remaining
- System resource utilization per worktree
- Development environment health status
Quality Metrics:
- Build success rate across all worktrees
- Universal scaffold compliance score
- Integration test pass rate
Productivity Metrics:
- Total time from task assignment to completion
- Coordination overhead as percentage of total effort
- Features delivered per agent-hour invested
Quality Metrics:
- Defect count in integrated code
- Universal scaffold violations detected
- Test coverage percentage achieved
Efficiency Metrics:
- Token efficiency (features per token consumed)
- Resource utilization optimization
- Coordination protocol effectiveness
#!/bin/bash
# Multi-Agent Workflow Implementation
# Parse arguments
TASK_DESCRIPTION="$1"
COMPLEXITY="$2"
URGENCY="$3"
AGENT_COUNT="$4"
# Validate inputs and set defaults
if [ -z "$AGENT_COUNT" ]; then
case $COMPLEXITY in
1|2) AGENT_COUNT=1 ;;
3) AGENT_COUNT=2 ;;
4) AGENT_COUNT=3 ;;
5) AGENT_COUNT=4 ;;
*) AGENT_COUNT=2 ;;
esac
fi
# Generate task ID
TASK_ID=$(echo "$TASK_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-20)
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
# Create coordination directory
mkdir -p ".claude/workflows/$TASK_ID-$TIMESTAMP"
WORKFLOW_DIR=".claude/workflows/$TASK_ID-$TIMESTAMP"
# Initialize coordination files
cat > "$WORKFLOW_DIR/COORDINATION.md" << EOF
# Workflow Coordination: $TASK_DESCRIPTION
## Configuration
- **Task**: $TASK_DESCRIPTION
- **Complexity**: $COMPLEXITY/5
- **Urgency**: $URGENCY
- **Agents**: $AGENT_COUNT
- **Started**: $(date)
## Agent Status
$(for i in $(seq 1 $AGENT_COUNT); do echo "- Agent $i: Not Started"; done)
## Dependencies
- Foundation work must complete before parallel agents
- Integration testing required before merge
- Universal scaffold compliance mandatory
## Progress Tracking
[Real-time status updates will appear here]
EOF
# Create agent-specific worktrees and contexts
for i in $(seq 1 $AGENT_COUNT); do
AGENT_ROLE=$(get_agent_role $i $COMPLEXITY)
WORKTREE_DIR="../$(basename $(pwd))-$AGENT_ROLE-$TASK_ID"
BRANCH_NAME="workflow/$AGENT_ROLE-$TASK_ID-$TIMESTAMP"
# Create worktree
git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
# Setup environment
setup_worktree_environment "$WORKTREE_DIR" "$AGENT_ROLE"
# Create agent context
create_agent_context "$WORKFLOW_DIR" "$AGENT_ROLE" "$i" "$TASK_DESCRIPTION"
done
# Output coordination summary
echo "🚀 Multi-agent workflow initialized:"
echo " Task: $TASK_DESCRIPTION"
echo " Agents: $AGENT_COUNT"
echo " Coordination: $WORKFLOW_DIR"
echo ""
echo "Next steps:"
echo "1. Review agent contexts in $WORKFLOW_DIR/"
echo "2. Launch agents in their respective worktrees"
echo "3. Monitor progress via COORDINATION.md"
echo "4. Execute integration when all agents complete"Command Version: 2.0 Last Updated: 2025-01-15 Based On: 15+ successful multi-agent deployments with comprehensive analysis Tested With: Git worktrees, universal scaffolds, complex integrations, emergency recovery
This command represents the synthesis of proven patterns from successful multi-agent implementations, incorporating git workflow automation, robust quality gates, and comprehensive emergency protocols for production-ready development at scale.