--- name: nav-multi description: Run multi-Claude parallel workflow for a task. Auto-invokes when user says "run multi-agent workflow", "parallel agents for", "multi-claude for", or "spawn agents for". allowed-tools: Bash, Read, Write, Glob version: 1.0.0 --- # 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: 1. `navigator-multi-claude.sh` in PATH 2. Git repository clean (no uncommitted changes) 3. Navigator initialized (`.agent/` exists) ## Execution Steps ### Step 1: Validate Prerequisites ```bash # 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: ```bash 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 fi ``` ### Step 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, refactoring ``` ### Step 4: Generate Session ID ```bash 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 ```bash 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" } EOF ``` ### Step 6: Launch Workflow ```bash 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 ;; esac ``` ### Step 7: Offer Dashboard ```bash 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`: ```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 ─────► Done ``` ### Standard (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-1705123456 ``` ### Example 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-1705123456 ``` ## Related 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