50db70cbf2
Both plugins removed from all config, scripts, and documentation: - ruflo: uninstalled globally (npm), removed from install/update/doctor/session-start/detect/lock/advisor - frontend-design: removed from install/session-start/detect/advisor (was already commented out) - plugin-advisor.md: compatibility matrix, decision table, conditional rules, recommended sets all updated - README.md/USAGE.md: all references cleaned, token cost estimates recalculated - install-plugins.sh: steps renumbered (10→9 steps) - CHANGELOG.md: kept as historical record Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
703 lines
30 KiB
Markdown
703 lines
30 KiB
Markdown
# claude-config
|
||
|
||
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 ?".
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
This repo is your personal Claude Code setup, versioned and reproducible across machines.
|
||
|
||
```
|
||
claude-config/
|
||
├── CLAUDE.md # Global coding preferences (style, rules, workflow)
|
||
├── settings.json # Global permissions (100 deny / 18 ask / 57 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)
|
||
├── link.sh # Symlinks this repo into ~/.claude/
|
||
├── doctor.sh # Setup diagnostic — checks symlinks, plugins, permissions, token budget
|
||
├── 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)
|
||
```
|
||
|
||
**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
|
||
|
||
---
|
||
|
||
## Fresh install (new machine)
|
||
|
||
```bash
|
||
# 1. Clone with submodules — choose any location
|
||
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)
|
||
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
|
||
bash doctor.sh
|
||
|
||
# 6. 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.
|
||
|
||
---
|
||
|
||
## Available slash commands
|
||
|
||
### Custom skills (this repo)
|
||
|
||
| 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 |
|
||
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
|
||
| `/skills-perso` | List personal (user-created) skills |
|
||
| `/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) |
|
||
|
||
---
|
||
|
||
## 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`
|
||
|
||
STEP 0 blocks if Superpowers is not installed (required for steps 1, 2, 4, 6, 7).
|
||
|
||
```
|
||
/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`
|
||
|
||
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
|
||
|
||
```
|
||
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
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Settings and permissions
|
||
|
||
### File hierarchy
|
||
|
||
```
|
||
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.
|
||
```
|
||
|
||
### 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
|
||
|
||
```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
|
||
|
||
**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
|
||
---
|
||
|
||
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.
|
||
|