GStack: Give Your Agent a Whole Software Team's Worth of Roles

I have a confession that took me a few years to make out loud: most of my best engineering decisions had nothing to do with engineering. They were decisions about which hat to wear. When I was about to start coding, the most useful thing I could do was stop being a coder for ten minutes and become a product person, or a designer, or the grumpy QA reviewer who assumes everything is broken until proven otherwise. The work didn't change. The role changed, and the role changed everything.

GStack is the first agent setup I've used that takes that idea seriously and builds the whole system around it. It's Garry Tan's Claude Code configuration — somewhere around 110k stars at the time I'm writing this, which makes it one of the most-installed skill collections in the ecosystem — and its core bet is simple: instead of giving your agent one big undifferentiated "be helpful" mode, you give it a roster of distinct roles, each behind its own slash command. Product vision. Designer. Engineering manager. QA. Release manager. Doc engineer. The post-launch retrospective. You don't ask the agent to "build a feature." You ask the product role to define it, then the designer role to shape it, then the engineering manager to plan it, and so on down the line.

If you've read my write-up of Superpowers, you'll recognize the genus. Both are full workflows, both are opinionated, both refuse to let the agent freelance its way into a mess. But they're organized around different axes, and that difference is the whole point of this article. Let me walk you through the mental model, when to reach for it, how to install and configure it across agents, how to actually drive each role, and where people trip.

The role-based mental model

Here's the thing GStack understands that most agent setups don't: an LLM is a fantastic actor and a mediocre director. Give it a character to play — a specific role with a specific point of view and a specific definition of "done" — and it will inhabit that character with surprising discipline. Leave it as itself, a general assistant trying to satisfy everyone, and it averages all the roles together into a bland, hedge-everything mush. It writes code that's kind of tested, kind of documented, sort of aligned with what you asked for, because it's trying to be all things at once.

A role is a constraint, and constraints are what make models good. When the agent is wearing the product hat, it is not allowed to talk about implementation. Its job is to answer "what are we building and for whom, and how will we know it worked." When it's wearing the QA hat, it is not allowed to be charitable about its own code — it actively hunts for the ways the feature breaks. Each role has a narrow mandate and a narrow output, and because the mandate is narrow, the output is sharp.

I think of it like this. A general agent is a single person trying to hold an entire product in their head at once. A GStack agent is that same person, but disciplined into wearing exactly one hat at a time and finishing that hat's job before moving to the next. The model is the same. The structure imposed on it is what produces the quality.

Roles are not personas

Let me draw a line here because people conflate these. A persona is cosmetic — "you are a senior engineer with 15 years of experience." It changes tone and not much else. A role in GStack's sense is structural: it changes what the agent is allowed to produce, what it must produce before it's done, and who it hands off to next. The persona affects vibe. The role affects the contract.

That contract is the secret. Each GStack role defines its inputs (what it needs from the previous role), its mandate (the one question it exists to answer), and its outputs (the artifact the next role consumes). When you string the roles together, you get an assembly line where each station has a clear deliverable. Nothing falls through the cracks because every role knows exactly what it's supposed to hand the next one.

The roster: who's on the team

GStack ships a team. The exact set evolves — check the repo for the canonical list — but the shape has been stable, and here's how I think about each member.

Role	The one question it answers	Primary artifact
Product vision	What are we building, for whom, and why now?	A crisp spec / problem statement
Designer	What should this feel like to use?	Flows, states, interaction notes
Engineering manager	How do we build this, in what order, with what risks?	A sequenced implementation plan
Implementer	(the actual coding role)	Working code + tests
QA	How does this break?	A defect list and test report
Release manager	Is this safe to ship, and how do we ship it?	Release checklist, changelog, version bump
Doc engineer	How does someone else understand and use this?	Docs, README updates, usage examples
Retrospective	What did we learn, and what do we change next time?	A short post-mortem / lessons file

Read that table top to bottom and you'll notice it's a team, not a pipeline of phases. The product person and the designer aren't "phase one" and "phase two." They're people with different jobs who, on a real team, might go back and forth a dozen times. GStack lets you invoke them in any order, revisit them, and replay them. That flexibility is exactly what distinguishes role-thinking from phase-thinking, which is the next thing I want to dig into.

The product role

This is the one most developers skip and most projects suffer for. The product role refuses to write code. It asks who the user is, what they're trying to accomplish, what the smallest version that delivers value looks like, and — critically — what you are explicitly not doing in this cut. When I let the product role do its job, the implementation that follows is half the size it would have been, because half the things I would have built were never actually needed.

The engineering manager role

Don't let the title fool you — this isn't about org charts. The EM role is a planner. It takes the product spec and the design and produces a sequenced plan: what to build first, what the risky unknowns are, where the integration seams live, and what could blow up. It's the role that thinks about order of operations so the implementer doesn't paint itself into a corner. If you've ever watched an agent build the easy 80% and then discover the hard 20% invalidates all of it, the EM role exists to prevent exactly that.

The QA role

My favorite, because it's adversarial by design. The QA role is instructed to distrust the implementation. It doesn't ask "does this work?" It asks "what input makes this fall over, what state did we forget, what happens at the boundaries, what did the implementer assume that isn't guaranteed?" Running the QA role over your own freshly written code is one of those things that feels slightly absurd — you wrote it, you know it's fine — and then it finds three real bugs and you stop arguing.

If you like the adversarial-review idea on its own, Grill Me is a whole skill built around that single muscle, and it pairs beautifully with GStack's QA role.

Release manager, doc engineer, retrospective

These three are the roles that hobbyist setups forget entirely, and they're the difference between a demo and a product. The release manager owns the boring-but-load-bearing work: version bumps, changelogs, "did we break the public API," "is this safe to deploy." The doc engineer makes sure a stranger can use what you built. And the retrospective role — short, honest, written after shipping — is where the system gets smarter over time. It's the closest thing to institutional memory an agent has.

When role-thinking beats phase-thinking

This is the question I get asked most, usually phrased as "isn't this just Superpowers with different labels?" No. And understanding why not will tell you which tool to grab.

Phase-thinking organizes work as a sequence: brainstorm → plan → implement → verify. It's linear by nature. You finish a phase, you move to the next, and going backward feels like failure — you "regressed" to an earlier phase. Phase-thinking is excellent when the work genuinely is sequential and you want a strong forcing function to stop the agent from coding before it has thought. Superpowers nails this.

Role-thinking organizes work as a set of perspectives that you cycle through as needed. It's not linear — it's a rotation. You might invoke the product role, jump to the designer, realize the design exposes a product question, jump back to product, then forward to the EM. Going "backward" isn't regression; it's just a different person weighing in. Role-thinking shines when the work is exploratory, when requirements are fuzzy, and when the most valuable thing is being able to switch lenses fluidly without feeling like you broke a process.

Here's the heuristic I actually use:

Reach for phases when you know what you're building and you need discipline about how and in what order. Reach for roles when you're still figuring out what you're building and you need different kinds of judgment, not a fixed sequence.

Concretely:

• Greenfield product, vague idea, lots of unknowns → roles. You'll bounce between product, design, and EM many times before a single line of code, and GStack makes that bouncing natural.
• Well-specified feature in an existing system → phases, or honestly just the implementer + QA roles. The product question is already answered; you mostly need order and verification.
• You keep shipping things that "work" but nobody uses or understands → roles, specifically because of the doc engineer and product roles that phase setups under-weight.
• You keep shipping things that break in production → roles again, leaning hard on QA and release manager.

The honest answer is that you'll often want both, and the two compose. I've run GStack's product and EM roles to figure out what and in what order, then handed the sequenced plan to a phase-based implement-and-verify loop. The role layer answers "what and who," the phase layer answers "how, carefully." They're not competitors. They're different altitudes. (If you want the deeper theory of why spelling out the "what" up front pays off, my guide on spec-driven development with AI agents is the long version of this paragraph.)

Installing and configuring per agent

GStack installs from a clone plus a setup script. The headline command — the one in the install field at the top of this page — is the Claude Code path:

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

The --single-branch --depth 1 keeps the clone small; you don't need the full history to use it. The ./setup script is where the per-agent magic happens. By default it wires GStack into Claude Code, dropping the role commands where the agent will find them.

Targeting other agents with --host

GStack isn't Claude-Code-only. The setup script takes a --host flag so you can install the same roster into a different agent's configuration:

# Claude Code (the default)
./setup

# Kiro
./setup --host kiro

# Cursor
./setup --host cursor

I want to flag the Kiro combination specifically because it's a genuinely nice pairing. Kiro's whole personality is spec-and-structure-forward, and GStack's role roster slots into that worldview cleanly — the product and EM roles produce exactly the kind of artifacts Kiro likes to chew on. If you already live in Kiro, ./setup --host kiro is close to free value.

The --host mechanism works because the content of a role — its mandate, its inputs, its outputs — is agent-agnostic. What differs between agents is the plumbing: where commands live, how slash commands are registered, what the config file format is. The setup script knows the plumbing for each supported host and translates the shared role definitions into that host's idiom. That's a clean design, and it's why the same mental model transfers when you switch tools.

What setup actually touches

Before you run any setup script from the internet, you should know what it does. GStack's setup writes role definitions into your agent's skills/commands directory and registers the slash commands. It's not subtle and it's not hiding anything — read the script, it's short. A couple of practical notes from my own installs:

• It installs into your user-level config by default (~/.claude/... for Claude Code), so the roles are available across all your projects, not just one. If you want project-scoped roles, install into the project's .claude/ directory instead and commit it.
• Re-running setup is generally safe and is how you upgrade — git pull in the clone directory, then ./setup again.
• If you run multiple agents, you can run setup once per host against the same clone. The clone is the source of truth; each host gets its own wiring.

A quick word on safety: any "clone and run a script" install deserves a glance before you execute it. This isn't paranoia specific to GStack — it's hygiene for every skill you install, and I wrote a whole piece on vetting them in the most popular AI coding skills. Read the setup script, confirm where it writes, run it.

How to drive each role

Installation is the easy part. Driving the roles well is where the leverage is. The pattern is always the same: you invoke a role with its slash command, you give it the context it needs, it produces its artifact, and you carry that artifact to the next role. Let me make that concrete.

Start with product, always

Even when you think you know what you're building, spend five minutes in the product role. Invoke it and resist the urge to talk about code:

/product

I want to add a "saved searches" feature to my app. Users run the
same filter combinations repeatedly and have to rebuild them each time.

The product role will push back with questions — how many saved searches, are they shared or private, do they need names, what's the smallest version that's still useful. Answer those and it produces a tight spec. The spec is your artifact. Everything downstream consumes it.

Hand off explicitly

The single biggest mistake people make is invoking the next role without giving it the previous role's output. Roles don't share a brain — each one starts from its mandate plus whatever you hand it. So the handoff is on you:

/eng-manager

Here's the product spec for saved searches: [paste the spec the
product role produced]. Plan the implementation. Call out the risky
parts and tell me what to build first.

When you make the handoff explicit, each role does sharp work. When you don't — when you just say "now plan it" and assume the agent remembers — you get vague work, because the EM role is operating without its required input. Treat the artifacts as physical objects you carry from station to station.

Use QA against your own code, deliberately

After the implementer role produces code, switch hats before you trust it:

/qa

Review the saved-searches implementation. Assume it's broken. Find the
edge cases: empty search, duplicate names, a saved search that
references a filter that no longer exists, concurrent edits.

The role switch is doing real work here. The same model that just wrote the code, asked to defend it, will be charitable. The same model, asked to attack it, will be ruthless. You're not getting a different intelligence — you're getting a different stance, and the stance is what surfaces bugs.

Close the loop with release and retro

Don't skip the last two roles just because the code works. Run the release manager to handle the version bump, changelog, and deploy checklist — the stuff that's boring until it bites you. Then, after you've shipped, run a short retrospective:

/retro

We just shipped saved searches. It took longer than expected because
the filter-reference problem wasn't caught until QA. What should we
change in how we plan features like this?

That retro output is gold over time. Save it. Feed it back into the product or EM role on the next feature. This is how the system compounds — the team gets better at working together because you're writing down what it learned.

Pitfalls, and how I avoid them

I've run GStack on enough projects to have collected the failure modes. Here are the ones worth warning you about.

Treating roles as decoration. If you invoke /qa and then argue with every finding because "I know my code is fine," you've defeated the point. The role's value comes from honoring its mandate. When QA finds a bug, your job is to evaluate the bug, not to defend your ego. Let the role be adversarial.

Forgetting the handoff. I'll say it again because it's the number-one issue: roles don't automatically inherit each other's output. If the EM role seems to be planning the wrong thing, nine times out of ten you didn't hand it the product spec. Carry the artifacts.

Over-rotating for tiny tasks. Fixing a typo does not need a product spec, a design review, and a retrospective. GStack is a team, and you don't convene the whole team to change a string. For small, well-understood changes, drop straight to the implementer and maybe QA. The roster is a buffet, not a mandatory seven-course meal. Match the ceremony to the stakes.

Letting roles bleed into each other. The discipline only works if each role stays in its lane. If you find the product role drifting into implementation details, redirect it — "stay at the product level, we'll plan the build separately." The boundaries are the feature. Defend them.

Skipping the unglamorous roles. Release manager, doc engineer, retro. Everyone wants to invoke product (fun) and implementer (satisfying) and nobody wants to invoke doc engineer (chores). But the chores roles are exactly the ones that separate a thing you built for yourself from a thing other people can actually use. Force yourself to run them.

Assuming the install is set-and-forget. GStack updates. Garry and contributors refine the roles. Pull and re-run setup periodically so you're not driving a year-old roster. The role concepts are stable; the prompts behind them improve.

Where GStack fits in a bigger setup

I rarely run a single skill in isolation, and GStack plays well with others. The role layer sits naturally on top of more foundational setups. I'll often have a base workflow skill handling the disciplined implement-and-verify loop, GStack supplying the higher-altitude product/design/EM judgment, and a couple of specialist skills for narrow jobs.

A few combinations I like:

• GStack + GSD Core — GSD's get-stuff-done loop as the implementation engine underneath GStack's role layer. Roles decide what and who; GSD grinds out the how.
• GStack + Grill Me — supercharge the QA role with a dedicated adversarial-review skill. When QA flags something, hand it to Grill Me for a deeper interrogation.
• GStack + a packaging skill — once you've defined your own house roles, ship them as a package so your whole team installs the same roster. This is where role-thinking scales from "my setup" to "our setup."

And if you're building these kinds of skills yourself rather than just consuming them, the broader discipline of writing good agent instructions — the thing that makes a role's mandate sharp instead of mushy — is the subject of my prompt engineering guide. A GStack role is a prompt, just a structured and named one. Everything that makes a prompt good makes a role good.

The bigger idea worth stealing

Even if you never install GStack, steal the mental model, because it's the durable part. The next time you sit down with any agent and feel it producing average work, ask yourself: which role does this work actually need right now? Not "be helpful." Specifically: is this a product question, a design question, a planning question, an implementation question, a quality question? Name the role. Make the agent be that one thing. Finish that role's job. Then name the next one.

That single habit — thinking in roles instead of in one undifferentiated "do the task" blob — will improve your output with any agent, any model, any setup. GStack is the most polished, most-starred packaging of the idea, with Garry's taste baked into the specific roles and a clean multi-host installer. But the idea is bigger than the package. A team of clear roles, each with a narrow mandate and an explicit handoff, beats one generalist trying to be everything at once. That's true for humans. It turns out it's just as true for the model on the other end of your slash commands.

Install it, run a real feature through the whole roster once — product to retro — and feel the difference. Then keep the roles you love, drop the ones you don't, and make the team your own.

Resources & links

• GStack on GitHub (garrytan/gstack) — the source, the setup script, and the canonical role roster. Read the setup script before running it.
• Garry Tan — the author's GitHub profile, worth a follow for context on the project's direction.
• Claude Code — the primary host GStack targets by default.
• Kiro — a spec-forward agent that pairs especially well with GStack via ./setup --host kiro.
• Cursor — another supported host via ./setup --host cursor.
• Internal — Superpowers: the phase-based cousin; read this to understand the roles-vs-phases distinction.
• Internal — GSD Core: a get-stuff-done implementation loop that fits neatly under GStack's role layer.
• Internal — Grill Me: an adversarial-review skill that supercharges GStack's QA role.
• Internal — Ship Skills with Package: package your own house roles so a whole team installs the same roster.
• Internal — The most popular AI coding skills: where GStack sits in the wider ecosystem, plus how to vet any clone-and-run installer.
• Internal — Spec-driven development with AI agents: the long version of why answering "what" before "how" pays off.
• Internal — Prompt engineering complete guide 2026: a GStack role is a structured prompt; this is how to make it sharp.
• Internal — Agentic automation track: the full learning path this skill belongs to.