bchanot/claude
1
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

final version seems

Browse Source
This commit is contained in:
bchanot
2026-04-08 13:46:45 +02:00
parent f8811fab37
commit f55a2b3fdf
34 changed files with 4270 additions and 1743 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+309 -108
View File
@@ -2,6 +2,8 @@
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 ?", cas de figure validés, et table des erreurs fréquentes.
---
## Overview
@@ -11,13 +13,13 @@ 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 (77 deny / 16 ask / 57 allow rules)
├── settings.json # Global permissions (100 deny / 18 ask / 57 allow rules)
├── 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)
├── plugins.lock.json # Version pinning for non-marketplace dependencies (RTK, GSD v2, ruflo)
├── version.txt # Semver version of this config
├── CHANGELOG.md # Release history
├── lib/
@@ -30,7 +32,9 @@ claude-config/
├── agents/
│ ├── analyzer.md # Factual codebase analysis (read-only)
│ ├── interviewer.md # Project questionnaire → PROJECT BRIEF
│ ├── plugin-advisor.md # Plugin check: detect mismatches, block if Superpowers missing
│ ├── onboarder.md # Onboard existing project — CLAUDE.md, settings, optional GSD ROADMAP
│ ├── status-reporter.md # Consolidated project status — read-only snapshot
│ ├── plugin-advisor.md # Plugin check: detect signals, apply compatibility matrix, block if needed
│ ├── readme-updater.md # Update README from git history + codebase
│ ├── refactorer.md # Surgical refactoring with norm enforcement
│ └── scaffolder.md # Full project generation (CLAUDE.md, README, code)
@@ -38,6 +42,8 @@ claude-config/
│ ├── analyze/ # /analyze — deep factual analysis
│ ├── health/ # /health — run setup diagnostic
│ ├── init-project/ # /init-project — full project initialization
│ ├── onboard/ # /onboard — onboard existing project into claude-config
│ ├── status/ # /status — consolidated project snapshot
│ ├── plugin-check/ # /plugin-check — check plugin config vs project needs
│ ├── readme/ # /readme — update README from current state
│ ├── refactor/ # /refactor — improve code without changing behavior
@@ -48,15 +54,16 @@ claude-config/
├── 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 # Full settings reference
└── 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, etc.) install separately and complement custom skills
- **Plugins** (Superpowers, GStack, GSD v2, ruflo, etc.) install separately and complement custom skills
---
@@ -73,23 +80,23 @@ bash link.sh
# 3. Install prerequisites + all plugins (detects OS, reads pinned versions from plugins.lock.json)
bash install-plugins.sh
# 4. Add Context7 API key (free at context7.com) — manual step
# 4. Add Context7 API key (free at upstash.com) — manual step
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_KEY
# 5. Verify setup
bash doctor.sh
# 6. Restart Claude Code then run /reload-plugins
# 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,
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 versions are pinned in `plugins.lock.json`. The install script reads those
versions automatically. Marketplace plugins install to `~/.claude/plugins/` (user scope).
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.
@@ -108,6 +115,7 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
| `/init-project` | Initialize a complete project from scratch (full orchestrator) |
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
| `/health` | Run setup diagnostic — check symlinks, plugins, permissions, token budget |
| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, optional GSD v2 ROADMAP |
### Superpowers skills (auto-invoked or explicit)
@@ -116,47 +124,100 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
| Command | When it auto-activates |
|---|---|
| `/superpowers:brainstorm` | When you describe something to build |
| `/superpowers:write-plan` | After design is approved |
| `/superpowers:execute-plan` | With an approved plan |
| `systematic-debugging` | Auto — when debugging |
| `test-driven-development` | Auto — when implementing |
| `requesting-code-review` | Auto — after a feature step |
| `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 skills (Garry Tan — full-product projects only)
> Installed as a git submodule at `skills-external/gstack/`, symlinked to `~/.claude/skills/gstack/`.
> **Use when:** project has UI + design + deploy + browser QA. Skip for backend/lib/CLI projects.
> Full command reference: `~/.claude/skills/gstack/README.md` or run `/office-hours` to start.
### GSD v2 — standalone CLI (multi-session large features)
> **Architecture change from v1:** GSD v2 (`gsd-pi`) is a standalone TypeScript CLI built on the Pi SDK.
> It is **not** a Claude Code plugin — it runs as an external process with its own session management.
> The `/gsd ...` commands are GSD-internal and are typed inside a `gsd` terminal session, not in Claude Code.
>
> **Install:** `npm install -g gsd-pi` (pinned version in `plugins.lock.json`)
>
> **Use when:** a feature spans multiple days/sessions, you need crash recovery, cost tracking per unit,
> parallel workers across milestones, or automatic context-fresh execution per task.
```bash
# Start a GSD session in your terminal (from your project directory)
gsd
# Or jump straight to autonomous mode — walk away and come back to built software
gsd # then inside the session:
/gsd auto # autonomous mode: research → plan → execute → commit → repeat
/gsd # step mode: pause between each unit for review
/gsd status # progress dashboard
/gsd discuss # talk through architecture decisions
/gsd quick # atomic quick task without full planning overhead
```
**Key commands inside a GSD session:**
| Command | Description |
|---|---|
| `/office-hours` | Discovery consultant — scope and challenge before code |
| `/plan-ceo-review` | CEO challenges product scope and feature value |
| `/plan-eng-review` | Staff engineer locks architecture decisions |
| `/design-consultation` | Build a design system from scratch |
| `/design-shotgun` | Generate multiple visual variants for comparison |
| `/design-html` | Turn approved mockup into production HTML |
| `/review` | Code review (GStack version) |
| `/ship` | One-command: test → build → deploy |
| `/qa` | QA with real Chrome browser automation |
| `/browse` | Headless Chrome web navigation |
| `/careful` | Activate safety guardrails |
| `/freeze` | Lock edits to current directory |
| `/retro` | Engineering retrospective |
| `/gstack-upgrade` | Self-update GStack |
| `/gsd auto` | Autonomous mode — research, plan, execute, commit, repeat until milestone done |
| `/gsd` or `/gsd next` | Step mode — execute one unit at a time, pause between each |
| `/gsd quick` | Quick atomic task with GSD guarantees (no full planning overhead) |
| `/gsd stop` | Stop auto mode gracefully |
| `/gsd status` | Progress dashboard (token usage, cost, milestone progress) |
| `/gsd discuss` | Discuss architecture decisions (works alongside auto mode) |
| `/gsd steer` | Hard-steer plan documents during execution |
| `/gsd prefs` | Model selection, timeouts, budget ceiling |
| `/gsd doctor` | Runtime health checks |
| `/gsd migrate` | Migrate a v1 `.planning` directory to `.gsd` format |
| `/gsd export --html` | Generate self-contained HTML report for a milestone |
| `/worktree` | Git worktree lifecycle — create, switch, merge, remove |
### GSD skills (glittercowboy — multi-session large features)
**GSD v2 vs v1:**
> Install: `npx get-shit-done-cc --claude --global`
> **Use when:** feature spans multiple days/sessions. Each session starts fresh with full context from previous phases.
| | v1 (deprecated) | v2 (current) |
|---|---|---|
| Runtime | Claude Code slash commands | Standalone CLI (Pi SDK) |
| Context management | None — fills up | Fresh session per task |
| Auto mode | LLM self-loop | State machine with `.gsd/` files |
| Crash recovery | None | Lock files + session forensics |
| Cost tracking | None | Per-unit token/cost ledger |
| Git strategy | LLM writes git commands | Worktree isolation, squash merge |
### Ruflo MCP (enterprise multi-agent orchestration)
> Ruflo (formerly claude-flow) is a heavy enterprise MCP server — 310+ tools, 100+ agent types,
> WASM kernel, self-learning architecture. ~500-1500 tokens passive cost when active.
>
> **Use when:** project explicitly requires coordinating 5+ specialized agents simultaneously,
> parallel swarm execution, or enterprise-grade multi-agent orchestration.
> **For standard multi-session work, GSD v2 is sufficient and much lighter.**
>
> **Install:**
> ```bash
> # Full install (~340MB)
> npm install -g ruflo@latest
> # Or minimal (faster, no ML/embeddings)
> npm install -g ruflo@latest --omit=optional
>
> # Register as MCP server in Claude Code
> claude mcp add --scope user ruflo -- npx ruflo mcp start
>
> # Verify
> claude mcp list | grep ruflo
> ```
### Bundled skills (Claude Code built-in, always available)
| Command | Description |
|---|---|
| `/gsd:discuss-phase` | Refine spec for a phase through conversation |
| `/gsd:plan-phase` | Generate hierarchical phase plan |
| `/gsd:execute-phase` | Execute phase in an isolated context window |
| `/gsd:ship` | Create PR from verified work |
| `/gsd:next` | Auto-advance to the next phase |
| `/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
@@ -167,6 +228,68 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory
---
## 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
```
# Pas de /init-project, pas de GSD
/analyze src/module-cible.py → rapport factuel sans solution
/ship-feature "corriger X" → brainstorm + plan + gate + impl + review
```
### Pattern E — Refactoring ciblé
```
/analyze src/legacy.py → liste les violations
/refactor src/legacy.py → corrections sans changement de comportement
```
### 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`
@@ -224,41 +347,77 @@ 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 ruflo is active with no multi-agent signal, or if GSD v2 CLI is not installed for multi-session work.
```
/plugin-check "I want to build a React + FastAPI SaaS"
→ Detects active plugins
→ Analyzes signals: frontend? design? QA? multi-session? fast-evolving libs?
→ Produces recommendation table
→ Blocks with OPTIONS if critical plugins are missing (including Superpowers)
→ Scans filesystem for project signals (frontend? design? deploy? multi-agent?)
→ Applies compatibility matrix
→ Produces recommendation table with passive cost estimate
→ Warns about plugin conflicts (gstack + ruflo, etc.)
→ Blocks with OPTIONS if critical plugins are missing
→ Or confirms "proceed" if config is optimal
```
---
## Plugin compatibility matrix
### Quick reference
| Pair | Relation | Notes |
|---|---|---|
| frontend-design ↔ ui-ux-pro-max | ⚠️ Overlap | Keep both for design-heavy. Drop ui-ux-pro-max for simple UI. |
| gstack ↔ gsd v2 | ✅ Complementary | Different scopes — CC workflow vs CLI orchestration |
| gstack ↔ ruflo | ⚠️ Overlap | Both orchestrate multi-step work. Use one or the other. ~3250-4250t combined. |
| gsd v2 ↔ ruflo | ⚠️ Overlap | Sequential (GSD) vs parallel swarm (ruflo). Pick based on need. |
| superpowers ↔ gsd v2 | ✅ Complementary | Single-session engine + multi-session CLI = no conflict |
| superpowers ↔ gstack | ✅ Complementary | Used together by orchestrators |
| context7 ↔ any | ✅ Independent | Doc lookup MCP — always safe to combine |
### Recommended sets by project type
| Project type | Plugins ON | OFF | Passive cost |
|---|---|---|---|
| Backend API / microservice | superpowers, context7* | frontend-design, ui-ux-pro-max, gstack, ruflo | ~800t |
| Frontend SPA / SSR | superpowers, frontend-design, ui-ux-pro-max, context7 | gstack, ruflo | ~1600t |
| Full-stack SaaS | superpowers, gstack, frontend-design, ui-ux-pro-max, context7 | ruflo | ~4400t |
| CLI tool / library | superpowers | all toggles | ~800t |
| Multi-session large feature | superpowers + gsd v2 CLI (external) | ruflo | ~800t CC |
| Quick fix / hotfix | superpowers | all toggles | ~800t |
| Design system / component lib | superpowers, frontend-design, ui-ux-pro-max | gstack, ruflo, gsd | ~1600t |
| Enterprise multi-agent | superpowers, ruflo + gsd v2 CLI (external) | others | ~2300t 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
---
## Plugins reference
All plugins below are installed by `install-plugins.sh`.
### Quick reference
### How loading works
The mechanism: Claude Code loads every active skill's **description** into a shared context budget
at session start (default 8000 chars). Even if you never invoke the skill, its description
is already consuming tokens. **Disabling a plugin prevents its descriptions from loading entirely.**
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 the current toggle status at the start of every session.
Run `/plugin-check` anytime to get a full recommendation for the current project type.
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 toggle ON | Installed by |
| Plugin | Status | Passive cost | When to use | Installed by |
|---|---|---|---|---|
| **security-guidance** | ✅ ALWAYS ON | 0 tokens (hook only) | — | marketplace |
| **RTK** | ✅ ALWAYS ON | 0 tokens (hook only) | — | cargo (pinned in plugins.lock.json) |
| **Superpowers** | ✅ REQUIRED | ~600–1000 tokens | — required by orchestrators, auto-detected | marketplace |
| **skill-creator** | ✅ ALWAYS ON | ~100 tokens | — | marketplace |
| **pr-review-toolkit** | ✅ ALWAYS ON | ~300 tokens | — use `/pr-review-toolkit:review-pr` | marketplace |
| **Superpowers** | ✅ REQUIRED | ~600–1000 tokens | — required by orchestrators | marketplace |
| **GStack** | 🔄 TOGGLE | ~2500–3000 tokens | Full-product: UI + design + deploy + browser QA | git submodule |
| **GSD** | 🔄 TOGGLE | ~500–800 tokens | Feature spanning multiple days/sessions | npx (pinned in plugins.lock.json) |
| **GSD v2** | 🖥️ CLI | 0 tokens (external CLI) | Multi-day features, crash recovery, cost tracking, parallel workers | npm (pinned in plugins.lock.json) |
| **ruflo** | 🔄 TOGGLE | ~500–1500 tokens | Enterprise multi-agent swarm (5+ concurrent agents) | npm + MCP manual |
| **skill-creator** | 🔄 TOGGLE | ~100 tokens | Creating or editing custom skills | marketplace |
| **pr-review-toolkit** | 🔄 TOGGLE | ~300 tokens | PR review sessions | marketplace |
| **frontend-design** | 🔄 TOGGLE | ~200 tokens | Any project with a UI | marketplace |
| **ui-ux-pro-max** | 🔄 TOGGLE | ~400 tokens | Design system, color/typography choices | marketplace |
| **Context7 MCP** | 🔄 TOGGLE | ~200 tokens | Fast-evolving libs (Next.js, React, Prisma…) | MCP manual |
@@ -269,12 +428,13 @@ and **blocks if Superpowers is not active**.
### Version pinning
RTK and GSD versions are pinned in `plugins.lock.json`:
RTK, GSD v2, and ruflo versions are pinned in `plugins.lock.json`:
```json
{
"rtk": { "version": "v0.34.3" },
"gsd": { "version": "1.30.0" }
"rtk": { "source": "https://github.com/rtk-ai/rtk", "version": "v0.34.3" },
"gsd": { "source": "npm:gsd-pi", "version": "2.64.0" },
"ruflo": { "source": "npm:ruflo", "version": "3.5.58" }
}
```
@@ -294,26 +454,7 @@ Or in the project's `.claude/settings.json`:
```json
{
"enabledPlugins": {
"gstack@gstack": false,
"gsd@gsd": false
}
}
```
### Enabling a plugin for a specific project (so teammates can install it)
```json
{
"enabledPlugins": {
"ui-ux-pro-max@ui-ux-pro-max-skill": true
},
"extraKnownMarketplaces": {
"ui-ux-pro-max-skill": {
"source": {
"source": "github",
"repo": "nextlevelbuilder/ui-ux-pro-max-skill"
}
}
"gstack@gstack": false
}
}
```
@@ -339,20 +480,27 @@ DENY always wins over ALLOW at any level.
### Global settings (this repo's `settings.json`)
77 deny rules, 16 ask rules, 57 allow rules.
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`, `sed -i` (in-place file editing) |
| `allow` — safe reads | Auto-approves git read-only, `ls`, `cat`, `grep`, `find`, `sed` (stdout only) |
| `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
@@ -374,7 +522,7 @@ echo ".claude/settings.local.json" >> .gitignore
cp "$CONF/templates/settings/.claudeignore" .claudeignore
# Project CLAUDE.md (commit to project git)
cp "$CONF/templates/project-CLAUDE.md" .claude/CLAUDE.md
cp "$CONF/templates/project-CLAUDE.md" CLAUDE.md
```
---
@@ -386,14 +534,14 @@ cp "$CONF/templates/project-CLAUDE.md" .claude/CLAUDE.md
```bash
# From the repo directory
bash update-all.sh
# Pulls config, updates GStack submodule, updates RTK (pinned version), refreshes symlinks, runs doctor
# Pulls config, prompts before updating GStack (tracks main), updates RTK + GSD v2 (pinned),
# updates ruflo if installed, refreshes symlinks, runs doctor
```
### Manual updates
#### This repo
```bash
# cd into the repo (wherever you cloned it)
git pull
# Symlinks → changes active immediately
```
@@ -404,23 +552,40 @@ git pull
/gstack-upgrade
# Option B — via submodule (from the repo directory)
# Note: GStack tracks branch = main, review upstream commits before updating
git submodule update --remote skills-external/gstack
cd skills-external/gstack && ./setup
git add skills-external/gstack
git commit -m "chore: update gstack to latest"
```
GStack is a git submodule. Its version is pinned in your config repo — reproducible on every machine.
#### RTK
```bash
# Uses the version pinned in plugins.lock.json (from the repo directory)
# Uses the version pinned in plugins.lock.json
bash update-all.sh
# Or manually (check latest at https://github.com/rtk-ai/rtk/releases)
# Or manually
cargo install --git https://github.com/rtk-ai/rtk --tag v0.34.3 --force
```
#### GSD v2
```bash
# Uses the version pinned in plugins.lock.json
bash update-all.sh
# Or manually
npm install -g gsd-pi@2.64.0
```
#### Ruflo MCP
```bash
# Uses the version pinned in plugins.lock.json
bash update-all.sh
# Or manually
npm install -g ruflo@3.5.58
```
#### Marketplace plugins
```bash
/plugin marketplace update # inside Claude Code
@@ -430,22 +595,30 @@ cargo install --git https://github.com/rtk-ai/rtk --tag v0.34.3 --force
## 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 the key use case (max 250 chars)
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:
- .claude/agents/myagent.md
- $HOME/.claude/agents/myagent.md
Execute MYAGENT on:
Execute on:
$ARGUMENTS
```
@@ -475,20 +648,24 @@ cp "$CONF/agents/refactorer.md" .claude/agents/refactorer.md
bash doctor.sh
# Or from within Claude Code
/health
/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 # link.sh + install-plugins.sh
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, prerequisites (git, Node, Cargo, Python, Claude Code),
plugins (RTK, Superpowers, Context7), permissions, token budget estimate, and config consistency
(frontmatter coherence, CRLF detection).
`doctor.sh` checks 7 axes: symlinks, GStack submodule (with pinning warning), prerequisites
(git, Node, Cargo, Python, Claude Code), plugins (RTK, Superpowers, Context7, GSD v2, ruflo),
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 with `/plugin-check` and `/health` hints.
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.
@@ -500,7 +677,8 @@ bash update-all.sh
# Or step by step
git pull # this repo
git submodule update --remote skills-external/gstack # GStack
# GStack: prompts for confirmation (tracks main branch)
git submodule update --remote skills-external/gstack
bash link.sh # refresh symlinks
bash doctor.sh # verify
```
@@ -513,7 +691,6 @@ bash doctor.sh # verify
Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`.
### Orchestrator blocks at STEP 0 — Superpowers missing
The plugin-advisor blocks `/init-project` and `/ship-feature` if Superpowers is not active.
Install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`
Then re-run the orchestrator.
@@ -525,32 +702,56 @@ Run `bash link.sh` and verify: `ls -la ~/.claude/skills/gstack`.
If missing: `cd` into your config repo and run `git submodule update --init`.
### link.sh warns "is a real directory"
If `~/.claude/agents/`, `~/.claude/skills/`, or `~/.claude/lib/` exist as real directories (not symlinks
from a previous `link.sh` run), the script skips them to avoid data loss. Rename or remove the directory, then re-run `link.sh`.
If `~/.claude/agents/`, `~/.claude/skills/`, `~/.claude/lib/`, or `~/.claude/templates/` exist as real
directories, the script skips them to avoid data loss. Rename or remove the directory, then re-run `link.sh`.
### Token budget exceeded / skills truncated at session start
### GSD v2 — "command not found: gsd"
npm's global bin directory is not in `$PATH`. Run `npm prefix -g` to find it, then add `$(npm prefix -g)/bin`
to your PATH. See the [GSD troubleshooting guide](https://github.com/gsd-build/gsd-2/blob/main/docs/troubleshooting.md).
### GSD v2 — migrating from v1 projects
If you have old projects with `.planning` directories from GSD v1, migrate them:
```bash
cd your-project
gsd # start a session
/gsd migrate # migrate .planning → .gsd format
```
### Ruflo MCP not detected by doctor.sh
Ruflo must be registered as an MCP server. Run:
```bash
claude mcp add --scope user ruflo -- npx ruflo mcp start
claude mcp list | grep ruflo
```
### Token budget exceeded — skills truncated at session start
Too many plugins active. Run `/plugin-check` to optimize.
Run `bash doctor.sh` for a token budget estimate.
Run `bash doctor.sh` for a token budget breakdown (vs Pro ~11k session budget).
### settings.json not applying
Check precedence: deny always wins over allow at any level. `.claudeignore` overrides all permission rules.
Verify deny count: `cat ~/.claude/settings.json | python3 -c "import json,sys; print(len(json.load(sys.stdin)['permissions']['deny']))"`
Expected: 77 deny rules.
Expected: 100 deny rules.
### Claude reads .env despite deny rules
The `Read(**/.env)` deny rule blocks the Read tool. `Bash(cat .env)` and similar commands have separate
deny rules (included in this config). For hard exclusion regardless of tool, use `.claudeignore` in the project root.
deny rules (included in this config). For hard exclusion regardless of tool, use `.claudeignore`.
### install-plugins.sh failed — where are the logs?
Check `install-YYYYMMDD-HHMMSS.log` in your config repo directory — the script logs all output to a timestamped file.
Check `install-YYYYMMDD-HHMMSS.log` in your config repo directory.
---
## Known limitations
- **Deny rules are pattern-based, not sandboxed.** Common bypass vectors (`bash -c`, `eval`, `xargs`, `cat .env`) are blocked, but novel indirect patterns are still possible. `.claudeignore` is the only hard file exclusion mechanism.
- **Superpowers is a hard dependency** for `/init-project` and `/ship-feature`. The plugin-advisor (STEP 0) auto-detects and blocks if Superpowers is missing, with install instructions. There is no manual fallback mode.
- **Marketplace plugin versions are not pinned.** They install latest. Non-marketplace tools (RTK, GSD) are pinned in `plugins.lock.json` and read by `install-plugins.sh`.
- **Token budget is finite and not directly observable.** With all toggle plugins active, the description budget can exceed 60%. Run `/health` or `bash doctor.sh` for an estimate.
- **Agent frontmatter fields** like `model` and `memory` are declared but their enforcement by Claude Code is not guaranteed. They serve as documentation more than strict runtime controls.
- **`Bash(cat *)` in allow vs `Bash(cat .env)` in deny** depends on Claude Code resolving deny-wins. This is the expected behavior but cannot be tested outside the runtime.
- **Deny rules are pattern-based, not sandboxed.** Core bypass vectors (`bash -c`, `eval`, `python3 -c *`, `node -e *`, `source /dev/stdin`, `mkfifo *`, `xargs * .env*`, `base64 .env*`) are blocked. Process substitution (`<(cmd)`, `>(cmd)`), here strings (`<<<`), and `/dev/fd/*` access remain possible without explicit patterns — `.claudeignore` is the only hard file exclusion mechanism.
- **`disableAutoMode` syntax not verified** against CC v2.1.89 — added as `"disableAutoMode": "disable"` by analogy with `disableBypassPermissionsMode`. # TODO: VERIFY
- **Superpowers is a hard dependency** for `/init-project` and `/ship-feature`. The plugin-advisor (STEP 0) auto-detects and blocks if missing, with install instructions. No manual fallback mode.
- **Marketplace plugin versions are not pinned.** They install latest. Non-marketplace tools (RTK, GSD v2, ruflo) are pinned in `plugins.lock.json`.
- **Token budget:** `CLAUDE.md` loads in full every session (~420t). Skill bodies load on-demand. Plugin descriptions load passively. With all toggles active, passive plugin cost can reach ~50% of the Pro session budget (~11k tokens/5h). Run `/health` or `bash doctor.sh` for a breakdown.
- **GSD v2 is a standalone CLI**, not a Claude Code plugin. `/gsd ...` commands are GSD-internal and do not work in the Claude Code slash command bar.
- **Ruflo is heavy** (~340MB default, ~500-1500t passive tokens). Only enable for genuine enterprise multi-agent needs. For multi-session work, GSD v2 is lighter and sufficient.
- **Agent frontmatter fields** `model`, `memory`, `effort` are enforced by Claude Code v2.1.x.
- **`bypassPermissions` mode is disabled** via `disableBypassPermissionsMode`.
- **GStack submodule is pinned to `branch = main`**, not a commit hash. `update-all.sh` now prompts for confirmation before updating. Review upstream commits before accepting.
- **`disable-model-invocation: true` on orchestrator skills** (`/init-project`, `/ship-feature`): behavior when a skill with this flag invokes sub-agents via loaded agent files has not been fully verified in CC v2.1.89. # TODO: VERIFY