docs(readme): streamline README — cut from ~700 to ~150 lines

Remove verbose sections (compatibility matrix, self-management, passive
cost model, marketplaces, detailed examples, versioning). Replace with:
single installed-components table with doc links, 3 core workflows
(from scratch / existing project / new feature), compact settings and
diagnostic sections. Add graphify to architecture description.

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -2,7 +2,7 @@
 
 Global Claude Code configuration — agents, skills, plugins, and project templates.
 
-> **Guide d'utilisation complet :** voir [`USAGE.md`](./USAGE.md) — workflows typiques, exemples par type de projet (mobile, web, CLI, firmware, monorepo), arbre de décision "quel skill utiliser ?".
+> **Guide d'utilisation complet :** voir [`USAGE.md`](./USAGE.md) — workflows typiques, exemples par type de projet, arbre de décision "quel skill utiliser ?".
 
 ---
 
@@ -13,690 +13,168 @@ This repo is your personal Claude Code setup, versioned and reproducible across
 ```
 claude-config/
 ├── CLAUDE.md              # Global coding preferences (style, rules, workflow)
-├── settings.json          # Global permissions (100 deny / 18 ask / 57 allow rules)
+├── settings.json          # Global permissions (deny / ask / allow rules)
 ├── install.sh             # Bootstrap: Claude Code CLI + auth + shell env vars + link + plugins
-├── install-plugins.sh     # One-shot installer: prerequisites + all plugins (reads plugins.lock.json)
+├── install-plugins.sh     # One-shot installer: prerequisites + all plugins
 ├── link.sh                # Symlinks this repo into ~/.claude/
-├── doctor.sh              # Setup diagnostic — checks symlinks, plugins, permissions, token budget
+├── doctor.sh              # Setup diagnostic
 ├── update-all.sh          # One-command update for all components
 ├── Makefile               # Unified entry point: make install / doctor / update
-├── plugins.lock.json      # Version pinning for non-marketplace dependencies (RTK, GSD v2)
-├── version.txt            # Semver version of this config
-├── CHANGELOG.md           # Release history
-├── lib/
-│   └── detect-plugins.sh  # Shared plugin detection — sourced by all scripts
-├── hooks/
-│   ├── session-start.sh   # Health check + toggle plugin status at session start
-│   ├── statusline.sh      # Claude Code status line configuration
-│   └── rtk-rewrite.sh     # RTK hook for code rewrites
-├── skills-external/
-│   └── gstack/            # Git submodule — garrytan/gstack (symlinked to ~/.claude/skills/gstack)
-├── .gitmodules            # Submodule declaration
-├── agents/
-│   ├── analyzer.md        # Factual codebase analysis (read-only)
-│   ├── bugfixer.md        # Structured bug fix with root cause investigation
-│   ├── code-cleaner.md    # Dead code removal, style/norm enforcement
-│   ├── commit-changer.md  # Smart commit grouping from staged/unstaged changes
-│   ├── doc-syncer.md      # Detect stale docs, audit, and patch
-│   ├── feater.md          # Small feature implementation (1-5 files)
-│   ├── hotfixer.md        # Quick fix for superficial bugs (max 2 files)
-│   ├── interviewer.md     # Project questionnaire → PROJECT BRIEF
-│   ├── onboarder.md       # Onboard existing project — CLAUDE.md, settings, optional GSD ROADMAP
-│   ├── plugin-advisor.md  # Plugin check: detect signals, apply compatibility matrix, block if needed
-│   ├── refactorer.md      # Surgical refactoring with norm enforcement
-│   ├── scaffolder.md      # Full project generation (CLAUDE.md, README, code)
-│   ├── seo-analyzer.md    # Full SEO/GEO audit and fix
-│   └── status-reporter.md # Consolidated project status — read-only snapshot
-├── skills/
-│   ├── analyze/           # /analyze — deep factual analysis
-│   ├── bugfix/            # /bugfix — structured bug fix with root cause investigation
-│   ├── code-clean/        # /code-clean — dead code removal, style enforcement
-│   ├── commit-change/     # /commit-change — smart commit grouping
-│   ├── doc/               # /doc — documentation audit and sync
-│   ├── feat/              # /feat — small feature implementation (1-5 files)
-│   ├── graphify/          # /graphify — codebase knowledge graph navigation
-│   ├── health/            # /health — run setup diagnostic
-│   ├── hotfix/            # /hotfix — quick fix for superficial bugs
-│   ├── init-project/      # /init-project — full project initialization
-│   ├── onboard/           # /onboard — onboard existing project into claude-config
-│   ├── plugin-check/      # /plugin-check — check plugin config vs project needs
-│   ├── refactor/          # /refactor — improve code without changing behavior
-│   ├── seo/               # /seo — full SEO/GEO audit and optimization
-│   ├── ship-feature/      # /ship-feature — ship a feature end-to-end
-│   ├── skills-perso/      # /skills-perso — list personal (user-created) skills
-│   └── status/            # /status — consolidated project snapshot
-└── templates/
-    ├── project-CLAUDE.md  # Template for per-project CLAUDE.md
-    └── settings/
-        ├── settings.json         # Template for project .claude/settings.json
-        ├── settings.local.json   # Template for personal .claude/settings.local.json
-        ├── .claudeignore         # Template for project .claudeignore
-        └── SETTINGS.md           # Rule syntax reference (rule types, patterns, defaultMode values)
+├── plugins.lock.json      # Version pinning for non-marketplace dependencies
+├── hooks/                 # Session start, statusline, RTK rewrite
+├── agents/                # Execution units called by skills (never invoked directly)
+├── skills/                # Entry points invoked via /skill-name
+├── skills-external/       # Git submodules (gstack)
+├── templates/             # Per-project config templates (CLAUDE.md, settings, .claudeignore)
+└── lib/                   # Shared shell functions (plugin detection)
 ```
 
 **Architecture principle:**
 - `skills/` = entry points you invoke via `/skill-name`
 - `agents/` = execution units called by skills (never invoked directly by user)
-- `lib/` = shared shell functions sourced by scripts (plugin detection)
-- `templates/` = symlinked to `~/.claude/templates/` — copy into projects via per-project setup
-- Custom skills use **Superpowers** agents for implementation phases (required — auto-detected)
-- **Plugins** (Superpowers, GStack, GSD v2, etc.) install separately and complement custom skills
+- `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually
+- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly.
 
 ---
 
 ## Fresh install (new machine)
 
 ```bash
-# 1. Clone with submodules — choose any location
+# 1. Clone with submodules
 git clone --recurse-submodules git@github.com:youruser/claude-config.git
 cd claude-config
 
-# 2. Bootstrap (installs Claude Code CLI, authenticates, sets up shell env vars, then runs link.sh + install-plugins.sh)
+# 2. Bootstrap (CLI + auth + symlinks + plugins)
 bash install.sh
-# Or step by step:
-#   bash link.sh                # symlink into ~/.claude/
-#   bash install-plugins.sh     # prerequisites + all plugins
 
-# 4. Context7 CLI (optional — fast-evolving libs docs lookup)
-npm install -g ctx7
-ctx7 setup --claude    # configures rules for Claude Code
-# Higher rate limits: ctx7 login (OAuth) or use --api-key from context7.com/dashboard
-
-# 5. Verify setup
+# 3. Verify setup
 bash doctor.sh
 
-# 6. Restart Claude Code — plugins load automatically
+# 4. Restart Claude Code — plugins load automatically
 ```
 
-All scripts use their own location to find the repo — run them from anywhere or from the repo directory.
-Symlinks point to the repo's actual path, so renaming or moving the repo requires re-running `bash link.sh`.
+All scripts use their own location to find the repo — run them from anywhere.
+Install output is logged to `install-YYYYMMDD-HHMMSS.log`.
+
+---
 
-The install script handles: git, Node.js 22, Rust/Cargo, Python 3, RTK, GStack (submodule), GSD v2,
-and all marketplace plugins on Linux (apt/dnf/pacman) and macOS (brew).
+## Installed components
 
-RTK and GSD v2 versions are pinned in `plugins.lock.json`. The install script reads those versions
-automatically. Marketplace plugins install to `~/.claude/plugins/` (user scope).
+| 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) |
+| **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) |
+| **RTK** | Plugin (always on) | Code rewrite hook. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
+| **security-guidance** | Plugin (always on) | Security hook. Zero passive cost. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
+| **ui-ux-pro-max** | Plugin (toggle) | Design system, color/typography choices. Enable for design-heavy projects. | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
+| **Context7** | Plugin (toggle) | Fast-evolving libs doc lookup (Next.js, React, Prisma...). | `npm install -g ctx7` |
+| **pr-review-toolkit** | Plugin (toggle) | Multi-agent PR review. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
+| **Graphify** | Python CLI | Codebase → knowledge graph → navigable wiki. Helps Claude map and search projects efficiently. | [pypi: graphifyy](https://pypi.org/project/graphifyy/) |
 
-Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory for post-mortem debugging.
+Versions are pinned in `plugins.lock.json`. To update: edit the file, then re-run `install-plugins.sh`.
 
 ---
 
-## Available slash commands
-
-### Custom skills (this repo)
+## Slash commands
 
 | Command | Description |
 |---|---|
-| `/analyze` | Deep factual analysis of code before any modification |
+| `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) |
+| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
+| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, .claudeignore |
+| `/feat` | Small feature implementation (1-5 files, lightweight) |
 | `/bugfix` | Structured bug fix with root cause investigation |
+| `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
+| `/analyze` | Deep factual analysis of code before any modification |
+| `/refactor` | Improve code quality without changing behavior |
 | `/code-clean` | Dead code removal, style/norm enforcement |
-| `/commit-change` | Smart commit grouping from staged/unstaged changes |
 | `/doc` | Documentation audit and sync — detect stale docs, patch |
-| `/feat` | Small feature implementation (1-5 files, lightweight) |
+| `/seo` | Full SEO/GEO audit and optimization |
+| `/commit-change` | Smart commit grouping from staged/unstaged changes |
 | `/graphify` | Codebase knowledge graph — navigation for large-scope tasks |
-| `/health` | Run setup diagnostic — check symlinks, plugins, permissions, token budget |
-| `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
-| `/init-project` | Initialize a complete project from scratch (full orchestrator) |
-| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, optional GSD v2 ROADMAP |
 | `/plugin-check` | Check active plugins vs project needs — recommend enable/disable |
-| `/refactor` | Improve code quality without changing behavior (strict norms) |
-| `/seo` | Full SEO/GEO audit and optimization |
-| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
-| `/skills-perso` | List personal (user-created) skills |
+| `/health` | Run setup diagnostic |
 | `/status` | Consolidated project snapshot — plugins, git, GSD milestone |
-
-### Superpowers skills (auto-invoked or explicit)
-
-> **Required dependency.** Superpowers must be active for `/init-project` and `/ship-feature`.
-> The plugin-advisor (STEP 0) blocks and shows install instructions if Superpowers is missing.
-
-| Command | When it auto-activates |
-|---|---|
-| `superpowers:brainstorming` | When you describe something to build |
-| `superpowers:writing-plans` | After design is approved |
-| `superpowers:subagent-driven-development` | With an approved plan |
-| `superpowers:requesting-code-review` | Auto — after a feature step |
-| `superpowers:finishing-a-development-branch` | After review is approved |
-
-### GStack (Garry Tan — full-product projects only)
-
-> Full-product workflow skills for UI + design + deploy + browser QA. Installed as a git submodule.
-> Skip for backend/lib/CLI projects. Docs: [github.com/garrytan/gstack](https://github.com/garrytan/gstack)
-
-### GSD v2 — standalone CLI (multi-session large features)
-
-> Standalone TypeScript CLI for multi-session work: crash recovery, per-unit cost tracking, parallel workers,
-> context-fresh execution per task. Not a Claude Code plugin — runs as an external process.
-> Docs: [github.com/gsd-build/gsd-2](https://github.com/gsd-build/gsd-2)
-
-### Bundled skills (Claude Code built-in, always available)
-
-| Command | Description |
-|---|---|
-| `/batch <instruction>` | Large-scale parallel refactoring — decomposes into 5–30 units, spawns one background agent per unit in isolated git worktrees |
-| `/debug [description]` | Enable debug logging for the session, analyze the session debug log |
-| `/simplify [focus]` | Review recent changes for code reuse, quality, efficiency issues |
-
-### Other plugin commands
-
-| Command | Plugin | Description |
-|---|---|---|
-| `/pr-review-toolkit:review-pr` | pr-review-toolkit | Multi-agent PR review (6 specialized agents) |
-| `/context7:docs <lib>` | context7 | Manual doc lookup for a specific library (via ctx7 CLI) |
-
----
-
-## Workflow patterns
-
-### Pattern A — Nouveau projet (court, 1 session)
-```
-/plugin-check "description"   → configure plugins
-/init-project "description"   → interview → scaffold → implement v1
-/ship-feature "feature"       → ship feature by feature
-```
-
-### Pattern B — Nouveau projet (long, multi-session)
-```
-/plugin-check "description"
-/init-project "description"   → à la fin, STEP 13 propose d'init GSD v2
-                                 → répondre "yes"
-# Ensuite dans un terminal :
-gsd                            → démarrer une session GSD
-/gsd auto                      → mode autonome — walk away
-/gsd status                    → vérifier la progression
-/gsd discuss                   → décisions d'architecture en cours de route
-```
-**À chaque reprise de session :**
-```
-/status                        → snapshot : plugins, token, git state, milestone GSD en cours
-```
-
-### Pattern C — Projet existant (onboarding)
-```
-cd mon-projet-existant/
-# Dans Claude Code :
-/onboard                       → génère CLAUDE.md + settings + .claudeignore
-                                 → optionnel : ROADMAP.md pour GSD v2
-/status                        → confirmer que l'onboarding est complet + état du projet
-/plugin-check "type de projet"
-/ship-feature "prochaine feature"
-```
-
-### Pattern D — Hotfix / modification ponctuelle
-```
-# Bug superficiel (typo, mauvais import, CSS cassé — max 2 fichiers, cause évidente) :
-/hotfix "le bouton submit est invisible sur mobile"
-
-# Bug plus complexe (investigation root cause nécessaire) :
-/bugfix "les notifications ne partent plus depuis mardi"
-```
-
-### Pattern E — Refactoring ciblé
-```
-/analyze src/legacy.py         → liste les violations
-/refactor src/legacy.py        → corrections sans changement de comportement
-```
-
-### Pattern F — Petite feature (1-5 fichiers)
-```
-# Pas d'orchestration lourde, pas de brainstorming superpowers
-/feat "ajouter un endpoint GET /api/v1/users/:id/stats"
-# → planning léger, implémentation directe, tests
-```
-
-### Choisir entre /ship-feature, /feat, /hotfix et /bugfix
-
-| Critère | /ship-feature | /feat | /bugfix | /hotfix |
-|---|---|---|---|---|
-| Scope | Feature complète | 1-5 fichiers | Bug complexe | Bug superficiel |
-| Orchestration | Superpowers pipeline | Léger | Investigation | Direct |
-| Fichiers touchés | Illimité | ≤ 5 | Variable | ≤ 2 |
-| Validation gate | Oui | Non | Non | Non |
-| Code review | Auto (superpowers) | Non | Régression test | Non |
-
-### Choisir entre /ship-feature et gsd auto
-
-| Critère | /ship-feature | gsd auto |
-|---|---|---|
-| Durée estimée | < 1 journée | > 1 journée |
-| Nombre de tâches | < 10 | > 10 |
-| Crash recovery nécessaire | non | oui |
-| Suivi de coût par tâche | non | oui |
-| Workers parallèles | non | oui (parallel mode) |
-| Contexte fresh par tâche | non (même session) | oui (Pi SDK) |
+| `/skills-perso` | List personal (user-created) skills |
 
 ---
 
-## Orchestrators in detail
-
-### `/init-project`
-
-Same rigor as `/ship-feature`. Two validation gates. Full TDD subagent pipeline for v1 features.
-The Scaffolder only creates the skeleton (no features, no README).
-readme-updater handles the README in two passes: CREATE then SYNC.
-
-STEP 0 blocks if Superpowers is not installed (required for steps 3, 6, 8, 10, 11).
-
-```
-/init-project <project idea>
-    │
-    ├── STEP 0:  PLUGIN CHECK (plugin-advisor)        ← blocks if Superpowers missing or wrong plugins
-    ├── STEP 1:  INTERVIEWER (custom)                 → PROJECT BRIEF
-    ├── STEP 2:  ANALYZER (custom)                    → ANALYSIS REPORT
-    ├── STEP 3:  superpowers:brainstorming             → VALIDATED DESIGN
-    ├── STEP 4:  VALIDATION GATE #1                   → approve architecture
-    ├── STEP 5:  SCAFFOLDER (custom)                  → skeleton only (CLAUDE.md +
-    │                                                    settings + structure +
-    │                                                    empty entry points, NO features,
-    │                                                    NO README)
-    ├── STEP 5b: README-UPDATER create mode (custom)  → CREATE README from CLAUDE.md
-    ├── STEP 6:  superpowers:writing-plans             → decompose v1 features into tasks
-    ├── STEP 7:  VALIDATION GATE #2                   → approve task plan
-    ├── STEP 8:  superpowers:subagent-driven (TDD)    → implement each feature (isolated)
-    ├── STEP 9:  ANALYZER (custom)                    → regression + deviation check
-    ├── STEP 10: superpowers:requesting-review         → full code review
-    ├── STEP 11: superpowers:finishing-branch          → cleanup + build + tests
-    └── STEP 12: README-UPDATER sync mode (custom)    → sync README with implementation
-```
-
-### `/ship-feature`
+## Three core workflows
 
-STEP 0 blocks if Superpowers is not installed (required for steps 1, 2, 4, 6, 7).
+### From scratch — `/init-project`
 
 ```
-/ship-feature <feature description>
-    │
-    ├── STEP 0: PLUGIN CHECK (plugin-advisor) ← blocks if Superpowers missing or wrong plugins
-    ├── STEP 1: superpowers:brainstorming     → VALIDATED DESIGN
-    ├── STEP 2: superpowers:writing-plans     → task plan
-    ├── STEP 3: VALIDATION GATE               → user approval required
-    ├── STEP 4: superpowers:subagent-driven   → implementation (TDD)
-    ├── STEP 5: ANALYZER (custom)             → regression / deviation check
-    ├── STEP 6: superpowers:requesting-review → code review
-    ├── STEP 7: superpowers:finishing-branch  → cleanup
-    └── STEP 8: README-UPDATER sync mode      → sync README with new feature
+/plugin-check "description"     # configure plugins (also runs as STEP 0)
+/init-project "description"     # interview → scaffold → implement → review
+/ship-feature "next feature"    # ship feature by feature
 ```
 
-### `/plugin-check`
-
-Standalone command you can run at any time to audit your plugin config
-against what you're about to do. Also embedded as STEP 0 in both orchestrators.
-
-Blocks if Superpowers is not active (required by orchestrators).
-Blocks if critical project-specific plugins are missing (frontend tools, Context7, GStack).
-Warns if GSD v2 CLI is not installed for multi-session work.
-
-```
-/plugin-check "I want to build a React + FastAPI SaaS"
-
-→ Detects active plugins
-→ Scans filesystem for project signals (frontend? design? deploy? multi-agent?)
-→ Applies compatibility matrix
-→ Produces recommendation table with passive cost estimate
-→ Warns about plugin conflicts
-→ Blocks with OPTIONS if critical plugins are missing
-→ Or confirms "proceed" if config is optimal
-```
-
----
-
-## Plugin compatibility matrix
-
-### Quick reference
-
-| Pair | Relation | Notes |
-|---|---|---|
-| gstack ↔ gsd v2 | ✅ Complementary | Different scopes — CC workflow vs CLI orchestration |
-| superpowers ↔ gsd v2 | ✅ Complementary | Single-session engine + multi-session CLI = no conflict |
-| superpowers ↔ gstack | ✅ Complementary | Used together by orchestrators |
-| context7 ↔ any | ✅ Independent | Doc lookup CLI (ctx7) — always safe to combine |
-
-### Recommended sets by project type
-
-| Project type | Plugins ON | OFF | Passive cost |
-|---|---|---|---|
-| Backend API / microservice | superpowers, context7* | ui-ux-pro-max, gstack | ~800t |
-| Frontend SPA / SSR | superpowers, ui-ux-pro-max, context7 | gstack | ~1400t |
-| Full-stack SaaS | superpowers, gstack, ui-ux-pro-max, context7 | — | ~4200t |
-| CLI tool / library | superpowers | all toggles | ~800t |
-| Multi-session large feature | superpowers + gsd v2 CLI (external) | — | ~800t CC |
-| Quick fix / hotfix | superpowers | all toggles | ~800t |
-| Design system / component lib | superpowers, ui-ux-pro-max | gstack, gsd | ~1200t |
-| Enterprise multi-agent | superpowers + gsd v2 CLI (external) | others | ~800t CC |
-
-> *context7 only if using fast-evolving libs (Next.js, React 18+, Prisma, Supabase)
-> security-guidance and rtk are ALWAYS ON (0 tokens) — omitted from estimates
-
----
-
-## Intelligent self-management
-
-This config doesn't just provide tools — it manages itself. The interconnection between plugins, skills, and agents creates an autonomous quality layer.
-
-### Plugin advisor — automatic configuration
-
-`/plugin-check` (or STEP 0 in orchestrators) analyzes your project and recommends the optimal plugin configuration:
-
-- **Signal detection:** scans filesystem for project type signals (frontend frameworks, mobile SDKs, embedded toolchains, monorepo markers, deploy configs)
-- **Compatibility matrix:** knows which plugins overlap, complement, or conflict with each other
-- **Cost awareness:** estimates passive token cost per plugin combination and warns when approaching budget limits
-- **Blocking gate:** orchestrators (`/init-project`, `/ship-feature`) refuse to start if critical plugins are missing
-
-### Token budget management
-
-Every plugin has a passive cost (loaded at session start). The system tracks this:
-
-- `session-start.sh` hook displays current passive cost and % of session budget at every session start
-- `/health` and `doctor.sh` provide detailed token budget breakdowns
-- `/plugin-check` recommends disabling unnecessary plugins to reclaim budget
-- Rule: toggle plugins are OFF by default — only enabled when project signals justify the cost
-
-### Tool and skill synergies
-
-Skills and tools are designed to work together, not in isolation:
-
-| Synergy | How it works |
-|---|---|
-| `/plugin-check` → `/init-project` | Plugin-check runs as STEP 0, blocks if config is wrong |
-| `/analyze` → `/refactor` | Analyzer produces violation report, refactorer uses it as input |
-| `/status` → `gsd auto` | Status shows GSD milestone progress, informs session resumption |
-| `/init-project` STEP 13 → GSD v2 | Orchestrator detects multi-session need, proposes GSD init |
-| `/ship-feature` STEP 0b → `/onboard` | Detects missing CLAUDE.md, redirects to onboarding first |
-| `doctor.sh` → `link.sh` | Doctor diagnoses broken symlinks, link.sh fixes them |
-| `/doc` → auto-mode | Other skills can trigger doc-sync automatically after changes |
-| Superpowers → custom agents | Orchestrators use Superpowers for brainstorm/plan/review phases, custom agents for analysis/scaffolding |
-
-### Passive vs active cost model
+### Existing project — `/onboard`
 
 ```
-Passive (always loaded):        Active (loaded on demand):
-├─ CLAUDE.md (~420t)            ├─ Skill body (when /skill invoked)
-├─ Plugin descriptions          ├─ Agent content (when skill loads agent)
-├─ Hook configs                 └─ Context7 docs (when ctx7 queried)
-└─ Session-start output
+cd my-existing-project/
+/onboard                        # generates CLAUDE.md + settings + .claudeignore
+/plugin-check "project type"
+/ship-feature "next feature"
 ```
 
-The system minimizes passive cost by loading skill bodies and agent content only when invoked. Plugin descriptions are the main passive cost lever — hence why `/plugin-check` exists.
-
----
-
-## Plugins reference
-
-All plugins below are installed by `install-plugins.sh`.
-
-### How loading works
-
-Only each skill's `description` field is pre-loaded into the system prompt at session start —
-the full skill body is loaded on demand when the skill is invoked. `CLAUDE.md` is the only file
-loaded in full at every session. Disabling a plugin prevents even its description from loading.
-
-A `hooks/session-start.sh` hook shows plugin toggle status at every session start.
-Run `/plugin-check` anytime to get a recommendation for the current project type.
-
-| Plugin | Status | Passive cost | When to use | Installed by |
-|---|---|---|---|---|
-| **security-guidance** | ✅ ALWAYS ON | 0 tokens (hook only) | — | claude-code-plugins |
-| **RTK** | ✅ ALWAYS ON | 0 tokens (hook only) | — | cargo (pinned in plugins.lock.json) |
-| **Superpowers** | ✅ REQUIRED | ~600–1000 tokens | — required by orchestrators | superpowers-marketplace |
-| **GStack** | 🔄 TOGGLE | ~2500–3000 tokens | Full-product: UI + design + deploy + browser QA | git submodule |
-| **GSD v2** | 🖥️ CLI | 0 tokens (external CLI) | Multi-day features, crash recovery, cost tracking, parallel workers | npm (pinned in plugins.lock.json) |
-| **plugin-dev** | 🔄 TOGGLE | ~100 tokens | Creating plugins or custom skills | claude-code-plugins |
-| **pr-review-toolkit** | 🔄 TOGGLE | ~300 tokens | PR review sessions | claude-code-plugins |
-| **ui-ux-pro-max** | 🔄 TOGGLE | ~400 tokens | Design system, color/typography choices | ui-ux-pro-max-skill |
-| **Context7 CLI** | 🔄 TOGGLE | ~200 tokens | Fast-evolving libs (Next.js, React, Prisma…) | npm (ctx7 CLI) |
-
-**Rule:** toggle plugins are OFF by default. `/plugin-check` signals when to enable them.
-If you use `/init-project` or `/ship-feature`, plugin-check runs automatically as STEP 0
-and **blocks if Superpowers is not active**.
-
-### Marketplaces
-
-Plugins are installed from GitHub-hosted marketplaces. Three are used by this config:
-
-| Marketplace | GitHub repo | Plugins | Auto-available |
-|---|---|---|---|
-| `claude-plugins-official` | `anthropics/claude-plugins-official` | Anthropic-curated third-party plugins | ✅ yes |
-| `claude-code-plugins` | `anthropics/claude-code` | Anthropic bundled plugins (security-guidance, pr-review-toolkit, plugin-dev) | ❌ add manually |
-| `superpowers-marketplace` | `obra/superpowers-marketplace` | Superpowers workflow plugin | ❌ add manually |
-| `ui-ux-pro-max-skill` | `nextlevelbuilder/ui-ux-pro-max-skill` | UI/UX Pro Max design plugin | ❌ add manually |
-
-`install-plugins.sh` adds all required marketplaces automatically.
-
-**Manual install example:**
-```bash
-# Add the marketplace (once)
-claude plugin marketplace add anthropics/claude-code
-
-# Install a plugin from it
-claude plugin install --scope user pr-review-toolkit@claude-code-plugins
+### New feature — `/ship-feature`
 
-# Browse all available plugins
-/plugin   # → Discover tab
 ```
-
-### Version pinning
-
-Non-marketplace tools are pinned in `plugins.lock.json`:
-
-```json
-{
-  "rtk":             { "source": "https://github.com/rtk-ai/rtk", "version": "v0.34.3" },
-  "gsd":             { "source": "npm:gsd-pi",  "version": "2.64.0" },
-  "ctx7":            { "source": "npm:ctx7",    "version": "latest" },
-  "graphifyy":       { "source": "pypi:graphifyy", "managed_by": "pipx" },
-  "emil-design-eng": { "source": "https://github.com/emilkowalski/skill", "managed_by": "curl" }
-}
+/ship-feature "feature description"
+# → STEP 0: plugin check
+# → STEP 1-2: brainstorm + plan (superpowers)
+# → STEP 3: validation gate — user approval required
+# → STEP 4-7: implement (TDD) → review → finish
+# → STEP 8: sync README
 ```
 
-`install-plugins.sh` reads these versions automatically.
-To update a pinned version: edit `plugins.lock.json`, then re-run `install-plugins.sh`.
-GStack is pinned via its git submodule pointer.
-
-### Disabling a plugin for a specific project
-
-```bash
-# In Claude Code
-/plugin
-# → Find the plugin → toggle off for this scope
-```
-
-Or in the project's `.claude/settings.json`:
-```json
-{
-  "enabledPlugins": {
-    "gstack@gstack": false
-  }
-}
-```
+For small features (1-5 files), use `/feat` instead — no orchestration overhead.
 
 ---
 
 ## Settings and permissions
 
-### File hierarchy
+Settings follow a hierarchy (highest priority first):
 
 ```
-Highest
-  managed-settings.json        — enterprise, cannot be overridden
-  CLI flags                    — --allowedTools / --disallowedTools (session only)
-  .claude/settings.local.json  — personal machine overrides (gitignored)
-  .claude/settings.json        — project rules (committed to project repo)
-  ~/.claude/settings.json      — global user rules (this repo's settings.json)
-Lowest
-
-DENY always wins over ALLOW at any level.
-.claudeignore applies independently of all permission rules.
+managed-settings.json   → enterprise (cannot be overridden)
+CLI flags               → session only
+.claude/settings.local  → personal machine overrides (gitignored)
+.claude/settings.json   → project rules (committed)
+~/.claude/settings.json → global user rules (this repo)
 ```
 
-### Global settings (this repo's `settings.json`)
-
-100 deny rules, 18 ask rules, 57 allow rules.
-
-| Section | Purpose |
-|---|---|
-| `deny` — secrets (Read) | Blocks `Read` on `.env`, `.pem`, `.key`, SSH keys, cloud credentials |
-| `deny` — secrets (Bash) | Blocks `cat`, `head`, `tail`, `grep`, `less`, `more` on `.env` and secret files |
-| `deny` — env leak | Blocks `env`, `printenv`, `export *` — prevents secret exposure via process environment |
-| `deny` — secret move | Blocks `cp`/`mv` on `.env*` and `secrets/` — closes copy-then-read bypass |
-| `deny` — destructive | Blocks `rm -rf`, `git push --force`, `chmod 777` |
-| `deny` — system | Blocks `sudo`, `ssh`, `scp`, `crontab`, `systemctl` |
-| `deny` — injection | Blocks `curl \| bash`, `wget \| sh` |
-| `deny` — escalation | Blocks `bash -c`, `eval`, `exec`, `find -delete`, `perl -e`, `ruby -e` |
-| `deny` — runtime exec | Blocks `python3 -c *`, `node -e *`, `source /dev/stdin`, `mkfifo *` |
-| `deny` — exfiltration | Blocks `xargs * .env*`, `tar * .env*`, `zip * .env*`, `base64 .env*` |
-| `ask` — risky | Prompts before `git push`, `docker run`, package managers |
-| `ask` — write tools | Prompts before `xargs`, all `sed` (including in-place) |
-| `ask` — stash destructive | Prompts before `git stash pop`, `drop`, `clear` |
-| `allow` — safe reads | Auto-approves git read-only, `ls`, `cat`, `grep`, `find` |
-| `allow` — stash safe | Auto-approves `git stash` (push), `list`, `show` |
-| `disableBypassPermissionsMode` | Prevents YOLO mode globally |
-| `disableAutoMode` | Prevents auto mode globally |
-
-### Per-project setup
+DENY always wins over ALLOW at any level. `.claudeignore` applies independently.
 
+Templates for per-project settings are in `templates/settings/`. Copy them with `/onboard` or manually:
 ```bash
-cd your-project
-mkdir -p .claude
-
-# Find the repo from any existing symlink
 CONF="$(dirname "$(readlink ~/.claude/CLAUDE.md)")"
-
-# Project settings (commit to project git)
 cp "$CONF/templates/settings/settings.json" .claude/settings.json
-
-# Personal overrides (never commit — gitignore it)
-cp "$CONF/templates/settings/settings.local.json" .claude/settings.local.json
-echo ".claude/settings.local.json" >> .gitignore
-
-# Hard file exclusions (commit to project git)
 cp "$CONF/templates/settings/.claudeignore" .claudeignore
-
-# Project CLAUDE.md (commit to project git)
-cp "$CONF/templates/project-CLAUDE.md" CLAUDE.md
-```
-
----
-
-## Updating
-
-### One-command update (recommended)
-
-```bash
-# From the repo directory
-bash update-all.sh
-# Updates Claude CLI, pulls config, prompts before updating GStack (tracks main),
-# updates RTK + GSD v2 (pinned), updates ctx7 + graphifyy,
-# refreshes marketplace plugins, refreshes symlinks, runs doctor
-```
-
-### Manual updates
-
-```bash
-git pull          # this repo — symlinks make changes active immediately
-bash link.sh      # refresh symlinks if needed
 ```
 
-All third-party tools (RTK, GSD v2, GStack, ctx7, marketplace plugins) are updated
-automatically by `update-all.sh`. Versions are pinned in `plugins.lock.json`.
-
 ---
 
-## Adding a new custom skill
+## Diagnostic and maintenance
 
-**Fastest way:**
 ```bash
-make new-skill name=myskill
-# Creates agents/myskill.md + skills/myskill/SKILL.md with templates filled
-# Edit both files, then: bash link.sh
-```
-
-**Manually:**
-1. Create `agents/myagent.md` — role, tasks, rules, output format
-2. Create `skills/myskill/SKILL.md`:
-
-```markdown
----
-name: myskill
-description: What this skill does — front-load key use case (max 250 chars)
-argument-hint: <what to pass>
-disable-model-invocation: true
-allowed-tools: Read, Write, Edit, Bash, Grep, Glob
----
+# Terminal
+bash doctor.sh              # full diagnostic (symlinks, plugins, permissions, token budget)
+bash update-all.sh          # update all components (CLI, plugins, submodules, symlinks)
 
-Load and follow strictly:
-- $HOME/.claude/agents/myagent.md
+# Claude Code
+/health                     # runs doctor.sh
+/status                     # project snapshot (plugins, git, GSD milestone)
+/plugin-check "description" # audit plugin config vs project needs
 
-Execute on:
-
-$ARGUMENTS
+# Makefile (from repo directory)
+make install                # bootstrap: CLI + auth + symlinks + plugins
+make doctor                 # diagnostic
+make update                 # pull + submodules + symlinks + doctor
+make plugin                 # install plugins only
+make new-skill name=myskill # scaffold agent + skill files
 ```
 
-3. Or use `/plugin-dev:create-plugin` to generate a skill from conversation.
-
----
-
-## Personal skills (skills-perso)
-
-List your personal skills (created in `~/.claude/skills/`) with:
-```
-/skills-perso
-```
-
-This lists all skills you've created outside of this repo — useful to remember what custom skills are available across projects.
-
-To create a personal skill:
-```bash
-# Quick way (from this repo)
-make new-skill name=myskill
-bash link.sh
-
-# Or manually
-mkdir -p ~/.claude/skills/myskill/
-# Create SKILL.md with frontmatter (see "Adding a new custom skill" above)
-```
-
----
-
-## Per-project agent overrides
-
-Override any global agent for a specific project:
-
-```bash
-CONF="$(dirname "$(readlink ~/.claude/CLAUDE.md)")"
-cp "$CONF/agents/refactorer.md" .claude/agents/refactorer.md
-# Edit .claude/agents/refactorer.md — the local version takes precedence
-```
-
----
-
-## Maintenance
-
-### Diagnostic
-
-```bash
-# Quick check from terminal (from the repo directory)
-bash doctor.sh
-
-# Or from within Claude Code
-/health       # full diagnostic (symlinks, plugins, permissions, token budget)
-/status       # project snapshot at session start (plugins, git, GSD milestone)
-
-# Unified commands via Makefile (from the repo directory)
-make doctor     # diagnostic
-make update     # pull + submodules + symlinks + doctor
-make install    # bootstrap: Claude Code CLI + auth + symlinks + plugins
-make plugin     # install prerequisites + all plugins only
-make onboard    # reminder to run /onboard in Claude Code
-make new-skill name=myskill  # scaffold agent + skill files
-```
-
-`doctor.sh` checks 7 axes: symlinks, GStack submodule (with pinning warning), prerequisites
-(git, Node, Cargo, Python, Claude Code), plugins (RTK, Superpowers, Context7, GSD v2),
-permissions (deny count, bypass mode), token budget (breakdown vs Pro session budget), and
-config consistency (frontmatter, CRLF detection).
-
-`session-start.sh` runs a quick health check at every session start (filesystem only, no subprocesses)
-and displays toggle plugin status, GSD v2 CLI status, with `/plugin-check` and `/health` hints.
-
-Both scripts source `lib/detect-plugins.sh` for consistent plugin detection logic.
-
+`doctor.sh` checks: symlinks, GStack submodule, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency.