b29c12d5e5
Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
97 lines
3 KiB
Markdown
97 lines
3 KiB
Markdown
# Parallel Orchestration
|
|
|
|
Run multiple milestones simultaneously in isolated git worktrees. Each milestone gets its own worker process, branch, and context window.
|
|
|
|
{% hint style="info" %}
|
|
Parallel mode is off by default. Enable it in preferences to use `/sf parallel` commands.
|
|
{% endhint %}
|
|
|
|
## Quick Start
|
|
|
|
1. Enable parallel mode:
|
|
```yaml
|
|
parallel:
|
|
enabled: true
|
|
max_workers: 2
|
|
```
|
|
|
|
2. Start parallel execution:
|
|
```
|
|
/sf parallel start
|
|
```
|
|
SF scans milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers.
|
|
|
|
3. Monitor:
|
|
```
|
|
/sf parallel status
|
|
```
|
|
|
|
4. Stop:
|
|
```
|
|
/sf parallel stop
|
|
```
|
|
|
|
## How It Works
|
|
|
|
Each worker is a separate SF process with complete isolation:
|
|
|
|
| Resource | Isolation |
|
|
|----------|----------|
|
|
| Filesystem | Own git worktree |
|
|
| Git branch | `milestone/<MID>` |
|
|
| Context window | Separate process |
|
|
| Metrics | Own `metrics.json` |
|
|
| Crash recovery | Own `auto.lock` |
|
|
|
|
Workers communicate with the coordinator through file-based IPC — heartbeat files and signal files in `.sf/parallel/`.
|
|
|
|
## Eligibility
|
|
|
|
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** — milestones touching the same files get a warning (but are still eligible since they run in separate worktrees)
|
|
|
|
## Configuration
|
|
|
|
```yaml
|
|
parallel:
|
|
enabled: false # master toggle (default: false)
|
|
max_workers: 2 # concurrent workers (1-4)
|
|
budget_ceiling: 50.00 # aggregate cost limit
|
|
merge_strategy: "per-milestone" # when to merge back
|
|
auto_merge: "confirm" # "auto", "confirm", or "manual"
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/sf parallel start` | Analyze and start workers |
|
|
| `/sf parallel status` | Show all workers with progress and 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
|
|
|
|
When milestones complete, their changes merge back to main:
|
|
|
|
- `.sf/` state files are auto-resolved
|
|
- Code conflicts halt the merge — resolve manually and retry with `/sf parallel merge <MID>`
|
|
|
|
## Budget Management
|
|
|
|
When `budget_ceiling` is set, aggregate cost across all workers is tracked. When the ceiling is reached, workers are signaled to stop.
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Fix |
|
|
|---------|-----|
|
|
| "Parallel mode is not enabled" | Set `parallel.enabled: true` |
|
|
| "No eligible milestones" | All milestones are complete or blocked; check `/sf queue` |
|
|
| Worker crashed | Run `/sf doctor --fix`, then `/sf parallel start` |
|
|
| Merge conflicts | Resolve in `.sf/worktrees/<MID>/`, then `/sf parallel merge <MID>` |
|
|
| Workers seem stuck | Check if budget ceiling was reached via `/sf parallel status` |
|