Navigator Multi-Agent Workflow
Launch parallel Claude agents to implement a task with orchestration, implementation, testing, review, and documentation phases.
When to Invoke
Auto-invoke when user says:
- "Run multi-agent workflow for TASK-XX"
- "Use parallel agents for this feature"
- "Multi-claude for implementing X"
- "Spawn agents for this task"
- "Launch multi-agent on TASK-XX"
DO NOT invoke if:
- Multi-Claude scripts not installed (use nav-install-multi-claude first)
- User is asking informational questions about multi-agent
- Task is trivial (single file change)
Prerequisites
Check before running:
navigator-multi-claude.shin PATH- Git repository clean (no uncommitted changes)
- Navigator initialized (
.agent/exists)
Execution Steps
Step 1: Validate Prerequisites
# Check scripts installed
if ! command -v navigator-multi-claude.sh &> /dev/null; then
echo "❌ Multi-Claude scripts not installed"
echo ""
echo "Install first with:"
echo ' "Install multi-Claude workflows"'
exit 1
fi
# Check Navigator initialized
if [ ! -d ".agent" ]; then
echo "❌ Navigator not initialized in this project"
echo ""
echo "Initialize first with:"
echo ' "Initialize Navigator in this project"'
exit 1
fi
# Check git clean
if [ -n "$(git status --porcelain)" ]; then
echo "⚠️ Uncommitted changes detected"
echo ""
git status --short
echo ""
echo "Multi-agent workflows work best with a clean git state."
echo "Commit or stash changes before proceeding?"
fi
echo "✅ Prerequisites validated"Step 2: Parse Task Information
Extract from user request:
- Task ID: TASK-XX (if mentioned)
- Task description: What to implement
If TASK-XX mentioned, read task file:
if [ -n "$TASK_ID" ]; then
TASK_FILE=".agent/tasks/${TASK_ID}*.md"
if ls $TASK_FILE 1> /dev/null 2>&1; then
TASK_DESC=$(head -1 $TASK_FILE | sed 's/# //')
echo "📋 Task: $TASK_DESC"
fi
fiStep 3: Choose Workflow Type
Present options to user:
Which workflow type?
1. **POC (2-phase)** - Quick validation
- Planning → Implementation
- ~3 minutes
- Best for: Simple features, utilities
2. **Standard (4-phase)** - Full quality gates
- Planning → Implementation → Testing + Docs → Review
- ~6 minutes
- Best for: Production features
3. **Full (6-phase)** - With simplification
- Planning → Implementation → Simplify → Testing + Docs → Review → Integration
- ~8 minutes
- Best for: Complex features, refactoringStep 4: Generate Session ID
TASK_NUM=$(echo "$TASK_ID" | grep -oE '[0-9]+' || echo "0")
SESSION_ID="task-${TASK_NUM}-$(date +%s)"
echo "📌 Session: $SESSION_ID"Step 5: Create State File
cat > ".agent/tasks/${SESSION_ID}-state.json" << EOF
{
"session_id": "${SESSION_ID}",
"task": "${TASK_DESC}",
"task_id": "${TASK_ID}",
"workflow_type": "${WORKFLOW_TYPE}",
"phases_completed": [],
"current_phase": "init",
"started_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"status": "in_progress"
}
EOFStep 6: Launch Workflow
echo "🚀 Launching multi-agent workflow..."
echo ""
case $WORKFLOW_TYPE in
poc)
navigator-multi-claude-poc.sh "$TASK_DESC"
;;
standard)
navigator-multi-claude.sh "$TASK_DESC"
;;
full)
navigator-multi-claude.sh "$TASK_DESC" --with-simplify
;;
esacStep 7: Offer Dashboard
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Monitor progress with dashboard?"
echo ""
echo "In another terminal, run:"
echo " ./scripts/multi-claude-dashboard.sh $SESSION_ID"
echo ""
echo "Or watch marker log:"
echo " tail -f .agent/.marker-log"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"Output Format
┌─────────────────────────────────────────────────────┐
│ Multi-Agent Workflow: task-36-1705123456 │
├─────────────────────────────────────────────────────┤
│ Task: Implement user authentication │
│ Type: standard (4-phase) │
├─────────────────────────────────────────────────────┤
│ Phases: │
│ 1. Planning → orchestrator │
│ 2. Implementation → implementer │
│ 3. Testing → tester (parallel) │
│ 3. Documentation → documenter (parallel) │
│ 4. Review → reviewer │
├─────────────────────────────────────────────────────┤
│ Monitor: ./scripts/multi-claude-dashboard.sh │
│ Logs: tail -f .agent/.marker-log │
└─────────────────────────────────────────────────────┘
🚀 Launching workflow...Error Handling
Scripts Not Installed
❌ Multi-Claude scripts not installed
The multi-agent workflow requires orchestration scripts.
Install with:
"Install multi-Claude workflows"
Then retry:
"Run multi-agent workflow for TASK-XX"Uncommitted Changes
⚠️ Uncommitted changes detected
M src/auth/login.ts
?? src/utils/temp.ts
Multi-agent workflows create branches and parallel changes.
Working with uncommitted changes may cause conflicts.
Options:
1. Commit changes first: git add -A && git commit -m "WIP"
2. Stash changes: git stash
3. Proceed anyway (risky)
Which option? [1/2/3]Workflow Already Running
⚠️ Workflow already in progress
Session: task-35-1705120000
Status: IMPL phase running
Started: 5 minutes ago
Options:
1. Resume existing workflow
2. Cancel existing and start new
3. Wait for completion
Which option? [1/2/3]Configuration
In .agent/.nav-config.json:
{
"multi_agent": {
"enabled": true,
"default_workflow": "standard",
"auto_dashboard": false,
"parallel_limit": 3,
"retry_attempts": 2,
"phase_timeout_seconds": 180
}
}Success Criteria
Workflow launch successful when:
- Prerequisites validated
- Session ID generated
- State file created
- Workflow script launched
- Dashboard instructions shown
Workflow Phases
POC (2-phase)
Planning ─────► Implementation ─────► DoneStandard (4-phase)
┌─► Testing ────┐
Planning ─► Implementation ───┤ ├─► Review ─► Done
└─► Docs ───────┘Full (6-phase)
┌─► Testing ────┐
Planning ─► Implementation ─► Simplify ───┤ ├─► Review ─► Integration ─► Done
└─► Docs ───────┘Role Templates
Each phase uses a minimal context CLAUDE.md:
templates/multi-claude/orchestrator-claude.md(~4k tokens)templates/multi-claude/implementer-claude.md(~5k tokens)templates/multi-claude/tester-claude.md(~4k tokens)templates/multi-claude/reviewer-claude.md(~4k tokens)templates/multi-claude/documenter-claude.md(~4k tokens)templates/multi-claude/simplifier-claude.md(~5k tokens)
Total: ~27k tokens across 6 roles (vs 50k+ loading full project context per role)
Examples
Example 1: Quick Feature with POC
User: "Run multi-agent POC for adding a logout button"
✅ Prerequisites validated
📋 Task: Add logout button
📌 Session: task-0-1705123456
🚀 Launching POC workflow (2-phase)...
Phase 1: Planning (orchestrator)
Phase 2: Implementation (implementer)
Monitor: ./scripts/multi-claude-dashboard.sh task-0-1705123456Example 2: Standard Workflow for TASK-XX
User: "Use parallel agents for TASK-36"
✅ Prerequisites validated
📋 Task: Multi-Agent Production Polish (from TASK-36)
📌 Session: task-36-1705123456
🚀 Launching standard workflow (4-phase)...
Phase 1: Planning
Phase 2: Implementation
Phase 3: Testing + Documentation (parallel)
Phase 4: Review
Dashboard available in another terminal.Example 3: Full Workflow with Simplification
User: "Multi-claude full workflow for auth refactor"
✅ Prerequisites validated
📋 Task: Auth refactor
📌 Session: task-0-1705123456
🚀 Launching full workflow (6-phase)...
Includes code simplification phase for clarity improvements.
Expected duration: ~8 minutes
Monitor progress:
./scripts/multi-claude-dashboard.sh task-0-1705123456Related Skills
- nav-install-multi-claude: Install orchestration scripts
- nav-task: Create task documentation
- nav-marker: Context preservation between phases
- nav-simplify: Code simplification (used in full workflow)
Notes
- Multi-agent workflows spawn headless Claude instances
- Each role gets fresh context (no cross-contamination)
- Marker files coordinate phase transitions
- Dashboard provides real-time visibility
- State file enables resume after interruption