GSD 2 — Autonomous Spec-Driven Agent Framework

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

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.

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

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

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

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

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

/gsd costs — Cost Report

Detailed cost breakdown with projections.

/gsd costs
/gsd costs --by-phase
/gsd costs --by-slice
/gsd costs --export costs.csv

---

Project Setup

1. Write ROADMAP.md

# My Project Roadmap

## Milestone 1: Core API

### S1: Database schema and migrations
Set up Postgres schema for users, posts, and comments.

### S2: REST endpoints
CRUD endpoints for all resources with validation.

### S3: Authentication
JWT-based auth with refresh tokens.

## Milestone 2: Frontend

### S1: React app scaffold
...

2. Write PROJECT.md

# My Project

A REST API for a blogging platform built with Express + TypeScript + Postgres.

## Tech Stack
- Node.js 20, TypeScript 5
- Express 4
- PostgreSQL 15 via pg + kysely
- Jest for tests

## Conventions
- All endpoints return `{ data, error }` envelope
- Database migrations in `db/migrations/`
- Feature modules in `src/features/<name>/`

3. Initialize

/gsd init

4. Run

/gsd auto

---

The Auto-Mode State Machine

Research → Plan → Execute (per task) → Complete → Reassess → Next Slice

Each phase runs in a fresh session with context pre-inlined into the dispatch prompt:

Phase	What the LLM receives	What it produces
Research	PROJECT.md, ROADMAP.md, slice description, codebase index	RESEARCH.md with findings, gotchas, relevant files
Plan	Research output, slice description, must-haves	PLAN.md with task breakdown, verification steps
Execute (task N)	Task plan, prior task summaries, dependency summaries, DECISIONS.md	Working code committed to git
Complete	All task summaries, slice plan	SUMMARY.md, UAT script, updated ROADMAP.md
Reassess	Completed slice summary, full ROADMAP.md	Updated roadmap with any corrections

---

Must-Haves: Mechanically Verifiable Outcomes

Every task plan includes must-haves — explicit, checkable criteria the LLM uses to confirm completion. Write them as shell commands or file existence checks:

## Must-Haves

- [ ] `npm test -- --testPathPattern=auth` passes with 0 failures
- [ ] File `src/features/auth/jwt.ts` exists and exports `signToken`, `verifyToken`
- [ ] `curl -X POST http://localhost:3000/auth/login` returns 200 with `{ data: { token } }`
- [ ] No TypeScript errors: `npx tsc --noEmit` exits 0

The execute phase ends only when the LLM can check off every must-have.

---

Git Strategy

GSD manages git automatically in auto mode:

main
 └── milestone/M1          ← worktree branch created at start
      ├── commit: [M1/S1/T1] implement user model
      ├── commit: [M1/S1/T2] add migrations
      ├── commit: [M1/S1] slice complete
      ├── commit: [M1/S2/T1] POST /users endpoint
      └── ...
 
 After milestone complete:
main ← squash merge of milestone/M1 as "[M1] Auth system"

Each task commits with a structured message. Each slice commits a summary commit. The milestone squash-merges to main as one clean entry.

---

Crash Recovery

GSD writes a lock file at .gsd/LOCK when a unit starts and removes it on clean completion. If the process dies:

# Next run detects the lock and auto-recovers:
/gsd auto

# Output:
# ⚠ Lock file found: M1/S3/T2 was interrupted
# Synthesizing recovery briefing from session artifacts...
# Resuming with full context

The recovery briefing is synthesized from every tool call that reached disk — file writes, shell output, partial completions — so the resumed session has context continuity.

---

Cost Controls

Set a budget ceiling to pause auto mode before overspending:

/gsd auto --budget 10.00

The cost ledger at .gsd/costs/ledger.json:

{
  "units": [
    {
      "id": "M1/S1/research",
      "model": "claude-opus-4",
      "inputTokens": 12400,
      "outputTokens": 3200,
      "costUsd": 0.21,
      "completedAt": "2025-01-15T10:23:44Z"
    }
  ],
  "totalCostUsd": 1.84,
  "budgetUsd": 10.00
}

---

Decisions Register

.gsd/DECISIONS.md is auto-injected into every task dispatch. Record architectural decisions here and the LLM will respect them across all future sessions:

# Decisions Register

## D1: Use kysely not prisma
**Date:** 2025-01-14
**Reason:** Better TypeScript inference, no code generation step needed.
**Impact:** All DB queries use kysely QueryBuilder syntax.

## D2: JWT in httpOnly cookie, not Authorization header
**Date:** 2025-01-14  
**Reason:** Better XSS protection for the web client.
**Impact:** Auth middleware reads `req.cookies.token`.

---

Stuck Detection

If the same unit dispatches twice without producing its expected artifact, GSD:

1. Retries once with a deep diagnostic prompt that includes what was expected vs. what exists on disk
2. If the second attempt fails, stops auto mode and reports:

✗ Stuck on M1/S3/T1 after 2 attempts
Expected: src/features/auth/jwt.ts (not found)
Last session: .gsd/sessions/M1-S3-T1-attempt2.log
Run `/gsd run --task M1/S3/T1` to retry manually

---

Skills Integration

GSD supports auto-detecting and installing relevant skills during the research phase. Create SKILLS.md in your project:

# Project Skills

- name: postgres-kysely
- name: express-typescript  
- name: jest-testing

Skills are injected into the research and plan dispatch prompts, giving the LLM curated knowledge about your exact stack without burning context on irrelevant docs.

---

Timeout Supervision

Three timeout tiers prevent runaway sessions:

Timeout	Default	Behavior
Soft	8 min	Sends "please wrap up" steering message
Idle	3 min no tool calls	Sends "are you stuck?" recovery prompt
Hard	15 min	Pauses auto mode, preserves all disk state

Configure in .gsd/config.json:

{
  "timeouts": {
    "softMinutes": 8,
    "idleMinutes": 3,
    "hardMinutes": 15
  },
  "defaultModel": "claude-opus-4",
  "researchModel": "claude-sonnet-4"
}

---

TypeScript Integration (Pi SDK)

GSD is built on the Pi SDK. You can extend it programmatically:

how to use gsd-2-agent-framework
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use gsd-2-agent-framework on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add gsd-2-agent-framework
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/aradotso/trending-skills --skill gsd-2-agent-frameworkcopy
The skills CLI fetches gsd-2-agent-framework from GitHub repository aradotso/trending-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/gsd-2-agent-framework
Reload or restart Cursor to activate gsd-2-agent-framework. Access the skill through slash commands (e.g., /gsd-2-agent-framework) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?