9d739dfa5d
- All gsdDir/gsdRoot/gsdHome → sfDir/sfRootDir/sfHome - GSDWorkspace* → SFWorkspace* interfaces - bootstrapGsdProject → bootstrapProject - runGSDDoctor → runSFDoctor - GsdClient → SfClient, gsd-client.ts → sf-client.ts - .gsd/ → .sf/ in all tests, docs, docker, native, vscode - Auto-migration: headless detects .gsd/ → renames to .sf/ - Deleted gsd-phase-state.ts backward-compat re-export - Renamed bin/gsd-from-source → bin/sf-from-source - Updated mintlify docs, github workflows, docker configs
123 lines
4.1 KiB
Text
123 lines
4.1 KiB
Text
---
|
|
title: "Parallel orchestration"
|
|
description: "Run multiple milestones simultaneously in isolated git worktrees."
|
|
---
|
|
|
|
Run multiple milestones simultaneously. Each gets its own worker process, branch, and context window — while a coordinator tracks progress, enforces budgets, and keeps everything in sync.
|
|
|
|
<Note>
|
|
Parallel mode is behind `parallel.enabled: false` by default. Opt-in only.
|
|
</Note>
|
|
|
|
## Quick start
|
|
|
|
1. Enable in preferences:
|
|
|
|
```yaml
|
|
parallel:
|
|
enabled: true
|
|
max_workers: 2
|
|
```
|
|
|
|
2. Start parallel execution:
|
|
|
|
```
|
|
/sf parallel start
|
|
```
|
|
|
|
3. Monitor progress:
|
|
|
|
```
|
|
/sf parallel status
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Coordinator (your SF session) │
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Worker 1 │ │ Worker 2 │ │ Worker 3 │ ... │
|
|
│ │ M001 │ │ M003 │ │ M005 │ │
|
|
│ └──────────┘ └──────────┘ └──────────┘ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ .sf/worktrees/ .sf/worktrees/ .sf/worktrees/ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Worker isolation
|
|
|
|
| Resource | Isolation method |
|
|
|----------|-----------------|
|
|
| Filesystem | Git worktree — separate checkout |
|
|
| Git branch | `milestone/<MID>` per milestone |
|
|
| State | `SF_MILESTONE_LOCK` — each worker sees only its milestone |
|
|
| Context | Separate process with its own agent sessions |
|
|
| Metrics | Each worktree has its own `metrics.json` |
|
|
|
|
## Eligibility analysis
|
|
|
|
Before starting, SF checks which milestones can run concurrently:
|
|
|
|
1. **Not complete** — finished milestones are skipped
|
|
2. **Dependencies satisfied** — all `dependsOn` entries must be complete
|
|
3. **File overlap check** — shared files get a warning (not a blocker)
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
parallel:
|
|
enabled: false
|
|
max_workers: 2
|
|
budget_ceiling: 50.00
|
|
merge_strategy: "per-milestone" # or "per-slice"
|
|
auto_merge: "confirm" # "auto", "confirm", or "manual"
|
|
```
|
|
|
|
| Key | Default | Description |
|
|
|-----|---------|-------------|
|
|
| `enabled` | `false` | Master toggle |
|
|
| `max_workers` | `2` | Concurrent workers (1-4) |
|
|
| `budget_ceiling` | none | Aggregate cost limit across all workers |
|
|
| `merge_strategy` | `"per-milestone"` | When to merge back to main |
|
|
| `auto_merge` | `"confirm"` | How merge-back is handled |
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/sf parallel start` | Analyze, confirm, and start workers |
|
|
| `/sf parallel status` | Show workers with state, progress, cost |
|
|
| `/sf parallel stop [MID]` | Stop all or a specific worker |
|
|
| `/sf parallel pause [MID]` | Pause all or a specific worker |
|
|
| `/sf parallel resume [MID]` | Resume paused workers |
|
|
| `/sf parallel merge [MID]` | Merge completed milestones to main |
|
|
|
|
## Merge reconciliation
|
|
|
|
- `.sf/` state files — auto-resolved (accept milestone branch version)
|
|
- Code conflicts — merge halts, shows conflicting files. Resolve manually and retry.
|
|
|
|
## Budget management
|
|
|
|
When `budget_ceiling` is set, aggregate cost is tracked across all workers. Ceiling reached → coordinator signals workers to stop.
|
|
|
|
## Troubleshooting
|
|
|
|
### "No milestones are eligible"
|
|
|
|
All milestones are complete or blocked by dependencies. Check `/sf queue`.
|
|
|
|
### Worker crashed
|
|
|
|
Workers persist state to disk. On restart, the coordinator detects dead PIDs. Run `/sf doctor --fix` to clean up, then `/sf parallel start` to spawn new workers.
|
|
|
|
### Merge conflicts
|
|
|
|
```
|
|
/sf parallel merge # see which milestones conflict
|
|
# resolve in .sf/worktrees/<MID>/
|
|
/sf parallel merge MID # retry
|
|
```
|