01b0d530c8
New: docs/parallel-orchestration.md — comprehensive guide covering: - Architecture overview with coordinator/worker diagram - Worker isolation model (process, worktree, state, context) - Eligibility analysis (dependencies + file overlap) - Configuration reference (all parallel.* keys) - Commands reference (/gsd parallel start|status|stop|pause|resume|merge) - Signal lifecycle (coordinator → worker communication) - Merge reconciliation with conflict handling - Budget management across workers - Doctor integration and health monitoring - Safety model breakdown - File layout (.gsd/parallel/ and .gsd/worktrees/) - Troubleshooting guide Updated existing docs: - auto-mode.md: cross-reference to parallel orchestration - configuration.md: parallel config block with all keys - commands.md: parallel commands table - git-strategy.md: parallel worktree branching diagram - README.md: added to documentation index
123 lines
5.4 KiB
Markdown
123 lines
5.4 KiB
Markdown
# Commands Reference
|
|
|
|
## Session Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/gsd` | Step mode — execute one unit at a time, pause between each |
|
|
| `/gsd next` | Explicit step mode (same as `/gsd`) |
|
|
| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat |
|
|
| `/gsd quick` | Execute a quick task with GSD guarantees (atomic commits, state tracking) without full planning overhead |
|
|
| `/gsd stop` | Stop auto mode gracefully |
|
|
| `/gsd steer` | Hard-steer plan documents during execution |
|
|
| `/gsd discuss` | Discuss architecture and decisions (works alongside auto mode) |
|
|
| `/gsd status` | Progress dashboard |
|
|
| `/gsd queue` | Queue and reorder future milestones (safe during auto mode) |
|
|
| `/gsd capture` | Fire-and-forget thought capture (works during auto mode) |
|
|
| `/gsd triage` | Manually trigger triage of pending captures |
|
|
| `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) |
|
|
| `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) |
|
|
| `/gsd help` | Categorized command reference with descriptions for all GSD subcommands |
|
|
|
|
## Configuration & Diagnostics
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/gsd prefs` | Model selection, timeouts, budget ceiling |
|
|
| `/gsd mode` | Switch workflow mode (solo/team) with coordinated defaults for milestone IDs, git commit behavior, and documentation |
|
|
| `/gsd doctor` | Runtime health checks (7 checks) with auto-fix for common state corruption issues |
|
|
| `/gsd skill-health` | Skill lifecycle dashboard — usage stats, success rates, token trends, staleness warnings |
|
|
| `/gsd skill-health <name>` | Detailed view for a single skill |
|
|
| `/gsd skill-health --declining` | Show only skills flagged for declining performance |
|
|
| `/gsd skill-health --stale N` | Show skills unused for N+ days |
|
|
| `/gsd hooks` | Show configured post-unit and pre-dispatch hooks |
|
|
| `/gsd run-hook` | Manually trigger a specific hook |
|
|
| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
|
|
|
|
## Parallel Orchestration
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/gsd parallel start` | Analyze eligibility, confirm, and start workers |
|
|
| `/gsd parallel status` | Show all workers with state, progress, and cost |
|
|
| `/gsd parallel stop [MID]` | Stop all workers or a specific milestone's worker |
|
|
| `/gsd parallel pause [MID]` | Pause all workers or a specific one |
|
|
| `/gsd parallel resume [MID]` | Resume paused workers |
|
|
| `/gsd parallel merge [MID]` | Merge completed milestones back to main |
|
|
|
|
See [Parallel Orchestration](./parallel-orchestration.md) for full documentation.
|
|
|
|
## Git Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/worktree` (`/wt`) | Git worktree lifecycle — create, switch, merge, remove |
|
|
|
|
## Session Management
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/clear` | Start a new session (alias for `/new`) |
|
|
| `/exit` | Graceful shutdown — saves session state before exiting |
|
|
| `/kill` | Kill GSD process immediately |
|
|
| `/model` | Switch the active model |
|
|
| `/login` | Log in to an LLM provider |
|
|
| `/thinking` | Toggle thinking level during sessions |
|
|
| `/voice` | Toggle real-time speech-to-text (macOS, Linux) |
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `Ctrl+Alt+G` | Toggle dashboard overlay |
|
|
| `Ctrl+Alt+V` | Toggle voice transcription |
|
|
| `Ctrl+Alt+B` | Show background shell processes |
|
|
| `Escape` | Pause auto mode (preserves conversation) |
|
|
|
|
> **Note:** In terminals without Kitty keyboard protocol support (macOS Terminal.app, JetBrains IDEs), slash-command fallbacks are shown instead of `Ctrl+Alt` shortcuts.
|
|
|
|
## CLI Flags
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `gsd` | Start a new interactive session |
|
|
| `gsd --continue` (`-c`) | Resume the most recent session for the current directory |
|
|
| `gsd --model <id>` | Override the default model for this session |
|
|
| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) |
|
|
| `gsd --mode <text\|json\|rpc\|mcp>` | Output mode for non-interactive use |
|
|
| `gsd --list-models [search]` | List available models and exit |
|
|
| `gsd sessions` | Interactive session picker — list all saved sessions for the current directory and choose one to resume |
|
|
| `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
|
|
| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
|
|
| `gsd update` | Update GSD to the latest version |
|
|
|
|
## Headless Mode
|
|
|
|
`gsd headless` runs `/gsd` commands without a TUI — designed for CI, cron jobs, and scripted automation. It spawns a child process in RPC mode, auto-responds to interactive prompts, detects completion, and exits with meaningful exit codes.
|
|
|
|
```bash
|
|
# Run auto mode (default)
|
|
gsd headless
|
|
|
|
# Run a single unit
|
|
gsd headless next
|
|
|
|
# Machine-readable output
|
|
gsd headless --json status
|
|
|
|
# With timeout for CI
|
|
gsd headless --timeout 600000 auto
|
|
|
|
# Force a specific phase
|
|
gsd headless dispatch plan
|
|
```
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--timeout N` | Overall timeout in milliseconds (default: 300000 / 5 min) |
|
|
| `--json` | Stream all events as JSONL to stdout |
|
|
| `--model ID` | Override the model for the headless session |
|
|
|
|
**Exit codes:** `0` = complete, `1` = error or timeout, `2` = blocked.
|
|
|
|
Any `/gsd` subcommand works as a positional argument — `gsd headless status`, `gsd headless doctor`, `gsd headless dispatch execute`, etc.
|