Tony gsd-2

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".

install

source · Clone the upstream repo

git clone https://github.com/jaydeland/Tony

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jaydeland/Tony "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/gsd-2" ~/.claude/skills/jaydeland-tony-gsd-2 && rm -rf "$T"

manifest: .claude/skills/gsd-2/skill.md

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
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

/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:

# 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

Plan — scouts codebase, researches docs, decomposes slice into tasks
Execute — runs each task in a fresh context window
Complete — writes summary, UAT script, marks roadmap, commits
Reassess — checks if roadmap still makes sense
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

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

Milestone is not complete
All dependencies have status
```
complete
```
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

---
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

# 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

```
npm install -g gsd-pi
```
```
gsd
```
(first launch runs setup wizard)
```
cd your-project
```
```
/gsd discuss
```
to align on architecture
```
/gsd new-milestone
```
to create first milestone
```
/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`

Tony gsd-2

GSD 2 Framework Skill

Overview

Core Concepts

Work Hierarchy

Execution Loop

Key Features

Command Reference

Primary Workflow Commands

Steering & Control

Configuration & Diagnostics

Milestone Management

Parallel Orchestration

Git Worktree Commands

Session Management

Keyboard Shortcuts

Headless Mode (CI/CD)

CLI Flags

Exit Codes

Auto Mode Deep Dive

How It Works

Key Phases

Recovery Features

When to Use Auto Mode

When to Use Step Mode Instead

Parallel Milestone Orchestration

Configuration

Eligibility Requirements

When to Use

Safety Features

Skills System

What Skills Are

Bundled Skills (16)

Custom Skills

Skill Configuration

Git Strategy

Three Isolation Modes

Branching Model (Worktree Mode)

Commit Format

Configuration

Preference Files

Key Settings

Artifacts in .gsd/

Recommended Workflow

Two Terminals

Getting Started

When to Use Each Command Type

Additional Resources

Artifacts in
`.gsd/`