From 1e7a88a9d478865512d0c2ddb0f07438db1b25b7 Mon Sep 17 00:00:00 2001 From: bastien Date: Thu, 16 Apr 2026 00:20:13 +0200 Subject: [PATCH] =?UTF-8?q?docs(readme):=20streamline=20README=20=E2=80=94?= =?UTF-8?q?=20cut=20from=20~700=20to=20~150=20lines?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 712 ++++++++---------------------------------------------- 1 file changed, 95 insertions(+), 617 deletions(-) diff --git a/README.md b/README.md index e903d39..26a4c4e 100644 --- a/README.md +++ b/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`. - -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). - -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). - -Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory for post-mortem debugging. +All scripts use their own location to find the repo — run them from anywhere. +Install output is logged to `install-YYYYMMDD-HHMMSS.log`. --- -## Available slash commands +## Installed components -### Custom skills (this repo) +| 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/) | + +Versions are pinned in `plugins.lock.json`. To update: edit the file, then re-run `install-plugins.sh`. + +--- + +## Slash commands | Command | Description | |---|---| -| `/analyze` | Deep factual analysis of code before any modification | -| `/bugfix` | Structured bug fix with root cause investigation | -| `/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) | -| `/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 | +| `/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) | -| `/skills-perso` | List personal (user-created) skills | +| `/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 | +| `/doc` | Documentation audit and sync — detect stale docs, patch | +| `/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 | +| `/plugin-check` | Check active plugins vs project needs — recommend enable/disable | +| `/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 ` | 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 ` | context7 | Manual doc lookup for a specific library (via ctx7 CLI) | +| `/skills-perso` | List personal (user-created) skills | --- -## Workflow patterns +## Three core workflows -### 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) | - ---- - -## 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). +### From scratch — `/init-project` ``` -/init-project - │ - ├── 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 +/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 ``` -### `/ship-feature` - -STEP 0 blocks if Superpowers is not installed (required for steps 1, 2, 4, 6, 7). +### Existing project — `/onboard` ``` -/ship-feature - │ - ├── 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 +cd my-existing-project/ +/onboard # generates CLAUDE.md + settings + .claudeignore +/plugin-check "project type" +/ship-feature "next 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. +### New feature — `/ship-feature` ``` -/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 +/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 ``` ---- - -## 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 - -``` -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 -``` - -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 - -# 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" } -} -``` - -`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) +## Diagnostic and maintenance ```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 +# Terminal +bash doctor.sh # full diagnostic (symlinks, plugins, permissions, token budget) +bash update-all.sh # update all components (CLI, plugins, submodules, symlinks) + +# Claude Code +/health # runs doctor.sh +/status # project snapshot (plugins, git, GSD milestone) +/plugin-check "description" # audit plugin config vs project needs + +# 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 ``` -### 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 - -**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: -disable-model-invocation: true -allowed-tools: Read, Write, Edit, Bash, Grep, Glob ---- - -Load and follow strictly: -- $HOME/.claude/agents/myagent.md - -Execute on: - -$ARGUMENTS -``` - -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.