Project Overview

GSD started life as a meta-prompting framework for Claude Code — a clever set of instructions that tried to wrangle an LLM into following a structured development workflow. It went viral, and for good reason: the problem it addressed was real. AI coding assistants are powerful but chaotic; they lose context, forget constraints, and drift off task. But v1 was fundamentally limited — it was just prompts asking an LLM to behave, with no real enforcement mechanism. GSD 2 represented a complete architectural rethink. By building on the Pi SDK (a TypeScript-native agent harness), the project moved from being a prompt template to a proper CLI agent that can actually manage its own execution environment. It can clear context windows, inject files at dispatch time, manage git branches, track token usage, detect when it’s stuck in a loop, and auto-advance through multi-step milestones. The shift from “asking nicely” to “controlling the harness” is the kind of architectural bet that separates a clever hack from a genuinely useful tool. The project has since evolved into GSD Pi under the Open GSD organization[2], having outgrown its original home at gsd-build/gsd-2 where it accumulated over 7,100 stars[1]. What makes this project particularly interesting isn’t just its methodology — it’s the architectural decision to treat specifications as executable artifacts rather than static documents. The framework provides a structured approach to context engineering and meta-prompting, essentially giving teams a shared vocabulary for describing what software should do before anyone writes a line of code. The move to a new repository signals that this isn’t a dead project; it’s one that outgrew its original home and needed room to expand its scope beyond what the v2.x line could accommodate.

What It’s For

GSD 2 is for developers who want to hand off a complex, multi-step development task to an AI agent and walk away with reasonable confidence it won’t go off the rails. The sweet spot is anything that involves a sequence of dependent operations — refactoring a module, implementing a feature across multiple files, running tests, fixing failures, and committing clean history — where the alternative would be sitting at the terminal feeding context to a chat interface for an hour. The project’s focus on “spec-driven development” means it works best when you can articulate what you want upfront in a structured specification, then let the agent execute. This makes it a poor fit for open-ended exploration or vague requirements; if you don’t know what you want, you’re better off in an interactive loop. Compared to alternatives like Claude Code’s built-in workflows or aider’s architect mode, GSD 2’s advantage is its explicit state management — DB-backed runtime coordination, worktree isolation, and crash recovery mean it’s designed for unattended operation rather than assisted pair programming. The tradeoff is complexity: the CLI surface is substantial, and the DB-backed architecture means there’s more to understand before you can debug issues. Teams already practicing test-driven development will find familiar patterns here, though GSD 2 extends the concept upstream, addressing specification before tests rather than tests before code. The framework fills a specific niche: it’s not a project management tool like Jira, nor a coding standard like ESLint, but something in between — a structured methodology for translating intent into executable specifications.

How to Use It

The core workflow revolves around writing a specification file and dispatching GSD to execute it autonomously. You define a milestone — a named unit of work with acceptance criteria — and GSD handles the rest: parsing the spec, planning the implementation, executing changes across files, running verification, and committing results. The recent v2.79 release[2] shifted runtime state into a SQLite database (gsd.db), replacing ad-hoc lock files and JSON state dumps. This means concurrent milestones in separate git worktrees no longer risk state corruption — each worktree gets its own DB connection and metrics ledger. The gsd headless recover command addresses a real pain point: when an automated run wedges in a CI environment where there’s no terminal to interact with, you can recover state programmatically. The gsd doctor command now surfaces DB-backed stale locks and exhausted retry counters, which is the kind of operational insight you need when things go wrong in production but rarely get in CLI tools aimed at interactive use. Teams coming from the repository will find the original documentation still available, though active development has shifted to the GSD Pi repository[2] where the specification format has been refined based on community feedback from the v2.x releases.

Install the GSD CLI globally from npm

npm install -g gsd-pi@latest

Clone the active repository where GSD development continues beyond the v2.x line

git clone https://github.com/open-gsd/gsd-pi

Recover a stuck milestone in non-TTY environments like CI

gsd headless recover

Diagnose stale locks and exhausted retry counters

gsd doctor

Recent Updates

Latest Release: v3.0.0 (N/A)

Major version bump coinciding with the migration to the Open GSD organization and rebranding to GSD Pi

The project is in an aggressive development cycle — five releases from v2.77 through v2.80 in rapid succession, with v2.79 through v2.82 releases suggesting active development leading up to the v3.0.0 migration. The focus on migrating state from files to a database suggests the team is prioritizing reliability for unattended operation, which aligns with the project’s stated goal of one-command autonomous execution. The worktree isolation work indicates real-world use cases involving concurrent milestone execution, possibly in CI/CD pipelines. The repository has been archived with a clear redirect to the new home, indicating the maintainers prioritized a clean transition over maintaining backward compatibility in the old location.

Sources & Attributions

[1] 7,183 stars as of repository archival — gsd-build/gsd-2 [2] Active development continues at open-gsd/gsd-pi — https://github.com/open-gsd/gsd-pi