Gsd 2 Agent Framework

# GSD 2 — Autonomous Spec-Driven Agent Framework

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection

GSD 2 is a standalone CLI that turns a structured spec into running software autonomously. It controls the agent harness directly — managing fresh context windows per task, git worktree isolation, crash recovery, cost tracking, and stuck detection — rather than relying on LLM self-loops. One command, walk away, come back to a built project with clean git history.

---

## Installation

```bash
npm install -g gsd-pi
```

Requires Node.js 18+. Works with Claude (Anthropic) as the underlying model via the Pi SDK.

---

## Core Concepts

### Work Hierarchy

```
Milestone  →  a shippable version (4–10 slices)
  Slice    →  one demoable vertical capability (1–7 tasks)
    Task   →  one context-window-sized unit of work
```

**Iron rule:** A task must fit in one context window. If it can't, split it into two tasks.

### Directory Layout

```
project/
├── .gsd/
│   ├── STATE.md          # current auto-mode position
│   ├── DECISIONS.md      # architecture decisions register
│   ├── LOCK              # crash recovery lock file
│   ├── milestones/
│   │   └── M1/
│   │       ├── slices/
│   │       │   └── S1/
│   │       │       ├── PLAN.md        # task breakdown with must-haves
│   │       │       ├── RESEARCH.md    # codebase/doc scouting output
│   │       │       ├── SUMMARY.md     # completion summary
│   │       │       └── tasks/
│   │       │           └── T1/
│   │       │               ├── PLAN.md
│   │       │               └── SUMMARY.md
│   └── costs/
│       └── ledger.json   # per-unit token/cost tracking
├── ROADMAP.md            # milestone/slice structure
└── PROJECT.md            # project description and goals
```

---

## Commands

### `/gsd auto` — Primary Autonomous Mode

Run the full automation loop. Reads `.gsd/STATE.md`, dispatches each unit in a fresh session, handles recovery, and advances through the entire milestone without intervention.

```bash
/gsd auto
# or with options:
/gsd auto --budget 5.00        # pause if cost exceeds $5
/gsd auto --milestone M1       # run only milestone 1
/gsd auto --dry-run            # show dispatch plan without executing
```

### `/gsd init` — Initialize a Project

Scaffold the `.gsd/` directory from a `ROADMAP.md` and optional `PROJECT.md`.

```bash
/gsd init
```

Creates initial `STATE.md`, registers milestones and slices from your roadmap, sets up the cost ledger.

### `/gsd status` — Dashboard

Shows current position, per-slice costs, token usage, and what's queued next.

```bash
/gsd status
```

Output example:
```
Milestone 1: Auth System  [3/5 slices complete]
  ✓ S1: User model + migrations
  ✓ S2: Password auth endpoints
  ✓ S3: JWT session management
  → S4: OAuth integration  [PLANNING]
    S5: Role-based access control

Cost: $1.84 / $5.00 budget
Tokens: 142k input, 38k output
```

### `/gsd run` — Single Unit Dispatch

Execute one specific unit manually instead of running the full loop.

```bash
/gsd run --slice M1/S4            # run research + plan + execute for a slice
/gsd run --task M1/S4/T2          # run a single task
/gsd run --phase research M1/S4   # run just the research phase
/gsd run --phase plan M1/S4       # run just the planning phase
```

### `/gsd migrate` — Migrate from v1

Import old `.planning/` directories from the original Get Shit Done.

```bash
/gsd migrate                        # migrate current directory
/gsd migrate ~/projects/old-project # migrate specific path
```

### `/gsd costs` — Cost Report

Detailed cost breakdown wit