/gsd-2

Name

gsd-2

Description

GSD 2 (Get Shit Done v2) — spec-driven autonomous development system. Use this skill when executing development tasks with GSD 2, managing milestones/slices/tasks, running auto/step/quick mode, configuring parallel orchestration, managing git worktrees, or automating via headless mode. Triggers on "gsd", "get shit done", "milestone", "slice", "auto mode", "worktree", "parallel execution".

version

1.0.0

tags

[gsd, autonomous-dev, spec-driven, milestones, git-worktree, parallel-orchestration, automation, pi-sdk]

authors

[jasondeland]

milestone_id

Milestone identifier (e.g., 'M001')

slice_number

Slice number within milestone (e.g., 'S01')

task_number

Task identifier (e.g., 'T01')

mode

Execution mode: auto, next, quick, discuss, parallel

config_path

Path to GSD config/preferences file

verification_cmd

Command to run after task completion

git_isolation

Git isolation mode: worktree, branch, none

cli_command

Complete gsd CLI command ready to execute

execution_plan

Step-by-step execution plan for milestone/slice

state_snapshot

Current GSD state as structured data

verification_result

Pass/fail status from verification commands

# GSD 2 Framework Skill

> **Get Shit Done v2** — An autonomous, spec-driven development system for AI coding agents

## Overview

**GSD 2** is a meta-prompting, context engineering, and spec-driven development system built on the Pi SDK. It enables AI coding agents to work autonomously for extended periods while maintaining project context.

- **Repository**: [github.com/gsd-build/gsd-2](https://github.com/gsd-build/gsd-2)
- **Package**: `gsd-pi` on npm
- **Install**: `npm install -g gsd-pi`
- **Requirements**: Node.js ≥ 22.0.0 (24 LTS recommended), Git, any supported LLM provider

---

## Core Concepts

### Work Hierarchy

```
Milestone → Slice → Task
```

| Unit | Purpose | Size |
|------|---------|------|
| **Milestone** | Shippable version | 4-10 slices |
| **Slice** | Demoable vertical capability | 1-7 tasks |
| **Task** | One context-window-sized unit | Single dispatch |

### Execution Loop

```
Plan → Execute → Complete → Reassess Roadmap → Next Slice
    ↓ (all slices done)
Validate Milestone → Complete Milestone
```

---

## Key Features

| Feature | Description |
|---------|-------------|
| **Fresh Context** | 200k-token context window per task—no accumulated garbage |
| **Context Pre-loading** | Files inlined into dispatch prompts |
| **Git Worktree Isolation** | Branch-per-milestone with squash merge |
| **Crash Recovery** | Lock files + session forensics; auto-resume with backoff |
| **Stuck Detection** | Retry once with diagnostics, then stop |
| **Timeout Supervision** | Soft/idle/hard timeouts with recovery steering |
| **Cost Tracking** | Per-unit token/cost ledger with dashboard |
| **Adaptive Replanning** | Roadmap reassessed after each slice |
| **Verification Enforcement** | Auto-fix retries on lint/test failures |
| **Parallel Orchestration** | Multi-worker milestone coordination |

---

## Command Reference

### Primary Workflow Commands

| Command | When to Use |
|---------|-------------|
| `/gsd` or `/gsd next` | **Step mode** — execute one unit at a time, pause between each. Use when you want tight control and visibility into each step. |
| `/gsd auto` | **Auto mode** — autonomous execution through entire milestones. Use when you can walk away and let it run. Best paired with a second terminal for steering. |
| `/gsd quick` | **Quick mode** — execute a quick task without full planning overhead. Use for small, well-defined tasks. |
| `/gsd discuss` | **Discussion mode** — architecture discussions alongside auto mode. Use when you need to make decisions while auto mode runs. |

### Steering & Control

| Command | When to Use |
|---------|-------------|
| `/gsd status` | View progress dashboard with milestones, slices, and task states |
| `/gsd steer` | Hard-steer plan documents during execution to redirect or adjust |
| `/gsd queue` | Queue and reorder future milestones (safe during auto mode) |
| `/gsd capture "thought"` | Fire-and-forget thought capture during auto mode |
| `/gsd stop` | Gracefully stop auto mode |
| `/gsd visualize` | Open workflow visualizer with progress, dependencies, metrics, and timeline |

### Configuration & Diagnostics

| Command | When to Use |
|---------|-------------|
| `/gsd prefs` | Model selection, timeouts, budget ceiling, git settings, skills configuration |
| `/gsd config` | Re-run the provider setup wizard |
| `/gsd keys` | API key manager—list, add, remove, test, rotate keys |
| `/gsd doctor` | Runtime health checks (7 checks) with auto-fix capabilities |
| `/gsd skill-health` | Skill lifecycle dashboard—usage stats, success rates, staleness detection |
| `/gsd migrate` | Migrate v1 `.planning` to v2 `.gsd` format |

### Milestone Management

| Command | When to Use |
|---------|-------------|
| `/gsd new-milestone` | Create a new milestone with planning |
| `/gsd skip` | Prevent a unit from auto-mode dispatch |
| `/gsd undo` | Revert last completed unit |
| `/gsd cleanup` | Archive completed milestone phases and clean stale worktrees |

### Parallel Orchestration

| Command | When to Use |
|---------|-------------|
| `/gsd parallel start` | Analyze eligibility and spawn workers for parallel milestone execution |
| `/gsd parallel status` | Show all workers with state, progress, and cost |
| `/gsd parallel stop` | Stop all workers |
| `/gsd parallel pause` | Pause workers (finish current unit) |
| `/gsd parallel resume` | Resume paused workers |
| `/gsd parallel merge` | Merge completed milestones back to main |

### Git Worktree Commands

| Command | When to Use |
|---------|-------------|
| `/worktree` or `/wt` | Git worktree lifecycle—create, switch, merge, remove |

### Session Management

| Command | When to Use |
|---------|-------------|
| `/exit` | Graceful shutdown—saves session state before exiting |
| `/kill` | Immediate process kill |
| `/clear` | Start a new session (alias for `/new`) |
| `/gsd help` | Categorized full command reference |

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Alt+G` | Toggle dashboard overlay |
| `Ctrl+Alt+V` | Toggle voice transcription (macOS, Linux) |
| `Ctrl+Alt+B` | Show background shell processes |
| `Ctrl+V` / `Alt+V` | Paste image from clipboard (screenshot → vision input) |
| `Escape` | Pause auto mode (preserves conversation) |

---

## Headless Mode (CI/CD)

For pipelines and scripts:

```bash
# Run auto mode in CI with timeout
gsd headless --timeout 600000

# Create milestone and execute end-to-end
gsd headless new-milestone --context spec.md --auto

# Cron-friendly single unit execution
gsd headless next

# Instant JSON state snapshot (~50ms, no LLM)
gsd headless query

# Force specific pipeline phase
gsd headless dispatch plan
```

### CLI Flags

| Flag | Description |
|------|-------------|
| `gsd --continue` (`-c`) | Resume the most recent session |
| `gsd --model <id>` | Override the default model |
| `gsd --print "msg"` (`-p`) | Single-shot prompt mode (no TUI) |
| `gsd --debug` | Enable structured JSONL diagnostic logging |
| `gsd sessions` | Interactive session picker |

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Complete |
| `1` | Error or timeout |
| `2` | Blocked |

---

## Auto Mode Deep Dive

### How It Works

Auto mode operates as a **state machine driven by files on disk**. It reads `.gsd/STATE.md`, determines the next unit of work, creates a fresh agent session, injects a focused prompt with pre-inlined context, and lets the LLM execute.

### Key Phases

1. **Plan** — scouts codebase, researches docs, decomposes slice into tasks
2. **Execute** — runs each task in a fresh context window
3. **Complete** — writes summary, UAT script, marks roadmap, commits
4. **Reassess** — checks if roadmap still makes sense
5. **Validate Milestone** — reconciliation gate comparing roadmap criteria against actual results

### Recovery Features

- **Crash Recovery**: Lock file tracks current unit; next `/gsd auto` synthesizes recovery briefing and resumes with full context
- **Provider Error Recovery**: Auto-resumes rate limits (429) after retry-after header or 60s; server errors (500-503) after 30s
- **Timeout Supervision**: Three tiers—soft (20 min warn), idle (10 min stall detection), hard (30 min pause)

### When to Use Auto Mode

- Large, well-scoped features that can run overnight
- When you have a second terminal to monitor and steer
- Multiple independent milestones that can run in parallel
- When you want to walk away and return to finished work

### When to Use Step Mode Instead

- Unclear requirements needing frequent clarification
- High-risk changes requiring careful review
- When you need to understand each decision as it's made
- Exploratory work where the path isn't clear

---

## Parallel Milestone Orchestration

Run multiple milestones simultaneously in isolated git worktrees.

### Configuration

```yaml
parallel:
  enabled: true          # Master toggle (default: false)
  max_workers: 2         # 1-4 concurrent workers
  budget_ceiling: 50.00  # Optional aggregate cost limit
  merge_strategy: "per-milestone"  # or "per-slice"
  auto_merge: "confirm"   # "auto", "confirm", or "manual"
```

### Eligibility Requirements

1. Milestone is not complete
2. All dependencies have status `complete`
3. File overlap checks (warnings only, not blockers)

### When to Use

- Independent milestones with no interdependencies
- When you need to ship multiple features faster
- When you have budget headroom for parallel execution

### Safety Features

- Disabled by default (preserves existing behavior)
- Dependency analysis prevents invalid orderings
- Worker isolation via git worktrees
- Budget ceilings prevent overspending
- Doctor integration for orphaned session cleanup

---

## Skills System

### What Skills Are

Specialized instruction sets GSD loads when tasks match. They provide domain-specific guidance—coding patterns, framework idioms, testing strategies, and tool usage.

### Bundled Skills (16)

| Category | Skills |
|----------|--------|
| **Frontend** | `frontend-design` |
| **Mobile** | `swiftui` |
| **Rust** | `rust-core`, `axum-web-framework`, `axum-tests` |
| **Desktop** | `tauri`, `tauri-ipc-developer`, `tauri-devtools` |
| **DevOps** | `github-workflows` |
| **Security** | `security-audit`, `security-review`, `security-docker` |
| **Quality** | `review`, `test`, `lint` |
| **Debugging** | `debug-like-expert` |

### Custom Skills

Create your own skills with a `SKILL.md` file:

```
~/.gsd/agent/skills/my-skill/
  SKILL.md — instructions for the LLM
  references/ — optional reference files
```

Project-local skills go in `.pi/agent/skills/`.

### Skill Configuration

```yaml
---
always_use_skills:
  - debug-like-expert
prefer_skills:
  - frontend-design
avoid_skills:
  - security-docker
skill_rules:
  - when: task involves Clerk authentication
    use: [clerk]
skill_discovery: suggest  # "auto", "suggest", or "off"
---
```

---

## Git Strategy

### Three Isolation Modes

| Mode | Working Directory | Best For |
|------|-------------------|----------|
| `worktree` (default) | `.gsd/worktrees/<MID>/` | Full file isolation between milestones |
| `branch` | Project root | Submodule-heavy repos where worktrees don't work |
| `none` | Project root | Hot-reload workflows, small projects |

### Branching Model (Worktree Mode)

```
main ─────────────────────────────────────────────────────────
  │                                                     ↑
  └── milestone/M001 (worktree) ────────────────────────┘
       commit: feat(S01/T01): core types
       commit: feat(S01/T02): markdown parser
       → squash-merged to main as single commit
```

### Commit Format

```
feat(S01/T01): core type definitions
feat(S01/T02): markdown parser for plan files
fix(M001/S03): bug fixes and doc corrections
```

---

## Configuration

### Preference Files

- **Global**: `~/.gsd/preferences.md`
- **Project**: `.gsd/preferences.md`

### Key Settings

```yaml
# Per-phase model selection
models:
  research: claude-sonnet-4-6
  planning:
    model: claude-opus-4-6
    fallbacks:
      - openrouter/z-ai/glm-5
  execution: claude-sonnet-4-6
  completion: claude-sonnet-4-6

# Token profile (controls phase skipping)
token_profile: balanced  # "budget", "balanced", "quality"

# Budget controls
budget_ceiling: 50.00
budget_enforcement: warn  # "warn", "pause", "halt"

# Timeout supervision (minutes)
auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30

# Verification commands (run after task execution)
verification_commands:
  - npm run lint
  - npm run test

# Git settings
git:
  isolation: worktree  # "worktree", "branch", "none"
  auto_push: true
  auto_pr: true
```

---

## Artifacts in `.gsd/`

| File | Purpose |
|------|---------|
| `PROJECT.md` | Living doc—what the project is now |
| `DECISIONS.md` | Append-only architectural decision register |
| `STATE.md` | Quick-glance dashboard (read first) |
| `M001-ROADMAP.md` | Milestone plan with slices, risks, dependencies |
| `M001-CONTEXT.md` | User decisions from discuss phase |
| `M001-RESEARCH.md` | Codebase and ecosystem research |
| `S01-PLAN.md` | Slice task decomposition |
| `T01-PLAN.md` | Individual task plan with verification criteria |
| `T01-SUMMARY.md` | What happened—YAML frontmatter + narrative |
| `S01-UAT.md` | Human test script from slice outcomes |

---

## Recommended Workflow

### Two Terminals

```
Terminal 1:  gsd → /gsd auto
Terminal 2:  gsd → /gsd discuss, /gsd status, /gsd queue
```

### Getting Started

1. `npm install -g gsd-pi`
2. `gsd` (first launch runs setup wizard)
3. `cd your-project`
4. `/gsd discuss` to align on architecture
5. `/gsd new-milestone` to create first milestone
6. `/gsd auto` to execute

---

## When to Use Each Command Type

| Scenario | Recommended Command |
|----------|---------------------|
| Clear spec, want to walk away | `/gsd auto` |
| Want to see each step | `/gsd next` |
| Small, well-defined task | `/gsd quick` |
| Making architectural decisions | `/gsd discuss` |
| Check progress | `/gsd status` |
| Add work during auto mode | `/gsd queue` |
| Redirect mid-execution | `/gsd steer` |
| Independent milestones | `/gsd parallel start` |
| CI/cron automation | `gsd headless` |

---

## Additional Resources

- [GSD 2 GitHub Repository](https://github.com/gsd-build/gsd-2)
- [Getting Started Guide](https://github.com/gsd-build/gsd-2/blob/main/README.md)
- [Auto Mode Documentation](https://github.com/gsd-build/gsd-2/blob/main/docs/auto-mode.md)
- [Parallel Orchestration](https://github.com/gsd-build/gsd-2/blob/main/docs/parallel-orchestration.md)
- [Skills Documentation](https://github.com/gsd-build/gsd-2/blob/main/docs/skills.md)
- [Commands Reference](https://github.com/gsd-build/gsd-2/blob/main/docs/commands.md)
- [Configuration Guide](https://github.com/gsd-build/gsd-2/blob/main/docs/configuration.md)
- [Migration from v1](https://github.com/gsd-build/gsd-2/blob/main/docs/migration.md)