Auto Parallel

Parallel Execution Mode

Enable parallel agent execution for multi-domain features.

What is Parallel Mode?

Parallel mode spawns multiple specialized agents that work simultaneously on different parts of your feature:

• Frontend Agent: React, Vue, Angular, UI components
• Backend Agent: API, services, controllers, middleware
• Database Agent: Schema, migrations, queries, indexes
• DevOps Agent: CI/CD, Docker, Terraform, infrastructure
• QA Agent: Tests, E2E, coverage, validation

Each agent works in its own git worktree for complete isolation - no merge conflicts during development!

Flags

Examples

Parallel Frontend + Backend:

/sw:auto --parallel --frontend --backend 0170-auth-feature

With PR Creation:

/sw:auto --parallel --frontend --backend --pr 0170-auth-feature

Analyze Prompt for Suggestions:

/sw:auto --prompt "Build React login with Express API and PostgreSQL"

# Output:
# ✓ Parallel execution recommended
# Detected domains: frontend, backend, database
# Suggestions:
#   --parallel --frontend --backend --database

Full Stack with All Domains:

/sw:auto --parallel --frontend --backend --database --qa 0170-feature

How Parallel Mode Works

1. /sw:auto --parallel --frontend --backend 0170
           │
           ▼
2. Session created with 2 agents
   └─ .specweave/state/parallel/session.json
           │
           ▼
3. Git worktrees created
   ├─ .specweave/worktrees/frontend-0170/
   └─ .specweave/worktrees/backend-0170/
           │
           ▼
4. Agents work in parallel
   ├─ Frontend agent: UI components
   └─ Backend agent: API endpoints
           │
           ▼
5. Completion detected
           │
           ├─ --pr flag? → Create PRs
           │   ├─ PR #1: [0170] frontend: Auth UI
           │   └─ PR #2: [0170] backend: Auth API
           │
           └─ --merge-strategy auto? → Merge to base
               ├─ database first
               ├─ backend second
               └─ frontend last

Status Dashboard

/sw:auto-status --parallel

# Output:
╔═══════════════════════════════════════════════════════════════════╗
║  PARALLEL SESSION: session-abc123                                  ║
╠═══════════════════════════════════════════════════════════════════╣
║  Agent      │ Status  │ Progress    │ Time   │ Branch               ║
║  ───────────────────────────────────────────────────────────────── ║
║  frontend   │ 🔄 run  │ ████░░ 4/6  │  12m   │ auto/frontend-0170   ║
║  backend    │ ✅ done │ ██████ 8/8  │  25m   │ auto/backend-0170    ║
║  database   │ ✅ done │ ██████ 3/3  │   5m   │ auto/database-0170   ║
╠═══════════════════════════════════════════════════════════════════╣
║  Overall: 78% │ Completed: 2 │ Running: 1 │ Failed: 0               ║
╚═══════════════════════════════════════════════════════════════════╝

Watch mode (auto-refresh):

/sw:auto-status --parallel --watch

Merge Order

Agents are merged in dependency order:

1. Database first (schema before API)
2. Backend second (API before UI)
3. Frontend last (depends on backend)
4. DevOps/QA anytime (parallel-safe)

Stop Hook Integration

The stop hook blocks exit while parallel agents are running:

🔄 2 parallel agent(s) running: frontend:running, backend:pending → wait for completion

Exit is approved when:

• All agents are completed or failed
• Session is cancelled via --reset

Configuration

In .specweave/config.json:

{
  "auto": {
    "parallel": {
      "enabled": true,
      "maxParallel": 3,
      "defaultDomains": ["frontend", "backend"],
      "defaultMergeStrategy": "auto",
      "createPR": false,
      "draftPR": false
    }
  }
}

Cross-Platform Support

Parallel mode works on all platforms:

• macOS: Native git worktrees
• Linux: Native git worktrees
• Windows: Long path support (\?\ prefix for >260 chars)

Troubleshooting

Best Practices

1. Start with 2-3 domains: frontend + backend is most common
2. Use --prompt first: Let the analyzer suggest the right flags
3. Use --draft-pr: Review before merging
4. Check status often: Use --watch for live updates
5. Reset on stuck: specweave auto --reset clears state

Related

• /sw:auto - Main auto mode command
• /sw:auto-status - Check session status