chore(config): superpowers citers by bare name, routing map, docs, settings

Every superpowers-prefixed skill call in ship-feature, init-project, tour,
deploy, audit-delta, plugin-advisor and lib/analyze-before-plan now names
the vendored skill directly. finishing-a-development-branch is described
as the upstream skill this config does not vendor (gitflow finish is the
integration path). CLAUDE.global.md Skill routing maps the four
non-vendored skills the vendored text still references. settings.json
loses the plugin key and its marketplace block; README, USAGE,
plugin-advisor and the profile skill describe superpowers as vendored
skills, always on, zero plugin cost. CHANGELOG entry with a known
residual.
This commit is contained in:
bastien
2026-09-28 14:54:53 +02:00
parent 18f8c898f8
commit ddea411491
16 changed files with 121 additions and 77 deletions
+32
View File
@@ -379,6 +379,21 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
`plugins.lock.json` pin 3.2.0 → 4.1.0 (the CLI only: the skill dist and `plugins.lock.json` pin 3.2.0 → 4.1.0 (the CLI only: the skill dist and
the engine binary have their own release tracks). `link.sh` drops the engine binary have their own release tracks). `link.sh` drops
impeccable from `EXTERNAL_SKILLS`; `skills-external/impeccable/` is gone. impeccable from `EXTERNAL_SKILLS`; `skills-external/impeccable/` is gone.
- **Superpowers plugin replaced by 7 vendored skills** (tier 2 of the
skill-catalog prune, BDR-105/106). `brainstorming`, `writing-plans`,
`subagent-driven-development`, `test-driven-development`,
`requesting-code-review`, `using-git-worktrees` and `writing-skills` are
curled byte-for-byte from `obra/superpowers` at the v6.4.1 commit
(`5bf4e78011075bcfc0dc295f0724994cd123ee71`) via `lib/vendor-skills.sh`
(new `superpowers` entry in `plugins.lock.json`, `always_on: true`),
linked by `link.sh` like the other externals: always on, no profile lists
them, same as `darwin-skill`. Every `superpowers:<skill>` citer across
`skills/`, `agents/` and `lib/` is renamed to the bare skill name.
`CLAUDE.global.md` Skill routing gains a map for the 4 dropped skills this
config used to reference: `executing-plans` to
`subagent-driven-development`, `finishing-a-development-branch` to
`gitflow finish`, `systematic-debugging` to `/bugfix`,
`verification-before-completion` to the verifier gates.
### Security ### Security
- **Ten secret-reader deny rules added**: `sed`, `awk`, `cut`, `tr`, - **Ten secret-reader deny rules added**: `sed`, `awk`, `cut`, `tr`,
@@ -433,6 +448,15 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
with it: the 4 `mcp__magic__*` `permissions.ask` entries (BDR-059), the with it: the 4 `mcp__magic__*` `permissions.ask` entries (BDR-059), the
`MAGIC_API_KEY` block in `.env.example`, `link.sh`'s missing-key warning, `MAGIC_API_KEY` block in `.env.example`, `link.sh`'s missing-key warning,
and the dead `MAGIC_API_KEY=abc123` gitleaks allowlist regex. and the dead `MAGIC_API_KEY=abc123` gitleaks allowlist regex.
- **Superpowers plugin uninstalled**: its 8 other skills
(`executing-plans`, `finishing-a-development-branch`,
`systematic-debugging`, `verification-before-completion`,
`dispatching-parallel-agents`, `receiving-code-review`,
`using-superpowers`, `diagnosing-superpowers`) and its SessionStart
injection (`using-superpowers`, ~3.6 KB every session start) are gone
with it. `lib/profile.sh` no longer protects it; `lib/detect-plugins.sh`
`detect_superpowers` now checks the linked vendored skill instead of the
plugin cache or `claude plugin list`.
### Fixed ### Fixed
- **gstack's shared helper tree was mostly unreachable.** gstack skills - **gstack's shared helper tree was mostly unreachable.** gstack skills
@@ -505,6 +529,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
`21st-ui-build` and `21st-cli-use` still point at the now-`max`-only `21st-ui-build` and `21st-cli-use` still point at the now-`max`-only
21st trio. A Skill call on a parked name fails, and the doctrine 21st trio. A Skill call on a parked name fails, and the doctrine
routing in `CLAUDE.global.md` applies instead. routing in `CLAUDE.global.md` applies instead.
- The 7 vendored superpowers skills are byte-for-byte upstream text, never
edited: their internal `superpowers:<x>` mentions and references to the
8 non-vendored skills stay in the prose (their own text, not ours to
patch). `CLAUDE.global.md` Skill routing carries the map for the 4 of
those this config used to reference. After a rollback that re-installs
the plugin while the 7 symlinks are still linked, delete the
`skills/<7>` symlinks or re-run `make plugin` to avoid duplicate skill
descriptions.
## [1.5.0] — 2026-09-13 ## [1.5.0] — 2026-09-13
+6
View File
@@ -258,6 +258,12 @@ cryptic names.
- Design / UI (build, system, audit, polish) → "Design work" below - Design / UI (build, system, audit, polish) → "Design work" below
- Architecture review → plan-eng-review - Architecture review → plan-eng-review
- Before /clear or /compact → capitalize; end-of-session ritual → close - Before /clear or /compact → capitalize; end-of-session ritual → close
- superpowers skills are vendored, called by bare name; an upstream
`superpowers` prefix names the same skill. Not vendored here:
executing-plans → subagent-driven-development
finishing-a-development-branch → `gitflow finish` (human signal)
systematic-debugging → bugfix
verification-before-completion → the verifier gates
- SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate; - SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate;
security audit (secrets, CVE, OWASP) → cso security audit (secrets, CVE, OWASP) → cso
gstack OFF → its skills (investigate, qa, review, health, retro, gstack OFF → its skills (investigate, qa, review, health, retro,
+1 -1
View File
@@ -118,7 +118,7 @@ ctx7 login # optional: OAuth / API key for higher rate limits
| Component | Type | Description | Docs | | Component | Type | Description | Docs |
|---|---|---|---| |---|---|---|---|
| **Superpowers** | Plugin (required) | Brainstorming, planning, subagent-driven dev, code review, branch finishing. Required by `/init-project` and `/ship-feature`. | [obra/superpowers-marketplace](https://github.com/obra/superpowers-marketplace) | | **Superpowers skills** | Vendored (7, always on) | brainstorming, writing-plans, subagent-driven development, TDD, code review request, git worktrees, writing-skills — pinned v6.4.1 in plugins.lock.json, no plugin, no session injection | [obra/superpowers](https://github.com/obra/superpowers) |
| **GStack** | Plugin (toggle) | Full-product workflow: UI + design + deploy + browser QA. Skip for backend/CLI projects. | [garrytan/gstack](https://github.com/garrytan/gstack) | | **GStack** | Plugin (toggle) | Full-product workflow: UI + design + deploy + browser QA. Skip for backend/CLI projects. | [garrytan/gstack](https://github.com/garrytan/gstack) |
| **GSD v2** | External CLI | Multi-session orchestration: crash recovery, cost tracking, parallel workers, context-fresh execution. | [gsd-build/gsd-2](https://github.com/gsd-build/gsd-2) | | **GSD v2** | External CLI | Multi-session orchestration: crash recovery, cost tracking, parallel workers, context-fresh execution. | [gsd-build/gsd-2](https://github.com/gsd-build/gsd-2) |
| **RTK** | Plugin (always on) | Code rewrite hook. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | | **RTK** | Plugin (always on) | Code rewrite hook. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
+16 -15
View File
@@ -181,8 +181,8 @@ Deploy + QA browser → gstack ON
Next.js/React/Prisma → context7 ON (WARN si absent, pas BLOCK) Next.js/React/Prisma → context7 ON (WARN si absent, pas BLOCK)
Multi-session (>1 jour) → gsd v2 CLI (gsd dans terminal) Multi-session (>1 jour) → gsd v2 CLI (gsd dans terminal)
Backend/CLI seulement → tout OFF sauf superpowers Backend/CLI seulement → tout OFF (skills superpowers vendorisés, toujours actifs, 0 t passif)
Hotfix/quick fix → tout OFF sauf superpowers Hotfix/quick fix → tout OFF (skills superpowers vendorisés, toujours actifs, 0 t passif)
``` ```
**GSD v2** n'est pas un plugin Claude Code — c'est un CLI externe. Il ne consomme pas de tokens passifs. Tu le lances dans un terminal séparé avec `gsd`, puis `/gsd auto` pour le mode autonome. **GSD v2** n'est pas un plugin Claude Code — c'est un CLI externe. Il ne consomme pas de tokens passifs. Tu le lances dans un terminal séparé avec `gsd`, puis `/gsd auto` pour le mode autonome.
@@ -586,7 +586,7 @@ ONBOARD COMPLETE: mycli
→ SIGNALS: none (CLI pur) → SIGNALS: none (CLI pur)
→ DISABLE: ui-ux-pro-max, gstack, context7 → DISABLE: ui-ux-pro-max, gstack, context7
→ KEEP: superpowers → (skills superpowers vendorisés, toujours actifs, 0 t passif)
→ COST: ~800t (minimal) → COST: ~800t (minimal)
→ ACTION REQUIRED? NO → ACTION REQUIRED? NO
``` ```
@@ -647,7 +647,7 @@ DO NOT TOUCH:
/plugin-check "CLI Rust, convertisseur de fichiers JSON/CSV/TOML, pas de réseau, pas de frontend" /plugin-check "CLI Rust, convertisseur de fichiers JSON/CSV/TOML, pas de réseau, pas de frontend"
→ SIGNALS: none (CLI pur, pas de deploy, pas de frontend) → SIGNALS: none (CLI pur, pas de deploy, pas de frontend)
→ KEEP: superpowers → (skills superpowers vendorisés, toujours actifs, 0 t passif)
→ DISABLE: ui-ux-pro-max, gstack, context7 → DISABLE: ui-ux-pro-max, gstack, context7
→ COST: ~800t (base seulement) → COST: ~800t (base seulement)
→ ACTION REQUIRED? NO → ACTION REQUIRED? NO
@@ -748,7 +748,7 @@ Simple à valider. L'architecture proposée est plate, pas de surprise.
**Contexte :** module `services/payment_service.py` dans un projet FastAPI existant. Écrit il y a 2 ans, jamais refactorisé. Violations connues : fonctions de 80 lignes, global state, pas de tests unitaires, logique métier mélangée avec appels HTTP. **Contexte :** module `services/payment_service.py` dans un projet FastAPI existant. Écrit il y a 2 ans, jamais refactorisé. Violations connues : fonctions de 80 lignes, global state, pas de tests unitaires, logique métier mélangée avec appels HTTP.
**Setup :** projet déjà onboardé (CLAUDE.md présent), superpowers actif, plugins inutiles désactivés. **Setup :** projet déjà onboardé (CLAUDE.md présent), skills superpowers vendorisés (toujours actifs, 0 t passif), plugins inutiles désactivés.
#### Étape 1 — Analyse avant toute modification #### Étape 1 — Analyse avant toute modification
@@ -861,7 +861,7 @@ PROJECT STATUS
CONFIG CONFIG
Version : v2.5.0 Version : v2.5.0
Plugins ON: superpowers, context7 (~1000t) Plugins ON: context7 (~200t), skills superpowers vendorisés (toujours actifs, 0 t passif)
GSD v2 : installed (2.64.0) GSD v2 : installed (2.64.0)
PROJECT PROJECT
@@ -956,19 +956,20 @@ GSD v2 met à jour le plan dans `.gsd/ROADMAP.md` sans perdre le travail déjà
/plugin-check "Firmware C STM32, bare-metal, pas de réseau, pas de frontend, pas de Docker" /plugin-check "Firmware C STM32, bare-metal, pas de réseau, pas de frontend, pas de Docker"
SIGNALS: simple, CLI/embedded SIGNALS: simple, CLI/embedded
COST: ~800t (superpowers seul) COST: ~0t (skills superpowers vendorisés, toujours actifs, 0 t passif)
RECOMMENDATIONS: RECOMMENDATIONS:
OK KEEP : superpowers (peut être utile pour brainstorm initial)
DISABLE : ui-ux-pro-max, gstack, context7 DISABLE : ui-ux-pro-max, gstack, context7
NOTE : Pour un firmware vraiment simple (hotfix, modification ciblée), NOTE : skills superpowers (brainstorming, writing-plans...) restent
même superpowers peut être désactivé → ~0t passif disponibles par nom bare sans coût passif, même pour un
firmware minimal.
``` ```
**Workflow minimaliste — modification d'un driver existant :** **Workflow minimaliste — modification d'un driver existant :**
``` ```
# Pas de /init-project, pas de GSD, pas de superpowers # Pas de /init-project, pas de GSD ; skills superpowers vendorisés
# (toujours actifs, 0 t passif) mais non invoqués ici
# 1. Comprendre avant de modifier # 1. Comprendre avant de modifier
/analyze src/drivers/uart.c /analyze src/drivers/uart.c
@@ -992,7 +993,7 @@ OUTPUT:
/ship-feature "Corriger l'accès non-atomique au ring_buffer_head dans l'ISR" /ship-feature "Corriger l'accès non-atomique au ring_buffer_head dans l'ISR"
STEP 0b — CLAUDE.md found STEP 0b — CLAUDE.md found
STEP 0 — plugin check: superpowers OK (ou désactivé si YOLO mode) STEP 0 — plugin check: skills superpowers vendorisés (toujours actifs, 0 t passif)
STEP 1 — BRAINSTORM (rapide, contexte déjà clair depuis /analyze): STEP 1 — BRAINSTORM (rapide, contexte déjà clair depuis /analyze):
Design: protéger ring_buffer_head avec __disable_irq()/__enable_irq() Design: protéger ring_buffer_head avec __disable_irq()/__enable_irq()
@@ -1015,7 +1016,7 @@ STEP 4 — IMPLEMENT (subagents légers, modifications chirurgicales)
``` ```
**Points clés :** **Points clés :**
- `/plugin-check` confirme "superpowers seulement" → aucun plugin inutile actif. - `/plugin-check` confirme qu'aucun plugin inutile n'est actif (skills superpowers vendorisés, toujours actifs, 0 t passif).
- `/analyze` est particulièrement utile sur du code C bas-niveau : l'analyzer identifie les accès non-atomiques, les race conditions, les violations de normes, **sans proposer de fix**. - `/analyze` est particulièrement utile sur du code C bas-niveau : l'analyzer identifie les accès non-atomiques, les race conditions, les violations de normes, **sans proposer de fix**.
- Pour un firmware, le workflow `analyze → ship-feature` peut se réduire à `analyze → edit direct` si la modification est triviale. - Pour un firmware, le workflow `analyze → ship-feature` peut se réduire à `analyze → edit direct` si la modification est triviale.
- GSD v2 n'est jamais pertinent pour du firmware : les sessions sont courtes et les tâches atomiques. - GSD v2 n'est jamais pertinent pour du firmware : les sessions sont courtes et les tâches atomiques.
@@ -1031,7 +1032,7 @@ Prisma / Supabase → context7 ON
"design élaboré" / tokens → ui-ux-pro-max ON "design élaboré" / tokens → ui-ux-pro-max ON
Docker + QA browser → gstack ON Docker + QA browser → gstack ON
"plusieurs semaines" → gsd v2 CLI "plusieurs semaines" → gsd v2 CLI
Rust / Python / Go / C → tout OFF sauf superpowers Rust / Python / Go / C → tout OFF (skills superpowers vendorisés, 0t)
Mobile / Flutter / RN → gstack OFF Mobile / Flutter / RN → gstack OFF
Hotfix / script rapide → tout OFF sauf superpowers Hotfix / script rapide → tout OFF (skills superpowers vendorisés, 0t)
``` ```
+23 -21
View File
@@ -77,7 +77,7 @@ Factors (weighted):
| Infra/deploy | 15% | Local only | Single deploy target | Multi-env, CI/CD, containers, monitoring | | Infra/deploy | 15% | Local only | Single deploy target | Multi-env, CI/CD, containers, monitoring |
**Score thresholds:** **Score thresholds:**
- **0-30% (simple)**: superpowers only. No gstack, no gsd, no ctx7, no graphify. - **0-30% (simple)**: superpowers skills only (vendored, always on). No gstack, no gsd, no ctx7, no graphify.
_Examples: site vitrine, landing page, script CLI, simple CRUD._ _Examples: site vitrine, landing page, script CLI, simple CRUD._
- **30-60% (moderate)**: + context7 if fast-libs. graphify only once the codebase passes 200 tracked code files (session-start banner informs, the user decides — BDR-097), never at scaffold. - **30-60% (moderate)**: + context7 if fast-libs. graphify only once the codebase passes 200 tracked code files (session-start banner informs, the user decides — BDR-097), never at scaffold.
_Examples: blog with auth, dashboard with charts, API with validation._ _Examples: blog with auth, dashboard with charts, API with validation._
@@ -143,7 +143,7 @@ ACTION REQUIRED? YES / NO
| `fast-libs` | context7 | — | Doc freshness critical | | `fast-libs` | context7 | — | Doc freshness critical |
| `multi-agent` + `complex-arch` | gsd v2 CLI | — | GSD v2 preferred for multi-session coordination | | `multi-agent` + `complex-arch` | gsd v2 CLI | — | GSD v2 preferred for multi-session coordination |
| `simple` / single-session | — | gsd, gstack, ui-ux-pro-max | Saves ~3000-5000t | | `simple` / single-session | — | gsd, gstack, ui-ux-pro-max | Saves ~3000-5000t |
| `embedded` / firmware | — | all toggles; superpowers optional | workflow: /analyze → /hotfix or /bugfix or /ship-feature | | `embedded` / firmware | — | all toggles (superpowers skills vendored, always on) | workflow: /analyze → /hotfix or /bugfix or /ship-feature |
| backend/lib/CLI only | — | ui-ux-pro-max, gstack | ~3100t saved | | backend/lib/CLI only | — | ui-ux-pro-max, gstack | ~3100t saved |
| small project / hotfix | — | gstack, gsd | Use /hotfix, /bugfix, or /feat | | small project / hotfix | — | gstack, gsd | Use /hotfix, /bugfix, or /feat |
@@ -174,12 +174,12 @@ When the plugin-advisor detects a `simple` or `hotfix` signal, suggest the appro
| Pair | Relation | Verdict | | Pair | Relation | Verdict |
|---|---|---| |---|---|---|
| gstack ↔ gsd v2 | ✅ Complementary | GStack = full-product CC workflow. GSD v2 = multi-session CLI. Different scopes, no conflict. | | gstack ↔ gsd v2 | ✅ Complementary | GStack = full-product CC workflow. GSD v2 = multi-session CLI. Different scopes, no conflict. |
| superpowers ↔ gsd v2 | ✅ Complementary | Superpowers = single-session execution. GSD v2 = multi-session CLI orchestration. No conflict. | | superpowers ↔ gsd v2 | ✅ Complementary | superpowers skills (vendored) = single-session execution. GSD v2 = multi-session CLI orchestration. No conflict. |
| superpowers ↔ gstack | ✅ Complementary | Used together in /init-project and /ship-feature. Superpowers = engine, GStack = full-product skills. | | superpowers ↔ gstack | ✅ Complementary | Used together in /init-project and /ship-feature. superpowers skills (vendored) = engine, GStack = full-product skills. |
| context7 ↔ any | ✅ Independent | Doc lookup CLI (ctx7), no workflow overlap. Always safe to combine. | | context7 ↔ any | ✅ Independent | Doc lookup CLI (ctx7), no workflow overlap. Always safe to combine. |
| plugin-dev ↔ superpowers | ⚠️ Minor overlap | Superpowers can create skills too. Keep plugin-dev only when actively building new plugins/skills. | | plugin-dev ↔ superpowers | ⚠️ Minor overlap | superpowers skills (vendored) can create skills too (writing-skills). Keep plugin-dev only when actively building new plugins. |
| ui-ux-pro-max ↔ gstack | ✅ Complementary | GStack = deploy/QA layer; ui-ux-pro-max = UI quality layer. Different concerns. | | ui-ux-pro-max ↔ gstack | ✅ Complementary | GStack = deploy/QA layer; ui-ux-pro-max = UI quality layer. Different concerns. |
| pr-review-toolkit ↔ superpowers | ✅ Complementary | superpowers:requesting-code-review and /pr-review-toolkit:review-pr cover different review styles. | | pr-review-toolkit ↔ superpowers | ✅ Complementary | `requesting-code-review` (vendored superpowers skill) and /pr-review-toolkit:review-pr cover different review styles. |
| rtk ↔ any | ✅ Independent | Hook-only token compression. Zero interaction with any plugin. | | rtk ↔ any | ✅ Independent | Hook-only token compression. Zero interaction with any plugin. |
| security-guidance ↔ any | ✅ Independent | Hooks + out-of-band LLM reviews (agentic review on commit/push; Stop diff review disabled by ENABLE_STOP_REVIEW=0). No context injection unless a regex hits. | | security-guidance ↔ any | ✅ Independent | Hooks + out-of-band LLM reviews (agentic review on commit/push; Stop diff review disabled by ENABLE_STOP_REVIEW=0). No context injection unless a regex hits. |
@@ -187,15 +187,15 @@ When the plugin-advisor detects a `simple` or `hotfix` signal, suggest the appro
| Project type | Plugins ON | OFF | Passive cost | | Project type | Plugins ON | OFF | Passive cost |
|---|---|---|---| |---|---|---|---|
| Backend API / microservice | superpowers, context7 (if fast libs) | ui-ux-pro-max, gstack | ~800t | | Backend API / microservice | (superpowers skills always on), context7 (if fast libs) | ui-ux-pro-max, gstack | ~0t |
| Frontend SPA / SSR | superpowers, ui-ux-pro-max, frontend-design, design-motion-principles, context7 | gstack | ~1400t | | Frontend SPA / SSR | (superpowers skills always on), ui-ux-pro-max, frontend-design, design-motion-principles, context7 | gstack | ~600t |
| Full-stack SaaS | superpowers, gstack, ui-ux-pro-max, frontend-design, design-motion-principles, context7 | — | ~4200t | | Full-stack SaaS | (superpowers skills always on), gstack, ui-ux-pro-max, frontend-design, design-motion-principles, context7 | — | ~3400t |
| CLI tool / library | superpowers | all toggles | ~800t | | CLI tool / library | (superpowers skills always on) | all toggles | ~0t |
| Multi-session large feature | superpowers + gsd v2 CLI (external) | — | ~800t CC | | Multi-session large feature | (superpowers skills always on) + gsd v2 CLI (external) | — | ~0t CC |
| Quick fix / hotfix | superpowers | all toggles | ~800t | | Quick fix / hotfix | (superpowers skills always on) | all toggles | ~0t |
| Design system / component lib | superpowers, ui-ux-pro-max, frontend-design, design-motion-principles | gstack, gsd | ~1200t | | Design system / component lib | (superpowers skills always on), ui-ux-pro-max, frontend-design, design-motion-principles | gstack, gsd | ~400t |
| Fast-evolving libs (Next.js etc.) | superpowers, context7 | — | ~1000t | | Fast-evolving libs (Next.js etc.) | (superpowers skills always on), context7 | — | ~200t |
| Enterprise multi-agent orchestration | superpowers + gsd v2 (external) | plugin-dev | ~800t CC | | Enterprise multi-agent orchestration | (superpowers skills always on) + gsd v2 (external) | plugin-dev | ~0t CC |
> rtk is always on at 0 context tokens; security-guidance is always on and > rtk is always on at 0 context tokens; security-guidance is always on and
> costs quota out of band (LLM reviews), not context — both omitted from > costs quota out of band (LLM reviews), not context — both omitted from
@@ -239,8 +239,9 @@ RULE: IF "simple" OR "hotfix":
RULE: IF "embedded" signal (firmware, bare-metal, microcontroller, or Makefile+C without Node/Rust/Go): RULE: IF "embedded" signal (firmware, bare-metal, microcontroller, or Makefile+C without Node/Rust/Go):
→ Disable ALL toggles including gstack, context7, plugin-dev → Disable ALL toggles including gstack, context7, plugin-dev
→ superpowers OPTIONAL: useful for initial design brainstorm on complex drivers, → superpowers skills stay on (vendored, no toggle): useful for initial
but unnecessary for single-function patches — user decides design brainstorm on complex drivers, unnecessary for single-function
patches; just don't invoke them, no disable needed
→ GSD v2 CLI: not recommended (sessions are short, tasks are atomic) → GSD v2 CLI: not recommended (sessions are short, tasks are atomic)
→ Recommend workflow: /analyze <file> → /hotfix (patch) or /bugfix (investigation) or /ship-feature (multi-file) → Recommend workflow: /analyze <file> → /hotfix (patch) or /bugfix (investigation) or /ship-feature (multi-file)
→ NOTE: print "embedded project detected — minimal plugin footprint recommended" → NOTE: print "embedded project detected — minimal plugin footprint recommended"
@@ -251,7 +252,7 @@ RULE: IF plugin-dev ON AND no `skill-creation` signal detected:
RULE: IF `skill-creation` signal: RULE: IF `skill-creation` signal:
→ plugin-dev ON (~100t) → plugin-dev ON (~100t)
→ superpowers ON — required for skill scaffolding → superpowers skills (vendored, always on): used for skill scaffolding (writing-skills)
RULE: IF `browser-qa` signal (e2e tests, Playwright/Cypress/Puppeteer in deps): RULE: IF `browser-qa` signal (e2e tests, Playwright/Cypress/Puppeteer in deps):
→ gstack ON — browser automation and QA → gstack ON — browser automation and QA
@@ -295,8 +296,9 @@ gstack + managed plugins — sessions stay focused and passive token cost drops.
`profile set <name>` actually toggles plugins (`claude plugin enable|disable`) `profile set <name>` actually toggles plugins (`claude plugin enable|disable`)
and external skill packs (delegates to `lib/toggle-external.sh`) — not just and external skill packs (delegates to `lib/toggle-external.sh`) — not just
advisory. No MCP server is auto-toggled today. Always-on plugins (`security-guidance`, `superpowers`) advisory. No MCP server is auto-toggled today. Always-on plugins (`security-guidance`)
are protected. Managed plugins that `set` may toggle: and the vendored superpowers skills are never toggled by a profile. Managed
plugins that `set` may toggle:
`ui-ux-pro-max@ui-ux-pro-max-skill`, `plugin-dev@claude-code-plugins`, `ui-ux-pro-max@ui-ux-pro-max-skill`, `plugin-dev@claude-code-plugins`,
`pr-review-toolkit@claude-code-plugins`. Other plugins are never auto-toggled. `pr-review-toolkit@claude-code-plugins`. Other plugins are never auto-toggled.
@@ -321,7 +323,7 @@ toggles the managed plugins like any `set`).
## BLOCK if ## BLOCK if
- Superpowers not active → install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace` - Superpowers skills missing → `make plugin` (vendors them) then `make link`
- Full-product (UI+deploy+QA) + gstack not installed - Full-product (UI+deploy+QA) + gstack not installed
## WARN (no block) ## WARN (no block)
+4 -3
View File
@@ -103,9 +103,10 @@ backfill, if ever wanted, is `/prune-memory` passe D — never this snippet.
## ORDERING (orchestrators only) ## ORDERING (orchestrators only)
`superpowers:brainstorming` / `writing-plans` are external skills — we cannot make them `brainstorming` / `writing-plans` (vendored superpowers skills) are external skills — we
read our registries. So this runs BEFORE them, pre-loading the disposition into the plan cannot make them read our registries. So this runs BEFORE them, pre-loading the
they form. Mirror of capitalize-commit running BEFORE finishing-a-development-branch: there disposition into the plan they form. Mirror of capitalize-commit running BEFORE
`gitflow finish` (the upstream finishing-a-development-branch is not vendored): there
the memory commit must precede integration; here the memory read must precede planning. the memory commit must precede integration; here the memory read must precede planning.
## NO-OP / IDEMPOTENT ## NO-OP / IDEMPOTENT
+10 -8
View File
@@ -17,9 +17,10 @@ code already committed.
- Inline-commit flows (feat / hotfix / bugfix / commit-change): run it right - Inline-commit flows (feat / hotfix / bugfix / commit-change): run it right
after writing the entries, on the current branch. after writing the entries, on the current branch.
- Orchestrators that integrate via `superpowers:finishing-a-development-branch` - Orchestrators that integrate via `gitflow finish` (the upstream
(ship-feature / init-project): run it BEFORE the FINISH step — otherwise the finishing-a-development-branch is not vendored; ship-feature / init-project):
memory commit strands outside the merge/PR. See ORDERING. run it BEFORE the FINISH step — otherwise the memory commit strands outside
the merge/PR. See ORDERING.
This snippet commits whatever is PENDING under `.claude/memory` + `.claude/tasks`; This snippet commits whatever is PENDING under `.claude/memory` + `.claude/tasks`;
it does NOT decide content. A flow whose gate wrote only a journal line yields a it does NOT decide content. A flow whose gate wrote only a journal line yields a
@@ -65,11 +66,12 @@ no-match pathspec is filtered, not fatal).
## ORDERING (orchestrators only) ## ORDERING (orchestrators only)
`finishing-a-development-branch` may merge-and-delete the branch or push a PR. A `finishing-a-development-branch` (upstream superpowers skill, not vendored
memory commit created AFTER it lands outside the integrated history — stranded here; `gitflow finish` is the only integration path) may merge-and-delete the
on the PR path. So in ship-feature / init-project this snippet runs BEFORE branch or push a PR. A memory commit created AFTER it lands outside the
FINISH. The code commits already exist (implementation step), so the entries' integrated history — stranded on the PR path. So in ship-feature / init-project
hash references are valid at this point. this snippet runs BEFORE FINISH. The code commits already exist (implementation
step), so the entries' hash references are valid at this point.
## WHAT THIS DOES NOT DO ## WHAT THIS DOES NOT DO
+5 -4
View File
@@ -81,10 +81,11 @@ do NOT bypass them:
## ORDERING (orchestrators) ## ORDERING (orchestrators)
`finishing-a-development-branch` merges/pushes COMMITTED history only — it never commits `finishing-a-development-branch` (upstream superpowers skill, not vendored here;
working-tree changes. A doc patch left uncommitted (or committed AFTER it) never reaches `gitflow finish` is the only integration path) merges/pushes COMMITTED history only — it
the merge/PR. So this snippet runs BEFORE FINISH: the doc commit lands on the branch FINISH never commits working-tree changes. A doc patch left uncommitted (or committed AFTER it)
integrates. Consumption is MECHANICAL (LRN-057 case a, like the memory commit) — production never reaches the merge/PR. So this snippet runs BEFORE FINISH: the doc commit lands on
the branch FINISH integrates. Consumption is MECHANICAL (LRN-057 case a, like the memory commit) — production
on the branch = consumption by the merge, automatic. on the branch = consumption by the merge, automatic.
## ACKNOWLEDGMENTS (conscious, not glossed) ## ACKNOWLEDGMENTS (conscious, not glossed)
-7
View File
@@ -420,7 +420,6 @@
"example-skills@anthropic-agent-skills": false, "example-skills@anthropic-agent-skills": false,
"ui-ux-pro-max@ui-ux-pro-max-skill": true, "ui-ux-pro-max@ui-ux-pro-max-skill": true,
"security-guidance@claude-code-plugins": true, "security-guidance@claude-code-plugins": true,
"superpowers@superpowers-marketplace": true,
"pr-review-toolkit@claude-code-plugins": false, "pr-review-toolkit@claude-code-plugins": false,
"brightdata-plugin@synced": false "brightdata-plugin@synced": false
}, },
@@ -431,12 +430,6 @@
"repo": "anthropics/claude-code" "repo": "anthropics/claude-code"
} }
}, },
"superpowers-marketplace": {
"source": {
"source": "github",
"repo": "obra/superpowers-marketplace"
}
},
"ui-ux-pro-max-skill": { "ui-ux-pro-max-skill": {
"source": { "source": {
"source": "github", "source": "github",
+2 -1
View File
@@ -318,7 +318,8 @@ Then offer to capitalize (per CLAUDE.md): recurring finding patterns →
## TDD note (skill itself) ## TDD note (skill itself)
Baseline-tested per superpowers:writing-skills (2026-06-11, isolated Baseline-tested per writing-skills (vendored superpowers skill;
2026-06-11, isolated
worktree, no skill): the agent (1) guessed the boundary from the most worktree, no skill): the agent (1) guessed the boundary from the most
recent file date in `.claude/audits/` — wrong file, date-based; (2) wrote recent file date in `.claude/audits/` — wrong file, date-based; (2) wrote
its checkpoint as prose in a dated report — unparseable next run; (3) kept its checkpoint as prose in a dated report — unparseable next run; (3) kept
+1 -1
View File
@@ -512,7 +512,7 @@ The deploy succeeded. Lay the oracle and close out.
## Note on this skill (authoring) ## Note on this skill (authoring)
Shaped via `superpowers:writing-skills`. The **cold cross-session resume** is the Shaped via `writing-skills` (vendored superpowers skill). The **cold cross-session resume** is the
novel form (design §10): the disk alone must carry the deploy across the novel form (design §10): the disk alone must carry the deploy across the
out-of-band gap, so `PENDING.json`'s presence marks the wait and STEP 0 resumes out-of-band gap, so `PENDING.json`'s presence marks the wait and STEP 0 resumes
from it without conversation memory — the `audit-delta` "state file is the only from it without conversation memory — the `audit-delta` "state file is the only
+5 -3
View File
@@ -13,8 +13,10 @@ fan-out, init, `.gitignore` reconcile, the protected-base predicate — are in
and bulletproofs the single judgment call: **`finish` merges only on an explicit and bulletproofs the single judgment call: **`finish` merges only on an explicit
human signal.** human signal.**
Replaces `finishing-a-development-branch` for gitflow flows — that skill is Replaces `finishing-a-development-branch` (upstream superpowers skill, not
single-target and cannot do the directed / fan-out merges below. vendored here; `gitflow finish` is the only integration path) for gitflow
flows — that skill is single-target and cannot do the directed / fan-out
merges below.
## When to Use ## When to Use
@@ -107,7 +109,7 @@ stays human-gated.
## Common Mistakes ## Common Mistakes
- Using `finishing-a-development-branch` for a gitflow merge → it can't do directed/fan-out merges. Use `gitflow finish`. - Using `finishing-a-development-branch` (upstream superpowers skill, not vendored here) for a gitflow merge → it can't do directed/fan-out merges anyway. Use `gitflow finish`, the only integration path.
- Hand-writing `git merge` instead of `gitflow finish` → loses fan-out, branch delete, base sync. - Hand-writing `git merge` instead of `gitflow finish` → loses fan-out, branch delete, base sync.
- Calling `finish` because the work *looks* done → see the gate. - Calling `finish` because the work *looks* done → see the gate.
- `git branch -d`/`-D` by hand → denied; a branch the lib refuses to delete still holds work. Keep it, say so. - `git branch -d`/`-D` by hand → denied; a branch the lib refuses to delete still holds work. Keep it, say so.
+4 -4
View File
@@ -68,7 +68,7 @@ contract.
Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack constraints, infra risks, open decisions. Produce ANALYSIS REPORT. Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack constraints, infra risks, open decisions. Produce ANALYSIS REPORT.
## STEP 3 — DESIGN ## STEP 3 — DESIGN
Invoke `superpowers:brainstorming` with BRIEF + ANALYSIS REPORT. Invoke `brainstorming` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT.
Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list. Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list.
Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the DESIGN Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the DESIGN
(minus what the BRIEF and the brainstorm settled): one batch before STEP 4; (minus what the BRIEF and the brainstorm settled): one batch before STEP 4;
@@ -179,7 +179,7 @@ This is the deterministic scaffold commit owner (closes BLK-010). The MVP is
implemented on a `feature/*` branch off `develop` (STEP 8). implemented on a `feature/*` branch off `develop` (STEP 8).
## STEP 6 — PLAN ## STEP 6 — PLAN
Invoke `superpowers:writing-plans` with BRIEF + skeleton. Invoke `writing-plans` (vendored superpowers skill) with BRIEF + skeleton.
Granular tasks (2-5 min each), exact file paths, TDD: tests before code. Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
## STEP 6b — CHALLENGE THE PLAN (before the gate) ## STEP 6b — CHALLENGE THE PLAN (before the gate)
@@ -212,7 +212,7 @@ Start the MVP feature branch off develop, then implement on it:
```bash ```bash
bash "$HOME/.claude/lib/gitflow.sh" start feature mvp bash "$HOME/.claude/lib/gitflow.sh" start feature mvp
``` ```
Invoke `superpowers:subagent-driven-development` for the per-task implement loop Invoke `subagent-driven-development` (vendored superpowers skill) for the per-task implement loop
**and** the final whole-branch review **only**. Do NOT run its terminal **and** the final whole-branch review **only**. Do NOT run its terminal
`finishing-a-development-branch` step — this orchestrator owns integration via `finishing-a-development-branch` step — this orchestrator owns integration via
`gitflow finish` (STEP 11). When SDD's flow reaches "Use `gitflow finish` (STEP 11). When SDD's flow reaches "Use
@@ -256,7 +256,7 @@ against the founding contract. Distinct axis from STEP 10 code review
([[LRN-095]]) — both run. ([[LRN-095]]) — both run.
## STEP 10 — CODE REVIEW ## STEP 10 — CODE REVIEW
Invoke `superpowers:requesting-code-review`. **Model routing (BDR-077):** the Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the
review subagent it dispatches MUST carry `model: "opus"` in the Agent call — review subagent it dispatches MUST carry `model: "opus"` in the Agent call —
craft review is dispatched judgment, never inherited from the session. Fix craft review is dispatched judgment, never inherited from the session. Fix
all CRITICAL before proceeding. all CRITICAL before proceeding.
+4 -2
View File
@@ -56,8 +56,10 @@ lists items + types:
| `mcp` | advisory — prints manual `claude mcp add …` command (no server is managed today: `MANAGED_MCPS` is empty since 21st.dev moved to a CLI) | | `mcp` | advisory — prints manual `claude mcp add …` command (no server is managed today: `MANAGED_MCPS` is empty since 21st.dev moved to a CLI) |
| `cli` | advisory only — reports installed/not-installed | | `cli` | advisory only — reports installed/not-installed |
**Always-on plugins** (`security-guidance`, `superpowers`) are **Always-on plugins** (`security-guidance`) and the vendored superpowers
protected — `set` will refuse to disable them even if the profile omits them. skills are never toggled by a profile — `set` will refuse to disable the
plugin even if the profile omits it, and the 7 superpowers skills are
linked outside any profile.
**Managed plugins** that `set` may disable when not in profile: **Managed plugins** that `set` may disable when not in profile:
`ui-ux-pro-max@ui-ux-pro-max-skill`, `plugin-dev@claude-code-plugins`, `ui-ux-pro-max@ui-ux-pro-max-skill`, `plugin-dev@claude-code-plugins`,
`pr-review-toolkit@claude-code-plugins`. Other plugins are never auto-toggled. `pr-review-toolkit@claude-code-plugins`. Other plugins are never auto-toggled.
+4 -4
View File
@@ -100,7 +100,7 @@ approved at STEP 3 ENRICHES it, and STEP 5's verifier judges the diff against
the ENRICHED contract. This is the only flow where the contract grows mid-run. the ENRICHED contract. This is the only flow where the contract grows mid-run.
## STEP 1 — BRAINSTORM ## STEP 1 — BRAINSTORM
Invoke `superpowers:brainstorming` — but FEED it the STEP 0d digest as binding context, Invoke `brainstorming` (vendored superpowers skill) — but FEED it the STEP 0d digest as binding context,
not the raw request alone: not the raw request alone:
"Feature request: <$ARGUMENTS>. "Feature request: <$ARGUMENTS>.
In-force constraints (must hold): <only the IN-FORCE + ALREADY-SEEN items from 0d's In-force constraints (must hold): <only the IN-FORCE + ALREADY-SEEN items from 0d's
@@ -114,7 +114,7 @@ Consumption = INPUT INJECTION (we can't modify the external skill; we control it
Refine request into validated design via Socratic questioning. Don't proceed until design approved. Refine request into validated design via Socratic questioning. Don't proceed until design approved.
## STEP 2 — PLAN ## STEP 2 — PLAN
Invoke `superpowers:writing-plans` with the validated design AND the 0d digest: every task Invoke `writing-plans` (vendored superpowers skill) with the validated design AND the 0d digest: every task
must be consistent with the in-force constraints; where a task implements or affects one, must be consistent with the in-force constraints; where a task implements or affects one,
note the ID inline. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps. note the ID inline. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps.
Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the plan: Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the plan:
@@ -173,7 +173,7 @@ Start the feature branch off develop, then implement on it:
```bash ```bash
bash "$HOME/.claude/lib/gitflow.sh" start feature <name> bash "$HOME/.claude/lib/gitflow.sh" start feature <name>
``` ```
Invoke `superpowers:subagent-driven-development` for the per-task implement loop Invoke `subagent-driven-development` (vendored superpowers skill) for the per-task implement loop
**and** the final whole-branch review **only**. Do NOT run its terminal **and** the final whole-branch review **only**. Do NOT run its terminal
`finishing-a-development-branch` step — this orchestrator owns integration via `finishing-a-development-branch` step — this orchestrator owns integration via
`gitflow finish` (STEP 9). When SDD's flow reaches "Use `gitflow finish` (STEP 9). When SDD's flow reaches "Use
@@ -234,7 +234,7 @@ conformity + security vs. craft/design) — both run, neither subsumes the
other ([[LRN-095]]). other ([[LRN-095]]).
## STEP 6 — CODE REVIEW ## STEP 6 — CODE REVIEW
Invoke `superpowers:requesting-code-review`. **Model routing (BDR-077):** the Invoke `requesting-code-review` (vendored superpowers skill). **Model routing (BDR-077):** the
review subagent it dispatches MUST carry `model: "opus"` in the Agent call — review subagent it dispatches MUST carry `model: "opus"` in the Agent call —
craft review is dispatched judgment, never inherited from the session. Fix craft review is dispatched judgment, never inherited from the session. Fix
all CRITICAL before proceeding. all CRITICAL before proceeding.
+4 -3
View File
@@ -315,9 +315,10 @@ without that approval — neither this repo's nor any target project's.
## TDD note (skill itself) ## TDD note (skill itself)
Baseline-tested per superpowers:writing-skills (2026-07-04, seeded Baseline-tested per writing-skills (vendored superpowers skill;
fixture, no skill): the agent branched correctly via gitflow and did not 2026-07-04, seeded fixture, no skill): the agent branched correctly via
merge, BUT (1) silently rewrote the target TODO (checked boxes, gitflow and did not merge, BUT (1) silently rewrote the target TODO (checked
boxes,
restructured) during "reconcile"; (2) authored BDR/journal registry restructured) during "reconcile"; (2) authored BDR/journal registry
entries autonomously; (3) ran security as ad-hoc grep + ruff — no entries autonomously; (3) ran security as ad-hoc grep + ruff — no
semgrep, no pinned rulesets; (4) left findings only in its final chat semgrep, no pinned rulesets; (4) left findings only in its final chat