# GSD: context-engineered phases for solo builders

URL: https://developertoolkit.ai/en/ecosystem/frameworks/gsd/
Description: Run GSD Core's discuss, plan, execute, verify and ship loop on one project in Claude Code, Codex or Cursor, and see what it automates and costs in tokens.

GSD Core, formerly Get Shit Done, is an open-source framework that drives Claude Code, Codex or Cursor through a discuss, plan, execute, verify and ship loop for each roadmap phase. Research, planning and coding run in fresh subagents while state lives in `.planning/`. As a Claude Code plugin it adds about 10,700 always-on tokens per session.

You are building a side product alone. The first evening with the agent goes well; by the third, the session has compacted twice, the agent has forgotten why you chose SQLite, and a "finished" endpoint turns out to be a stub. You do not have a reviewer, and you do not want to read 4,000 lines of generated code to find out what works.

This page runs one real project through GSD, shows which files and gates prove each phase works, and says what the framework costs.

**Versions on this page**

Checked on 2026-09-26 against `@opengsd/gsd-core` **1.14.0** (npm, published 2026-09-14) and **1.15.0** (published 2026-09-26), Claude Code 2.1.283 and codex-cli 0.157.1. Popularity: 9.9k GitHub stars on [open-gsd/gsd-core](https://github.com/open-gsd/gsd-core); the archived original, gsd-build/get-shit-done, shows 64.5k. Both read 2026-09-26. Stars measure attention, not usage.

## What you get from running GSD on one project

- A working install for Claude Code, Codex or Cursor, and the command spelling each one uses.
- One uptime monitor taken from a one-page brief to an open pull request, with the file each step writes, so you check a 40-line plan instead of a 400-line diff.
- Three copy-paste prompts, the verification layers GSD runs, and a CI job that makes the pull request prove itself.
- The token bill, and the five settings that change it.

## How does the GSD phase loop work?

GSD's premise is that a long session degrades as its context fills (*context rot*), so the main session only orchestrates. Each heavy job goes to a subagent that starts with a clean context, writes its result to a file in `.planning/`, and exits. The next subagent reads the file, not the conversation. For the underlying mechanics, see [how context windows fill and degrade](/en/workflows/context/context-windows/).

Each roadmap phase goes through the same five steps:

| Step | Command (Claude Code) | What runs | File it writes | Your job |
| ---- | --------------------- | --------- | -------------- | -------- |
| Discuss | `/gsd-discuss-phase 1` | Adaptive questions about *how* to build the phase | `01-CONTEXT.md`, `01-DISCUSSION-LOG.md` | Answer. Every answer becomes an input to the planner |
| Plan | `/gsd-plan-phase 1` | Optional researcher, then a planner, then a plan-checker loop | `01-RESEARCH.md`, `01-01-PLAN.md`…, `01-VALIDATION.md` | Read the plans, not the code |
| Execute | `/gsd-execute-phase 1` | Executor subagents in parallel waves, one per plan, each committing its work; then a verifier | `01-01-SUMMARY.md`…, `01-VERIFICATION.md` | Nothing, unless a checkpoint asks |
| Verify | `/gsd-verify-work 1` | A walkthrough of the user-visible deliverables, one checkpoint at a time | `01-UAT.md`, fix plans if anything fails | Try each behaviour; type `pass` or describe what is wrong |
| Ship | `/gsd-ship 1` | Preflight gates, push, `gh pr create` with a body built from the artifacts | The pull request | Merge when CI is green |

In Codex type `$gsd-discuss-phase 1` and so on; with the plugin, `/gsd-core:discuss-phase 1`.

After the first phase of the project in the next section, `.planning/` looks like this:

- .planning/
  - PROJECT.md what you are building and why
  - REQUIREMENTS.md one ID per capability, for example CHK-01
  - ROADMAP.md phases, each with a goal and success criteria
  - STATE.md where you are; survives /clear and a closed laptop
  - config.json mode, model profile, gates
  - research/
  - phases/
    - 01-check-runner/
      - 01-CONTEXT.md your decisions from discuss
      - 01-RESEARCH.md
      - 01-01-PLAN.md a task with a verify command and a done condition
      - 01-02-PLAN.md
      - 01-01-SUMMARY.md what the executor built and committed
      - 01-02-SUMMARY.md
      - 01-VERIFICATION.md requirement coverage from the verifier
      - 01-UAT.md your walkthrough results
      - 01-SECURITY.md written by /gsd-secure-phase

The files are the point: small, committed by default (`planning.commit_docs: true`), and each answers a question you would otherwise answer by reading code.

## Install GSD Core for Claude Code, Codex or Cursor

The npm package is `@opengsd/gsd-core`. Versions 1.14.0 and 1.15.0 declare Node.js 24 or later and npm 10 or later in their `engines` field. Ship also needs the GitHub CLI (`gh`), authenticated.

1. Run the installer from your project directory (terminal). With no flags it asks for the runtime and the scope:

   ```bash
   npx @opengsd/gsd-core@latest
   ```

   Or name them directly:

     **Claude Code**

       ```bash
       npx @opengsd/gsd-core@latest --claude --local    # this project only, in ./.claude/
       npx @opengsd/gsd-core@latest --claude --global   # every project, in ~/.claude/
       ```

       Restart Claude Code. Commands appear as `/gsd-new-project`, `/gsd-plan-phase` and so on. The installer also changes your `settings.json`:

       - **Hooks:** an update check, `PreToolUse` guards (prompt injection, secret-file reads, destructive writes and more) and a context monitor.
       - **Allow rules** for `Bash(npx gsd-core *)` and for `Read` and `Edit` on `.planning/*`.
       - **Removed deny rules:** it deletes the exact rules `Read(.env)`, `Read(.env.*)` and `Read(.secrets)`, even ones you wrote, because its secret-read hook replaces them. Re-add them if other tools rely on them.

       The alternative is the native plugin:

       ```text
       /plugin marketplace add open-gsd/gsd-core
       /plugin install gsd-core@gsd-core
       ```

       Plugin commands are namespaced `/gsd-core:plan-phase`, and the plugin still needs the `gsd-tools` binary from the npm package on your `PATH`. Use one path, not both.

     **Codex**

       ```bash
       npx @opengsd/gsd-core@latest --codex --global
       ```

       In a 1.15.0 test install, 72 skills landed in `~/.agents/skills/gsd-*/` (not `~/.codex/skills/`, as GSD's install guide still says) and 64 agent roles in `~/.codex/agents/`, and the installer set `hooks = true` under `[features]`. Restart Codex, then type `$gsd-new-project`, `$gsd-plan-phase 1` and so on. GSD's install guide names Codex CLI 0.130.0 as the minimum. On Codex, GSD registers only an update-check hook, so its context warnings do not fire. Codex (0.157.1) runs a hook only after you trust it, so approve the GSD hook when Codex asks.

     **Cursor**

       ```bash
       npx @opengsd/gsd-core@latest --cursor --global
       ```

       The installer writes skills to `~/.cursor/skills/gsd-*/`, with agents beside them. Restart Cursor and type `/` in the agent chat; pick whatever `gsd-help` entry the menu shows. Cursor's skills docs (checked 2026-10-12) list `~/.cursor/skills/` as a personal skills location; this page did not verify how Cursor lists the `gsd-*` skills.

2. Check that the commands resolved. In the agent, run the help command (`/gsd-help` in Claude Code, `$gsd-help` in Codex, the `gsd-help` entry in Cursor's `/` menu). If it is missing, see the recovery table at the end of this page.

3. Decide your permission posture before the first execute. GSD's allow rules cover its own files, but executor subagents also run `git add`, `git commit` and your tests. With Claude Code v2.1.283 or later (both release channels on 2026-10-12), interactive sessions start in auto mode on supported models unless your settings disable it. In Manual mode, add allow rules such as `Bash(git add *)` and `Bash(git commit *)` to `.claude/settings.local.json` instead of the `--dangerously-skip-permissions` flag GSD's user guide suggests. See [permissions and sandboxing for agents](/en/workflows/harness/permissions-and-sandboxing/).

**GSD traps from old tutorials (checked against 1.14.0 and 1.15.0)**

- `npx get-shit-done-cc` installs a package npm marks "Package no longer supported" (last version 1.42.3). The original repository was archived on 2026-06-26. npm `get-shit-done` and `gsd` are unrelated packages. Use `@opengsd/gsd-core`.
- "GSD 2" moved too: the standalone agent is `@opengsd/gsd-pi` (1.20.1), not `gsd-pi`, which is deprecated.
- The command spelling depends on the install path: `/gsd-plan-phase` (npm installer, Claude Code), `/gsd-core:plan-phase` (plugin), `$gsd-plan-phase` (Codex). GSD's own workflow messages still print the older `/gsd:plan-phase` form. Type whatever your `/` menu shows.
- GSD Core is a community fork, announced after no contact with the original maintainer since 2026-04-01. Pin the version (`@opengsd/gsd-core@1.15.0`) and read the release notes before upgrading.
- `--config-dir` does not contain a Codex install: the skills still go to `~/.agents/skills/` and the runtime defaults to `~/.gsd/`. Test GSD in a throwaway user account or container instead.

## Run one project through GSD, phase by phase

The project is **pingboard**, a self-hosted uptime monitor: a Fastify API in TypeScript that checks URLs on a schedule, stores results in SQLite, and alerts by email when a check fails twice in a row. Three phases: the check runner and storage, the HTTP API, then alerting. This section takes phase 1 all the way to a pull request.

1. Write the brief GSD will ingest. `/gsd-new-project --auto @file.md` extracts the project from a document instead of interviewing you. Have the agent draft it, then edit it yourself: every later subagent inherits it.

   **Copy-paste prompt: a brief GSD can turn into a roadmap**

   ```text
   Write docs/prd.md for a project called pingboard. Keep it under 80 lines.

   Product: a self-hosted uptime monitor for one developer. Fastify 5 API in
   TypeScript, SQLite through better-sqlite3, Vitest for tests, Node 24.

   Sections, in this order:
   1. Problem: two sentences.
   2. Users: one persona.
   3. Requirements: numbered, each one observable from outside the process
      (an HTTP response, a row in the database, an email sent). Give each an ID
      with a CHK-, API- or ALR- prefix.
   4. Out of scope: at least five items (auth, multi-user, dashboards, SMS,
      distributed checks).
   5. Constraints: no external services except SMTP; every check result is
      persisted; a failing check alerts only after two consecutive failures.
   6. Suggested phases: check runner and storage, HTTP API, alerting.

   Do not write code. Do not invent requirements I did not ask for; list open
   questions at the end instead.
   ```

2. Create the project (agent prompt):

   ```text
   /gsd-new-project --auto @docs/prd.md
   ```

   After a few config questions, `--auto` runs research, requirements and the roadmap without stopping. Because nothing pauses for your approval, open `ROADMAP.md` before you go on: each phase needs a goal and success criteria you can observe. Nobody can verify "the scheduler is robust"; the verifier and you can both verify "a check that times out after 5 s is stored with status `timeout`".

3. Clear the session and discuss phase 1:

   ```text
   /clear
   /gsd-discuss-phase 1
   ```

   GSD asks about implementation choices: interval granularity, what counts as a failure, how to store timings. Answer concretely; `--assumptions` lists what the agent would assume instead, a fast way to find the questions that matter. Answers land in `01-CONTEXT.md`.

4. Plan phase 1 with a failing test per behaviour:

   ```text
   /gsd-plan-phase 1 --tdd
   ```

   A planner turns `01-CONTEXT.md` into small plans, and a plan-checker loops with it until each plan meets the goal. `--tdd` makes each behaviour-adding task start with a failing test; `--skip-research` saves a researcher on a familiar stack.

5. Review the plans before anything runs. Each `PLAN.md` holds tasks with the files they touch, action steps, a `<verify>` command and a done condition. This is the cheapest place to catch a wrong decision.

   **Copy-paste prompt: review a GSD plan before execution**

   ```text
   Read .planning/ROADMAP.md, .planning/phases/01-check-runner/01-CONTEXT.md
   and every 01-*-PLAN.md in that folder. Do not change any file.

   Report, as a table with one row per task:
   - the requirement ID it serves (flag any task that serves none)
   - its <verify> command, and whether that command can fail if the task
     is done wrong (flag any verify that only checks a file exists or that
     the build passes)
   - any decision in 01-CONTEXT.md the task contradicts

   Then list every requirement mapped to phase 1 that no task covers.
   End with GO or NO-GO and one sentence of reasoning.
   ```

   On NO-GO, fix `01-CONTEXT.md` or re-run `/gsd-plan-phase 1` with the gap named in your prompt. Do not hand-edit the plans and hope the executor agrees.

6. Execute:

   ```text
   /clear
   /gsd-execute-phase 1
   ```

   Independent plans run in parallel waves (up to 3 executors by default), each in a fresh context, each task committed on its own. A verifier then checks the code against the phase's requirements and writes `01-VERIFICATION.md`. A checkpoint stops the run only for a human decision, such as an irreversible schema change.

7. Walk the deliverables:

   ```text
   /gsd-verify-work 1
   ```

   GSD turns each `SUMMARY.md` into user-visible checks, one at a time: "Adding `https://example.com` with a 30 s interval stores a result row within 35 s." Type `pass` or describe what is wrong. On a failure it writes fix plans for `/gsd-execute-phase 1 --gaps-only`.

8. Close the security gate and ship:

   ```text
   /gsd-secure-phase 1
   /gsd-ship 1
   ```

   Ship runs its gates (verification `passed`, zero open threats, a clean tree; see the next section), then pushes and opens a pull request built from the phase artifacts.

Repeat steps 3 to 8 for phases 2 and 3; `/gsd-progress` tells you where you are. For an existing codebase, start with `/gsd-onboard`. For a one-off change, `/gsd-quick "fix the timeout parsing"` keeps atomic commits and state but skips the optional agents.

## How do you know a GSD phase actually works?

GSD automates roadmap, planning, execution, requirement coverage and the pull request. Your share is judgement: observable criteria, reading plans, UAT and merging. It stacks five checks, none of which requires you to read the diff:

1. **Plan-checker.** Every plan is checked against the phase goal before execution; do not turn it off with `--skip-verify`.
2. **Per-task verify commands.** Each task's `<verify>` command runs after the executor writes the code. With `--tdd`, the first run is red by design.
3. **Verifier.** `01-VERIFICATION.md` maps every requirement in the phase to evidence. The verifier fingerprints the files its verdict covered, so editing one afterwards marks the result `stale`.
4. **UAT.** `/gsd-verify-work` is the one check that needs you: you exercise the behaviour and GSD records the result in `01-UAT.md`.
5. **Ship gates.** In 1.14.0 and 1.15.0, verification must be `passed` (not `stale`), and with the default `workflow.security_enforcement: true` the phase's `SECURITY.md` must report `threats_open: 0`. The working tree must be clean.

All five run inside the agent that wrote the code. Add one that does not: CI on the pull request, from a clean checkout, with no secrets and read-only access:

```yaml
# .github/workflows/pr-gate.yml
name: pr-gate
on: pull_request
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npx tsc --noEmit
      - run: npx vitest run
```

GitHub runs this workflow from the pull request's merge ref, so an agent's pull request can edit it or the tests it runs; put `.github/` under `CODEOWNERS` with required review so such an edit cannot merge unnoticed. For more independence, `/gsd-code-review 1 --depth=deep` reviews the phase's changed files before UAT, and [an agent review on the pull request](/en/workflows/ship/agent-pr-review/) adds a second model's view. Sign-off stays with you. On a team, the pull request body GSD writes is a ready-made [evidence bundle](/en/workflows/ship/evidence-bundle/) for the reviewer.

**Copy-paste prompt: check the evidence before you ship a phase**

```text
Phase 1 of this project is about to ship. Do not change any file.

1. Read .planning/REQUIREMENTS.md and list every requirement mapped to
   phase 1 in ROADMAP.md.
2. For each one, find the test that proves it (file and test name). Run
   `npx vitest run` and report whether that test passed.
3. Compare with .planning/phases/01-check-runner/01-VERIFICATION.md and
   01-UAT.md. Flag any requirement that VERIFICATION.md marks as covered
   but has no automated test, and any UAT item recorded as pass that
   contradicts a failing test.
4. Report requirements with no evidence at all.

Answer with a table, then SHIP or HOLD.
```

## What does GSD cost in tokens?

GSD spends context in three places, and each needs a different fix.

**Always-on cost.** On Claude Code 2.1.283, `claude plugin details gsd-core@gsd-core` projects about **10,700 tokens** in every session: 144 skills, 64 agents and 7 hooks, measured on plugin 1.14.0. Superpowers projects about 838 and Everything Claude Code about 41,515. Much of it is duplication: the plugin ships both `plan-phase` and `gsd-plan-phase`, while the npm installer writes one form of each (72 skills). Measure your own install:

```bash
claude plugin details gsd-core@gsd-core   # terminal, plugin path only
```

On the npm path, run `/gsd-surface status` (enabled skills with a token summary) or compare `/context` in a fresh session before and after installing. codex-cli 0.157.1 has no equivalent of `details` (`codex plugin` offers only `add`, `list`, `marketplace` and `remove`); compare the context meter there.

To cut the listing without losing the loop, switch off skill clusters you do not use, for example `/gsd-surface disable ui` or `/gsd-surface disable ai_eval`; it re-stages the skills in place, with no reinstall. The installer's `--minimal` flag is the bigger cut (its help text estimates about 700 tokens instead of about 12,000), but in 1.14.0 and 1.15.0 neither the `core` nor the `standard` profile includes `ship` or `secure-phase`, so step 8 of this walkthrough disappears with it.

**Per-invocation cost.** A skill's body is small (about 1.8k tokens for `gsd-plan-phase`), but it `@`-includes a workflow file into your main session: about 96 KB for `workflows/plan-phase.md` and 91 KB for `execute-phase.md` in 1.15.0. Hence the `/clear` between steps.

**Per-phase cost.** Every step spawns subagents (researcher, planner, plan-checker, one executor per plan, verifier, debuggers), each starting from an agent definition of about 47 KB in 1.15.0 plus the `.planning/` files it reads; plan and execute declare `effort: max` in Claude Code. The default `balanced` profile puts the planner on `opus` and most agents on `sonnet`, which Claude Code resolves to the models on the [models hub](/en/ecosystem/models/); the other tiers are in GSD's `gsd-core/references/model-profiles.md`. On Codex, the 1.15.0 agent `.toml` files pin no model, so they run on your session's model unless you set GSD's `model_overrides`.

The settings that change the bill, in the order to try them:

| Lever | Command | What you give up |
| ----- | ------- | ---------------- |
| Disable unused skill clusters | `/gsd-surface disable ui` | Commands you would not have used on this project |
| Skip research on familiar stacks | `/gsd-plan-phase 1 --skip-research`, or `workflow.research: false` | Library and pattern research before planning |
| Cheaper model profile | `/gsd-config --profile budget` | Planner and checker quality on hard phases |
| Coarser plans | `/gsd-plan-phase 1 --granularity coarse` | Fewer, larger plans; more risk of stubs |
| Use `/gsd-quick` for small fixes | `/gsd-quick "…"` | The full discuss, plan and verify loop |

Measure the real spend with `/usage` after a phase (Claude Code and Codex both have it), and track it per phase over a milestone with the approach in [agent cost tracking](/en/ecosystem/observability/agent-cost-tracking/).

## Should you let /gsd-autonomous run the remaining phases?

`/gsd-autonomous` runs discuss, plan and execute for every remaining phase without stopping, and `--from`, `--to` and `--only` bound the range. It runs the verifier, but when a phase needs human verification it records `verification_deferred_human` in `STATE.md` and moves on. So an overnight run ends with code that passed automated checks and a list of `/gsd-verify-work` sessions you still owe.

Run it only when the success criteria are observable, your tests fail on wrong behaviour (see [oracle strength](/en/workflows/test/oracle-strength/)), and the agent runs in a disposable environment with no production credentials. `--no-reversibility-gates` on plan-phase removes the human checkpoint before irreversible decisions; do not combine it with an unattended run on anything that holds real data. For single-goal runs without GSD's ceremony, the built-in [`/goal` command](/en/workflows/automate/goal-command/) is lighter, and [hours of autonomy](/en/ecosystem/frameworks/autonomous-loops/) compares GSD with Ralph loops.

## When is GSD the wrong choice?

| Your situation | Better fit | Why |
| -------------- | ---------- | --- |
| A one-evening feature in an existing repo | [Superpowers](/en/ecosystem/frameworks/superpowers/) or plain plan mode | GSD's roadmap and phase files cost more than the feature |
| A team that reviews specs, not plans | [Spec Kit](/en/ecosystem/frameworks/spec-kit/) | Its artifacts are feature specs a team can review; GSD's are one builder's plans |
| Brownfield changes that must leave a living spec | [OpenSpec](/en/ecosystem/frameworks/openspec/) | OpenSpec merges each change into a current spec; GSD archives phases |
| One well-defined goal with a strong test oracle | `/goal` | One command, no framework, no 10,700-token listing |
| An organisation that needs a supplier review | Wait, or pin and audit | GSD Core is a community fork after a governance incident |
| A multi-phase greenfield build by one person | GSD | Durable state, fresh contexts and verification gates are what it was built for |

The [frameworks comparison](/en/ecosystem/frameworks/) puts GSD next to every other framework on ceremony, artifacts and context cost.

## What breaks when you run GSD, and how do you recover?

| Symptom | Cause | Recovery |
| ------- | ----- | -------- |
| `/gsd-*` commands missing after install | The agent was not restarted, or you installed the plugin and typed the npm spelling | Restart; check the `/` menu for `/gsd-`, `/gsd-core:` or `$gsd-` |
| Plugin commands run but fail on their backing logic | `gsd-tools` is not on `PATH`, or `node` is not available to the hooks | Install the npm package as well, and confirm `node --version` works in the agent's shell |
| An executor stops with "Permission denied" on Bash | Manual mode with no allow rules for git and your test runner | Add allow rules for `git add`, `git commit` and your test command to `.claude/settings.local.json` |
| Execution produces stubs or half-built files | Plans too large for one executor | Re-plan with `--granularity fine`; GSD's guidance is two or three tasks per plan |
| The main session gets slow and forgetful | The orchestrating session itself filled up | `/gsd-health --context` (warns from 60% and suggests `/gsd-thread`), or `/clear` then `/gsd-resume-work` |
| "FATAL: worktree base mismatch — HEAD is …, expected …" | Your branch is ahead of the default branch, and executor worktrees fork from `origin/HEAD` | GSD falls back to sequential execution on its own; see its worktree base-mismatch guide to restore parallel runs |
| Codex agents fail on an unknown model | Agent `.toml` files from an older install pin an Anthropic alias such as `sonnet` | Reinstall with `--codex --global`, which writes the files without a model pin; `gsd-tools validate agents` flags any pin left behind |
| `/gsd-ship` blocks with `PHASE_VERIFICATION_INCOMPLETE` | Verification is stale, failed or deferred | `/gsd-verify-work 1`, then ship again |
| `/gsd-ship` blocks with `SECURITY_SHIP_GATE_NO_REVIEW` | No phase `SECURITY.md` | `/gsd-secure-phase 1`, resolve open threats, ship again |

A subagent can report failure even though its commits landed. Check `git log --oneline -10` before you re-run anything: the commits are the ground truth.

## Where to go next with GSD

- [Agentic development frameworks compared](/en/ecosystem/frameworks/) — GSD next to Superpowers, Spec Kit, OpenSpec and the rest, with context costs.
- [Hours of autonomy](/en/ecosystem/frameworks/autonomous-loops/) — GSD Core, Ralph loops, /goal and oh-my-claudecode for long unattended runs.
- [Executable acceptance criteria](/en/workflows/plan/acceptance-criteria/) — Write success criteria the verifier and your tests can actually check.
- [Oracle strength](/en/workflows/test/oracle-strength/) — Make sure the tests GSD's executors run can fail on wrong behaviour.
- [Evidence, not diffs](/en/ladder/evidence-not-diffs/) — Why you check plans, verification files and UAT instead of reading every line.
- [Everything Claude Code](/en/ecosystem/frameworks/everything-claude-code/) — Measuring and pruning a framework's context cost.
