diff --git a/README.md b/README.md index 181b76f..7cdd143 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 ?", cas de figure validés, et table des erreurs fréquentes. +> **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 ?". --- @@ -97,10 +97,10 @@ bash install.sh # bash link.sh # symlink into ~/.claude/ # bash install-plugins.sh # prerequisites + all plugins -# 4. Context7 CLI (optional — for fast-evolving libs like Next.js, React, Prisma) +# 4. Context7 CLI (optional — fast-evolving libs docs lookup) npm install -g ctx7 -ctx7 setup --claude # configures MCP + rules for Claude Code (OAuth login) -# Or use standalone: ctx7 docs /vercel/next.js "middleware" +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 @@ -158,90 +158,22 @@ Install output is logged to `install-YYYYMMDD-HHMMSS.log` in the repo directory | `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) +### GStack (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. +> 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) -> **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. +> 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) -```bash -# Start a GSD session in your terminal (from your project directory) -gsd +### Ruflo CLI — OFF (disabled by default) -# 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 | -|---|---| -| `/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 v2 vs v1:** - -| | 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 CLI (enterprise multi-agent orchestration) - -> Ruflo (formerly claude-flow) is a heavy enterprise multi-agent orchestration CLI — 310+ tools, 100+ agent types, -> WASM kernel, self-learning architecture. ~500-1500 tokens passive cost when hooks 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 -> # Minimal install (~40MB, no ML/embeddings) -> npm install -g ruflo@latest --omit=optional -> -> # Initialize in your project -> ruflo init --wizard -> -> # Useful commands -> ruflo agent spawn -t coder # spawn a coding agent -> ruflo swarm init # start a swarm -> ruflo memory search -q "..." # search vector memory -> ruflo doctor # diagnostics -> -> # Verify -> ruflo --version -> ``` +> Enterprise multi-agent orchestration CLI (310+ tools, WASM kernel, self-learning architecture). +> Heavy: ~500-1500 tokens passive cost. For standard multi-session work, GSD v2 is lighter and sufficient. +> Docs: [github.com/ruflo-ai/ruflo](https://github.com/ruflo-ai/ruflo) ### Bundled skills (Claude Code built-in, always available) @@ -446,6 +378,57 @@ Warns if ruflo is active with no multi-agent signal, or if GSD v2 CLI is not ins --- +## 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`. @@ -466,12 +449,12 @@ Run `/plugin-check` anytime to get a recommendation for the current project type | **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) | -| **ruflo** | 🔄 TOGGLE | ~500–1500 tokens | Enterprise multi-agent swarm (5+ concurrent agents) | npm (CLI) | +| **ruflo** | ⚫ OFF (disabled) | ~500–1500 tokens | Enterprise multi-agent swarm (5+ concurrent agents) | npm (CLI) | | **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 | | **frontend-design** | 🔄 TOGGLE | ~200 tokens | Any project with a UI | 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) + optional ctx7 setup --claude | +| **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 @@ -620,56 +603,13 @@ bash update-all.sh ### Manual updates -#### This repo ```bash -git pull -# Symlinks → changes active immediately +git pull # this repo — symlinks make changes active immediately +bash link.sh # refresh symlinks if needed ``` -#### GStack (submodule) -```bash -# Option A — inside Claude Code (recommended) -/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" -``` - -#### RTK -```bash -# Uses the version pinned in plugins.lock.json -bash update-all.sh - -# 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 CLI -```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 -``` +All third-party tools (RTK, GSD v2, ruflo, GStack, ctx7, marketplace plugins) are updated +automatically by `update-all.sh`. Versions are pinned in `plugins.lock.json`. --- @@ -707,6 +647,28 @@ $ARGUMENTS --- +## 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: @@ -750,99 +712,3 @@ and displays toggle plugin status, GSD v2 CLI status, with `/plugin-check` and ` Both scripts source `lib/detect-plugins.sh` for consistent plugin detection logic. -### Updating - -```bash -# One-command update (from the repo directory) -bash update-all.sh - -# Or step by step -git pull # this repo -# GStack: prompts for confirmation (tracks main branch) -git submodule update --remote skills-external/gstack -bash link.sh # refresh symlinks -bash doctor.sh # verify -``` - ---- - -## Troubleshooting - -### "command not found" after install -Restart your shell or run `source ~/.bashrc` / `source ~/.zshrc`. - -### Orchestrator blocks at STEP 0 — Superpowers missing -Install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace` -Then re-run the orchestrator. - -### "agent not found" or hallucinated agent content -Symlinks are broken. `cd` into your config repo and run `bash link.sh`, then verify with `bash doctor.sh`. - -### GStack skills not showing up -Run `bash link.sh` and verify: `ls -la ~/.claude/skills/gstack`. -If missing: `cd` into your config repo and run `git submodule update --init`. - -### GStack submodule "directory not found after init" -The submodule is not registered in `.gitmodules` (never added). Fix: -```bash -cd ~/Documents/claude # chemin de ton config repo -git submodule add https://github.com/garrytan/gstack skills-external/gstack -git submodule update --init --recursive -bash link.sh -git add .gitmodules skills-external/gstack && git commit -m "chore: add gstack submodule" -``` - -### link.sh warns "is a real directory" -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`. - -### 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 CLI not detected by doctor.sh -Ruflo must be installed globally. Run: -```bash -npm install -g ruflo@latest --omit=optional -ruflo --version -``` - -### 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 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: 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`. - -### install-plugins.sh failed — where are the logs? -Check `install-YYYYMMDD-HHMMSS.log` in your config repo directory. - ---- - -## Known limitations - -- **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 diff --git a/USAGE.md b/USAGE.md index ec547ff..d4739ab 100644 --- a/USAGE.md +++ b/USAGE.md @@ -558,8 +558,6 @@ WHAT TO VERIFY NEXT: DO NOT TOUCH: src/store/cartStore.ts dans son ensemble — corriger seulement la ligne 47 ``` - - --- ### Exemple 6 — CLI Rust from scratch (workflow minimaliste) @@ -664,11 +662,7 @@ Simple à valider. L'architecture proposée est plate, pas de surprise. **`/analyze` avant `/refactor` :** toujours. Le refactorer attend le rapport d'analyse avant de toucher au code. Le passer en bypass donne de moins bons résultats. -**`/readme` régulièrement :** après chaque milestone. Le mode AUDIT compare le README à l'état réel du code et liste les divergences — évite la documentation périmée. - ---- - ---- +**`/doc` régulièrement :** après chaque milestone. Le mode AUDIT compare la documentation à l'état réel du code et liste les divergences — évite la documentation périmée. --- @@ -775,417 +769,6 @@ TESTS: ✅ 8 tests passent (créés avant refactoring) --- -## Cas de figure — corrections v2.2.0 validées - -Ces exemples valident les bugs corrigés dans la version 2.2.0. - ---- - -### Cas A — Onboarding d'un monorepo Next.js + FastAPI - -**Contexte :** repo avec `apps/web/` (Next.js 14) et `apps/api/` (FastAPI). Pas de `CLAUDE.md`. La racine n'a qu'un `package.json` de workspace vide. - -**Avant v2.2.0 :** `/onboard` lisait le `package.json` racine (workspaces uniquement), ne trouvait pas de stack claire, produisait un `CLAUDE.md` incomplet ou demandait trop de questions. - -**Avec v2.2.0 :** -``` -/onboard - -→ PHASE 1: apps/, pnpm-workspace.yaml détectés - -MONOREPO DETECTED -Sub-packages: apps/web/, apps/api/ -Options: - A) Workspace entier — un CLAUDE.md à la racine - B) apps/web seulement - C) Chaque package séparément - -[User: A] - -→ Lit apps/web/package.json → Next.js 14, TypeScript, Tailwind -→ Lit apps/api/pyproject.toml → FastAPI, SQLAlchemy, alembic -→ Lit Makefile racine → make dev-web, make dev-api, make test - -→ CLAUDE.md généré: - Stack: Next.js 14 (apps/web/) + FastAPI (apps/api/) + PostgreSQL - Build: make dev-web | make dev-api | docker compose up --build - Structure: monorepo, 2 apps indépendantes, DB partagée -``` - ---- - -### Cas B — ship-feature : subagent en échec - -**Contexte :** feature notifications email, STEP 4, tâche 3 (worker retry) échoue. - -**Avant v2.2.0 :** arrêt abrupt. L'utilisateur devait diagnostiquer lui-même, relancer manuellement. - -**Avec v2.2.0 :** -``` -STEP 4 — Tâche 3 échoue: - pytest FAILED test_retry_on_failure — AssertionError: worker ne retente pas - -→ STEP 4b déclenché automatiquement - -DEBUG ANALYSIS: Worker ne retente pas après timeout SMTP -ROOT CAUSE: - 1. [HIGH] Mock déclenche ConnectionRefusedError ≠ SMTPException — le retry handler ne s'active pas - 2. [MED] max_retries non configuré dans le worker (valeur par défaut = 0) - -SHIP FEATURE — ERROR IN STEP 4 -OPTIONS: - A) Corriger le mock (hypothesis 1) - B) Passer cette tâche - C) Abort - -[User: A] → fix ciblé → re-run tâche 3 → passe ✅ → suite de la feature -``` - ---- - -### Cas C — Projet mobile React Native : signal correct - -**Contexte :** `/init-project "App mobile KartApp React Native Expo iOS Android"`. - -**Avant v2.2.0 :** signal `frontend` uniquement → `gstack` potentiellement recommandé (aberrant sur mobile). - -**Avec v2.2.0 :** -``` -SIGNALS: mobile (React Native + Expo détectés) - -RECOMMENDATIONS: - ⚡ ENABLE : frontend-design — composants React Native (~200t) - ⚠️ DISABLE : gstack — mobile, pas de browser QA ni deploy web - ℹ️ OPTIONAL: ui-ux-pro-max — uniquement si design system complexe - ℹ️ NOTE : Docker N/A pour les apps mobiles - -BLOCKING: none -``` - ---- - -### Cas D — STEP 13 avec GSD v2 non installé - -**Contexte :** `/init-project` multi-session atteint STEP 13. `gsd` absent du PATH. - -**Avant v2.2.0 :** `gsd init` → "command not found" → erreur opaque. - -**Avec v2.2.0 :** -``` -STEP 13 — GSD v2 INIT -→ Vérification: command -v gsd → NOT FOUND - -⚠️ GSD v2 not installed. - Run: npm install -g gsd-pi - Then: /onboard add gsd (pour générer ROADMAP.md) - -→ STEP 13 skippé proprement -→ Projet initialisé correctement ✅ -→ GSD v2 peut être ajouté plus tard -``` - ---- - -### Cas E — CLI Rust : workflow minimaliste (0 plugin inutile) - -**Contexte :** `/init-project "CLI Rust jsonconv, pas de réseau, pas de frontend"`. - -``` -/plugin-check "CLI Rust convertisseur JSON/CSV/TOML" - -SIGNALS: simple, CLI pur -COST: ~800t - -RECOMMENDATIONS: - ✅ KEEP : superpowers - ⚠️ DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo -BLOCKING: none → "proceed" - -→ Scaffolder: cargo check comme verify (pas cargo build) -→ Docker: N/A (CLI pur) -→ Pipeline complet en ~800t passif, zéro bruit -``` - -Point clé : **`/plugin-check` est utile même pour confirmer qu'on n'a rien à activer.** Évite de polluer le contexte avec 3000t de plugins inutiles sur un projet simple. - ---- - -## Cas de figure — corrections v2.3.0 validées - ---- - -### Cas F — `/ship-feature` sans CLAUDE.md (nouveau repo cloné) - -**Contexte :** développeur clone un repo existant, lance directement `/ship-feature` sans avoir run `/onboard`. - -**Avant v2.3.0 :** le brainstorm (STEP 1) démarrait sans contexte projet → questions génériques, architecture inadaptée au projet réel. - -**Avec v2.3.0 :** -``` -/ship-feature "Ajouter authentification OAuth Google" - -→ STEP 0 : plugin check OK -→ STEP 0b : ls CLAUDE.md .claude/CLAUDE.md → rien trouvé - -⚠️ No CLAUDE.md found in this directory. - This project has not been onboarded into claude-config. - Run `/onboard` first, then re-run `/ship-feature`. - STOP. -``` - -L'utilisateur fait `/onboard`, obtient son CLAUDE.md, relance `/ship-feature` avec le bon contexte. - ---- - -### Cas G — Onboarding monorepo turborepo (Option C séquentielle) - -**Contexte :** repo avec `apps/web/`, `apps/api/`, `packages/ui/`, `turbo.json`, `pnpm-workspace.yaml`. - -**Avant v2.3.0 :** Option C non implémentée — comportement indéfini. - -**Avec v2.3.0 :** -``` -/onboard - -MONOREPO DETECTED (turbo.json + pnpm-workspace.yaml) -Sub-packages: apps/web/, apps/api/, packages/ui/ -[User: C] - -── Package 1/3: apps/web ── - Stack: Next.js 14 / TypeScript - Genere: apps/web/CLAUDE.md + settings + .claudeignore - OK - -── Package 2/3: apps/api ── - Stack: Express / Prisma / PostgreSQL - Genere: apps/api/CLAUDE.md + settings + .claudeignore - OK - -── Package 3/3: packages/ui ── - Stack: React + Storybook + Tailwind - Genere: packages/ui/CLAUDE.md + settings + .claudeignore - OK - -Resume: 3 packages onboardes - apps/web | Next.js 14 | OK - apps/api | Express/Prisma| OK - packages/ui | React/Storybook| OK - -"Generate root-level ROADMAP.md? (yes/skip)" -``` - -Chaque package a son propre CLAUDE.md. Pas de CLAUDE.md racine (Option C). - ---- - -### Cas H — plugin-advisor : signal `monorepo` evite gstack inutile - -**Contexte :** monorepo Next.js (apps/web/) + FastAPI (apps/api/). Avant : signal `frontend` + `deploy` → gstack recommandé pour tout le repo. - -**Avec v2.3.0 :** -``` -SIGNALS: monorepo, frontend(apps/web/), fast-libs(Next.js), deploy(apps/api/) - -RECOMMENDATIONS: - OK KEEP : superpowers - ENABLE : frontend-design — apps/web/ uniquement (~200t) - WARN : context7 — Next.js detecte dans apps/web/ - DISABLE : gstack — apps/api/ n'a pas de browser-qa - (NOTE: gstack aurait ete recommande si browser-qa present) - DISABLE : ui-ux-pro-max — pas de design-system signal - -Cout total: ~1200t (au lieu de ~4400t avec gstack) -``` - ---- - -### Cas I — doctor.sh detecte templates/ manquant (installation pre-v2.0.0) - -**Contexte :** installation ancienne (avant v2.0.0), `link.sh` n'avait pas de templates dans la boucle. - -**Avant v2.3.0 :** `/init-project` echouait silencieusement en STEP 5 (scaffolder ne trouvait pas `~/.claude/templates/project-CLAUDE.md`). - -**Avec v2.3.0 :** -``` -bash doctor.sh - -── Symlinks ── - OK ~/.claude/CLAUDE.md - OK ~/.claude/settings.json - OK ~/.claude/agents - OK ~/.claude/skills - MISSING: ~/.claude/templates ← nouveau check - OK ~/.claude/hooks/session-start.sh - -Fix: cd /path/to/claude-config && bash link.sh -``` - -L'utilisateur voit exactement ce qui manque et la commande pour corriger. - ---- - -### Cas J — session-start : box ne deborde pas avec 5 plugins actifs - -**Avant v2.3.0 :** avec `gstack frontend-design ui-ux-pro-max context7 ruflo` tous actifs, la ligne `ON` depassait la largeur de la box. - -**Avec v2.3.0 :** -``` -┌─ Claude Code config ──────────────────────────────────┐ -│ ✅ ON : security-guidance rtk superpowers │ -│ 🟢 ON : gstack frontend-design ui-ux-pro-ma... │ <- tronque a 37+... -│ ⚫ OFF : none │ -│ 💰 ~5350t passif (48% budget) │ -│ 📦 v2.3.0 │ -└───────────────────────────────────────────────────────┘ -``` - -La box reste alignee. L'utilisateur voit qu'il y a plus de plugins (les `...` indiquent la troncature) et peut faire `/health` pour la liste complete. - ---- - -## Cas de figure — corrections v2.4.0 validées - ---- - -### Cas K — `/init-project` sur un projet avec CLAUDE.md existant - -**Contexte :** projet FastAPI avec un `CLAUDE.md` minimal (stack documenté, features absentes). L'utilisateur veut ajouter un module de facturation. - -**Avant v2.4.0 :** STEP 1 posait toutes les questions (stack, purpose, features, conventions) même si le stack était déjà documenté. - -**Avec v2.4.0 :** -``` -/init-project "Ajouter un module de facturation au projet" - -STEP 1 — ls CLAUDE.md → FOUND -📄 Existing CLAUDE.md found — using as context. - -Questions posées (manquantes seulement): - → Features v1 du module facturation ? - → Stratégie de tests ? - → Conventions spécifiques ? - -Questions SKIP (déjà dans CLAUDE.md): - → Stack (Python 3.12 / FastAPI / PostgreSQL) ✓ - → Architecture ✓ -``` -3 questions au lieu de 6. Gain de temps significatif sur les projets déjà documentés. - ---- - -### Cas L — `/status` en début de session (projet multi-semaines) - -**Contexte :** projet CardForge repris après 3 jours. GSD v2 initialisé, milestone 2 en cours. - -``` -/status - -PROJECT STATUS -============== - -CONFIG - Version : v2.4.0 - Plugins ON: superpowers, frontend-design, context7 (~1200t) - GSD v2 : installed (2.64.0) - -PROJECT - CLAUDE.md : found - Stack : React 18 + FastAPI + PostgreSQL + Docker - Branch : feature/stripe-integration - Uncommitted: 3 files - -RECENT COMMITS (last 5): - a1b2c3d feat: add card collection schema - e4f5g6h fix: jwt refresh token expiry - ... - -GSD v2 - Status : initialized - Milestone : Milestone 2 — Boutique in-app - Progress : 2/5 slices done - -QUICK ACTIONS - /ship-feature "..." — next feature - /health — full diagnostic -``` - -Vue complète en une commande. Utile après un break pour se réorienter avant de taper `/gsd auto`. - ---- - -### Cas M — plugin-advisor depuis un sous-package de monorepo - -**Contexte :** l'utilisateur est dans `apps/web/` et lance `/plugin-check`. Le monorepo a `turbo.json` et `pnpm-workspace.yaml` à la racine (`../`). - -**Avant v2.4.0 :** pas de détection monorepo → plugins recommandés comme pour un projet standalone Next.js. - -**Avec v2.4.0 :** -``` -/plugin-check "Next.js frontend" (depuis apps/web/) - -PHASE 1 — upstream detection: - ls ../turbo.json → FOUND - ls ../pnpm-workspace.yaml → FOUND - -SIGNALS: monorepo (upstream), frontend, fast-libs(Next.js) -NOTE: dans apps/web/ d'un monorepo (détecté via parent dir) - -RECOMMENDATIONS: - ENABLE: frontend-design — apps/web/ uniquement - WARN: context7 — Next.js détecté - DISABLE: gstack — pas de browser-qa dans ce package -``` - -La recommandation est correcte même sans être à la racine du monorepo. - ---- - -### Cas N — doctor.sh avec compteur de symlinks - -**Contexte :** installation avant v2.0.0 — `templates/` n'est pas symlinké. - -``` -bash doctor.sh - -── Symlinks ── - ✓ ~/.claude/CLAUDE.md - ✓ ~/.claude/settings.json - ✓ ~/.claude/agents - ✓ ~/.claude/skills - ✗ ~/.claude/templates — MISSING - ✓ ~/.claude/hooks/session-start.sh - → Symlinks: 5/6 OK - -Fix: cd /path/to/claude-config && bash link.sh -``` - -Le compteur `5/6 OK` indique exactement le problème sans lire toutes les lignes. - ---- - -### Cas O — session-start avec 5 toggles actifs - -**Avant v2.4.0 :** avec gstack + frontend-design + ui-ux-pro-max + context7 + ruflo actifs, la ligne débordait la box. - -**Avec v2.4.0 :** -``` -┌─ Claude Code config ──────────────────────────────────┐ -│ ✅ ON : security-guidance rtk superpowers │ -│ 🟢 ON : gstack frontend-design +3 more │ -│ ⚫ OFF : none │ -│ 💰 ~5350t passif (48% budget) │ -│ 📦 v2.4.0 │ -│ 💡 /plugin-check before starting a new project │ -│ 🩺 /health to run full diagnostic │ -└───────────────────────────────────────────────────────┘ -``` - -`+3 more` indique qu'il y a 3 plugins actifs supplémentaires. `/health` donne la liste complète. - ---- - ---- - ### Exemple 8 — Reprise d'une session interrompue avec GSD v2 **Contexte :** projet CardForge (React + FastAPI), milestone 2 "Boutique Stripe" en cours. Travail interrompu 4 jours plus tôt. GSD v2 initialisé, 3/7 slices terminées. @@ -1284,142 +867,6 @@ GSD v2 met à jour le plan dans `.gsd/ROADMAP.md` sans perdre le travail déjà - **GSD v2 `step mode`** est préférable à `auto` après une longue pause — permet de vérifier que les décisions sont toujours valides. - **`.gsd/ROADMAP.md`** est la source de vérité du progress — parsé par `/status` et par GSD lui-même. - **`/gsd discuss`** permet de modifier l'architecture en cours de route sans recommencer depuis zéro. - ---- - -## Cas de figure — corrections v2.5.0 validées - ---- - -### Cas P — `/init-project` détecte `.claude/CLAUDE.md` - -**Contexte :** projet Node.js/Express avec CLAUDE.md dans `.claude/` (pas à la racine). - -**Avant v2.5.0 :** `ls CLAUDE.md` ne trouvait rien → 6 questions pour redécouvrir le stack. - -**Avec v2.5.0 :** -``` -/init-project "Ajouter notifications push" - -STEP 1: ls CLAUDE.md .claude/CLAUDE.md → .claude/CLAUDE.md FOUND -📄 Existing CLAUDE.md found — using as context. - -Questions posées (manquantes seulement): - → Service push ? (Firebase/OneSignal/APNs ?) - → Types ? (in-app/email/mobile ?) - -Questions SKIP (déjà dans .claude/CLAUDE.md): - → Stack (Node.js 20 / Express / MongoDB) ✓ - → Purpose ✓ -``` -2 questions au lieu de 6. - ---- - -### Cas Q — `/status` avec GSD v2 et ROADMAP.md présent - -**Contexte :** projet CardForge avec `.gsd/ROADMAP.md` contenant des checkboxes GSD. - -**Avant v2.5.0 :** `cat .gsd/STATUS.md` → fichier inexistant → `"no STATUS.md"`. - -**Avec v2.5.0 :** -``` -/status - -PHASE 3 — parse ROADMAP.md: - - [x] Slice 1 — Schema DB ✓ - - [x] Slice 2 — Auth JWT ✓ - - [x] Slice 3 — Collection cards ✓ - - [ ] Slice 4 — Boutique Stripe (en cours) - - [ ] Slice 5 — PvP - ... - -GSD v2 - Status : initialized - Milestone : Milestone 2 — Boutique in-app - Progress : 3/7 slices done (43%) -``` - ---- - -### Cas R — `/status` avec `.gsd/` vide (pas de ROADMAP.md) - -**Contexte :** `gsd init` fait mais `/gsd discuss` pas encore lancé. - -``` -/status - -GSD v2 - Status : initialized - Milestone : N/A - Progress : N/A - - GSD v2 initialized — no ROADMAP.md yet. - Run /gsd init or /gsd discuss to create one. -``` - -Message actionnable au lieu d'une erreur silencieuse. - ---- - -### Cas S — `doctor.sh` détecte `status-reporter.md` manquant - -**Contexte :** installation v2.3.0 ou antérieure — `status-reporter.md` n'existait pas. - -``` -bash doctor.sh - -── Consistency ── - ✓ All skills have disable-model-invocation - ⚠ Missing agents: status-reporter.md — run: bash link.sh - ✓ No CRLF line endings detected -``` - -Sans ce check : `/status` chargerait un agent inexistant → erreur cryptique. - ---- - -### Cas T — session-start avec 6 plugins actifs (tous affichés) - -**Avant v2.5.0 :** `gstack frontend-design +4 more` — 4 plugins masqués. - -**Avec v2.5.0 :** -``` -┌─ Claude Code config ──────────────────────────────────┐ -│ ✅ ON : security-guidance rtk superpowers │ -│ 🟢 ON : gstack frontend-design ui-ux-pro-max context7│ -│ + ruflo plugin-dev │ -│ ⚫ OFF : none │ -│ 💰 ~5750t passif (52% budget) │ -│ 📦 v2.5.0 │ -└───────────────────────────────────────────────────────┘ -``` - -Tous les noms visibles, box alignée. - ---- - -### Cas U — onboarder crée `.gitignore` pour protéger `settings.local.json` - -**Contexte :** monorepo, Option B (apps/api/), aucun `.gitignore` dans le package. - -``` -/onboard B apps/api - -PHASE 5b — .gitignore check: - ls .gitignore → absent - - Créé: apps/api/.gitignore - # claude-config — personal settings (never commit) - .claude/settings.local.json - -📝 Created .gitignore with .claude/settings.local.json entry -``` - -Sans ce check : `settings.local.json` risquait d'être commité avec les clés API et credentials. - ---- - --- ### Exemple 9 — Firmware C/C++ embarqué (workflow sans superpowers) @@ -1494,566 +941,6 @@ STEP 4 — IMPLEMENT (subagents légers, modifications chirurgicales) - `/analyze` est particulièrement utile sur du code C bas-niveau : l'analyzer identifie les accès non-atomiques, les race conditions, les violations de normes, **sans proposer de fix**. - Pour un firmware, le workflow `analyze → ship-feature` peut se réduire à `analyze → edit direct` si la modification est triviale. - GSD v2 n'est jamais pertinent pour du firmware : les sessions sont courtes et les tâches atomiques. - ---- - -## Cas de figure — corrections v2.6.0 validées - ---- - -### Cas V — `/status` compte les slices, pas les tasks - -**Contexte :** `.gsd/ROADMAP.md` avec 3 milestones, chacun subdivisé en slices (`###`) contenant des tasks (`- [ ]`). - -**Avant v2.6.0 :** comptait `- [x]` = nombre de tasks terminées → résultat faux (ex: `6/8 "slices"` alors que c'était des tasks). - -**Avec v2.6.0 :** -``` -ROADMAP.md: - ## Milestone 1 — Auth [x] - ### Slice 1 — JWT setup [x] ← slice terminée - ### Slice 2 — Login UI [x] ← slice terminée - ## Milestone 2 — Boutique - ### Slice 3 — Cart UI [x] ← slice terminée - ### Slice 4 — Stripe checkout ← en cours - ### Slice 5 — Webhook handler ← en attente - -/status → GSD v2 : Progress = 3/5 slices done (60%) - Milestone actuel : Milestone 2 — Boutique -``` - -3/5 correspond exactement au dashboard GSD v2. - ---- - -### Cas W — `/ship-feature` affiche le contexte projet dès STEP 0b - -**Avant v2.6.0 :** STEP 0b trouvait CLAUDE.md → continuait silencieusement. Pas de rappel de contexte. - -**Avec v2.6.0 :** -``` -/ship-feature "Ajouter webhook Stripe" - -STEP 0b — CLAUDE.md found -📋 PROJECT CONTEXT - Project : CardForge - Stack : React 18 + FastAPI + PostgreSQL + Docker - Branch : feature/stripe-integration - Recent : feat: add cart persistence - feat: implement collection display - chore: setup Stripe SDK - GSD : Milestone 2 — Boutique (3/5 slices) - -→ STEP 1 — BRAINSTORM -``` - -Developer se réoriente instantanément — pas de risque d'implémenter sur la mauvaise branche. - ---- - -### Cas X — session-start : 6 plugins actifs, tous affichés - -``` -┌─ Claude Code config ──────────────────────────────────┐ -│ ✅ ON : security-guidance rtk superpowers │ -│ 🟢 ON : gstack frontend-design ui-ux-pro-max context7│ -│ ruflo plugin-dev │ -│ ⚫ OFF : none │ -│ 💰 ~5750t passif (52% budget) │ -│ 📦 v2.6.0 │ -└───────────────────────────────────────────────────────┘ -``` - -Tous les 6 plugins actifs visibles. Ligne de continuation alignée avec la ligne principale. - ---- - -### Cas Y — Exemple 8 en action : reprise de session CardForge - -``` -# Dans Claude Code -/status -→ 3/5 slices, branche feature/stripe-integration, 1 fichier uncommitted - -# Dans un terminal -gsd -/gsd (step mode — relire le plan avant d'exécuter) - -# Architecture change détectée pendant la pause -/gsd discuss "Je veux PaymentElement pas CardElement" -→ Plan mis à jour - -# Reprendre l'exécution autonome -/gsd auto -→ GSD exécute Slice 4 avec le plan mis à jour, commits propres -``` - -Cycle complet : orientation → vérification plan → décision → exécution. Zero perte de contexte. - ---- - -## Cas de figure — corrections v2.7.0 validées - ---- - -### Cas Z1 — `/status` détecte le bon milestone courant - -**Avant v2.7.0 :** `grep -E '^## ' | tail -5` → retournait les 5 derniers headings `##`, pouvait inclure des milestones **terminés** comme courant. - -**Avec v2.7.0 :** -``` -ROADMAP.md: - ## Milestone 1 — Auth [x] - ### Slice 1 — JWT [x] - ## Milestone 2 — Boutique - ### Slice 3 — Cart UI [x] - ### Slice 4 — Stripe checkout ← première slice en attente - -awk scan top-to-bottom: - → Slice 4 n'a pas [x] → milestone courant = "Milestone 2 — Boutique" ✓ -``` - ---- - -### Cas Z2 — `/status` affiche l'état des tests - -**Contexte :** projet Python, dernier pytest avec 1 test échoué. - -``` -/status - -PROJECT - CLAUDE.md : found - Stack : FastAPI / PostgreSQL - Branch : feature/notifications - Uncommitted : 2 files - Tests : 1 failing (test_email_worker.py::test_retry) -``` - -Developer voit immédiatement le test cassé avant de relancer GSD. - ---- - -### Cas Z3 — `/ship-feature` : commits tronqués à 50 chars - -``` -📋 PROJECT CONTEXT - Recent : a1b2c3d feat: add Stripe PaymentIntent creation wi... - e4f5g6h fix: jwt token refresh not working on mobi... - i7j8k9l chore: update all dependencies to latest v... -``` - -Messages complets disponibles via `git log` — le contexte PROJECT affiche uniquement les 50 premiers caractères. - ---- - -### Cas Z4 — `doctor.sh` détecte `lib/` non symlinké - -``` -bash doctor.sh - -── Symlinks ── - ✓ ~/.claude/CLAUDE.md - ... - ⚠ ~/.claude/lib exists but is NOT a symlink - ✓ ~/.claude/hooks/session-start.sh - → Symlinks: 6/7 OK - -Fix: mv ~/.claude/lib ~/.claude/lib.bak && bash link.sh -``` - -Si `lib/` n'est pas un symlink vers le repo, `detect-plugins.sh` sourcé est la version installée localement — potentiellement périmée. - ---- - -### Cas Z5 — plugin-advisor warn sur plugin-dev inactif - -**Contexte :** projet React SaaS, `plugin-dev` resté actif par oubli. - -``` -/plugin-check "React SaaS avec FastAPI" - -SIGNALS: frontend, deploy, fast-libs(React) - -WARN: plugin-dev ON — aucun signal skill-creation détecté - → ~100t économisés si désactivé - → Activer uniquement quand vous créez des skills custom -``` - ---- - -### Cas Z6 — Firmware C STM32 : aucun plugin inutile - -``` -/plugin-check "Firmware C STM32, bare-metal, I2C driver" - -SIGNALS: simple, embedded -COST: ~800t (superpowers seul) - -DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo, plugin-dev -NOTE: Pour hotfix ultra-ciblé, superpowers aussi optionnel -``` - -Pipeline complet disponible : `/analyze` → `/ship-feature` avec 0 overhead de plugins inutiles. Voir Exemple 9 pour le détail. - ---- - -## Cas de figure — corrections v2.8.0 validées - ---- - -### Cas AA — awk portable : milestone courant sur macOS et Linux - -``` -ROADMAP: - ## Milestone 1 — Auth [x] - ### Slice 1 — JWT [x] - ## Milestone 2 — Boutique - ### Slice 3 — Cart UI [x] - ### Slice 4 — Stripe checkout ← pas de [x] - -awk scan (index() au lieu de regex): - ## Milestone 2 → ms = "## Milestone 2 — Boutique" - ### Slice 3 [x] → index = 14 ≠ 0 → skip - ### Slice 4 → index = 0 → PRINT "## Milestone 2" → EXIT ✓ -``` - -Fonctionne identiquement sur GNU awk (Linux) et nawk (macOS). - ---- - -### Cas AB — Tests field : fallback sur la commande de test - -``` -Projet Node.js, pas de run récent, mais package.json présent: - -/status → Tests: run 'jest --coverage' to check - -Projet Rust (pas de CI log): -/status → Tests: run 'cargo test' to check - -Firmware C (pas de test infra du tout): -/status → Tests: N/A -``` - -Plus jamais "unknown" quand il y a un test script défini. - ---- - -### Cas AC — signal `embedded` sur firmware ESP32 - -``` -/plugin-check "Firmware ESP32 WiFi driver, FreeRTOS, C" - -SIGNALS: embedded (ESP32, Firmware, FreeRTOS détectés) -NOTE: embedded project detected — minimal plugin footprint - -RECOMMENDATIONS: - superpowers OPTIONAL - DISABLE: tout le reste (frontend-design, gstack, context7, ruflo, plugin-dev) - gsd v2: NOT recommended - -Workflow: /analyze src/wifi_driver.c → /ship-feature si multi-fichiers -COST: ~800t (ou 0 si superpowers désactivé) -``` - ---- - -### Cas AD — doctor.sh liste les 8 agents - -``` -── Consistency ── - ✓ All 8 agents present (analyzer, interviewer, plugin-advisor, readme-updater, - refactorer, scaffolder, onboarder, status-reporter) -``` - -Confirme visuellement la présence de `onboarder` et `status-reporter` (ajoutés en v2.4.0). - ---- - -### Cas AE — Arbre de décision "Quel skill utiliser ?" - -| Situation | Skill | -|---|---| -| Bug dans API FastAPI existante | `/ship-feature` | -| Comprendre un module avant modifier | `/analyze` | -| Reprise après 4 jours | `/status` | -| Install Claude Code cassée | `/health` | -| App Flutter from scratch | `/init-project` | -| Quels plugins pour React ? | `/plugin-check` | - -L'arbre de décision est maintenant disponible en début de USAGE.md (section "Quel skill utiliser ?"). - ---- - -## Cas de figure — corrections v2.9.0 validées - ---- - -### Cas AF — signal `embedded` détecté depuis le filesystem - -**Contexte :** dossier firmware ESP32, `platformio.ini` présent, `src/*.c`, pas de `package.json`. L'utilisateur tape `/plugin-check` sans argument. - -**Avant v2.9.0 :** aucun signal détecté → recommandations génériques. - -**Avec v2.9.0 :** -``` -/plugin-check (sans argument, depuis le dossier firmware) - -PHASE 1 filesystem scan: - platformio.ini → FOUND → signal embedded - -SIGNALS: embedded (platformio.ini) -NOTE: embedded project detected — minimal plugin footprint - -KEEP : superpowers (optional) -DISABLE: frontend-design, ui-ux-pro-max, gstack, context7, ruflo, plugin-dev -gsd v2 : NOT recommended (sessions courtes, tâches atomiques) -``` - ---- - -### Cas AG — ROADMAP.md flat (pas de `###` slices) - -**Contexte :** GSD v2 initialisé avec un ROADMAP minimal : tasks directement sous `##`, sans `### Slice`. - -**Avant v2.9.0 :** awk ne trouvait aucun `###` → retournait `"all milestones complete"` → faux. - -**Avec v2.9.0 :** -``` -ROADMAP: - ## Milestone 2 — Core - - [x] Create models - - [ ] Implement CRUD ← task en attente - -awk fallback flat: - → "## Milestone 2 — Core (flat)" - -/status → GSD v2: Milestone 2 — Core (flat) -``` - ---- - -### Cas AH — pytest cache `{}` = all passing - -**Avant v2.9.0 :** `cat .pytest_cache/.../lastfailed` affichait `{}` littéralement. - -**Avec v2.9.0 :** -```python -d = json.load(open('.pytest_cache/v/cache/lastfailed')) -# d = {} → n = 0 -# Output: "pytest: all passing" -``` - ---- - -### Cas AI — Refactoring profond : cycle `/analyze` → `/refactor` → `/analyze` - -``` -# Étape 1 : comprendre avant de toucher -/analyze src/payment/ -→ RISKS: process_payment 95 lignes, global non-mockable, 0 tests - -# Étape 2 : corriger sur la base du rapport -/refactor src/payment/ -→ split, injection, tests ajoutés - -# Étape 3 : confirmer que les violations sont résolues -/analyze src/payment/ -→ VIOLATIONS FIXED: 95→18 lignes, injectable ✓ -→ TESTS: 8 passing -``` - -Ce cycle est maintenant documenté dans l'arbre de décision ("Quel skill utiliser ?"). - ---- - -### Cas AJ — README renvoie vers USAGE.md - -``` -# claude-config - -Global Claude Code configuration... - -> Guide d'utilisation complet : voir USAGE.md — workflows typiques, exemples -> par type de projet, arbre de décision, cas validés... -``` - -Un nouvel utilisateur trouve immédiatement le guide pratique. - ---- - -## Cas de figure — corrections v3.0.0 validées - ---- - -### Cas AK — Rust FFI : plus de faux positif embedded - -**Contexte :** bibliothèque Rust avec bindings C (FFI). `tests/c_binding_test.c` présent mais c'est du Rust, pas du firmware. - -**Avant v3.0.0 :** présence de `.c` → signal embedded → recommandations firmware inutiles. - -**Avec v3.0.0 :** -``` -PHASE 1: ls platformio.ini → absent, ls *.ld → absent -Signal embedded: NOT detected ✓ - -SIGNALS: none (Rust library) -→ workflow normal Rust, superpowers + context7 -``` - -Seuls `platformio.ini` ou un linker script `*.ld` déclenchent le signal embedded. - ---- - -### Cas AL — ROADMAP avec `## Prerequisites` (faux positif évité) - -**Contexte :** ROADMAP.md avec sections `## Overview`, `## Prerequisites`, puis `## Milestone 1`. - -**Avant v3.0.0 :** awk flat matchait `## Prerequisites → - [ ] Node 22` → fausse progression. - -**Avec v3.0.0 :** -``` -awk scoped: - ## Overview → ms="" (non-Milestone) - - [ ] review → ms="" → SKIP ✓ - ## Prerequisites → ms="" (non-Milestone) - - [ ] Node 22 → ms="" → SKIP ✓ - ## Milestone 1 — Auth → ms="## Milestone 1" - - [ ] Login UI → PRINT "## Milestone 1 (flat)" ✓ -``` - ---- - -### Cas AM — Projet Go : commande de test affichée - -``` -/status (projet Go avec go.mod) - -Tests: run 'go test ./...' to check -``` - -Couverture: Python (`pytest`), Node.js (`jest`), Rust (`cargo test`), Go (`go test ./...`). - ---- - -### Cas AN — `/analyze` : mode DEBUG découvrable via argument-hint - -``` -Dans Claude Code, argument-hint visible: - /analyze - -→ /analyze "TypeError at CartSummary.tsx:47 — Cannot read 'map' of undefined" -→ DEBUG MODE activé automatiquement ✓ -``` - ---- - -### Cas AO — GSD v2 interrompu : reprise depuis l'arbre de décision - -``` -Arbre: "Session GSD v2 interrompue ?" -→ gsd → /gsd auto (reprend depuis .gsd/) -→ /gsd steer (modifier le plan) -→ /gsd forensics (analyser un échec) -``` - -GSD v2 reprend automatiquement depuis `.gsd/` — l'utilisateur n'a pas besoin de recommencer. - ---- - -## Cas de figure — corrections v3.1.0 validées - ---- - -### Cas AP — STM32 avec Makefile+C : signal embedded retrouvé - -**Contexte :** firmware STM32, `Makefile` + `src/main.c`, pas de `platformio.ini`, pas de `*.ld` séparé (linker inline dans Makefile). - -**Avant v3.1.0 :** `Makefile` retiré en v3.0.0 → signal absent → recommandations génériques. - -**Avec v3.1.0 :** -``` -PHASE 1: ls Makefile → FOUND, ls src/*.c → 3 fichiers C - ls package.json Cargo.toml go.mod → absent - -Signal embedded: DETECTED (Makefile + .c + no ecosystem) -→ DISABLE all toggles, superpowers optional ✓ -``` - ---- - -### Cas AQ — Rust FFI : toujours pas de faux positif - -``` -Cargo.toml présent + src/ffi.c -→ Signal embedded: NOT detected (Cargo.toml = contre-indicateur) ✓ -``` - ---- - -### Cas AR — Onboarder PHASE 6 : ROADMAP.md généré même sans GSD installé - -**Avant v3.1.0 :** `gsd init` échouait silencieusement si GSD absent. - -**Avec v3.1.0 :** -``` -PHASE 6 — command -v gsd → NOT FOUND - -⚠️ GSD v2 not installed — run: npm install -g gsd-pi -ROADMAP.md generated (ready to use once GSD is installed). -After installing: gsd → /gsd auto -``` - -ROADMAP.md est utile même sans GSD installé — l'utilisateur peut l'installer plus tard. - ---- - -### Cas AS — `doctor.sh` détecte skill `/status` manquant - -``` -bash doctor.sh - -── Consistency ── - ⚠ Missing skills: status/ — run: bash link.sh - ✓ All 8 agents present (...) -``` - ---- - -### Cas AT — Token cost visible sur les patterns - -``` -### Pattern A — Nouveau projet court (≤1 session) · ~3000-5000t - -Budget Pro note: - /init-project ≈ 3000-5000t ≈ 30-45% d'une session Pro (~11k tokens) - Planifier les grosses features sur des sessions séparées. -``` - ---- - -## Erreurs fréquentes — diagnostic rapide - -| Erreur / Symptôme | Cause probable | Solution | -|---|---|---| -| `⚠️ No CLAUDE.md found` | `/ship-feature` dans un projet non onboardé | `/onboard` d'abord, puis relancer | -| `command not found: gsd` | GSD v2 non installé ou pas dans PATH | `npm install -g gsd-pi` puis `source ~/.bashrc` | -| `MISSING: ~/.claude/templates` dans doctor.sh | Installation pre-v2.0.0, `link.sh` pas rejoué | `cd /path/to/claude-config && bash link.sh` | -| Scaffolder échoue sur projet Flutter | `flutter` non installé ou pas dans PATH | Installer Flutter SDK, puis `flutter doctor` | -| Scaffolder échoue sur projet Expo | `npx` non disponible ou Node < 18 | `node --version` → mettre à jour Node si < 18 | -| Plugin-check recommande gstack sur mobile | Signal `mobile` non détecté (manque RN/Expo/Flutter dans description) | Ajouter "React Native" ou "Flutter" explicitement dans le prompt | -| Plugin-check recommande gstack sur monorepo sans browser QA | Signal `monorepo` non détecté | Vérifier que `apps/` ou `turbo.json` est détecté ; relancer depuis la racine du monorepo | -| Session-start box mal alignée | Version < v2.3.0 | Mettre à jour depuis l'archive v2.3.0+ | -| `/init-project` pose des questions déjà dans le prompt | Prompt incomplet (stack ou features manquants) | Ajouter stack, features v1, et conventions dans le prompt initial | -| STEP 13 `gsd init` : "command not found" | GSD v2 non installé au moment de init-project | `npm install -g gsd-pi`, puis `/onboard add gsd` | -| Plugin-check recommande plugins web sur firmware | signal `embedded` non détecté | Vérifier: `platformio.ini` ou `*.ld` présent, ou `Makefile` + `.c` + pas de `package.json`/`Cargo.toml`/`setup.py` | -| `detect_ruflo` retourne faux positif | Ancien MCP config resté dans `~/.claude.json` | Vérifier que `ruflo --version` fonctionne ; ignore les vieux configs MCP | -| `doctor.sh` : deny rules count mismatch | `settings.json` modifié manuellement | Vérifier avec `python3 -c "import json; print(len(json.load(open('~/.claude/settings.json'))['permissions']['deny']))"` — attendu : 100 | -| Subagent échoue en STEP 4, pas de guidance | Version < v2.2.0 | Mettre à jour, le STEP 4b est ajouté en v2.2.0 | -| `/analyze` ne passe pas en mode DEBUG | L'erreur n'est pas passée en argument | Copier l'erreur exacte dans l'argument : `/analyze "FAILED test_foo — TypeError: ..."`| -| GStack skills/ manquant | Submodule initialisé mais `./setup` pas exécuté | `cd skills-external/gstack && ./setup` | - --- ## Référence rapide — signaux → plugins