Superpowers + GStack: Routing, Context Management & Workflow

"Superpowers owns the implementation loop, GStack owns everything before and after it. Context Guard keeps the session clean."

A Claude Code plugin that integrates Superpowers and GStack into one workflow — with skill routing, automatic context management, and project auto-configuration. Already have an existing project? Run /adapt and it analyzes your setup, preserves your CLAUDE.md, and adds routing — so you can jump right in.

Status: Work in Progress — Actively developed. Contributions, feedback, and ideas are very welcome. See Contributing.

What problem does this solve?

If you've installed both Superpowers and GStack, you've probably run into these issues:

• Claude picks the wrong framework for the task (GStack's /investigate when you wanted Superpowers' debugging)
• No clear handoff between planning (GStack) and implementation (Superpowers)
• Context rot in long sessions — quality degrades as the context window fills up
• You don't know which skills to use when, or which to skip for your project type

This project solves all of that with routing rules, automatic context management, and a structured 4-phase workflow.

Why Both?

Every comparison article says "use both" but nobody explains how. This project fills that gap:

They never overlap. GStack focuses on what roles review the work. Superpowers focuses on how code gets written.

What's Included

• Claude Code Plugin with sixteen skills:
  • /setup-routing — Generates a tailored CLAUDE.md for new projects
  • /adapt — Adds routing to existing projects without losing your CLAUDE.md content
  • /autoimplement — Auto-advance through a multi-phase implementation plan by chaining /review and /pitfall-verification (which auto-chains /codex review + the third lens per tier) at each phase boundary. Skips the y/n prompts you'd always answer "yes" to when reviews pass. Active pre-flight (v2.14.0+, tightened in v2.14.2): unless the latest commit touching the plan path matches the pre-flight marker regex ^(chore|fix)\(plan\):[[:space:]]*pre-flight([[:space:]]|$), autoimplement itself runs pitfall + codex on the plan body before Phase 1 dispatch — closes the gap between /writing-plans and autonomous execution. The pre-flight step commits a marker (chore(plan): pre-flight reviewed clean (...) or fix(plan): pre-flight {reviews_ran} feedback) so subsequent runs skip it. Stops by default when any review flags actionable issues; severe findings (security/data-loss/correctness in test assertions) always stop regardless of policy; pitfall/codex per-phase findings can be treated as advisory via the upfront policy question. Hard refusals: fewer than 2 phases, missing per-phase commit steps, dirty working tree, on main/master branch, plan touches migrations / secrets / credentials / .env / .ssh.
  • /context-handoff — Writes a human-readable handoff to docs/superpowers/handoff.md before /clear or /compact. Auto-resumes on next session start. Different from gstack's /context-save — this lives in the repo and works cross-machine.
  • /htmlify — Generates beautiful, pedagogical HTML companions for MD artefakter (design docs, plans, handoffs). v2 (2.0.0): opt-in --plan flag aktiverer rich rendering med 9 visuelle komponenter (comparison-matrix, flowchart-svg, pullquote, callout-box, stats-bar, two-column, expandable, diff-card, feedback-panel). Plan'en genereres av Claude Code i samme sesjon (Max-plan compute — ingen Anthropic API-kall). Uten --plan: v1-template-rendering (backwards compatible). Auto-opens via --open flag (macOS); aggregated per-directory dashboard via htmlify dashboard <dir>. Optional PostToolUse hook auto-fires on artifact writes. Bun + TypeScript with its own test suite (skills/htmlify/tests/); sanitized via DOMPurify.
  • /pitfall-verification — Final-check skill run after any PRD, spec, plan, or code artifact. Multi-model orchestrator: Claude self-pitfall (max 2 rounds), then for substantive changes it auto-chains /codex review (ship-worthy tier) and /superpowers-gstack:third-lens-review (high-stakes tier), ending in an adversarial synthesis — no separate invocation to remember. Trivial changes get only the free self-pitfall pass. Stages fire without a confirmation prompt; cost is reported after each call.
  • /quality-review — Perceived-quality gate run after a PRD, spec, or implementation plan, before implementation begins. Hunts pitfalls that make a product feel cheap or broken even when it technically works (silent failures, missing loading/empty states, error recovery, state drift, animations, AI output, sudo flows). Complementary to /pitfall-verification: that one asks "will this work?", this one asks "will this feel good?".
  • /third-lens-review — External model house lens, normally auto-invoked by /pitfall-verification Stage 3 for high-stakes changes (architecture / real-time / security / contracts / migration-logic); invoke directly only for an ad-hoc third-house read. A different training distribution sees what two Western houses both took for granted (dead code, use-after-free, degraded-state bugs). Runs via OpenRouter (scripts/third-lens-review.py) on the patched artifact, then a mandatory adversarial synthesis (finding is real until refuted). Routing by --role: architecture=GLM-5.2 (default, OpenRouter), correctness=DeepSeek V4-Pro (OpenRouter), countersynthesis=OpenAI via the codex CLI. GLM/DeepSeek run on non-Western infra — keep sensitive artifacts (auth/keys/health/finance) to the self + Codex lenses. ~$0.05/run; key in macOS Keychain openrouter-api-key.
  • /macos-native-review — Apple-native conformance gate for macOS PRDs, specs, and plans. 12 HIG-citation-grounded categories: vocabulary, control choices, keyboard shortcuts, semantic colors, sheets/popovers/alerts, animation timing, privileged operations, accessibility, menu bar, app lifecycle, dock behavior, App menu. Every finding cites a developer.apple.com HIG page via WebFetch. Phase 0 self-check rejects non-macOS artifacts. Complementary to /pitfall-verification ("will this work?") and /quality-review ("will this feel good?") — this asks "is this Apple-native?".
  • /ios-native-review — Apple-native conformance gate for iOS/iPadOS PRDs, specs, and plans. 13 HIG-citation-grounded categories: vocabulary, controls/touch targets (44×44pt), navigation paradigm (tab bar / navigation stack / split view), modal presentation (.presentationDetents, .fullScreenCover, popover), gestures, system surfaces (safe area, Dynamic Island), keyboard handling, haptics, semantic colors, animation timing, privileged operations, accessibility (VoiceOver, Dynamic Type to AX5), app lifecycle. Every finding cites a developer.apple.com HIG (iOS) page via WebFetch. Phase 0 self-check rejects non-iOS artifacts. Same shape as /macos-native-review but iOS-specific surfaces and conventions.
  • /macos-e2e-scaffold — One-shot XCUITest scaffolding for macOS SwiftUI projects. Walks the Scene tree deterministically, generates ranked TIER-1/2/3 test stubs (Smoke + Happy-path + Error-recovery always; Modal/Menubar/Multi-window/Toolbar conditional on pattern detection). Suggests accessibility identifiers (<ViewName>_<ControlType>_<Purpose>) with batch confirmation, emits a Claude-readable xcresult runner script. Three project-type branches (xcodegen / SPM / plain .xcodeproj). Manual invocation only — modifies project files. Phase 0 self-check refuses non-Swift, non-SwiftUI, non-macOS, or already-scaffolded projects.
  • /ios-e2e-scaffold — iOS twin of /macos-e2e-scaffold: TabView/NavigationStack scene-walk, sheet/tab/push/gesture TIERs, iOS-Simulator xcresult runner. Manual invocation only; normally reached via /e2e-route.
  • /e2e-route — pure dispatcher for Swift E2E requests: reads platform × intent and routes to the right executor (scaffold skills, MCP-live simulator automation, visual review, or /ios-visual-explore). Names the executor + next action, then hands off.
  • /ios-visual-explore — Tier-2 visual exploration of an iOS/iPadOS app via Gemini computer-use: drives the app from screenshots, a context-aware vision critic flags visual issues, text-only Markdown report. For when the accessibility tree is insufficient; paid Gemini API per run.
  • /superpowers-gstack:office-hours-track-aware (v2.3.0+) — wraps upstream /office-hours for dual-track projects. Runs the gstack brainstorm, then infers track from the idea (native vs web signals), asks the platform question (iOS/macOS/both) inline only if needed, relocates the design doc into the project's docs/ directory, runs /htmlify --open so the rich HTML opens BEFORE the approval gate, and only then asks Approve / Revise / Restart. Suggests /superpowers-gstack:swiftui-design-consultation next for native tracks. Intercepts /office-hours via CLAUDE.md routing rules.
  • /superpowers-gstack:swiftui-design-consultation — Apple-canon design system consultation for SwiftUI projects; produces DESIGN.md + a Swift Package starter; chains into macos-native-review with HIG conformance budget. Inlines the platform question (iOS/macOS/both) on first run if .gstack/track is missing (v2.3.0+).
• Per-skill model routing (v0.2) — /setup-routing and /adapt emit a ## Model Routing section inside the generated CLAUDE.md. Routes by two axes: a per-skill base tier (fable/opus/sonnet/haiku) and a project-level domain-sensitivity modifier (very high/high/medium/low — inferred from project type and security signals). See skills/setup-routing/model-routing.md for the canonical table. Advisory — orchestrator-Claude consults it when dispatching subagents.
• Appendix — Skill internals, troubleshooting, and anti-patterns
• Automated update pipeline — GitHub Actions keeps the plugin in sync when upstream frameworks change

Tip: In autocomplete, type /setup-routing, /adapt, or /context-handoff — Claude Code matches on the skill name. The full prefixed form (e.g. /superpowers-gstack:adapt) also works.

Kickstart

Vibe coding with a flight plan. Because your AI already has opinions. Might as well make them good.

1. Install the frameworks

# Superpowers (in Claude Code)
/plugin marketplace add claude-plugins-official
/plugin install superpowers

# GStack
git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
cd ~/.claude/skills/gstack && ./setup

2. Install this plugin

# In Claude Code:
/plugin marketplace add Paretofilm/claude-marketplace
/plugin install superpowers-gstack@paretofilm-plugins

Restart Claude Code after installation.

Important: Start Claude Code from your project directory before running setup:

cd ~/Developer/my-project
claude

3. Set up your project

# New project:
/setup-routing

# Existing project:
/adapt

This generates a CLAUDE.md with routing rules tailored to your project type, tech stack, and deployment target.

4. Start working

The Workflow

┌─────────────────────────────────────────────────┐
│  PHASE 1: DISCOVERY & PLANNING (GStack)         │
│                                                  │
│  /office-hours    → Product framing              │
│  /plan-ceo-review → Strategic validation         │
│  /plan-eng-review → Architecture lock            │
│  /plan-design-review → Design validation         │
│  /autoplan        → Chains all three reviews     │
├─────────────────────────────────────────────────┤
│  PHASE 1.5: SPEC REVIEW (this plugin)            │
│                                                  │
│  /pitfall-verification → "will this work?"       │
│  /quality-review       → "will this feel good?"  │
│  /macos-native-review  → "is this Apple-native?" │
│                          (macOS projects only)   │
│  /ios-native-review    → "is this iOS-native?"   │
│                          (iOS/iPadOS only)       │
├─────────────────────────────────────────────────┤
│  PHASE 2: IMPLEMENTATION (Superpowers)           │
│                                                  │
│  /superpowers:brainstorming           → Refine   │
│  /superpowers:writing-plans           → TDD tasks│
│  /superpowers:subagent-driven-development → Build│
│  /superpowers:systematic-debugging    → Fix bugs │
├─────────────────────────────────────────────────┤
│  PHASE 3: REVIEW & QA (GStack)                   │
│                                                  │
│  /review          → Pre-landing code review      │
│  /qa <url>        → Browser-based testing        │
│  /cso             → Security audit               │
│  /design-review   → Visual audit                 │
├─────────────────────────────────────────────────┤
│  PHASE 4: SHIP & MONITOR (GStack)                │
│                                                  │
│  /ship            → Tests, coverage, PR          │
│  /canary          → Post-deploy monitoring       │
│  /retro           → Sprint retrospective         │
│  /document-release → Update docs                 │
└─────────────────────────────────────────────────┘

Phase transitions

Use /clear when switching between GStack and Superpowers phases (skip for small projects < 5 tasks). Before clearing after Phase 1, save key decisions:

# Save decisions, then clear
/clear
/superpowers:brainstorming
Adopt the design as-is from the Phase 1 design doc — focus on technical details only.

If review feedback needs code changes: /superpowers:receiving-code-review → fix → /review again.

Context Management

Long sessions degrade Claude's output quality — a problem known as context rot. GSD solves this with a full orchestration layer, but that creates nesting issues when combined with Superpowers' subagent-driven development (three layers of orchestration). This plugin takes a lighter approach:

How it works:

1. After /compact, Claude asks if you want to activate auto context handoff for the session
2. If yes, it keeps docs/superpowers/handoff.md updated as a living document — current task, decisions, next step
3. When context gets heavy again, Claude suggests /clear
4. After /clear, Claude automatically reads the handoff file, presents where you left off, and clears it — no "resume" command needed

Manual use: Run /context-handoff anytime to save state before a /clear.

No hooks, no orchestration overhead, no nesting. Just save and restore.

Common Scenarios

New Feature (Full Workflow)

/office-hours          → Frame the idea
/plan-ceo-review       → Validate scope
/plan-eng-review       → Lock architecture
  → Save key decisions to docs/
/clear
/pitfall-verification  → Spec-level: "will this work?"
/quality-review        → Spec-level: "will this feel good?"
[macOS only]
/macos-native-review   → Spec-level: "is this Apple-native?"
[iOS only]
/ios-native-review     → Spec-level: "is this iOS-native?"
/superpowers:brainstorming         → Adopt design, refine technical approach
/superpowers:writing-plans         → Break into TDD tasks
/pitfall-verification  → Plan-level: re-check after writing-plans
/superpowers:subagent-driven-development → Build it
/clear
/review                → Code review
/qa http://localhost:3000 → Browser testing
/cso                   → Security check
/ship                  → PR and deploy

Bug Fix

/superpowers:systematic-debugging  → Find root cause + fix with TDD
/clear
/review                → Verify the fix
/ship                  → Deploy

Small Feature (Skip Planning)

/superpowers:brainstorming         → Quick technical refinement
/superpowers:writing-plans         → TDD tasks
/superpowers:subagent-driven-development → Build it
/clear
/review → /ship

Tiny Project (< 5 tasks)

/superpowers:brainstorming         → Adopt quickly
/superpowers:writing-plans         → TDD breakdown
/superpowers:executing-plans       → Inline execution (no subagents)
/review → /ship

Skip Phase 1, skip /clear between phases, skip subagents, skip review specialists for < 200 LOC.

Security-Critical Feature

/office-hours → /plan-eng-review (security focus)
/clear
/superpowers:brainstorming → /superpowers:writing-plans → SDD
/clear
/cso                   → Security audit FIRST
/review → /qa → /ship → /canary

Quick Reference

Decision Tree

New idea or feature?
  YES → /office-hours (GStack)
  NO  →
    Bug?
      During coding?    → /superpowers:systematic-debugging
      During QA/prod?   → /investigate (GStack)
    Scope clear?
      YES → /superpowers:brainstorming
      NO  → /office-hours

Spec or plan written? (after writing-specs / writing-plans / plan-eng-review)
  → /pitfall-verification → /quality-review
  → [macOS] /macos-native-review
  → [iOS] /ios-native-review
  → /superpowers:writing-plans (or /superpowers:subagent-driven-development)

Code written?  → /clear → /review
Review feedback needs changes? → /superpowers:receiving-code-review → fix → /review
Review passed? → /qa → /cso → /ship

GStack Commands

Superpowers Commands

Model Routing (v0.2)

When orchestrator-Claude dispatches a subagent, it should pick the model based on the task being executed and the project's domain sensitivity, not the orchestrator's default. The full table lives at skills/setup-routing/model-routing.md. Highlights:

The recommendations are advisory v0.2. Domain sensitivity (inferred at setup/adapt time from project type and Q3 security signals) acts as a modifier: very-high/high domains floor coding at opus; medium uses the base tier; low can go one tier cheaper. See skills/setup-routing/model-routing.md for the full table with phase-level breakdowns and caveats.

How It Stays Up to Date

A GitHub Actions workflow runs weekly and checks for new versions of GStack, Superpowers, and Claude Code. When changes are found, it automatically updates the plugin and creates a PR. A self-repair workflow handles failures automatically.

See VERSIONS.md for currently tracked versions.

Testing

Plugin behaviors that depend on LLM dispatch (track-aware routing, slash-command interception) are tested end-to-end against claude --print. See tests/README.md for prerequisites, cost (~1 min per case, a few cents each), and what's covered.

bash tests/run.sh --integration

Contributing

This is a work in progress and any help is welcome:

• Try it out — Use the workflow on a real project and report what works and what doesn't
• Open issues — Bug reports, unclear documentation, missing scenarios
• Submit PRs — Fixes, improvements, new common scenarios
• Share your experience — Write about your setup or workflow adaptations

Areas that need help

• Testing with more project types (mobile, data pipelines, monorepos, infrastructure)
• Better routing heuristics for edge cases
• Integration testing after upstream framework updates

How to contribute

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Submit a PR

Frequently Asked Questions

Should I use GStack or Superpowers? Both. They cover different phases. This project gives you the workflow to combine them.

Can I use this with an existing project? Yes. Run /adapt — it preserves your existing CLAUDE.md and adds only the routing section.

Do I need both frameworks installed? Yes. Install both Superpowers and GStack, then add this plugin for routing.

What if I only want one framework? Each works fine on its own. This project is for people who want to use both together.

How does context management compare to GSD? GSD is a full orchestration framework with wave-based execution and state machines. It's powerful but creates nesting problems with Superpowers' SDD (three layers of orchestration). This plugin takes GSD's best idea — context hygiene — and implements it as a lightweight save/restore mechanism. If you want full GSD, install it separately.

Does this work with Cursor / Windsurf? No. Built for Claude Code only.

What project types does this support? Web apps, APIs, mobile, CLI tools, libraries, data pipelines, monorepos, Claude Code plugins, and more. The setup skill tailors routing to your project.

Keywords

claude code best setup claude code workflow gstack superpowers together best claude code plugins claude code TDD workflow ai coding workflow claude code skills agentic development workflow claude code framework comparison how to use gstack and superpowers claude code project setup CLAUDE.md generator claude code routing ai-assisted software development claude code context management context rot prevention claude code session management gsd alternative

A Note on How This Was Built

This entire project — the routing plugin, the skill evaluation tables, the consistency checks, and even this README — was developed by Claude Code using the very workflow it documents. No human wrote or edited the content. A human guided the direction and reviewed the results, but every line was authored by AI.

The workflow needed to make sense to an AI that would actually follow it, not just read well to a human skimming a README. The result is a set of instructions that Claude Code genuinely works well with — because it wrote them for itself.

Whether that's reassuring or unsettling is left as an exercise for the reader.

License

MIT

Acknowledgments

• Superpowers by Jesse Vincent — the implementation backbone
• GStack by Garry Tan — the planning and review backbone
• Built for Claude Code by Anthropic