copilot-gstack

gstack, ported to the GitHub Copilot CLI.

This project turns the GitHub Copilot CLI into a virtual engineering team. It ships 14 custom agents that give Copilot structured, opinionated roles: a CEO who rethinks the product, an engineering manager who locks the architecture, a designer who catches AI slop, a staff engineer who finds the production bugs, a QA lead who drives a real browser, a security officer who runs OWASP plus STRIDE, a release engineer who opens the PR, and a debugger who refuses to patch symptoms.

It is a faithful port of gstack by Garry Tan, which was built for Claude Code. Because the GitHub Copilot CLI now supports custom agents defined in Markdown, the same methodology runs natively in Copilot, with one upgrade: the second-opinion agent runs on a genuinely different model (GPT-5.3-Codex) instead of shelling out to an external CLI.

• Original project: https://github.com/garrytan/gstack
• GitHub Copilot CLI: https://github.com/github/copilot-cli
• Copilot custom agents: https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents

Why this exists

Developers move fast in the terminal. The GitHub Copilot CLI already lets you generate commands, debug, and work directly with your repositories. Custom agents take that further: instead of a blank prompt every time, you encode a repeatable workflow once (its role, its tools, its guardrails) and invoke it whenever you need it.

gstack is one of the most complete expressions of that idea, a full software sprint encoded as slash-command skills. Those skills were written for Claude Code. The GitHub Copilot CLI supports the same shape of extension (Markdown agent profiles with YAML frontmatter), so there is no reason the same sprint cannot run in Copilot. This repository is that port.

The sprint

The agents run in the order a sprint runs. Each one feeds the next, so nothing falls through the cracks.

Think          Plan            Build     Review           Test         Ship          Reflect
office-hours -> autoplan   ->  (code) -> review        -> qa        -> ship       -> retro
                ceo-review              investigate                    document-release
                eng-review              codex
                design-review

The agents

Agent	Role	What it does
gstack-office-hours	YC office hours	Six forcing questions that reframe your product before you write code. Produces a design doc, never code.
gstack-plan-ceo-review	CEO / founder	Finds the 10-star product in the request. Four scope modes (Expansion, Selective, Hold, Reduction) and an 11-section deep review.
gstack-plan-eng-review	Engineering manager	Locks architecture, data flow, ASCII diagrams, edge cases, and full test coverage. The Confusion Protocol forces hidden assumptions into the open.
gstack-plan-design-review	Senior designer	Rates each design dimension 0 to 10, explains what a 10 looks like, detects AI slop, maps every interaction state.
gstack-autoplan	Review pipeline	Orchestrates the CEO, design, and eng reviews as subagents. Auto-resolves routine decisions, surfaces only taste decisions.
gstack-review	Staff engineer	Pre-landing PR review. Finds the bugs that pass CI but blow up in production. Auto-fixes the obvious ones, asks about the rest.
gstack-investigate	Debugger	Systematic root-cause debugging. Iron Law: no fixes without investigation. Stops after three failed attempts.
gstack-codex	Second opinion	Independent cross-model review on GPT-5.3-Codex. Review (pass or fail gate), adversarial challenge, or consultation. Read only.
gstack-qa	QA lead	Tests the running app like a real user, fixes bugs with atomic commits, re-verifies, writes a regression test for every fix.
gstack-ship	Release engineer	Sync base, run tests, audit coverage, review, bump version, changelog, commit in bisectable chunks, push, open the PR.
gstack-cso	Chief security officer	OWASP Top 10 plus STRIDE threat model with a zero-noise confidence gate. Every finding includes a concrete exploit scenario.
gstack-retro	Engineering manager	Team-aware weekly retro from git history: per-person breakdowns, shipping streaks, test-health trends.
gstack-document-release	Technical writer	Updates every doc to match what shipped and builds a Diataxis documentation-debt map for the PR.
gstack-guard	Safety	Advisory mode: warns before destructive commands and refuses edits outside a chosen directory.

The cross-model second opinion

This is the one place where the Copilot port improves on a mechanical translation.

In gstack, the /codex skill shells out to the external OpenAI Codex CLI to get a review from a different model. In this port, gstack-codex is a native Copilot agent that sets model: gpt-5.3-codex in its frontmatter. When gstack-review, gstack-ship, or the plan reviews invoke it as a subagent, Copilot runs that subagent on GPT-5.3-Codex while the primary agent runs on its own model (Claude by default). You get a genuine cross-model review with no external tools: two different model families looking at the same diff. Findings that both models reach independently are the highest-confidence findings and get fixed first.

The default model is configurable per agent. If GitHub ships a newer Codex model, change one line in scripts/manifest.json and rebuild.

Requirements

• GitHub Copilot CLI 1.0.66 or newer, with an active Copilot subscription.
• Node.js 18 or newer (only to build and verify the agents, there are no runtime dependencies).
• Git.
• Optional: the Playwright MCP server for gstack-qa browser testing, and the Context7 MCP server for live library docs.

Install

Clone the repo and run the installer.

git clone https://github.com/anxkhn/copilot-gstack.git
cd copilot-gstack
./install.sh

By default this installs the agents at the user level (~/.copilot/agents/), so they are available in every project. To install them into a single repository instead (so teammates get them through source control), run:

./install.sh --repo /path/to/your/project

To also register the optional Context7 MCP server for live library documentation:

./install.sh --context7

To remove the agents:

./install.sh --uninstall

Manual install

The agents are committed under .github/agents/. Copy the ones you want into ~/.copilot/agents/ (user level) or into your project's .github/agents/ directory (repository level). No build step is required to use them.

Usage

Start Copilot in your project and pick an agent:

copilot
/agent

Or name the agent in a prompt and let Copilot route to it:

Use the gstack-office-hours agent to help me plan a notifications feature

Or select it directly, including non-interactively:

copilot --agent gstack-review -p "Review my current branch"
copilot --agent gstack-cso -p "Run a security audit on this repo"
copilot --agent gstack-retro -p "Run a weekly retro"

A full sprint looks like this:

copilot --agent gstack-office-hours -p "I want to build a daily briefing app"
# ... approve the design doc ...
copilot --agent gstack-autoplan -p "Review the plan"
# ... implement ...
copilot --agent gstack-review -p "Review the branch"
copilot --agent gstack-qa -p "QA the app at http://localhost:3000"
copilot --agent gstack-ship -p "Ship it"

How it is built

The agents are generated, not hand-maintained one by one. The pipeline has three parts:

• scripts/manifest.json defines each agent's frontmatter: name, description, tool list, and optional model override.
• sources/*.md holds the agent bodies (the methodology prompt for each role).
• scripts/convert.mjs assembles frontmatter plus body into .github/agents/<name>.agent.md and validates the result.

Commands:

npm run build         # build all agents from sources
npm run verify        # static checks on every generated agent
npm run verify:live   # also load one agent through the real Copilot CLI
npm run list          # list the agents in the manifest

The verifier checks that every agent has valid frontmatter, a required description, recognized tool aliases (or namespaced MCP tools), a known model id, a body under the 30000 character Copilot prompt limit, and no leftover gstack infrastructure (no template placeholders, no browser-binary references).

Converting a gstack skill with Copilot itself

The converter can also distill a gstack skill straight from its source through the Copilot CLI. This is how the port scales to gstack's other skills without hand translation:

node scripts/convert.mjs --distill-missing      # distill any skill lacking a source
node scripts/convert.mjs --regen review         # re-distill one skill via Copilot

The converter runs copilot -p with a strict conversion prompt that reads the gstack SKILL.md.tmpl, strips gstack-specific infrastructure, keeps the methodology and voice, and returns a Copilot-ready agent body under the character limit. The result is cached into sources/ so future builds are deterministic and free. The shipped agents in this repo use curated sources for quality, but the distillation path is real and tested.

How the port maps to gstack

gstack (Claude Code)	copilot-gstack (Copilot CLI)
SKILL.md skills invoked as slash commands	.agent.md custom agents invoked with /agent, a prompt, or --agent
~/.claude/skills/gstack/	~/.copilot/agents/ (user level) or .github/agents/ (repo level)
/codex shells out to the external OpenAI Codex CLI	gstack-codex runs natively on model: gpt-5.3-codex and is invoked as a subagent
The custom $B Chromium browser daemon for QA	The Playwright MCP server or the project e2e runner, tool-agnostic
Pre-tool-use hooks for careful and freeze	gstack-guard, an advisory agent that layers on top of the Copilot CLI native permission prompts
Template placeholders, telemetry, gbrain, session tracking	Removed. Only the reusable methodology and voice are kept.

Repository layout

copilot-gstack/
  .github/agents/        generated Copilot custom agents (committed)
  sources/               the agent bodies (methodology prompts)
  scripts/
    manifest.json        per-agent frontmatter and tool lists
    convert.mjs          build agents, or distill a gstack skill via Copilot
    verify.mjs           validate every generated agent
  install.sh             install into Copilot (user or repo level)
  AGENTS.md              agent routing that Copilot reads
  package.json           build and verify scripts (no dependencies)

Verification

Everything in this repository was tested end to end against the GitHub Copilot CLI:

• All 14 agents are discovered by copilot from the .github/agents/ directory.
• The gstack-codex agent confirms it runs on GPT-5.3-Codex, a different model than the primary agent.
• gstack-review successfully invokes gstack-codex as a subagent, and the cross-model synthesis works: on a deliberately vulnerable branch, review delegated to codex, codex returned a FAIL gate for a command-injection finding, and review reported both verdicts.
• Every generated agent passes static verification (frontmatter, tool names, model ids, and the 30000 character prompt limit).

Credits

• gstack is created and maintained by Garry Tan. All of the methodology, the roles, the forcing questions, and the sprint structure come from that project. This repository only adapts it to a different runtime.
• The GitHub Copilot CLI and its custom agents are from GitHub.

License

MIT. Same spirit as the original gstack: free, open, fork it and make it yours.