# gsd-2-agent-framework

A skill that documents the GSD 2 CLI, which walks a spec through milestone, slice and task levels and writes the code unattended. Handy when you want a long job to run while you are away.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1500 installs · ★ 88
- Author: reason-machines
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/reason-machines/trending-skills/tree/HEAD/skills/gsd-2-agent-framework/SKILL.md
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/skills/gsd-2-agent-framework

## What it does

GSD 2 is a separate command-line tool: feed it a structured spec and it produces a working project. The skill covers how its loop is wired. Every task gets its own fresh context window instead of one endless conversation where edits start contradicting each other. Position lives in `.gsd/STATE.md`, architecture choices accumulate in `.gsd/DECISIONS.md`, and token spend is tracked per unit in `.gsd/costs/ledger.json`.

The hierarchy is strict. A milestone is a shippable version, a slice is one demonstrable vertical capability, and a task is a chunk of work that fits one context window. If it does not fit, you split it. That is why a crash does not wipe the whole run: a lock file in `.gsd/LOCK` drives recovery. Git is handled for you — a branch per milestone, a commit per task, then a single squash merge into `main`.

Before any of this runs you need Node.js 18+ and the `gsd-pi` package installed globally; the underlying model is Claude through the Pi SDK, so Anthropic access is required. Done means the must-haves pass: shell commands and file checks written into the task plan. Set `--budget` on auto runs, otherwise spending keeps going past the point you had in mind.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill gsd-2-agent-framework -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/gsd-2-agent-framework/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/gsd-2-agent-framework/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill gsd-2-agent-framework -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/gsd-2-agent-framework/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill gsd-2-agent-framework -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/gsd-2-agent-framework/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install reason-machines/trending-skills gsd-2-agent-framework
```

2. **Manually: put the files in place**
- File: `.github/skills/gsd-2-agent-framework/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill gsd-2-agent-framework -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/reason-machines/trending-skills --path skills/gsd-2-agent-framework
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/gsd-2-agent-framework/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add reason-machines/trending-skills --skill gsd-2-agent-framework -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/reason-machines/trending-skills/tree/HEAD/skills/gsd-2-agent-framework/SKILL.md

## When to use it
- split a large feature into context-sized tasks
- take an API from spec to working code without watching the terminal
- resume an agent run after the process dies
- cap token spending at a chosen budget
- keep git history readable with one commit per task

## Example prompts
- Build the `.gsd/` directory from my `ROADMAP.md` and `PROJECT.md`, then run `/gsd init`
- Start `/gsd auto --milestone M1 --budget 5.00` and pause if the spend crosses the limit
- Tell me which slice we are on and what it has cost so far with `/gsd status`

## Similar
- [setup-matt-pocock-skills](https://affpapa.org/en/nevibecode/skills/setup-matt-pocock-skills.md) — skill · 1052851 installs
- [ask-matt](https://affpapa.org/en/nevibecode/skills/ask-matt.md) — skill · 766587 installs
- [to-tickets](https://affpapa.org/en/nevibecode/skills/to-tickets.md) — skill · 711230 installs
- [writing-plans](https://affpapa.org/en/nevibecode/skills/writing-plans.md) — skill · 282859 installs
- [caveman-review](https://affpapa.org/en/nevibecode/skills/caveman-review.md) — skill · 411800 installs
- [caveman-compress](https://affpapa.org/en/nevibecode/skills/caveman-compress.md) — skill · 411500 installs

From the same set: [reason-machines/trending-skills](https://affpapa.org/en/nevibecode/by/reason-machines/trending-skills.md) — 139 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md