| name | adapt |
| description | Adapt an existing project to the Superpowers + GStack workflow. Analyzes the project, identifies gaps, updates CLAUDE.md routing without losing existing content, and sets up required structure. |
Adapt to Superpowers + GStack
You are adapting an existing project to the Superpowers + GStack combined workflow. Unlike setup-routing (which is for new/empty projects), this skill preserves everything that already exists and makes only the changes needed for a smooth transition.
Invoke this skill with: /superpowers-gstack:adapt
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:adapt 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:adapt again.
Version check: The current version is ALWAYS the installed plugin version read from plugin.json (see the marker step) — never a number stated in this file. If the project's CLAUDE.md contains a version marker (<!-- superpowers-gstack: X.Y.Z -->) with an older version, inform the user that routing and session rules will be updated to the current version as part of this adaptation. Projects with an older Model Routing block (v0.1 ### Model Routing with Pi/MLX columns) will have it replaced by the new top-level ## Model Routing (v0.2, Claude-only, domain-aware); projects with none will gain one unless they opt out — surface this clearly so it's not a silent change. Projects on 1.11.1 or earlier will gain three new gstack skill rows (/sync-gbrain, /scrape, /skillify) in the evaluation tables.
Process
Follow these steps in order. Do NOT skip steps.
Step 1: Analyze the project
Read and analyze the following (skip any that don't exist):
- CLAUDE.md — existing instructions, conventions, routing rules
- Package files —
package.json, Package.swift, Cargo.toml, pyproject.toml, go.mod, Gemfile, plugin.json, etc.
- Test configuration —
jest.config.*, vitest.config.*, pytest.ini, .swiftpm/, Makefile test targets, etc.
- CI/CD —
.github/workflows/, .gitlab-ci.yml, Jenkinsfile, etc.
- Git state — current branch, remotes, branching strategy (check recent branch names)
- Project structure —
ls the root and key directories to understand the layout
- docs/ — existing documentation structure
Summarize what you found to the user. Be concise — focus on what matters for the transition.
Step 2: Identify the project type and stack
Based on Step 1, determine:
- Project type (web app, API, mobile, plugin, library, monorepo, etc.)
- Language(s) and frameworks
- Test framework and how to run tests
- Deploy target (if any)
- QA URL (if browser-testable)
- Whether it's a team or solo project
Present this to the user for confirmation:
Based on my analysis, this is a [type] using [stack]. Tests run with [command]. [Deployed to X / not deployed]. [Has browser UI at X / No browser UI].
Is this correct? Anything to add?
STOP HERE. Do not continue to the next step until the user responds. Do not add "Next steps", suggestions, or any other content after the question. End your message with the question.
Step 3: Evaluate relevant skills
Use the same evaluation tables as setup-routing to determine which Superpowers and GStack skills are relevant. The tables are reproduced here for reference:
Superpowers skills:
| 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 |
GStack skills — 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 |
GStack skills — 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) |
GStack skills — 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 |
GStack skills — Utility:
| 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 4: Identify gaps and plan changes
Compare the current project state against what Superpowers + GStack needs. Check each item:
CLAUDE.md routing:
Project structure:
Potential conflicts:
Present the gap analysis to the user:
Ready for Superpowers + GStack:
- [things that already work]
Needs changes:
- [what needs to be added/modified — be specific]
Potential conflicts:
- [anything that might cause issues]
Shall I proceed with these changes?
STOP HERE. Do not continue to the next step until the user responds. Do not add "Next steps", suggestions, or any other content after the question. End your message with the question.
Step 5: Apply changes
Apply the changes identified in Step 4. Follow these rules strictly:
CLAUDE.md updates:
- 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). Add or update an HTML comment at the very top of CLAUDE.md: <!-- superpowers-gstack: {version} -->
- If CLAUDE.md exists: READ it first, then INSERT or UPDATE the
## Skill routing section
- NEVER delete or rewrite existing sections (conventions, tech stack, project-specific rules)
- If a
## Skill routing section already exists: UPDATE its plugin-managed subsections per the per-section case-logic below (cases 1-4 for each marker-section). Do NOT wholesale-replace the entire Skill routing block — that would destroy any user-authored subsections nested inside (e.g. a hand-written ### Code reuse discipline markerless heading). The per-section logic handles every plugin-managed subsection individually; anything inside Skill routing that the per-section logic does NOT match must be PRESERVED verbatim, including its position and surrounding whitespace.
- If no
## Skill routing section exists: ADD it after the first heading (or at the top if no heading)
- The routing section follows the same template as
setup-routing Step 6, adapted to this project. 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).
- Model Routing (v0.2): read the canonical routing table from
~/.claude/plugins/cache/*/superpowers-gstack/*/skills/setup-routing/model-routing.md. Infer this project's domain sensitivity from the project analysis and Step 3 evaluation:
-
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 (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?"
-
First, replace any stale Model Routing block. If the project's existing CLAUDE.md already has a Model Routing section from a prior plugin version — whether a v0.1 ### Model Routing subsection (the one with Pi/MLX/local-model columns) or an older top-level ## Model Routing — DELETE that entire section (from its heading through the line before the next heading of equal-or-higher level) before emitting the new one. This is an explicit exception to the "never delete existing sections" rule above: Model Routing is fully plugin-managed, so a stale copy must be replaced, not preserved alongside the new block — otherwise the generated CLAUDE.md carries two contradictory routing tables (old Pi/MLX + new Claude-only).
-
Then emit a top-level ## Model Routing section (placed after ## Skill routing and all its subsections): read blocks/model-routing-section.md from the plugin's skills/setup-routing/blocks/ directory (same path resolution as model-routing.md above) and emit its content verbatim, substituting {{DOMAIN_SENSITIVITY}} with the inferred value.
-
Fallback: If model-routing.md is missing (older cached plugin), warn the user and skip the section entirely.
-
If the user opts out, skip this section entirely and note the choice in the final report
Shared block files. Every "block to insert" below is single-sourced in the plugin at skills/setup-routing/blocks/<name>.md (sibling skill directory — from this skill's base directory: ../setup-routing/blocks/<name>.md; via the cache glob: ~/.claude/plugins/cache/*/superpowers-gstack/*/skills/setup-routing/blocks/). Read the named file and use its content as the verbatim block. Resolve {{...}} placeholders per blocks/PLACEHOLDERS.md before inserting — 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 skip the affected sections.
Insert or upgrade the Autonomy and user interruption section. This section applies to ALL projects (web and native equally — agents over-asking is platform-agnostic). Scan CLAUDE.md for the heading ^#{2,3} Autonomy and user interruption and its version marker <!-- gstack-autonomy-vN -->. Apply the same four-case logic:
- Heading present + marker matches
v2 → skip (idempotent).
- Heading present + marker present + different version → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. If the existing root is H3 (nested under
## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level (H3 → H4) so subsections do not sit at the same level as the root — same demote requirement as case 4 below.
- Heading present + marker absent (legacy pre-v2.8.0) → REPLACE the same way; one-time silent upgrade adds the current marker.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on the v2.12.0 Code reuse section.
The block to insert: read blocks/autonomy.md (see Shared block files above) and insert its content verbatim.
Insert or upgrade the Git hygiene & commit cadence section. This section applies to ALL projects (git is universal). Scan CLAUDE.md for heading ^#{2,3} Git hygiene and its version marker <!-- gstack-git-hygiene-vN -->. Apply the same four-case logic:
- Heading present + marker matches
v3 → skip (idempotent).
- Heading present + marker
v1 or v2 (older emitters — universalist convention rule, autonomy cross-ref missing, stash advice without WIP-branch caveat) OR different version → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. (The Git hygiene block has H4 subsections; "next heading" alone would stop at the first one and leave old v1 prose behind.) If the existing root is H3 (nested under ## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level so subsections do not sit at the same level as the root — same demote requirement as case 4 below.
- Heading present + marker absent → REPLACE the same way; one-time silent upgrade adds the current marker.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on the v2.12.0 Code reuse section.
The block to insert: read blocks/git-hygiene.md (see Shared block files above) and insert its content verbatim.
Insert or upgrade the Multi-lens review section. This section applies to ALL projects (review hygiene is universal). Scan CLAUDE.md for heading ^#{2,3} Multi-lens review and its version marker <!-- gstack-multi-lens-review-vN -->. Apply the same four-case logic:
- Heading present + marker matches the current version (
v5) → skip (idempotent).
- Heading present + marker present + different version → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. If the existing root is H3 (nested under
## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level (H3 → H4) so subsections do not sit at the same level as the root — same demote requirement as case 4 below. (The Multi-lens review block has H4 subsections; "next heading" alone would stop at the first one and leave old prose behind.)
- Heading present + marker absent → REPLACE the same way; one-time silent upgrade adds the current marker.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on the v2.12.0 Code reuse section.
The block to insert: read blocks/multi-lens-review.md (see Shared block files above) and insert its content verbatim.
Insert or upgrade the Code reuse discipline section. This section applies to ALL projects (the agentic-duplication failure mode is platform-agnostic). Scan CLAUDE.md for heading ^#{2,3} Code reuse discipline and its version marker <!-- gstack-code-reuse-vN -->. Apply the four-case logic, but with a CRITICAL difference from the other marker-managed sections in case 3:
- Heading present + marker matches
v2 → skip (idempotent).
- Heading present + marker present + different version → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. If the existing root is H3 (nested under
## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level (H3 → H4) so subsections do not sit at the same level as the root — same demote requirement as case 4 below. (The Code reuse block has subsections one level below the root; "next heading" alone would stop at the first subsection and leave old prose behind.)
- Heading present + marker absent → PRESERVE, do NOT replace. This section was newly introduced in v2.12.0 of the plugin — markerless
Code reuse discipline headings cannot be pre-marker plugin content, which means they are user-authored sections that happen to share the heading. Replacing them would silently destroy the user's hand-written content. Instead, leave the user's section intact and surface a notice to the user in the adapt summary: "Found existing markerless Code reuse discipline section in CLAUDE.md; preserved as-is. To switch to the plugin-managed version, delete your existing section and re-run /adapt." This is the key difference from the other marker-sections (Autonomy, Git hygiene, Multi-lens review, etc.) where case 3 legitimately treats markerless content as pre-marker plugin legacy.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on this section at ship time.
The block to insert: read blocks/code-reuse.md (see Shared block files above) and insert its content verbatim.
Preserve or upgrade existing Track-aware routing. Before
inserting the Track-aware routing section, scan the project's
CLAUDE.md. Check two things independently: (a) does any heading
matching ^#{2,3} Track-aware routing \(dual-track\) exist (H2 or
H3 — setup-routing emits H3 as subsection, adapt historically
emitted H2 as top-level), and (b) is there a version marker
<!-- gstack-routing-vN --> on that heading line (currently v1).
Four cases:
- Heading present + marker matches current version (
v1) →
skip (idempotent — re-running adapt does not pollute the file).
- Heading present + marker present + different version →
REPLACE the section from the heading down to (but not including)
the next heading of the same OR shallower level. Preserves
surrounding CLAUDE.md content. This is how routing rules evolve
without manual editing across N projects. Preserve the original
heading level (H2 or H3) — do not change it during upgrade.
- Heading present + marker absent (legacy v2.3.0/v2.3.1
projects) → REPLACE the section the same way as case 2. Treats
the missing marker as "older than v1". This is a one-time silent
upgrade; the content replaced is byte-identical to what's already
there in v2.3.2, plus the marker. Preserve the original heading
level.
- Heading absent → APPEND the full section as H2 (truly new
adaptations, or projects that never had dual-track routing).
The version marker is an HTML comment so it does not render in
Markdown previews. Bump the version (v1 → v2) only when the
section's semantics change, not for cosmetic edits.
The block to insert: read blocks/track-routing.md (see Shared block files above) and insert its content verbatim.
Insert or upgrade the Native Apple development tools section. Only emit this section when .gstack/track exists and equals ios, macos, or both (skip entirely for web-only projects). Scan CLAUDE.md for the heading ^#{2,3} Native Apple development tools and its version marker <!-- gstack-xcode-tools-vN -->. Apply the same four-case logic as Track-aware routing above:
- Heading present + marker matches
v4 → skip (idempotent).
- Heading present + marker
v1, v2, or v3 (v1 assumed XcodeBuildMCP universally; v2 added CLI fallback but missed capabilities; v3 hardcoded one team's DEVELOPMENT_TEAM as default/signing/portal split) → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. (The Native Apple tools block has H4 subsections; "next heading" alone would stop at the first one and leave old prose behind.) If the existing root is H3 (nested under ## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level so subsections do not sit at the same level as the root — same demote requirement as case 4 below. Auto-upgrade is what the marker pattern is for.
- Heading present + marker absent (pre-v2.7.0) → REPLACE the same way; one-time silent upgrade adds the current marker.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on the v2.12.0 Code reuse section.
The block to insert: read blocks/xcode-tools.md (see Shared block files above) and insert its content verbatim.
Insert or upgrade the Companion skills (discovery) section. Only emit when .gstack/track exists and equals ios, macos, or both (skip for web-only projects). Scan CLAUDE.md for heading ^#{2,3} Companion skills and its version marker <!-- gstack-companion-skills-vN -->. Apply the same four-case logic:
- Heading present + marker matches
v2 → skip (idempotent).
- Heading present + marker present + different version → REPLACE through next heading of equal-or-shallower level. Preserve original heading level. If the existing root is H3 (nested under
## Skill routing, as pre-2.34.0 setup-routing emitted), you MUST demote every subsection in the replacement block one level (H3 → H4) so subsections do not sit at the same level as the root — same demote requirement as case 4 below.
- Heading present + marker absent → REPLACE the same way; one-time silent upgrade adds the current marker.
- Heading absent → APPEND the block below as H2 (subsections stay at H3, one level below the root — the REPLACE-through-equal-or-shallower-heading invariant holds). If you instead insert the block under
## Skill routing as H3 to match setup-routing's structure, you MUST also demote every H3 subsection in the block to H4. Otherwise the H3 subsections sit at the SAME level as the H3 root, and the next marker upgrade stops at the first subsection and leaves stale content behind — same heading-hierarchy class bug /codex review flagged on the v2.12.0 Code reuse section.
The block to insert: read blocks/companion-skills.md (see Shared block files above) and insert its content verbatim.
- If no
## Session Continuity section exists in CLAUDE.md: ADD the following block. If it already exists, REPLACE it with the current version:
## 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 guard for this session? I'll keep handoff.md updated and suggest /clear when context gets heavy." If yes, invoke the context-handoff skill.
Structure setup:
- Create
docs/superpowers/specs/ and docs/superpowers/plans/ if they don't exist
- Add a
.gitkeep in each empty directory
Git preparation:
- If on
main with uncommitted work: warn the user, do NOT create branches automatically
- If on
main with clean state: suggest creating a feature branch for the adaptation itself
What NOT to change:
- Existing test configuration
- CI/CD pipelines
- Git hooks (unless they directly conflict)
- Code style / linting configuration
- Any existing CLAUDE.md content outside the routing section
Step 6: Verify and report
After applying changes, verify:
- Read the updated CLAUDE.md and confirm routing section is correct
- Confirm
docs/superpowers/ directories exist
- Check that no existing content was lost
Report to the user:
Changes made:
Preserved:
- [existing CLAUDE.md content that was kept]
Then ask:
Would you like me to run a comprehensive review of the adaptation? This will check that:
- All routing rules are consistent with your project structure
- No existing CLAUDE.md content was lost or corrupted
- The selected skills match your actual tech stack, test setup, and deployment
- docs/superpowers/ structure is correct
- There are no conflicts between existing project conventions and the new workflow
The review takes a minute but catches issues before you start using the workflow. Recommended for projects with complex existing setups.
STOP HERE. Do not continue to Step 7 or add any other content. End your message with the question above. Wait for the user's response before proceeding.
If the user says yes, run the review:
- Re-read the updated CLAUDE.md end-to-end and check for internal consistency
- Cross-check routing against project files — does the routing reference skills that don't make sense? (e.g.,
/qa listed but no browser UI, /cso listed but no auth/user data)
- Verify preserved content — diff the old vs new CLAUDE.md mentally. Was anything accidentally removed or mangled?
- Check for contradictions — do existing CLAUDE.md instructions conflict with the new routing rules?
- Validate structure — do all referenced directories exist? (
docs/superpowers/specs/, docs/superpowers/plans/)
- Test routing logic — walk through 3-4 common scenarios for this project type and verify the decision tree produces the right skill
Report findings. If issues are found, fix them immediately and re-verify.
Step 7: Suggest next steps
After the review (or if the user skipped it):
Next steps:
- [suggest the appropriate first action based on project state]
- Working on a new feature? →
/superpowers:brainstorming
- Have code ready for review? →
/review
- Starting fresh? →
/office-hours
Tip: Run /superpowers-gstack:adapt again after major project changes (new deploy target, added test framework, etc.) to update routing.
