Gauntlette

Gauntlette is the structured part of gstack without the ads, upgrade nagging, or lake chatter.

It is a review and delivery pipeline for Claude Code and Codex. Every feature gets:

• a durable design doc in ~/.gauntlette/designs/{repo}/
• one active plan document that gets refined stage by stage
• browser QA that acts like a real user
• architecture diagrams that render well in markdown

There is no telemetry, no auto-update behavior, and no phone-home.

Preferred Commands

/gauntlette-start → /gauntlette-ceo-review → /gauntlette-design-review → /gauntlette-eng-review
    → /gauntlette-fresh-eyes → [/gauntlette-cso-review] → /gauntlette-implement
    → /gauntlette-code-review → /gauntlette-quality-check → /gauntlette-human-review → /gauntlette-ship-it

Claude Code surfaces installed Gauntlette skills as /gauntlette-* slash commands. Codex uses Gauntlette skills plus generated custom prompt wrappers; after install and restart, invoke the preferred commands as /prompts:gauntlette-help, /prompts:gauntlette-start, and so on, or search for gauntlette in the slash menu.

Legacy aliases still work:

• /survey-and-plan, /survey, and /help-me-plan all map to /gauntlette-start
• /ceo-review, /design-review, and /eng-review are supported
• older names like /product-review, /ux-review, and /arch-review still work
• unprefixed stage names like /quality-check still work
• /gauntlette-help shows the current stage and preferred command names

Codex prompt wrappers are installed only for the preferred /gauntlette-* command set. Legacy aliases still install as skills, but they do not get Codex prompt wrappers in this release.

What Changed

• Planning is now closer to gstack-office-hours: one question at a time, sharper forcing questions, explicit premises, and alternatives generation.
• The kickoff stage writes both a design doc and the active plan.
• QA is now diff-aware and browser-first. It prefers an existing preview or browser session, falls back to local ports, writes evidence into .gstack/qa-reports/, and tracks a health score.
• Architecture review now emits Mermaid plus ASCII diagrams.
• The prompts now prefer complete options over shortcuts and use a stricter AskUserQuestion format.
• Install now targets both ~/.claude/skills/ and ~/.codex/skills/.
• Install now adds Codex custom prompt wrappers under ~/.codex/prompts/ so preferred Gauntlette stages are available from Codex as /prompts:gauntlette-*.
• Token reporting is bundled under gauntlette/bin/estimate-tokens.sh, so it no longer depends on a separate Moe checkout.

How It Works

Planning artifacts

/gauntlette-start writes:

• ~/.gauntlette/designs/{repo}/{branch}-design-{timestamp}.md
• ~/.gauntlette/{repo}/{branch}.md

The design doc is the durable planning artifact. The plan is the stage-by-stage working document.

Promotion

When /gauntlette-implement starts, the plan is promoted into the repo at docs/plans/{branch}.md and the scratch copy is removed.

Review report

Every plan ends with a Gauntlette Review Report table that tracks which stages ran, what they found, and what still needs to happen.

Install

git clone https://github.com/robertkarl/gauntlette.git
cd gauntlette
./install.sh

install.sh regenerates the skill docs, then symlinks gauntlette into:

• ~/.claude/skills/
• ~/.codex/skills/

It also writes generated Codex custom prompt wrappers into:

• ${CODEX_HOME:-~/.codex}/prompts/

Codex custom prompts are a compatibility layer for command discovery. The Gauntlette skills remain the source of truth. Restart Codex or open a new Codex chat after install so the slash menu reloads the prompt wrappers.

Conflicts with existing installs are skipped, not overwritten.

Prompt wrappers are overwritten only when they contain Gauntlette's generated-file marker. User-owned files with the same names are skipped. uninstall.sh uses the same marker to remove only Gauntlette-owned prompt wrappers.

The shared gauntlette/ root symlink also carries helper tools like gauntlette/bin/estimate-tokens.sh, so install and uninstall pick them up automatically.

QA Dependency

/gauntlette-quality-check reuses the gstack browse binary if it exists at ~/.claude/skills/gstack/browse/dist/browse.

That gives gauntlette the same click-through web QA flow you liked from gstack, while still working well from Codex or Cursor when a built-in preview pane is already live.

Repo Instructions Snippet

Add the command list to your repo instructions file, for example CLAUDE.md or AGENTS.md:

## Gauntlette
Preferred commands: /gauntlette-help, /gauntlette-start, /gauntlette-ceo-review, /gauntlette-design-review, /gauntlette-eng-review, /gauntlette-fresh-eyes, /gauntlette-cso-review, /gauntlette-implement, /gauntlette-code-review, /gauntlette-quality-check, /gauntlette-human-review, /gauntlette-ship-it
Legacy aliases: /survey-and-plan, /survey, /help-me-plan, /ceo-review, /design-review, /eng-review, /product-review, /ux-review, /arch-review, /fresh-eyes, /cso-review, /implement, /code-review, /quality-check, /human-review, /ship-it

Principles

• No telemetry. No analytics. No phone-home.
• No upgrade checks. No ads. No auto-update prompts.
• One question at a time. Ask better questions, not more questions.
• Prefer complete implementations over cute shortcuts.
• Planning artifacts live outside the repo during review so bad edits do not dirty the worktree.
• Mermaid plus ASCII diagrams are mandatory for non-trivial architecture.
• QA should use the browser like a user, not excuse itself into unit-test theater.

Engineering Axioms

1. Main is sacred.
2. Tiny fixes go direct.
3. Test before fix.
4. Run the tests.
5. One branch, one concern.
6. Dead branches are dead.
7. Leave the campsite clean.
8. Simplest thing that works.
9. Read the repo instructions file, the plan, and the tests before you write.
10. Escalate decisions, not problems.