Jeremy edf9d0be6f docs: add GitBook-ready user-facing documentation

33 markdown files organized for GitBook import with SUMMARY.md navigation.
Covers installation, core concepts, auto mode, configuration, all providers,
cost management, skills, parallel orchestration, remote questions, teams,
headless CI, and full command reference. User-facing only — no internal/dev content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-11 10:34:07 -05:00

3 KiB

Raw Blame History

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 /gsd parallel commands. {% endhint %}

Quick Start

Enable parallel mode:

parallel:
  enabled: true
  max_workers: 2

Start parallel execution:
```
/gsd parallel start
```
GSD scans milestones, checks dependencies and file overlap, shows an eligibility report, and spawns workers.
Monitor:
```
/gsd parallel status
```
Stop:
```
/gsd parallel stop
```

How It Works

Each worker is a separate GSD 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 .gsd/parallel/.

Eligibility

Before starting, GSD checks which milestones can run concurrently:

Not complete — finished milestones are skipped
Dependencies satisfied — all dependsOn entries must be complete
File overlap — milestones touching the same files get a warning (but are still eligible since they run in separate worktrees)

Configuration

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
`/gsd parallel start`	Analyze and start workers
`/gsd parallel status`	Show all workers with progress and cost
`/gsd parallel stop [MID]`	Stop all or a specific worker
`/gsd parallel pause [MID]`	Pause all or a specific worker
`/gsd parallel resume [MID]`	Resume paused workers
`/gsd parallel merge [MID]`	Merge completed milestones to main

Merge Reconciliation

When milestones complete, their changes merge back to main:

.gsd/ state files are auto-resolved
Code conflicts halt the merge — resolve manually and retry with /gsd 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 `/gsd queue`
Worker crashed	Run `/gsd doctor --fix`, then `/gsd parallel start`
Merge conflicts	Resolve in `.gsd/worktrees/<MID>/`, then `/gsd parallel merge <MID>`
Workers seem stuck	Check if budget ceiling was reached via `/gsd parallel status`

3 KiB Raw Blame History