| name | setup-routing |
| description | Generate a tailored CLAUDE.md with routing rules for the Superpowers + GStack workflow. Asks about project type, evaluates relevant skills from both frameworks, and produces a project-specific routing plan. |
Setup Routing — CLAUDE.md Generator
You are setting up the Superpowers + GStack combined workflow for a new project. Your job is to generate a CLAUDE.md file with routing rules tailored to this specific project.
Invoke this skill with: /superpowers-gstack:setup-routing
Dependency check: Before anything else, verify both upstream frameworks are installed. Run:
ls -d ~/.claude/plugins/cache/claude-plugins-official/superpowers/*/ 2>/dev/null | head -1
ls -d ~/.claude/skills/gstack/ 2>/dev/null
If either path is missing, STOP and tell the user:
This plugin is glue for two upstream frameworks. Install them first:
Missing: Superpowers — /plugin marketplace add claude-plugins-official then /plugin install superpowers
Missing: GStack — git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup
Only mention the framework(s) that are actually missing. Restart Claude Code after installing, then run /superpowers-gstack:setup-routing again.
Do NOT proceed until both frameworks are present.
Directory check: Verify that Claude Code's working directory is the target project. If the current directory appears to be a different project (e.g., the superpowers-gstack repo itself rather than the user's project), STOP and tell the user:
You're currently in [cwd]. This skill needs to run from your target project directory. Start a new Claude Code session:
cd /path/to/your-project && claude
Then run /superpowers-gstack:setup-routing again.
Important: If the project already has a CLAUDE.md file with existing content, STOP and suggest the user runs /superpowers-gstack:adapt instead — it preserves existing content while adding routing.
Version: The CLAUDE.md version marker is ALWAYS the installed plugin version read from plugin.json (see Step 6) — never a number stated in this file. (Historical feature labels like "v1.11.0 Model Routing" below refer to old marker generations, not to the value to write.)
Process
Follow these steps in order. Do NOT skip steps.
Step 1: Ask about the project
Ask the user ONE question:
What kind of project is this? (e.g., Swift iOS app, React/Next.js web app, Python API, Node.js backend, Flutter mobile app, Claude Code plugin/skill, data pipeline, infrastructure/Terraform, monorepo, static site, or describe it)
STOP HERE. Do not continue to the next step until the user responds. End your message with the question.
Step 2: Ask follow-up questions
Based on the project type, ask 3-5 focused follow-up questions. Always include questions 1-3. Add 4-9 based on relevance:
- What test framework will you use? (or "no tests yet")
- Will this be deployed? Where? (or not deployed)
- Any security concerns? (auth, user data, payments, external APIs — helps evaluate
/cso)
- Will this have a UI testable in a browser? What URL? (skip for CLI tools, libraries, pipelines)
- Is there a design component? (UI mockups, design system — skip for backend-only)
- Is this a team project with a regular cadence? (helps evaluate
/retro)
- Is this a long-running project or a one-off? (helps evaluate
/learn)
- Do you have existing linting, type checking, or test suites? (helps evaluate
/health)
- Is this a monorepo? Which directory will you work in? (helps evaluate
/freeze)
Ask all follow-up questions in a single message. STOP HERE. Do not continue to the next step until the user responds. Do not add suggestions or any other content after the questions. End your message with the questions.
Step 3: Evaluate relevant Superpowers skills
Based on the project type and answers, evaluate which Superpowers skills are relevant. Think through each one:
| Skill | Consider relevant when... |
|---|
/superpowers:brainstorming | Almost always — skip only for trivial projects |
/superpowers:writing-plans | Almost always — skip only for single-file changes |
/superpowers:subagent-driven-development | Projects with 5+ tasks, benefits from parallel TDD |
/superpowers:executing-plans | Smaller projects (< 5 tasks), or when user wants more control |
/superpowers:systematic-debugging | Any project with code that can have bugs |
/superpowers:dispatching-parallel-agents | Projects with clearly independent modules |
/superpowers:using-git-worktrees | Projects where feature isolation matters |
/superpowers:finishing-a-development-branch | Projects using feature branches and PRs |
/superpowers:test-driven-development | Projects with testable code (most projects) |
/superpowers:verification-before-completion | Complex projects where correctness is critical |
/superpowers:requesting-code-review | Multi-file changes (runs automatically during SDD, but can be invoked manually) |
/superpowers:receiving-code-review | After /review or PR feedback requires code changes — structures the response with TDD |
/superpowers:writing-skills | Only for Claude Code plugin/skill projects |
Step 4: Evaluate relevant GStack skills
Think through each GStack skill, organized by phase:
Phase 1 — Planning:
| Skill | Consider relevant when... |
|---|
/office-hours | New product ideas, features with unclear scope |
/plan-ceo-review | Projects with strategic decisions or significant scope |
/plan-eng-review | Projects needing architecture decisions |
/plan-design-review | Projects with UI/UX components |
/design-consultation | New projects defining a design system from scratch (creates DESIGN.md) |
/design-shotgun | When you want multiple design variants to compare before committing |
/plan-devex-review | Projects with developer-facing surfaces (APIs, CLIs, SDKs, libraries) |
/plan-tune | Tune plan-skill question preferences (one-time, per-project) |
/autoplan | When all three plan reviews are relevant — chains them automatically |
Phase 3 — Review & QA:
| Skill | Consider relevant when... |
|---|
/review | Almost always — pre-merge code review |
/qa <url> | Projects with a browser-accessible UI (include the URL) |
/qa-only <url> | Same, but report-only (no auto-fixes) |
/cso | Projects handling auth, user data, payments, or external APIs. For security-critical features, run BEFORE /review |
/design-review | Projects with visual UI — catches spacing, alignment, inconsistencies |
/design-html | When you have an approved design and need production HTML/CSS |
/devex-review | Developer-facing projects — live audit of onboarding flow, docs, CLI help |
/investigate | Bugs discovered AFTER Phase 2 — in QA, staging, or production. Do NOT use during Phase 2 implementation (use /superpowers:systematic-debugging instead) |
Phase 4 — Ship & Monitor:
| Skill | Consider relevant when... |
|---|
/ship | Projects using git with feature branches and PRs |
/land-and-deploy | Projects with CI/CD deployment pipelines |
/canary | Projects with production monitoring needs |
/landing-report | Read-only PR queue + sibling-workspace dashboard (workspace-aware ship) |
/setup-deploy | One-time: configure deploy platform (Fly.io, Vercel, Render, etc.) for /land-and-deploy |
/document-release | Projects with documentation to maintain |
/retro | Team projects with regular sprint cadence |
/learn | Long-running projects (> 2 weeks) — saves cross-session learnings |
/setup-gbrain | Long-running projects wanting cross-session memory (PGLite local or Supabase) |
/sync-gbrain | Long-running projects with gbrain — keeps the brain current with this repo's code and refreshes CLAUDE.md search guidance |
/health | Projects with existing linting, type checking, or test suites |
/make-pdf | Projects needing publication-quality documentation or reports |
Utility (any phase):
| Skill | Consider relevant when... |
|---|
/careful | Projects where destructive commands are risky (production DBs, shared infra) |
/freeze | Monorepos or projects where edits should be restricted TO a specific directory (allow-list, not block-list) |
/unfreeze | Clear the /freeze boundary mid-session without ending the session |
/guard | Production / shared-infra work — combines /careful warnings with /freeze directory lock |
/browse | Projects needing headless browser interaction beyond QA |
/scrape | Projects pulling data from web pages — prototypes a flow once, codifies it via /skillify |
/skillify | After a successful /scrape — persists the flow as a permanent browser-skill so future calls run in ~200ms |
/open-gstack-browser | Projects wanting a visible AI-controlled Chromium with live activity feed |
/pair-agent | When pairing a remote AI agent with your browser session |
/setup-browser-cookies | One-time: import cookies for authenticated /qa and /browse testing |
/context-handoff | Long implementation sessions, projects using SDD, or any multi-step workflow |
/htmlify | Any project — generates beautiful HTML companions for MD artefacts (design docs, plans, handoffs) so verbose output stays readable. Optional PostToolUse hook auto-fires. |
/context-save | Save progress and working state |
/context-restore | Resume where you left off |
/benchmark | Projects with performance monitoring needs |
/benchmark-models | Projects comparing AI model performance |
/codex | Projects needing second opinions or adversarial code review |
/superpowers-gstack:autoimplement | Multi-phase plans where the user always confirms phase boundaries — chains /review + /pitfall-verification automatically (pitfall auto-chains /codex review + the third lens per tier — no separate codex step). v2.14.0+ adds active pre-flight that reviews the plan body itself before Phase 1 unless the latest plan commit matches the marker regex ^(chore|fix)\(plan\):[[:space:]]*pre-flight([[:space:]]|$) (closes the gap between writing-plans and autoimplement). Refuses on <2 phases, missing per-phase commit steps, dirty tree, main/master branch, or plans touching migrations/secrets/credentials/.env/.ssh. |
/superpowers-gstack:office-hours-track-aware | All new-project brainstorming — wraps /office-hours with track inference (web vs native), inline platform question, design-doc relocation, htmlify --open, and approve-before-render gate. Intercepts /office-hours — see routing-intercept rules below. |
/superpowers-gstack:swiftui-design-consultation | Native SwiftUI projects — produces DESIGN.md + Swift Package starter; equivalent to /design-consultation for web. Inlines the platform question (iOS/macOS/both) on first run if .gstack/track is missing. |
/superpowers-gstack:macos-native-review | macOS apps — pre-implementation HIG-citation-grounded review (vocabulary, controls, keyboard shortcuts, semantic colors, sheets, menu bar, dock, App menu). Run on PRDs/specs/plans before implementation. Phase 0 detects macOS signals; auto-N/A for non-macOS projects. |
/superpowers-gstack:ios-native-review | iOS / iPadOS apps — pre-implementation HIG-citation-grounded review (vocabulary, touch targets, navigation paradigm, modal presentation, gestures, system surfaces, keyboard, haptics, semantic colors, animation, privileged operations, accessibility, lifecycle). Run on PRDs/specs/plans before implementation. Phase 0 detects iOS signals; auto-N/A for non-iOS projects. |
/superpowers-gstack:quality-review | After any PRD/spec/plan, before implementation — hunts perceived-quality pitfalls (silent failures, loading/empty states, error recovery, state drift). Complementary to pitfall-verification ("will it work?" vs "will it feel good?"). |
/superpowers-gstack:e2e-route | Swift projects — pure dispatcher for E2E test requests: reads platform × intent and routes to the right executor (scaffold skills, MCP-live simulator automation, visual review, ios-visual-explore). |
/superpowers-gstack:ios-e2e-scaffold | iOS SwiftUI apps — one-shot XCUITest scaffolding (TabView/NavigationStack scene-walk, TIER-ranked stubs, iOS-Simulator xcresult runner). Normally reached via /e2e-route. |
/superpowers-gstack:macos-e2e-scaffold | macOS SwiftUI apps — one-shot XCUITest scaffolding (Scene-walk, TIER-ranked stubs, xcresult runner). Normally reached via /e2e-route. |
/superpowers-gstack:ios-visual-explore | iOS/iPadOS apps — Tier-2 visual exploration via Gemini computer-use when the accessibility tree is insufficient (layout regressions, visual landmarks). Paid API per run; normally reached via /e2e-route. |
Step 5: Present the routing plan
Show the user which skills from each framework you've selected and why. Format as:
Superpowers (implementation):
- Skill — why it's relevant
GStack (by phase):
- Phase 1: Skill — why
- Phase 3: Skill — why
- Phase 4: Skill — why
Excluded:
- Skill — why it's not relevant for this project
Ask: "Does this look right? Any skills to add or remove?"
STOP HERE. Do not continue to the next step until the user responds. Do not generate the CLAUDE.md or add any other content. End your message with the question.
If the user wants changes, update your selection and re-present. Repeat until confirmed.
Step 5.5: Present model routing recommendations
Read skills/setup-routing/model-routing.md (sibling file in this skill's directory) — it holds the canonical per-skill base-tier recommendations and the domain-sensitivity axis (v0.2).
If model-routing.md does not exist (older cached plugin version, file deletion, etc.): tell the user "Model routing reference is unavailable — likely an older plugin cache. Run /plugin update superpowers-gstack and re-run this skill, or proceed without model routing." Then skip directly to Step 6 with the ## Model Routing section omitted.
Present the base-tier routing for this project:
Build a routing preview containing only the skills selected in Step 5 (skip everything excluded). Present as:
Model routing — base tiers:
| Skill | Base tier |
|---|
| [Skills from Step 5 confirmation, one per row] | [Base tier from model-routing.md] |
For skills marked see phases in model-routing.md, include a sub-table for that skill showing the per-phase recommendations.
Infer this project's domain sensitivity from the Step-2 answers and project type, using the domain table in model-routing.md:
- Real-time audio / DSP / signal processing, or any lock-free concurrency (incl. Swift audio engines, game-audio) → very high — NB: a plain Swift/SwiftUI CRUD or UI app with none of these signals is medium, not very high
- Database migrations / ETL / data-transform, OR security concerns named in Q3 (auth/payments/PII/external APIs) → high
- Web/mobile app UI feature work → medium
- CLI tools / libraries / format-plumbing / serialization → low
- If ambiguous, ask the user one line: "How silently could a subtle bug here compound — very high / high / medium / low?"
After presenting, ask:
Does this model routing look right? Any adjustments?
STOP HERE. Do not continue to Step 6 until the user responds. If adjustments are requested, update and re-present. If the user wants to keep model routing out of CLAUDE.md entirely, note that and skip the Model Routing section in Step 6.
Step 6: Generate CLAUDE.md
Generate the CLAUDE.md file in the project root. Adapt the structure below based on what's relevant — omit entire sections that don't apply.
Keep the generated content tight — every word is a per-session context tax on the project: routing-table row descriptions ≤ 15 words; decision-tree lines ≤ 10 words; no rationale prose in generated sections (the rules carry the behavior; the why lives in this plugin's docs).
Before writing the file, read the plugin version from .claude-plugin/plugin.json in the superpowers-gstack plugin directory (check ~/.claude/plugins/cache/*/superpowers-gstack/*/plugin.json, use the latest). Include this version as an HTML comment at the top of the generated CLAUDE.md:
<!-- superpowers-gstack: {version} -->
# [Project Name]
## Skill routing
This project uses Superpowers + GStack. Each owns a distinct phase:
### GStack — [list relevant phases, e.g., "Planning, Review, Shipping"]
**Planning:**
- [Only skills selected in Step 4, Phase 1]
**Review & QA:**
- [Only skills selected in Step 4, Phase 3]
**Ship & Monitor:**
- [Only skills selected in Step 4, Phase 4]
### Superpowers — Implementation
- [Only skills selected in Step 3]
### Routing Logic
[Generate a project-specific decision tree. See examples below.]
### Rules
- Never run GStack and Superpowers skills in the same phase
- Never nest subagents from different frameworks
- Use `/superpowers:systematic-debugging` for bugs found during implementation (Phase 2)
- Use `/investigate` only for bugs found in QA or production (Phase 3+)
- Superpowers specs go in `docs/superpowers/`
- GStack state lives in `~/.gstack/projects/`
### Session Continuity
On session start or after /compact: if `docs/superpowers/handoff.md` exists and contains content, read it and present a one-line summary of where you left off. Then proceed normally — do not ask "ready to continue?". Clear the file (write empty string) immediately after presenting the summary.
After /compact: if handoff.md does not contain `## Mode: auto`, ask the user once: "Context was compressed. Want me to activate auto context handoff for this session? I'll keep handoff.md updated and suggest /clear when context gets heavy." If yes, invoke the context-handoff skill.
### Session Management
- `/clear` when transitioning between GStack and Superpowers phases
- Save architecture decisions to `docs/` before clearing after Phase 1
- Reference key changes when starting Phase 3 review
- Skip `/clear` for small projects (< 5 tasks, < 30 min)
[SHARED BLOCKS — emit here, as top-level (H2) sections. Read each file from this
skill's `blocks/` directory (sibling of this SKILL.md) and paste its content
verbatim, in this order:
1. `blocks/autonomy.md`
2. `blocks/git-hygiene.md`
3. `blocks/multi-lens-review.md`
4. `blocks/code-reuse.md`
5. `blocks/track-routing.md`
6. `blocks/xcode-tools.md` — ONLY when `.gstack/track` is `ios`, `macos`, or `both`; skip for web
7. `blocks/companion-skills.md` — same native-track condition as xcode-tools.md
Resolve `{{...}}` placeholders per `blocks/PLACEHOLDERS.md` before writing — never
let a raw `{{...}}` token reach the generated CLAUDE.md. If the `blocks/` directory
is missing (older plugin cache), warn the user to run `/plugin update
superpowers-gstack` and omit these sections.]
[MODEL ROUTING — emit `blocks/model-routing-section.md` here verbatim, resolving
`{{DOMAIN_SENSITIVITY}}` per `blocks/PLACEHOLDERS.md`. Omit the whole section if the
user opted out in Step 5 or `model-routing.md` was unavailable.]
## Project
### Tech Stack
[From user answers]
### Testing
[Test framework and commands]
### QA
[QA URL if applicable — omit this section if no browser UI]
### Deployment
[Deployment target — omit if not deployed]
Routing Logic examples — adapt to the project, don't copy verbatim:
For a web app with UI:
New feature idea → /office-hours
Ready to build → /superpowers:brainstorming
Bug during coding → /superpowers:systematic-debugging
Bug found in QA → /investigate
Code complete → /review → /qa http://localhost:3000
Review feedback? → /superpowers:receiving-code-review → fix → /review again
Security-sensitive? → /cso (before /review)
Ready to ship → /ship
Trivial change → Just do it
For a CLI tool / library (no UI):
New feature idea → /office-hours
Ready to build → /superpowers:brainstorming
Bug fix → /superpowers:systematic-debugging
Code complete → /review
Review feedback? → /superpowers:receiving-code-review → fix → /review again
Ready to ship → /ship
Trivial change → Just do it
For a Claude Code plugin:
New skill idea → /superpowers:brainstorming
Writing skills → /superpowers:writing-skills
Bug fix → /superpowers:systematic-debugging
Code complete → /review
Ready to ship → /ship
Important rules for generation:
- Do NOT include skills that were excluded in Step 5
- Do NOT add generic descriptions — keep it actionable
- DO adapt the routing logic to this specific project type
- DO include the default QA URL if the user provided one
- DO include test commands if known
- Omit entire sections that don't apply (no empty "QA: N/A" sections)
- Model Routing section: emit the
## Model Routing block verbatim (from Step 5.5) with {{DOMAIN_SENSITIVITY}} replaced by the inferred value. If the user opted out of model routing in Step 5.5, omit the entire ## Model Routing section.
- Phase sub-tables: include inline only for multi-phase skills selected in Step 5 (e.g. skip the TDD sub-table if
/superpowers:test-driven-development is not in the selected set).
- Target 100-180 lines total (was 60-100 in v1.10.0 — Model Routing adds ~20 lines). Projects with many multi-phase skills can legitimately reach 200 lines. The 150-line "compliance budget" from v1.10.0 is officially relaxed to 200 lines starting v1.11.0 when Model Routing is present. To stay tight: omit phase sub-tables for skills not selected.
Step 7: Confirm
After writing the file, tell the user:
- What was generated and which skills were included
- Remind them to add project-specific conventions as they develop them
- Suggest next step based on project type (usually
/office-hours for new ideas or /superpowers:brainstorming if scope is already clear)
