A software factory built entirely out of markdown files. One person describes a feature; a line of specialists talks it over, writes it, breaks it, fixes it, and ships it. This atlas walks one change from idea to production, then lists all 53 workers.
gstack is a set of 53 skills — markdown files an agent reads and follows — that turn one coding agent into a virtual engineering team. Each skill plays a role: a CEO who rethinks the product, an eng manager who locks architecture, a designer who catches slop, a staff engineer who finds the bug that passes CI, a QA lead who opens a real browser, a security officer, a release engineer. You call them as slash commands. There is no server, no account, no runtime beyond your agent — the only compiled thing in the repo is a headless-browser daemon, because giving the agent eyes was the one job markdown couldn't do.
The organising idea is that a sprint is a pipeline of artifacts: /office-hours writes a design doc that /plan-ceo-review reads; /plan-eng-review writes a test plan that /qa picks up; /review finds bugs that /ship checks are fixed. Files on disk are the handoff, so nothing is lost when the agent's context window resets.
| Shared term | gstack's word | Where it lives |
|---|---|---|
| skill | skill (same) | one directory per skill, each with a SKILL.md.tmpl |
| dispatcher | skill routing | a routing block written into your project's CLAUDE.md, plus per-skill trigger phrases |
| always-on | the preamble | scripts/resolvers/preamble.ts — baked into every skill at build time |
| filing gate | the Review Readiness Dashboard + the Verification Gate | scripts/resolvers/review.ts, ship/SKILL.md.tmpl |
| intake fan | the Review Army | scripts/resolvers/review-army.ts — one diff out to 7 specialists and back |
| self-repair loop | the fix-and-re-verify loop | qa/SKILL.md.tmpl, investigate/SKILL.md.tmpl (stops after 3 failed fixes) |
| pruning | prune / gating / decay | /learn prune, hit-rate gating, a taste profile that decays 5%/week |
| night shift | — none automated | the closest thing is /retro, which you run yourself once a week |
| meta layer | the generator + /skillify + /plan-tune | scripts/gen-skill-docs.ts — skills that make and tune skills |
| brain | gbrain (a separate repo) | optional; wired in by /setup-gbrain and /sync-gbrain |
| compile vs retrieve fork | generated-and-committed docs | gstack compiles: templates become SKILL.md at build time, never at run time |
The body is Claude Code (and nine other agents). gstack is the process layer that sits inside it — it does not run anything, it tells the agent what to do next and in what order. The brain is a separate project, gbrain, which gstack can plug in but never requires. Not part of gstack: your model provider, your CI, your deploy platform, and your code.
One honest caveat. Almost none of this is enforced. Skills are prose that an agent chooses to follow, so "the gate blocks you" means "the instructions say stop." Exactly two things in the pipeline are real mechanical blocks: /freeze, which denies Edit and Write through a tool hook, and the credential scanner, which exits non-zero before a push. Everything else — the review gates, the iron laws, the completeness rules — is a very well-written suggestion. gstack says so about its own redaction guard: it is a guardrail, not airtight enforcement.
The same sentence fairly describes the whole product.
The repo rendered as answers to the library's canonical questions. IDs are stable, so the same number can be compared across atlases.
~/.gstack/projects/<slug>/. Nothing hosted is required for any of it to work.every architectural decision, every past bug pattern, and every time it was wrong— and a context window can't hold that, so it goes to disk beside the repo. Four separate stores, deliberately non-overlapping:
Learnings = what you know. Timeline = what happened. Checkpoints = where you are. Health = how good the code is.
the wrong primitivefor multi-writer canonical state — lost updates on rewrite, partial-line corruption on crash, no transactions. It was hardened with file locks and append-only opens; SQLite is the intended fix and hasn't landed. State also lives outside your repo, so it does not travel with a clone.
The security property comes from physical port separation: a tunnel caller cannot reach /health or /cookie-picker because those paths don't exist on that TCP socket. Header inference … is unreliable; socket separation isn't.On injection: a single confident classifier is not enough, because a Stack Overflow page about prompt injection looks exactly like prompt injection — so BLOCK needs two classifiers agreeing at ≥0.75, while a leaked canary token blocks on its own.
git push --no-verify, a direct gh issue create, or one env var all walk around it. There is intentionally no config key to disable the HIGH-severity block.catch 95% of issues for free, use LLMs only for judgment calls.The same instinct runs through the skills — reviews under 50 changed lines skip all specialists, a specialist with zero findings in ten dispatches gets auto-skipped, and the paid transcript security check only fires when a cheaper local scan scores above 0.40.
/qa or /autoplan session actually spends, and /autoplan deliberately runs four full reviews back to back. Concurrent eval runs on one machine had to be serialised behind a machine-wide lock because they were rate-limiting each other.No MCP protocol. MCP adds JSON schema overhead per request and requires a persistent connection. Plain HTTP + plain text output is lighter on tokens and easier to debug.The generator, setup script, uninstaller, health check and tests all read the host configs, so none of them contain per-host branching.
SKILL.md.tmpl. You write the prose and judgment; 22 resolver modules fill in placeholders from the actual source code at build time; the generated SKILL.md is committed to git.structurally sound — if a command exists in code, it appears in docs. If it doesn't exist, it can't appear.Committed rather than generated at run time for three reasons: the agent reads the file at load time with no build step available, CI can diff it to catch staleness, and git blame keeps working.
/plan-design-review vs /design-review, /plan-devex-review vs /devex-review). Code reviewers run as separate subagents with fresh context.no prior review bias.
for context but never block shipping, so the pipeline stays fast for the bug fixes that are most of the work. The Verification Gate exists because agents lie about being done:
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
the ‘don't bother me’ setting. And the 7-day freshness window means a review from last Tuesday clears a diff written this morning.
/autoplan runs four full reviews this way, using six named principles, so you answer one question instead of fifteen to thirty.AI models recommend. Users decide.And explicitly:
Two AI models agreeing on a change is a strong signal. It is not a mandate.When Claude and Codex both want something and the user says no,
the user is right. Always.Every question uses one format — context, question, a
RECOMMENDATION: Choose X because ___ line, then lettered options./autoplan's six principles are opinionated in one direction — "choose completeness", "bias toward action" — which is the right default for a solo founder and the wrong one for a regulated codebase.test_stub field when the finding is testable). The citation rule attacks the second: Rationalization prevention: ‘This looks fine’ is not a finding. Either cite evidence it IS fine, or flag it as unverified.A matching rule governs blaming a failure on someone else's change:
‘Pre-existing’ without receipts is a lazy claim. Prove it or don't say it.
path:line:category), which merges the easy duplicates and misses the reworded ones./freeze registers a PreToolUse hook that returns deny for any Edit or Write outside one directory. /careful warns before destructive shell commands. /guard is both. A continuous checkpoint mode auto-commits work-in-progress locally. /canary watches production after a deploy./freeze is the one place gstack decided prose wasn't enough — it is a hard block, not just a warning, because an agent debugging one module will cheerfully "fix" an unrelated one.
/investigate auto-freezes to the module under investigation. Checkpoint pushes are off by default so WIP commits don't trigger everyone's CI.~/.claude/settings.json, so gstack edits a file you own; it writes a timestamped backup first and has a rollback command, which is the right mitigation but still a real intrusion. Everything else in this group is advisory and can be talked out of.{{INHERIT:…}} directive so a specific version builds on its family. Genuine multi-model work is a deliberate act: /codex for a second opinion, /benchmark-models to race three vendors on the same prompt.They are subordinate to skill workflow, STOP points, AskUserQuestion gates … If a nudge below conflicts with skill instructions, the skill wins. Treat these as preferences, not rules.Where real routing exists it's inside the browser sidebar — a fast model for clicking, a stronger one for reading, and a small one for the security transcript check.
~/.claude/skills/gstack, with per-skill directories symlinked out of it. Team mode bootstraps your repo — not with vendored files, but with a CLAUDE.md section and a hook that installs gstack for any teammate who doesn't have it. Every session does a silent update check, throttled to once an hour and safe to fail.No vendored files in your repo, no version drift, no manual upgrades.Vendoring is explicitly deprecated, and
gstack-team-init will find and remove an old vendored copy for you. Changes that alter on-disk state ship with a migration script that the upgrade skill runs automatically../setup after every git pull or silently run stale skills. Team mode in required mode also blocks teammates' AI work until they install, which is a strong ask.A /review session catches an N+1 query pattern, and the next /review on the same codebase starts from scratch.The differentiator claimed against Cursor and CLAUDE.md is structure — typed, scored, decaying, cross-skill — rather than storage. The decision log is event-sourced (decide / supersede / redact) so "active" is computed and history stays honest.
/learn prune flags learnings that reference deleted files or contradict each other and then asks you about each one. Nothing expires on its own, so the store grows. Cross-project recall is off by default — deliberately, so a consultant doesn't carry Client A's patterns into Client B's repo.Nine steps, in the order a change actually moves through the factory.
Before anything runs, a skill has to exist and be correct. A human writes prose and judgment into a template. A build step fills the mechanical parts — the command list, the flags, the shared methodology blocks — straight out of the source code. The result is committed to git.
That ordering is the whole trick. Docs can't claim a flag the code doesn't have, because the flag list is read from the code. And because the output is committed, the agent can just open the file: there is no build step at the moment you type a slash command.
Every skill opens with the same generated block — the always-on layer. It checks for an update, touches a session file, recovers context from disk, states the question format, and injects the builder ethos. None of it is skill-specific, which is exactly why it's generated in rather than copied.
One nice detail: it counts how many gstack sessions you've touched in the last two hours. At three or more, every skill switches to a mode where each question re-states which project and branch it's about — because you're juggling windows and you will get them confused.
A change starts as a sentence. /office-hours interrogates it — six forcing questions, pushes back on your framing, and writes a design doc. Then up to four reviewers read that doc with different eyes: strategy, architecture, visual design, developer experience. Each writes its own artifact and a task list.
Run individually, that's fifteen to thirty questions. /autoplan runs the same four reviews at full depth but auto-answers the intermediate questions using six stated principles, sorting each call into mechanical (decide silently) or taste (decide, but show your work at the end). You answer once.
/autoplan doesn't shorten the reviews — it only collapses their questions, so the depth is unchanged and the interruptions go from ~20 to 1.While the agent writes code, three opt-in guards are available. Two of them are advisory prose: /careful warns before rm -rf, DROP TABLE, or a force-push, and you can override any warning. One is real: /freeze installs a tool hook that returns deny on any Edit or Write whose path falls outside a directory you name.
That distinction matters more than it looks. An agent debugging one module will happily "improve" an unrelated one on the way past. A warning it wrote itself won't stop it; a hook will. /investigate knows this and auto-freezes itself to the module under investigation.
This is the intake fan shape, run backwards: one diff goes out to several specialist subagents at once, and their findings come back to one place. Each specialist gets a fresh context and exactly one checklist, so it can't be talked out of its own domain by the rest of the review.
Three gates decide who runs. Diffs under 50 changed lines skip everyone. Then scope detection asks whether this diff even touches auth, migrations, or an API contract. Then hit-rate gating: a specialist that has found nothing in ten dispatches gets auto-skipped — except security and data-migration, which are tagged never-gate because they're insurance, not throughput.
Findings come back as one JSON object per line with a severity, a confidence score and a fingerprint. They get merged, deduplicated, then split: mechanical ones are fixed on the spot, judgment ones are batched into a single question. Anything that came with a proposed test is always escalated to you.
This is the one part of gstack that isn't markdown, and the reason is latency. Launching a browser per command costs 2–3 seconds and loses your login between calls. So a long-lived Chromium sits behind a localhost HTTP server: first command ~3 seconds, every command after ~100–200 ms, cookies and tabs intact.
The agent addresses elements by ref — @e1, @e2 — which come from the accessibility tree, not from injected DOM attributes. Injecting attributes breaks on content-security policies, on React re-renders, and on shadow DOM; accessibility-tree locators don't touch the page at all. Refs are cleared on navigation on purpose, so a stale ref fails loudly instead of clicking the wrong thing.
On top of that, /qa runs a self-repair loop: find a bug, fix it, write the regression test, re-run the flow, confirm it's gone.
/qa-only runs the top half and the first box of the loop, then stops./ship is the longest skill in the repo and mostly it is a checklist: merge the base branch first so tests run against the merged state, run the tests, run its own review, bump the version, write the changelog, split the work into bisectable commits, push, open the pull request.
Only two things stop it. The readiness dashboard wants a clean eng review from the last seven days — and that's it; CEO, design, adversarial and outside-voice status are printed for context and explicitly never block. Then the verification gate at step 16: if any code changed after the last test run, the tests run again, and stale output is not accepted. "Should work now" is answered with "run it."
One more check sits between push and PR: a credential and PII scanner reads the exact bytes about to leave the machine — write to a temp file, scan that file, send that same file — because scanning a string and then re-rendering it reopens the gap.
Everything so far wrote something down. Four stores, deliberately not overlapping — learnings are what you know, the timeline is what happened, checkpoints are where you are, health history is how good the code is — plus an event-sourced decision log so a settled call doesn't get re-litigated next week.
Most of that is just recall. Three parts genuinely change future behaviour, and they're the interesting ones: a specialist's hit rate decides whether it runs again, a design taste profile decays 5% a week so old preferences fade, and a per-site browser note stays quarantined until it has worked three times.
What doesn't happen automatically: forgetting. Nothing expires. /learn prune finds learnings that point at deleted files or contradict each other and asks you about each one — which is honest, but it means the store only shrinks when you sit down with it.
/retro is the weekly roll-up, but you run it. The three orange arrows are the only paths where past runs silently change future ones.Install is one clone plus ./setup. Setup detects which of the ten supported agents you have and links the skills into each one's directory — real directories at the top level, with a symlinked SKILL.md inside, so the agent discovers /qa rather than something buried three levels down.
Team mode is the interesting bit: it doesn't vendor anything into your repo. It writes a CLAUDE.md section and a hook, so a teammate who clones the repo gets gstack installed for them. Every session then does a silent, once-an-hour, network-failure-safe update check. Changes that alter on-disk layout ship with a migration script that the upgrade skill runs for you.
/qa or /gstack-qa.All 53 skills, grouped by the job they do. writes means it can change files in your repo, your git history, or your install; reads means it inspects and reports, though it may still drive a browser or write gstack's own notes.
| Skill | Kind | What it does |
|---|---|---|
| Think & plan — 8 | ||
| /office-hours | reads | Six forcing questions that reframe your product before code exists. Writes the design doc everything downstream reads. |
| /plan-ceo-review | reads | Founder-mode scope challenge. Four modes: expansion, selective expansion, hold scope, reduction. |
| /plan-eng-review | reads | Locks architecture, data flow, state machines, error paths, test matrix, failure modes. |
| /plan-design-review | reads | Rates each design dimension 0–10, says what a 10 looks like, edits the plan toward it. Flags AI slop. |
| /plan-devex-review | reads | Developer-experience review: personas, competitor time-to-hello-world, magical moment, friction traces. |
| /plan-tune | reads | Learns which questions you actually want asked, and tunes question sensitivity accordingly. |
| /autoplan | reads | Runs CEO, design, eng and DX review at full depth, auto-deciding the mechanical calls. One approval gate. |
| /spec | writes | Five phases from vague intent to a filed GitHub issue. Can spawn an agent in a fresh worktree to execute it. |
| Design — 4 | ||
| /design-consultation | writes | Builds a whole design system from scratch — research, creative risks, mockups — and writes DESIGN.md. |
| /design-shotgun | reads | Generates 4–6 mockup variants, opens a comparison board, collects your feedback, iterates. Learns your taste. |
| /design-html | writes | Turns an approved mockup into production HTML with computed text layout, so it reflows instead of breaking. |
| /design-review | writes | Live visual audit that also fixes what it finds, with atomic commits and before/after screenshots. |
| Review & investigate — 6 | ||
| /review | writes | Pre-landing review: specialist fan-out, auto-fix the mechanical findings, batch-ask about the rest. |
| /codex | reads | Second opinion from a different vendor's model. Review, adversarial challenge, or open consultation. |
| /investigate | writes | Root-cause debugging under an iron law: no fixes without investigation. Stops after 3 failed fixes. |
| /cso | reads | OWASP Top 10 plus STRIDE threat model, tuned for zero noise. Every finding carries an exploit scenario. |
| /devex-review | reads | Actually walks your onboarding: navigates the docs, times time-to-hello-world, screenshots the errors. |
| /health | reads | Type checker, linter, tests and dead code as one composite score, tracked over time. |
| Test with real eyes — 9 | ||
| /qa | writes | Real browser, real clicks. Finds bugs, fixes them, generates the regression test, re-verifies. |
| /qa-only | reads | The same QA methodology, report only. Exists so you can QA a codebase you don't want touched. |
| /browse | reads | The headless Chromium CLI. Persistent daemon, ~100 ms a command, plus a gated raw DevTools escape hatch. |
| /open-gstack-browser | reads | A visible browser with a sidebar agent, anti-bot stealth, and the layered prompt-injection defence. |
| /setup-browser-cookies | reads | Imports cookies from your real browser so authenticated pages can be tested. Values never hit disk. |
| /pair-agent | reads | Lets another vendor's agent drive the same browser in its own tab, over a separately-bound tunnel port. |
| /benchmark | reads | Page load, Core Web Vitals and resource sizes, compared before and after on every PR. |
| /scrape | reads | Pulls data off a page. The first call prototypes the flow; a codified call replays it in ~200 ms. |
| /skillify | reads | Freezes the last working /scrape flow into a permanent per-site browser skill. |
| Ship & operate — 8 | ||
| /ship | writes | Twenty-one steps from feature branch to open PR, with the two gates that can actually stop you. |
| /land-and-deploy | writes | Merge the PR, wait for CI and the deploy, verify production health. One command from approved to verified. |
| /canary | reads | Post-deploy watch loop for console errors, performance regressions and page failures. |
| /landing-report | reads | Read-only dashboard for the version queue when several workspaces are shipping at once. |
| /setup-deploy | reads | One-time detection of your platform, production URL and deploy commands. |
| /document-release | writes | Reads every doc, cross-references the diff, updates what drifted, maps documentation coverage. |
| /document-generate | writes | Writes missing docs from scratch on the four-quadrant model: tutorial, how-to, reference, explanation. |
| /gstack-upgrade | writes | Self-updater. Detects install shape, syncs, runs migrations, shows what changed. |
| Safety rails — 4 | ||
| /freeze | reads | Hard-blocks Edit and Write outside one directory via a deny hook. The only mechanical rail in the build stage. |
| /unfreeze | reads | Clears the freeze boundary. |
| /careful | reads | Warns before rm -rf, DROP TABLE, force-push, git reset --hard. Any warning can be overridden. |
| /guard | reads | Careful plus freeze in one command. The recommended posture for production work. |
| Memory & reflection — 7 | ||
| /learn | reads | Show, search, prune, export and stat what gstack has learned on this project. |
| /retro | reads | Weekly retro: per-person breakdowns, shipping streaks, test-health trends. Global mode spans every project. |
| /context-save | reads | Snapshots working state — decisions, files, what's left — so a context reset isn't fatal. |
| /context-restore | reads | Rebuilds that state, including from the structured bodies of WIP checkpoint commits. |
| /setup-gbrain | reads | Zero to a running brain in under five minutes: local, hosted, auto-provisioned, or remote. |
| /sync-gbrain | writes | Re-indexes this repo into the brain and refreshes the search-guidance block in your CLAUDE.md. |
| /benchmark-models | reads | Same prompt through Claude, GPT and Gemini. Latency, tokens, cost, and an optional judged quality score. |
| iOS on real hardware — 5 | ||
| /ios-qa | reads | Drives a real iPhone over a USB tunnel through a debug state server. Optionally exposed to remote agents. |
| /ios-fix | writes | Autonomous iOS bug-fix loop with regression snapshot capture. |
| /ios-design-review | reads | Designer's-eye audit on real hardware against a ten-dimension Apple interface rubric. |
| /ios-clean | writes | Strips the debug bridge and its conditional wiring before a release build. |
| /ios-sync | writes | Regenerates the debug bridge and typed state accessors against the latest templates. |
| Publish — 2 | ||
| /make-pdf | writes | Markdown in, publication-quality PDF out. Diagram fences render as vectors, fully offline. Also HTML and DOCX. |
| /diagram | writes | English in, a triplet out: mermaid source, an editable file, and a rendered image. Zero network. |