# gstack: a role-based skill stack for Claude Code

URL: https://developertoolkit.ai/en/ecosystem/frameworks/gstack/
Description: Run gstack's product, eng-manager, reviewer, QA and release skills on one feature, and map each role's output onto the artifact chain.

gstack is Garry Tan's MIT-licensed set of Claude Code skills that splits feature work into roles invoked as slash commands: `/office-hours` and `/plan-ceo-review` for product, `/plan-eng-review` for the engineering manager, `/review` for a staff engineer, `/qa` for QA, and `/ship` for release. The same skills also install into Codex and Cursor. Its planning documents live outside your repository by default.

You open Claude Code with a one-line ticket, "Add CSV export to invoices", and get back a working button in 10 minutes. Then the questions start. Which date range does the export use? What happens with 80,000 rows? Did anyone check the timezone of `issued_at`? Nobody asked, because a blank prompt plays no roles: no product owner, no tech lead, no QA.

This page is for the developer who wants those roles played every time without hiring them or reading every generated line. It runs one feature through gstack from idea to pull request, shows the file each role leaves behind, and marks where you still have to step in.

**Versions on this page**

gstack is MIT-licensed and maintained by Garry Tan. Checked on 2026-09-26 against gstack **1.91.2.0** (`VERSION` file; CHANGELOG entry dated 2026-09-25): the README, `docs/skills.md`, the `setup` script, and the `office-hours`, `plan-eng-review`, `review`, `qa` and `ship` skill files on the `main` branch. Claude Code facts are for v2.1.283 (`latest` channel), Codex facts for codex-cli 0.157.1. Popularity: 134.2k GitHub stars and 20.0k forks on [garrytan/gstack](https://github.com/garrytan/gstack), read from the GitHub API on 2026-09-26 for the frameworks research dossier. Stars measure attention, not usage, and gstack publishes no install count.

## What running one feature through gstack gives you

- A working install for Claude Code, Codex or Cursor, and the one setup flag that avoids a command-name collision.
- One feature, CSV export for an invoicing app, taken from idea to an open pull request in seven commands.
- A table that maps each gstack role onto the [artifact chain](/en/method/lifecycle/artifact-chain/), including the two links gstack does not produce at all.
- Four copy-paste prompts: a scoped `/office-hours` opener, a constrained engineering review, promoting gstack's private notes into committed files, and a pre-ship evidence check.
- The gates that prove the result without you reading the diff, and the traps that old tutorials miss.

## Which roles does gstack give you?

gstack presents its skills as specialists who run in sprint order: Think, Plan, Build, Review, Test, Ship, Reflect. Each skill reads what the previous one wrote. The README lists more than 30 commands; these nine carry a normal feature:

| Role | Command | What it does | What it leaves behind |
| ---- | ------- | ------------ | --------------------- |
| Product partner | `/office-hours` | Asks forcing questions about the problem, challenges your premises, and proposes two or three approaches with effort estimates | A design doc in `~/.gstack/projects/<repo>/` |
| Founder or CEO | `/plan-ceo-review` | Reviews scope in one of four modes: expansion, selective expansion, hold scope, or reduction | Scope decisions in `~/.gstack/projects/` |
| Engineering manager | `/plan-eng-review` | Locks architecture, data flow, failure modes, and the test matrix, with diagrams | A reviewed plan and a test plan in `~/.gstack/projects/` |
| Review pipeline | `/autoplan` | Runs the CEO, design, developer-experience, and engineering reviews in sequence, and asks you only about taste decisions | The same files, with fewer questions |
| Staff engineer | `/review` | Hunts for bugs that pass CI: N+1 queries, races, trust boundaries, missing enum branches. Fixes the obvious ones and asks about the rest | In-place fixes (listed as `[AUTO-FIXED]` lines) and a review record |
| QA lead | `/qa` | Reads the diff, opens the affected pages in a real browser, fixes what breaks, and writes a regression test per fix | A report in `.gstack/qa-reports/` and new tests |
| Release engineer | `/ship` | Syncs the main branch, runs tests, audits coverage, updates docs, pushes, and opens the PR | The pull request with a coverage summary |
| Debugger | `/investigate` | Root-cause debugging that stops after three failed fixes | Findings in the session |
| Engineering manager | `/retro` | Weekly retrospective from commit history, with test-ratio trends | A JSON snapshot in `.context/retros/` |

Only one of these is a hard gate by default: the engineering review. gstack's Review Readiness Dashboard marks it **Required**; the CEO and design reviews are informational.

## Install gstack for Claude Code, Codex or Cursor

gstack needs Git and [Bun](https://bun.sh/) 1.0 or later, plus Node.js on Windows. It is a Git repository with a `setup` script, not a plugin marketplace, so `/plugin marketplace add garrytan/gstack` installs nothing.

1. Clone and run setup for your agent (terminal):

     **Claude Code**

       ```bash
       git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
       cd ~/.claude/skills/gstack && ./setup --prefix
       ```

       `--prefix` installs every skill as `/gstack-<name>` (`/gstack-review`, `/gstack-qa`). The default is short names (`/review`, `/qa`), and on Claude Code 2.1.283 `/review` is already the alias of the bundled `/code-review`. With the prefix you always know which reviewer you invoked. Switch back later with `./setup --no-prefix`. The rest of this page uses the short names for readability; add `gstack-` if you installed with the prefix.

       Restart Claude Code. The skills are user-level, so they appear in every project.

     **Codex**

       ```bash
       git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
       cd ~/gstack && ./setup --host codex
       ```

       Setup generates Codex-format skills into `${CODEX_HOME:-~/.codex}/skills/gstack-*/`. Restart Codex, then mention a skill with `$`, for example `$gstack-office-hours`, or pick it from `/skills`. The `/codex` second-opinion skill does not exist on Codex; the counterpart is `gstack-claude-code`, which needs Claude Code installed and signed in. If Codex prints "Skipped loading skill(s) due to invalid SKILL.md", the generated descriptions are stale: run `cd ~/gstack && git pull && ./setup --host codex`.

     **Cursor**

       ```bash
       git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
       cd ~/gstack && ./setup --host cursor
       ```

       Setup writes the skills to `~/.cursor/skills/gstack-*/`. Cursor's skills docs (checked 2026-10-12) list `~/.cursor/skills/` as a personal skills location; this page did not verify how Cursor lists and triggers them, so ask the agent for a skill by name ("use the gstack-qa skill") if it does not appear in the menu.

2. Decide on the hooks before your first session. Setup writes hooks into `~/.claude/settings.json`: a default-on `Stop` hook that closes session-timeline entries, `AskUserQuestion` hooks only if you accept them when setup asks, and a `SessionStart` auto-update check in team mode. Hooks run outside the permission prompt. To skip the timeline hook, rerun with `./setup --no-timeline-stop-hook`; to see what is registered, run `~/.claude/skills/gstack/bin/gstack-settings-hook list-sources`. On first use gstack also asks about telemetry, which stays off unless you say yes.

3. Measure what gstack adds to every session. The skill descriptions load at startup; the skill bodies load when you call them. gstack ships an offline estimator (terminal):

   ```bash
   ~/.claude/skills/gstack/bin/gstack-context-bill ~/.claude/skills
   ```

   It prints the always-on cost and the per-invocation cost of each skill. Compare `/context` in a fresh session before and after install. On 1.91.2.0 the `office-hours`, `review` and `ship` skill files are each 70–85 KB, so a single invocation is a large prompt. For scale: run against the 1.91.2.0 source tree on 2026-09-26, the estimator reported 63 skills with about 25.7 KB of frontmatter, roughly 6.6k tokens always on (offline estimate; `--exact` needs an Anthropic API key). Your installed figure depends on which hosts and skills setup linked. `claude plugin details` does not apply, because gstack installs as skills, not as a plugin.

For the general mechanics of skill folders and scopes, see [installing and managing skills](/en/ecosystem/skills/installing-managing/).

## Run one feature through gstack, role by role

The project is an invoicing app on Next.js App Router with Postgres through Prisma, unit tests in Vitest and browser tests in Playwright. The ticket: finance wants a CSV export of invoices for a date range. Work on a feature branch; `/qa` and `/review` compare against the main branch.

1. **Think: `/office-hours`.** Start with the problem, not the button. `/office-hours` has two modes. Startup mode, meant for founders and intrapreneurs, asks six forcing questions about demand, the status quo, and the narrowest wedge. Builder mode, meant for side projects and hackathons, is generative rather than interrogative. For a feature that paying customers asked for, ask for startup mode: its questions are the ones that test whether "a CSV export" is the real need. It pushes back on your framing, lists premises for you to accept or reject, and ends with a design doc that the later skills read.

   **Copy-paste prompt: open office hours on a real feature**

   ```text
   /office-hours
   Feature for our existing invoicing app (Next.js App Router, Prisma, Postgres).
   Finance exports invoices to reconcile them in their accounting tool every
   month. Today they copy rows by hand from the invoices table. They asked for
   "a CSV export". Constraints: accounts can have 80,000+ invoices a year,
   amounts are stored in minor units with a currency column, issued_at is UTC,
   and finance works in Europe/Warsaw. Use startup mode: I am the
   intrapreneur here. Challenge whether CSV is the real need before proposing
   approaches, and keep anything beyond invoice export out of scope.
   ```

   Accept the design doc only when it names the users, the outcome, and what is out of scope. You are the product owner here: this is the one step gstack cannot sign off for you.

2. **Plan: `/plan-eng-review`.** Switch Claude Code to plan mode (Shift+Tab, or `/plan`), let it draft the plan, then run the engineering review. In plan mode the skill reviews the active plan automatically and says so in one line. It forces the decisions a blank prompt skips: streaming against buffering, the timezone boundary, and what a partial failure does. It writes a test plan that `/qa` picks up later. Use `/autoplan` instead when you want the CEO, design, and engineering reviews in one pass and only the taste decisions surfaced.

   **Copy-paste prompt: an engineering review with hard limits**

   ```text
   /plan-eng-review
   Review the active plan for the invoice CSV export. Hold these as fixed:
   stream rows with a Prisma cursor instead of loading them into memory, cap an
   export at 12 months, convert date-range boundaries from Europe/Warsaw to UTC
   before querying, and format amounts from minor units per currency. I want a
   sequence diagram of the request, the failure modes (timeout mid-stream,
   client disconnect, empty range), and a test matrix that names the Vitest
   and Playwright test for each acceptance criterion.
   ```

3. **Build: exit plan mode and approve the plan.** Claude Code implements it. gstack adds no build role of its own here; the plan is the contract.

4. **Review: `/review`** (or `/gstack-review`). It applies mechanical fixes and lists each one as an `[AUTO-FIXED]` line, and asks about anything ambiguous, such as a race or a trust boundary. For a CSV export, the findings worth having are formula injection in cells that start with `=`, `+`, `-` or `@`, and a missing index on `(account_id, issued_at)`. If the review reports neither, ask about both by name. For a second model, `/codex` sends the same diff to Codex CLI if you have it installed and signed in.

5. **Test: `/qa http://localhost:3000/invoices`.** On a feature branch, `/qa` is diff-aware: it reads the branch diff, opens the affected pages in a browser (the Aside browser, if it is installed and open on macOS 15+, otherwise the Chromium that setup builds), exercises them, fixes what breaks, and writes a regression test for each fix. Use `/qa-only` when you want the report without code changes.

6. **Ship: `/ship`.** It syncs the main branch, runs your tests, builds a coverage map of the diff, writes tests for gaps, updates docs through `/document-release`, pushes, and opens the PR with a line such as `Tests: 42 → 47 (+5 new)`. Before it opens the PR, it checks the Review Readiness Dashboard. If the engineering review is missing it asks, but it does not block you.

7. **Reflect: `/retro`** at the end of the week. It reads commit history and flags a test ratio below 20%. Treat its numbers as signals for a conversation, not as a performance metric.

Deployment stays with your pipeline. gstack also has `/land-and-deploy` (merge, wait for CI and deploy, check production health) and `/canary` (post-deploy monitoring). If your team deploys only through CI, leave them out and let the PR merge trigger the pipeline.

## Where does each gstack role land on the artifact chain?

The [artifact chain](/en/method/lifecycle/artifact-chain/) asks for a committed file at each stage, accepted by a named person. gstack produces most of the content, but it stores the planning half in `~/.gstack/projects/` on your machine, not in the repository. Teammates, reviewers, and CI never see it unless you move it.

| Chain stage | Artifact | gstack role that produces it | Where gstack puts it | What you add |
| ----------- | -------- | ---------------------------- | -------------------- | ------------ |
| Plan | `intent.md` | `/office-hours`, `/plan-ceo-review` | Design doc in `~/.gstack/projects/` | Commit it; the product owner accepts it |
| Design | `spec.md` | `/plan-eng-review` (acceptance criteria, test matrix) | Test plan in `~/.gstack/projects/` | Commit it; turn every criterion into a named test |
| Build | `plan.md` and the diff | Claude Code's plan, reviewed by `/plan-eng-review` | Plan file, then commits | Commit the approved plan beside the change |
| Test | Test evidence | `/qa`, plus the coverage audit in `/ship` | `.gstack/qa-reports/`, new test files | CI must run the new tests; attach the report to the PR |
| Review | Review findings | `/review`, `/codex` | In-place fixes (listed as `[AUTO-FIXED]` lines) and a review record | A code owner reads the findings, not the whole diff |
| Maintain | Incident record, next intent | `/investigate`, `/retro`, `/canary` | Session output, `.context/retros/` | Write the incident record yourself |

The two links gstack does not produce at all are the committed intent/spec in the repository and the incident record; everything else needs only promoting.

**Copy-paste prompt: promote gstack's notes into committed artifacts**

```text
Find the most recent design doc and test plan that gstack wrote for this repo
under ~/.gstack/projects/ (the files matching *-design-*.md and
*-test-plan-*.md for the current branch). Copy them into
docs/features/invoice-export/ as intent.md and spec.md. In spec.md, rewrite
each acceptance criterion so it names the exact test file and test name that
proves it, and mark any criterion that has no test yet as MISSING. Do not
change the substance of either document. Show me the diff before committing.
```

## How do you prove the gstack output without reading every line?

gstack's claim is that the roles catch what you would otherwise catch by reading. Make each claim checkable:

- **Acceptance criteria as tests.** After promoting the test plan, every criterion names a test. `/ship` adds tests for coverage gaps, and `/qa` adds a regression test per bug it fixes. CI, not the agent, runs them. See [acceptance criteria that tests can check](/en/workflows/plan/acceptance-criteria/).
- **A gate that stops the turn.** gstack's opt-in `gstack-verify-gate` is a `Stop` hook that blocks Claude Code from ending a turn until your verify command passes. Declare the command in `CLAUDE.md`, trust it once per repository, then register the hook (terminal, from the repository root):

  ```bash
  echo '<!-- gstack:verify: npm test -->' >> CLAUDE.md
  ~/.claude/skills/gstack/bin/gstack-verify-gate --trust
  ~/.claude/skills/gstack/bin/gstack-settings-hook add-event --event Stop \
    --command ~/.claude/skills/gstack/bin/gstack-verify-gate --source verify-gate
  ```

  Editing the declared command cancels the trust until you run `--trust` again. After three blocked attempts it lets the turn end with a warning, so it does not loop forever.
- **Fresh reviews only.** gstack grades each diff review CURRENT, STALE, or UNVERIFIED against a fingerprint of the working tree. A review of code that changed afterwards does not count, and `/ship` reads the same grade.
- **Test evidence bound to the code it ran against.** `gstack-evidence run --label unit -- npx vitest run` wraps your test command, passes its exit code through, and records which working-tree fingerprint it ran on. Its `check` subcommand grades each label FRESH, STALE, or MISSING, and `/ship` cites fresh evidence instead of rerunning the suite. A green run on yesterday's code does not count.
- **Two models, one diff.** `/review` runs on Claude and `/codex` on Codex, so they can miss different things. Read a finding that both report first.
- **A named sign-off.** You accept the design doc and the reviewed plan. A code owner merges on green CI with the review findings resolved. The [evidence bundle](/en/workflows/ship/evidence-bundle/) page describes what that PR should carry.

**Copy-paste prompt: pre-ship evidence check**

```text
Before /ship: list every acceptance criterion in
docs/features/invoice-export/spec.md with the test that proves it and the
result of its last run in this branch. Then show the /review findings that are
still open and the path of the latest /qa report. If any criterion has no
passing test or any finding is open, stop and tell me which, instead of
shipping.
```

## What breaks when you adopt gstack?

**gstack traps (checked against 1.91.2.0 and Claude Code 2.1.283)**

- **`/review` means two things.** Claude Code's `/review` is an alias of its bundled `/code-review`, and gstack's short-name install claims the same name. Install with `./setup --prefix` and type `/gstack-review`.
- **It is not a plugin.** `/plugin marketplace add garrytan/gstack` yields nothing. Install with `git clone` and `./setup`.
- **The plan is off the record.** Design docs, CEO plans, and test plans live in `~/.gstack/projects/`. Copy them into the repository, or the next person has only the diff.
- **Hooks run code without asking.** Setup registers a `Stop` hook by default, plus `AskUserQuestion` hooks if you accept them and a `SessionStart` hook in team mode. Deleting the folder by hand leaves them behind, and they error on every event. Remove gstack with `~/.claude/skills/gstack/bin/gstack-uninstall`, and delete the `## gstack` and `## Skill routing` sections from each project's `CLAUDE.md` yourself: the uninstall script does not edit it.
- **`/freeze` is not a sandbox.** It blocks the Edit and Write tools outside one directory; a Bash `sed` still reaches everything. Use [permissions and sandboxing](/en/workflows/harness/permissions-and-sandboxing/) for real containment.
- **`/ship` may add CI.** In a repository without a test framework it installs one, writes tests, and creates a GitHub Actions workflow. Review that workflow's `permissions:` block before merging.
- **`/cso` can quietly skip.** Without its extra native toolchain it reports `not assessed` instead of failing.

| Symptom | Cause | Recovery |
| ------- | ----- | -------- |
| Skills do not appear in Claude Code | Setup did not finish, or the session predates it | `cd ~/.claude/skills/gstack && ./setup`, then restart. If they still do not appear, check that `~/.claude/skills/gstack-*` or `~/.claude/skills/<name>` links exist (`ls ~/.claude/skills`) and rerun `./setup`. If the links exist and Claude still says it cannot see the skills, add the README's `## gstack` section to the project's `CLAUDE.md`: it lists the skills so Claude routes to them, it does not register them |
| Setup ends with "Not registered (a skill you own already uses the name)" | You have your own `qa/` or `ship/` skill | Rename yours, or switch to `./setup --prefix` so the names stop colliding |
| `/qa` or `/browse` fails on Linux or Windows | The bundled Chromium did not install or cannot launch | `cd ~/.claude/skills/gstack && bun install && bun run build`. On Ubuntu 24.04+ with blocked user namespaces, set `GSTACK_CHROMIUM_NO_SANDBOX=1` |
| A teammate's session behaves differently after lunch | Team mode auto-updates gstack at session start, at most once per hour | For a shared repository, agree on who upgrades and when, read the CHANGELOG first, and run `/gstack-upgrade` deliberately |
| `/office-hours` turns a small feature into a product pitch | A vague opener leaves it free to hunt for a bigger product, and builder mode actively looks for the "whoa" version | Name the users, the constraint, and what is out of scope, as in the prompt above; then run `/plan-ceo-review` in hold-scope or reduction mode |

**Team mode runs upstream code in every session**

`./setup --team` with `gstack-team-init required` makes gstack mandatory for everyone who opens the repository, and each session checks for updates. That is convenient and also a supply-chain decision: every upstream commit reaches every developer's hooks. Read [skill security](/en/ecosystem/skills/skill-security/) before you turn it on, and prefer a reviewed upgrade cadence over silent updates.

## When is gstack the right framework?

Pick gstack when you want opinionated roles with a lot of built-in browser QA and release automation, and you mostly work in Claude Code. Prefer [Superpowers](/en/ecosystem/frameworks/superpowers/) when you want a smaller, test-driven discipline that fires on its own, and [GSD](/en/ecosystem/frameworks/gsd/) when your problem is context loss across a long multi-phase build. Two role packs at once give you two `/review` commands and two opinions about process, so pick one. The [frameworks comparison](/en/ecosystem/frameworks/) sets them side by side.

## Where to go next with gstack

- [The artifact chain](/en/method/lifecycle/artifact-chain/) — The committed files each gstack role should feed, and who accepts each one.
- [Discipline packs compared](/en/ecosystem/frameworks/discipline-packs/) — gstack beside Pocock's skills, addyosmani/agent-skills, Ponytail and Everything Claude Code.
- [Code review skills](/en/ecosystem/skills/code-review-skills/) — The built-in /code-review, review plugins, and how to avoid command collisions.
- [The evidence bundle](/en/workflows/ship/evidence-bundle/) — What a pull request should carry so a reviewer can trust it without reading every line.
