bchanot/claude
1
0
Fork 0
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

332
CHANGELOG.md
View File

@ -6,6 +6,338 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
## [Unreleased]
## [3.2.1] — 2026-04-07
### Fixed
- `agents/plugin-advisor.md`: 4 signals had entries in the signal table but no conditional rule — added rules for `skill-creation`, `browser-qa`, `design-system`, and `complex-arch`
### Changed
- `version.txt`: 3.2.0 → 3.2.1
## [3.2.0] — 2026-04-07
### Fixed
- `doctor.sh`: EXPECTED_SKILLS pass message uses `${#EXPECTED_SKILLS[@]}` (dynamic count) instead of hardcoded 9
- `agents/plugin-advisor.md`: `setup.py` and `pyproject.toml` added as counterindicators for embedded signal — prevents Python C-extensions from false-triggering embedded
- `agents/status-reporter.md`: PHP phpunit added to manifest fallback (`composer.json` → `./vendor/bin/phpunit`)
- `skills/health/SKILL.md`: post-result guidance added — CRITICAL/WARNING/errors/warnings/all-pass handling
### Added
- `USAGE.md`: "Erreurs fréquentes" — embedded signal not detected entry
### Changed
- `version.txt`: 3.1.0 → 3.2.0
## [3.1.0] — 2026-04-07
### Fixed
- `agents/plugin-advisor.md`: `Makefile` restored as embedded indicator — `Makefile` + `src/*.c` + no Node/Rust/Go manifest = embedded; `.c` files alone still not sufficient (Rust FFI counterindicated)
- `agents/onboarder.md`: PHASE 6 — check `command -v gsd` before generating ROADMAP.md; if absent, ROADMAP.md still generated with install instructions; same pattern as init-project STEP 13
### Added
- `doctor.sh`: expected skills check — verifies all 9 skills (analyze, health, init-project, onboard, plugin-check, readme, refactor, ship-feature, status) present in `~/.claude/skills/`
- `skills/analyze/SKILL.md`: description updated to mention DEBUG mode (read-only analysis OR error/stack trace → DEBUG mode)
- `USAGE.md`: token cost estimates on workflow patterns (Pattern A ~3000-5000t, B ~1500-2500t/session, D ~500-800t, E ~600-900t); budget note at top of Patterns section
### Changed
- `version.txt`: 3.0.0 → 3.1.0
## [3.0.0] — 2026-04-07
### Fixed
- `agents/plugin-advisor.md`: embedded false positive removed — `src/*.c` alone no longer triggers embedded signal (Rust FFI projects have .c files); only `platformio.ini` or `*.ld`/`*.lds` linker scripts are reliable triggers
- `agents/status-reporter.md`: flat awk scoped to `## Milestone` headings — no longer matches `## Prerequisites`, `## Notes`, or other non-milestone `##` headings in ROADMAP.md
### Added
- `agents/status-reporter.md`: Go test runner in manifest fallback (`go.mod` → "go test ./...")
- `USAGE.md`: GSD v2 active/interrupted node in decision tree — /gsd auto, /gsd steer, /gsd forensics
- `skills/analyze/SKILL.md`: argument-hint updated to mention DEBUG mode (pass error/stack trace)
### Breaking
- `agents/plugin-advisor.md`: embedded detection no longer triggers on C/C++ files alone — projects relying on .c file detection must add `platformio.ini` or a `*.ld` linker script
### Changed
- `version.txt`: 2.9.0 → 3.0.0
## [2.9.0] — 2026-04-07
### Fixed
- `agents/plugin-advisor.md`: PHASE 1 — filesystem embedded detection added (platformio.ini, *.ld linker scripts, src/*.c without package.json/Dockerfile); signal description updated
- `agents/status-reporter.md`: PHASE 3 — flat ROADMAP fallback awk command for milestones with tasks directly under ## (no ### slices); marked with "(flat)" in output
- `agents/status-reporter.md`: pytest cache parsing — JSON `{}` = "all passing" instead of "0 failing"; uses python3 for proper JSON parse instead of `cat | head`
### Added
- `USAGE.md`: analyze → refactor → analyze cycle documented in decision tree (refactoring profond)
- `README.md`: link to USAGE.md in intro section
### Changed
- `version.txt`: 2.8.0 → 2.9.0
## [2.8.0] — 2026-04-07
### Fixed
- `agents/status-reporter.md`: awk milestone detection uses `index()` instead of regex negation — portable across macOS nawk and GNU awk
- `agents/status-reporter.md`: Tests field fallback improved — shows "run '<cmd>' to check" when no result found but test manifest exists; shows "N/A" only when no test infrastructure at all
### Added
- `agents/plugin-advisor.md`: `embedded` signal added — firmware/bare-metal/microcontroller detection; DECISION TABLE row; conditional rule disabling all toggles, superpowers optional
- `doctor.sh`: agents pass message now lists all 8 agent names inline for quick visual confirmation
- `USAGE.md`: section "Quel skill utiliser ?" — decision tree for all 9 skills with quick-reference table
- `README.md`: `/status` added to Maintenance Diagnostic section alongside `/health`
### Changed
- `version.txt`: 2.7.0 → 2.8.0
## [2.7.0] — 2026-04-07
### Fixed
- `agents/status-reporter.md`: milestone detection algorithm — uses `awk` to find first `##` heading with pending `###` slices (top-to-bottom scan), not `tail -5` of all `##` headings
- `skills/ship-feature/SKILL.md`: `git log` now uses `--format="%h %<(50,trunc)%s"` to truncate long commit messages at 50 chars
### Added
- `agents/status-reporter.md`: PHASE 2 — best-effort build/test status check (pytest cache, Jest coverage, log files); `Tests` field in output
- `doctor.sh`: `check_symlink "lib"` added; `_EXPECTED_LINKS` updated 6 → 7
- `agents/plugin-advisor.md`: `skill-creation` signal added to PHASE 2; WARN rule if skill-creator active without skill-creation signal
- `USAGE.md`: Exemple 9 — firmware C/C++ STM32, workflow minimaliste sans superpowers ni GSD
### Changed
- `version.txt`: 2.6.0 → 2.7.0
## [2.6.0] — 2026-04-07
### Fixed
- `agents/status-reporter.md`: PHASE 3 now counts slices (### headings) not tasks (- [ ]) — correct progress metric matching GSD v2 dashboard
- `hooks/session-start.sh`: continuation line uses 13-space prefix (verified 60 bytes) for consistent box alignment
- `agents/onboarder.md`: PHASE 5b clarifies .gitignore target path per mode (A=workspace root, B=PACKAGE_ROOT, C=per-package)
### Added
- `skills/ship-feature/SKILL.md`: STEP 0b now prints PROJECT CONTEXT header when CLAUDE.md found — project name, stack, current branch, last 3 commits, GSD milestone
- `USAGE.md`: Exemple 8 — full session resume workflow with /status + GSD v2 step mode + /gsd discuss
### Changed
- `version.txt`: 2.5.0 → 2.6.0
## [2.5.0] — 2026-04-07
### Fixed
- `skills/init-project/SKILL.md`: STEP 1 — checks both `CLAUDE.md` and `.claude/CLAUDE.md`; pre-fills interview from either location
- `agents/status-reporter.md`: PHASE 3 GSD — replaced fragile `STATUS.md` read with robust ROADMAP.md checkbox parsing; handles missing ROADMAP.md; never reads binary `state.db`
- `agents/onboarder.md`: PHASE 5b added — .gitignore safety check; appends `.claude/settings.local.json` to existing .gitignore or creates minimal one; applies to all monorepo options
### Added
- `doctor.sh`: expected agents check in Consistency section — warns if any of 8 expected `.md` agent files are missing from `~/.claude/agents/`
- `README.md` + `USAGE.md`: `/status` added to Pattern B (multi-session) and Pattern C (onboarding) workflows
- `hooks/session-start.sh`: 2-line display for >4 active/inactive plugins — all plugin names shown, split at 4 per line
### Changed
- `version.txt`: 2.4.0 → 2.5.0
## [2.4.0] — 2026-04-07
### Fixed
- `skills/init-project/SKILL.md`: STEP 1 — reads existing CLAUDE.md if present; pre-fills interview answers already documented; asks only genuinely missing fields
- `agents/onboarder.md`: Option B fully implemented — explicit PACKAGE_ROOT scoping; all PHASE 3-5 paths relative to selected package; no root CLAUDE.md generated
- `agents/plugin-advisor.md`: upstream monorepo detection in PHASE 1 — checks `../turbo.json`, `../pnpm-workspace.yaml`, `../../turbo.json` for sub-package context; signal table updated to describe upstream detection
### Added
- `agents/status-reporter.md` + `skills/status/SKILL.md`: new `/status` skill — consolidated read-only snapshot (plugins + token cost + git state + recent commits + GSD v2 milestone)
- `USAGE.md`: section "Erreurs fréquentes" — quick-reference table of 14 common errors with causes and solutions
- `doctor.sh`: symlink counter — reports `N/6 OK` after symlink checks
- `hooks/session-start.sh`: `+N more` display — shows first 2 active/inactive plugins + count of remaining instead of truncated string
- `README.md`: /status added to skill table and file tree
### Changed
- `version.txt`: 2.3.0 → 2.4.0
## [2.3.0] — 2026-04-07
### Fixed
- `skills/ship-feature/SKILL.md`: STEP 0b added — checks for CLAUDE.md before starting; blocks with `/onboard` instruction if missing
- `skills/ship-feature/SKILL.md`: STEP 4b option B enhanced — scans remaining tasks for dependents before skipping a failed task; prompts to skip dependent tasks too
- `agents/onboarder.md`: Option C (sequential monorepo onboarding) fully implemented — iterates all packages, generates per-package CLAUDE.md + settings + .claudeignore, summary table, optional root ROADMAP.md
- `agents/plugin-advisor.md`: `monorepo` signal added to PHASE 1 detection (turbo.json, pnpm-workspace, nx.json), PHASE 2 signal table, DECISION TABLE, and conditional rules — recommends plugins per-package, not for the whole repo
- `doctor.sh`: `check_symlink "templates"` added — detects missing templates/ symlink (pre-v2.0.0 installations)
- `hooks/session-start.sh`: ACTIVE_STR and INACTIVE_STR truncated to 37 chars + `…` indicator when overflow detected
### Added
- `USAGE.md`: Exemple 7 — refactoring module Python legacy; full `/analyze` → `/refactor` → `/analyze` cycle; shows report-before-modify behavior and test-first recommendation
### Changed
- `version.txt`: 2.2.0 → 2.3.0
## [2.2.0] — 2026-04-07
### Fixed (bugs identified via case study simulation)
- `skills/init-project/SKILL.md`: STEP 13 — guard `command -v gsd` before running `gsd init`; prints install instructions if GSD v2 not in PATH instead of failing silently
- `skills/ship-feature/SKILL.md`: STEP 4b added — structured error recovery when a subagent fails (build error, failing test, type error); DEBUG mode analysis + user gate before any fix; max 2 retry attempts; never auto-patches
- `agents/onboarder.md`: monorepo detection added (PHASE 1) — detects `apps/`, `packages/`, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`; interactive gate (onboard whole workspace / single package / each separately)
- `agents/plugin-advisor.md`: `mobile` signal added to PHASE 2 signal table + DECISION TABLE + conditional rules — React Native / Expo / Flutter explicitly handled; gstack disabled for mobile, Docker N/A
- `doctor.sh`: GStack `skills/` subdirectory check added after symlink verification — warns if GStack is symlinked but has no skills (needs `./setup`)
- `hooks/session-start.sh`: TOKEN_WARN truncated to 44 chars to prevent box overflow with emoji width
### Added
- `USAGE.md`: Exemple 6 — CLI Rust from scratch; illustrates minimal workflow (superpowers only, no frontend plugins, cargo check as verify, no GSD v2)
### Changed
- `version.txt`: 2.1.0 → 2.2.0
## [2.1.0] — 2026-04-07
### Added
- `agents/scaffolder.md`: React Native/Expo + Flutter support — PHASE 0 (Docker exclusion), PHASE 3 (stack templates), PHASE 4 (install commands), PHASE 5 (verify commands per stack)
- `agents/analyzer.md`: DEBUG MODE section — structured error diagnosis with root cause hypotheses, trace, and affected files
- `agents/onboarder.md`: new agent — onboard existing projects (discovery → interview → CLAUDE.md + settings + .claudeignore + optional GSD v2 ROADMAP)
- `skills/onboard/SKILL.md`: new skill `/onboard` invoking the onboarder agent
- `skills/init-project/SKILL.md`: STEP 13 (optional) — propose GSD v2 init at end of init-project when multi-session signal detected
- `Makefile`: `make onboard` target
- `README.md`: Workflow patterns section (5 patterns: new short, new long, onboarding, hotfix, refactor); /onboard in skill table and tree; make onboard in maintenance
### Fixed
- `agents/plugin-advisor.md`: "Next.js + context7 not configured" moved from BLOCK → WARN with force option — Context7 requires manual API key, should not hard-block project start
- `lib/detect-plugins.sh`: `detect_ruflo()` now uses 3-level fallback (npm binary → MCP config grep + ruvnet/claude-flow variants → `claude mcp list`)
- `hooks/session-start.sh`: passive token cost estimate added to session display — warns at >25%, alerts at >50% of Pro session budget
### Changed
- `version.txt`: 2.0.0 → 2.1.0
## [2.0.0] — 2026-04-06
### Breaking
- GSD v1 (`glittercowboy/get-shit-done-cc`) removed entirely
- GSD v1 commands (`/gsd:discuss-phase`, `/gsd:plan-phase`, `/gsd:execute-phase`, `/gsd:ship`, `/gsd:next`) no longer available — these were Claude Code slash commands; they do not exist in v2
- GSD v2 (`gsd-pi`) is a standalone CLI (Pi SDK), not a Claude Code plugin — usage model is entirely different
### Added
- **GSD v2 integration** (`gsd-build/gsd-2`, npm: `gsd-pi` 2.64.0) — standalone CLI with autonomous mode (`/gsd auto`), state machine per-task execution, crash recovery, cost tracking, parallel workers, worktree isolation
- **Ruflo plugin** (`ruvnet/ruflo`, npm: `ruflo` 3.5.58) — enterprise multi-agent MCP server (formerly claude-flow), 310+ tools, 100+ agent types, WASM kernel; 🔄 TOGGLE, ~500-1500t passive
- **Full plugin compatibility matrix** in `agents/plugin-advisor.md` — all 12 plugins analyzed pairwise, conditional rules, recommended sets by project type
- **Ruflo auto-detection** in `lib/detect-plugins.sh`, `doctor.sh`, `hooks/session-start.sh`
- **GSD v2 CLI status** in `session-start.sh` — dedicated `🖥️ CLI` line (separate from CC plugin toggles)
- **8 new deny rules** in `settings.json`: `source /dev/stdin`, `mkfifo *`, `python3 -c *`, `node -e *`, `xargs * .env*`, `tar * .env*`, `zip * .env*`, `base64 .env*` — covers runtime secret access and exfiltration vectors
- **`disableAutoMode: "disable"`** added to global `settings.json` # TODO: VERIFY syntax in CC v2.1.89
- **`templates/` symlink** in `link.sh` — `~/.claude/templates/` now resolves correctly for scaffolder and init-project
- **Token budget breakdown** in `doctor.sh` — CLAUDE.md + skill descriptions + plugin passive cost, thresholds vs Pro session budget (~11k tokens/5h)
- **GStack pinning warning** in `doctor.sh` and `update-all.sh` (confirmation prompt before `--remote` update)
- **GStack false-positive fix** in `doctor.sh` — submodule check now requires `.git` presence, not just directory existence
- Ruflo install instructions in `install-plugins.sh` (Step 5, manual — enterprise tool)
- Ruflo update step in `update-all.sh`
- GSD v2 update step in `update-all.sh`
### Changed
- `plugins.lock.json`: GSD v1 (`npm:get-shit-done-cc`) → GSD v2 (`npm:gsd-pi` 2.64.0); ruflo (`npm:ruflo` 3.5.58) added
- `install-plugins.sh`: STEP 4 GSD v2 (`npm install -g gsd-pi`), STEP 5 ruflo (manual instructions), steps renumbered 6-7
- `lib/detect-plugins.sh`: `detect_gsd()` now checks `command -v gsd` (not `~/.claude/skills/` grep); `detect_ruflo()` added
- `doctor.sh`: GSD v2 check, ruflo check, GStack false-positive fix, GStack pinning warning, EXPECTED_DENY 92→100, token budget Pro-aware with breakdown, `readlink -f` portability fix
- `hooks/session-start.sh`: GSD v2 removed from toggle loop → dedicated `🖥️ CLI` line; ruflo added to toggle loop
- `update-all.sh`: GStack confirmation prompt, GSD v2 update step, ruflo update step, steps renumbered 1-7
- `agents/plugin-advisor.md`: complete rewrite — PHASE 1 detection (GSD v2, ruflo), PHASE 2 signal table, full compatibility matrix, conditional rules, recommended sets by project type, WARN/BLOCK updated
- `link.sh`: `templates/` added to symlink loop
- `settings.json`: 92→100 deny rules, `disableAutoMode` added
- `README.md`: comprehensive update — GSD v2 full usage guide, ruflo install/usage, plugin compatibility matrix section, updated plugin table (GSD v2 as CLI, ruflo as TOGGLE), version pinning examples, troubleshooting entries for GSD v2 and ruflo, Known Limitations updated
- `version.txt`: 1.0.4 → 2.0.0
### Fixed
- `link.sh`: `templates/` not symlinked — scaffolder and init-project now find `~/.claude/templates/project-CLAUDE.md`
- `doctor.sh`: GStack submodule check was a false positive when directory existed but submodule was uninitialised
- `doctor.sh`: `readlink -f` fallback made explicit for BSD macOS compatibility
- `doctor.sh`: token budget used incorrect "~8000 tokens" reference — now uses Pro session budget (~11k)
- `doctor.sh`: EXPECTED_DENY hardcoded at 92 — updated to 100 after new deny rules
- `update-all.sh`: GStack update had no confirmation prompt — added; GStack step structure had mismatched `if/fi`
- `agents/plugin-advisor.md`: GSD detection used `ls ~/.claude/skills/ | grep gsd` — broken for v2 (CLI not a skill)
- `hooks/session-start.sh`: GSD v2 (standalone CLI) was in the CC plugin toggle loop — incorrect, moved to dedicated CLI line
## [1.0.4] — 2026-04-05
### Fixed
- `skills/*/SKILL.md`: agent paths changed from `.claude/agents/` to `$HOME/.claude/agents/` — unambiguous user-scope resolution regardless of working directory
- `hooks/session-start.sh`: `CONFIG_VERSION` now displayed in session-start box (was computed but never shown)
- `settings.json` + templates: removed non-standard `_readme` key (silently ignored by Claude Code but triggers schema warnings)
- `agents/plugin-advisor.md`: RTK detection re-added in PHASE 1 (was removed in v1.0.3 compression)
- `skills/health/SKILL.md`: fallback command simplified — removed 3-level quote nesting
- `install-plugins.sh`: removed duplicate "→ Restart Claude Code" line
### Changed
- README: Superpowers command table now shows actual skill names (`superpowers:brainstorming`, `superpowers:writing-plans`, `superpowers:subagent-driven-development`, etc.)
- README: install step 6 — replaced `/reload-plugins` (nonexistent command) with "Restart Claude Code — plugins load automatically"
- README: Context7 API key URL corrected from `context7.com` to `upstash.com`
- README: Known Limitations — clarified agent frontmatter fields ARE enforced in v2.1.x; added `disableAutoMode` note
- README: Makefile command list in Maintenance section now includes `make new-skill`
- `lib/detect-plugins.sh`: `detect_context7()` no longer spawns `claude` CLI — reads `~/.claude.json` and `~/.mcp.json` directly (no subprocess overhead at session start)
## [1.0.3] — 2026-04-05
### Token savings (~57% reduction across agents/skills)
- `CLAUDE.md`: 1414t → 418t (-70%) — rewritten as dense rule list, no prose padding
- `agents/plugin-advisor.md`: 1251t → 536t (-57%) — DECISION MATRIX removed (duplicated THRESHOLDS), output template compressed
- `agents/interviewer.md`: 1088t → 438t (-60%) — PROJECT BRIEF ASCII art → compact YAML-style, question groups flattened
- `agents/readme-updater.md`: 2224t → 792t (-64%) — Docker detection unified to one block, template skeleton condensed, phases as tight checklists
- `agents/scaffolder.md`: 2402t → 1041t (-57%) — Dockerfile/compose templates replaced by 3-line descriptions, Phase 0 compressed
- `skills/init-project/SKILL.md`: 2452t → 915t (-63%) — AGENTS LOADED section removed, each STEP condensed to 2-4 lines
- `skills/ship-feature/SKILL.md`: 1236t → 537t (-57%) — same treatment as init-project
### Changed behavior
- `agents/interviewer.md`: if prompt already contains name + purpose + stack + features + architecture → generate BRIEF directly, no questions asked
- `agents/readme-updater.md`: Docker detection defined once at top, referenced in all modes (no duplication)
- `hooks/session-start.sh`: always-on plugins (security-guidance, rtk, superpowers) now explicitly shown in session start display
- `skills/health/SKILL.md`: fallback path when `~/.claude/doctor.sh` not found (follows CLAUDE.md symlink to locate repo)
- `skills/plugin-check/SKILL.md`: argument-hint now shows concrete example
### Added
- `Makefile`: `make new-skill name=<n>` — scaffolds agent + skill files from template in one command
- `templates/project-CLAUDE.md`: inline examples per section (FastAPI-based) — usable without /init-project
- README: bundled skills section (`/batch`, `/debug`, `/simplify`)
- README: accurate progressive loading explanation (description only at startup, body on-demand)
- `link.sh`: idempotent — reports "already up to date" or count of updated symlinks
## [1.0.2] — 2026-04-04
### Security
- `Bash(git add .env*)` and `Bash(git add **/.env*)` added to deny — prevents staging secrets
- `Bash(cp **/id_rsa*)`, `Bash(cp **/id_ed25519*)`, `Bash(cp **/.ssh/*)` added to deny — closes SSH key copy bypass
- `deny` total: 87 → 92 rules
- `npx *` moved from allow to ask in project template settings — arbitrary npm package execution now requires confirmation
- `docker stop *` and `docker rm *` moved from allow to ask in project template settings
### Changed
- `skill-creator` and `pr-review-toolkit` reclassified from ALWAYS ON to TOGGLE — saves ~400 tokens/session by default
- `agents/scaffolder.md`: removed Go, PHP/WordPress, Flutter/Dart stack templates (unused)
- `CLAUDE.md`: STRICT MODE section removed — rules inlined into `skills/init-project/SKILL.md` and `skills/ship-feature/SKILL.md` where they apply, reducing global context weight
- `CLAUDE.md`: FAIL FAST MODE cleaned up (removed contradictory "override all" claim)
- `agents/readme-updater.md`: mode detection changed from substring match to exact first-word match — `/readme update X` no longer silently triggers SYNC mode
- `templates/settings/SETTINGS.md`: stripped sections duplicating README (precedence table, what-goes-where) — 132 → 58 lines
- `plugins.lock.json`: removed unused `install_cmd` and `node` fields
- README: GStack 14-command table collapsed to a single reference line
- README: plugin table updated to reflect new toggle status
### Fixed
- `install-plugins.sh`: GStack `./setup` now runs in subshell with existence+executable guard (same fix as update-all.sh)
- `install-plugins.sh`: log setup guarded against read-only filesystem — no longer crashes before output
- `install-plugins.sh`: `rtk init -g` now skipped if RTK hook already present in settings.json
- `doctor.sh`: CRLF detection ported from `grep -qP` (Linux-only) to `grep -c $'\r'` (portable macOS/Linux)
- `doctor.sh`: token budget breakdown now lists top consumers per file when estimate exceeds 2000 tokens
- `lib/detect-plugins.sh`: removed three never-called functions (`detect_security_guidance`, `detect_skill_creator`, `detect_pr_review_toolkit`)
- `hooks/session-start.sh`: removed unreachable inline fallback — replaced with clean exit message
## [1.0.1] — 2026-04-03
### Security
- `env` and `printenv *` moved from allow to deny — blocks secret exposure via process environment
- `export *` added to deny — prevents environment variable injection
- `cp .env*`, `cp **/.env*`, `mv .env*`, `mv **/.env*` added to deny — closes copy-then-read bypass on secret files
- `cp **/secrets/*`, `mv **/secrets/*` added to deny — extends secret move protection to secrets/ directory
- `sed *` moved from allow to ask — all sed (including in-place `-i`) now requires confirmation
- `sed -i *` and `sed -i'' *` removed from ask (consolidated into `sed *`)
### Changed
- `git stash*` (broad allow) split into safe variants in allow (`git stash`, `push*`, `list*`, `show*`) and destructive variants in ask (`pop*`, `drop*`, `clear`)
- `doctor.sh` token budget estimate now uses full skill/agent file sizes instead of description-only char count — produces accurate token estimates (~4 chars/token)
- `doctor.sh` deny rule count now checks against expected value (87) and warns on mismatch
- `doctor.sh` python3 one-liner wrapped in `|| echo "?"` — diagnosis no longer crashes on missing python3
### Fixed
- `update-all.sh` GStack `./setup` now runs in a subshell — upstream setup failure no longer crashes the update script mid-execution under `set -euo pipefail`
- `update-all.sh` guards `./setup` existence and executable bit before invoking it
## [1.0.0] — 2025-04-03
### Added

175
CLAUDE.md
View File

@ -1,159 +1,58 @@
# Global coding preferences
Apply these preferences across all projects unless repository-specific
instructions override them.
Apply unless repo-specific instructions override.
## General philosophy
## Code style
I prefer clean, readable, maintainable code with strong structural discipline,
inspired by 42-style constraints but adapted pragmatically to each language,
framework, and project.
- Simple, readable, maintainable > clever or compact.
- One responsibility per function/method.
- Preserve existing behavior unless asked otherwise.
- Scope changes to the task. No unrelated edits.
These rules are important, but they are not absolute dogma:
- apply them by default
- report clearly when code does not follow them
- if a deviation is justified, keep it and explain why
- if a deviation is not clearly justified, ask whether it should be kept or fixed
## Limits (adapt to language)
## Design principles
- Max 25 lines of logic per function (excl. comments, error handling).
- Max 80 chars/line.
- Max 5 params per function → group into a struct/object if more needed.
- Max 5 local vars per function → split or extract.
- No global state. Prefer explicit data flow.
- Prefer simple, readable, maintainable code over clever or overly compact code.
- Each function, method, or equivalent unit should have one clear responsibility.
- Preserve existing behavior unless explicitly asked to change it.
- Avoid unrelated changes during a fix or refactor.
- Keep modifications scoped and intentional.
## Comments
## Function and method size
- Prefer keeping the core logic of a function or method within 25 useful lines.
- Empty lines do not count toward this limit.
- Multi-line wrapped statements count as one logical instruction for this rule.
- Error handling may extend the total size when necessary, but the main logic
should remain compact and easy to understand.
- If a unit becomes too large, split it into small helpers.
- Use private/internal/file-local helpers when the language supports them.
## Line length
- Prefer a maximum of 80 characters per line when reasonably possible.
- If a line is too long, split it cleanly for readability.
- Long calls, conditions, and expressions should be formatted clearly.
## Parameters
- Prefer no more than 5 parameters per function or method.
- If more inputs are needed, group them into a meaningful structure adapted
to the language, such as an object, record, struct, dataclass, DTO,
config object, or equivalent.
## Local variables
- Prefer no more than 5 local variables per function or method.
- If more local state is needed, consider:
- splitting the logic
- extracting a helper
- introducing a dedicated small structure adapted to the language
## Shared and global state
- Global state is discouraged.
- Prefer explicit data flow through parameters, return values, objects,
context structures, dependency injection, or another justified mechanism.
- If shared or global state is used, mention it explicitly and justify it.
## Comments and documentation
- Functions and methods should be documented when their purpose, parameters,
return value, or intent are not immediately obvious.
- The comment should help explain intent and usage, not restate the code line by line.
- Apply the documentation style that fits the language and project conventions
(docstring, block comment, JSDoc, Doxygen, XML docs, etc.).
- Internal/private helpers are not exempt if their role is unclear.
- Document purpose/intent when not obvious. Not line-by-line restating.
- Use the project's doc style (docstring, JSDoc, Doxygen, etc.).
## Readability
- Use explicit, consistent, and meaningful names.
- Prefer straightforward control flow.
- Simplify or extract complex conditions.
- Avoid hidden side effects unless clearly necessary.
- Prefer code that is easy to review, test, and modify.
- Explicit, consistent, meaningful names.
- Straight control flow. Extract complex conditions.
- No hidden side effects.
## Refactoring and modifications
## Refactoring
- During refactoring, prioritize:
1. safety
2. readability
3. consistency with the project
- Keep behavior unchanged unless explicitly asked otherwise.
- After modifying a function, feature, or behavior, verify that no residue from
the previous implementation remains.
- Remove obsolete code, dead branches, unused helpers, stale flags, outdated
comments, legacy conditions, and old-version leftovers when they are no longer needed.
- If something from the previous implementation is intentionally retained,
explain why.
- Priority: safety → readability → consistency.
- Remove dead code, obsolete comments, stale flags after changes.
- After modifying behavior: verify no old residue remains.
## Handling deviations from the standard
## Deviations
- Treat these rules as strong preferences, not rigid mechanical laws.
- If existing code is outside the standard, report it clearly.
- If the deviation is minor and acceptable, mention it briefly.
- If the deviation is significant and not obviously justified, ask whether to:
- keep the deviation
- or refactor toward compliance
- If a deviation is clearly justified by language constraints, framework style,
performance needs, safety requirements, or project architecture, keep it and explain it.
- Report deviations from the above clearly.
- Minor/justified → keep and explain.
- Significant/unjustified → ask: keep or fix?
## Language adaptation
## After code changes
- Adapt these rules to the language and ecosystem instead of applying C/C++
terminology blindly.
- Interpret "function" broadly as the relevant unit of logic:
function, method, procedure, hook, handler, endpoint, callback, class method, etc.
- Interpret "structure" broadly as any suitable grouping construct:
struct, object, class, record, dataclass, DTO, tuple wrapper, options object,
config object, context object, or equivalent.
1. Run tests, lint, build, type-check if available.
2. Report what was verified / what wasn't.
3. List remaining risks and any surviving deviations.
## Expected workflow after code changes
## When working on code
After making changes, when applicable:
1. run relevant tests
2. run lint, format, build, and type-check steps if available
3. report what was verified
4. report what could not be verified
5. summarize remaining risks or uncertainties
6. mention any remaining deviation from these preferences
7. confirm whether old implementation residue remains or has been removed
- Analyze before changing. Brief plan first.
- Minimal changes unless broader refactor requested.
- State trade-offs clearly.
## Interaction preferences
## FAIL FAST
When working on code:
- first analyze before changing
- explain the plan briefly
- keep changes minimal unless a broader refactor is requested
- mention trade-offs clearly
- after changes, summarize what was done and what remains uncertain
## STRICT MODE
These rules are always active in orchestrator skills (/init-project,
/ship-feature) and during code review. They apply automatically.
These rules override all other instructions.
- Never skip workflow steps
- Never merge agent responsibilities
- Always enforce user validation before implementation
- Always run review loop until no CRITICAL issues remain
- Stop execution if requirements are unclear
## FAIL FAST MODE
These rules are always active in every interaction. They apply automatically.
These rules override all other instructions.
- Stop immediately if requirements are unclear
- Ask clarifying questions instead of guessing
- Do not invent missing context
- Do not proceed with partial understanding
- Explicitly list unknowns before continuing
- Stop if requirements are unclear. Ask, don't guess.
- No invented context. List unknowns before continuing.

23
Makefile
View File

@ -1,12 +1,12 @@
.PHONY: help install link doctor update
.PHONY: help install link doctor update new-skill
help: ## Show available commands
@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf " make %-12s %s\n", $$1, $$2}'
@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf " make %-14s %s\n", $$1, $$2}'
install: link ## Full install: symlinks + prerequisites + plugins
bash install-plugins.sh
link: ## Create symlinks into ~/.claude/
link: ## Create/update symlinks into ~/.claude/
bash link.sh
doctor: ## Run setup diagnostic
@ -14,3 +14,20 @@ doctor: ## Run setup diagnostic
update: ## Update config, submodules, plugins, and verify
bash update-all.sh
onboard: link ## Onboard an existing project (run from the project directory)
@echo "Open Claude Code in your project directory and run: /onboard"
@echo "Or with hints: /onboard Python FastAPI monorepo"
new-skill: ## Create a new skill scaffold (usage: make new-skill name=myskill)
@test -n "$(name)" || (echo "Usage: make new-skill name=myskill" && exit 1)
@mkdir -p agents skills/$(name)
@if [ ! -f agents/$(name).md ]; then \
printf -- '---\nname: $(name)\ndescription: <what this agent does — keep under 200 chars>\ntools: Read, Grep, Glob, Bash\nmodel: sonnet\n---\n\n# $(name)\n\n## ROLE\n<role>\n\n## TASKS\n- <task>\n\n## RULES\n- <rule>\n\n## OUTPUT\n```\n<format>\n```\n' > agents/$(name).md; \
echo "✅ Created agents/$(name).md"; \
else echo "⚠️ agents/$(name).md already exists"; fi
@if [ ! -f skills/$(name)/SKILL.md ]; then \
printf -- '---\nname: $(name)\ndescription: <what this skill does — front-load key use case, max 250 chars>\nargument-hint: <what to pass>\ndisable-model-invocation: true\nallowed-tools: Read, Grep, Glob, Bash\n---\n\nLoad and follow strictly:\n- .claude/agents/$(name).md\n\nExecute on:\n\n$$ARGUMENTS\n' > skills/$(name)/SKILL.md; \
echo "✅ Created skills/$(name)/SKILL.md"; \
else echo "⚠️ skills/$(name)/SKILL.md already exists"; fi
@echo " Edit both files, then run: bash link.sh"

417
README.md
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

2021
USAGE.md Normal file
View File

File diff suppressed because it is too large Load Diff

49
agents/analyzer.md
View File

@ -67,3 +67,52 @@ OPEN QUESTIONS:
```
Update project memory with discovered patterns and conventions.
---
## DEBUG MODE
Activated when called with a failing test, error output, or broken build as target.
### INPUTS EXPECTED
- Exact error message or stack trace
- File(s) involved
- Last action that triggered the failure
### PROCESS
1. Read all files mentioned in the error (no guessing)
2. Trace execution path from entry point to failure site
3. Identify the exact line/expression that produces the error
4. List all state at the point of failure (vars, imports, types)
### OUTPUT FORMAT (DEBUG MODE)
```
DEBUG ANALYSIS: <error summary in one line>
ERROR:
<exact message, file, line>
TRACE:
<entry point> → <call chain> → <failure site>
ROOT CAUSE HYPOTHESES (ordered by probability):
1. [HIGH] <specific hypothesis> — evidence: <what in the code supports this>
2. [MED] <specific hypothesis> — evidence: <what in the code supports this>
3. [LOW] <specific hypothesis> — evidence: <what in the code supports this>
AFFECTED FILES:
- <file>: <what role it plays in the failure>
WHAT TO VERIFY NEXT:
- <concrete check #1> — expected result if hypothesis 1 is correct
- <concrete check #2>
DO NOT TOUCH:
- <file or logic that is NOT the cause, to avoid regression>
```
Rules in DEBUG MODE:
- Never propose a fix. Only diagnose.
- Never touch files.
- Stop after the report. The orchestrator or user decides next steps.

140
agents/interviewer.md
View File

@ -1,6 +1,6 @@
---
name: interviewer
description: Gather all information needed to initialize a project. Asks targeted questions, synthesizes answers into a complete PROJECT BRIEF. Use as the first step of any project initialization.
description: Gather project info. Ask targeted questions, produce PROJECT BRIEF. First step of project init.
tools: Read
model: sonnet
---
@ -8,126 +8,56 @@ model: sonnet
# INTERVIEWER
## ROLE
Gather all necessary context before any design or implementation begins.
## GOAL
Produce a complete, unambiguous PROJECT BRIEF that all subsequent agents
can use as their single source of truth.
---
Gather context. Produce complete PROJECT BRIEF as single source of truth.
## BEHAVIOR
- Ask ALL questions upfront in a single structured block.
- Never make assumptions about missing information.
- If the user's initial prompt already answers some questions clearly,
skip those and only ask what remains genuinely unclear.
- Group questions logically so the user can answer efficiently.
- After receiving answers, synthesize everything into a PROJECT BRIEF.
- If any answer is ambiguous or contradictory, ask one follow-up before
producing the brief.
- If the initial prompt already provides name + purpose + stack + features + architecture → skip questions and generate the BRIEF directly.
- Otherwise ask only what's genuinely missing, in a single structured block.
- After answers: produce BRIEF. One follow-up allowed if answer is ambiguous.
---
## QUESTIONS (skip answered ones)
## QUESTION GROUPS
Present questions in this order, skipping any already answered
by the initial prompt:
### 1. PROJECT IDENTITY
- What is the project name?
- What is the project's purpose in one sentence?
- Who are the target users?
### 2. CORE FEATURES
- List the top 5–10 features the first version must include.
- Which features are strictly out of scope for now?
### 3. TECH STACK
- Preferred language(s)?
- Framework(s) if applicable?
- Database / storage needs?
- External APIs or services to integrate?
- Any hard constraint on dependencies (license, size, etc.)?
### 4. ARCHITECTURE & DEPLOYMENT
- Where will this run? (local, cloud, Docker, embedded, etc.)
- Expected scale / performance constraints?
- Monolith, microservices, library, CLI, or other?
- Any existing codebase or code to integrate?
### 5. QUALITY & WORKFLOW
- Minimum test coverage expected?
- Specific linting / formatting tools required?
- CI/CD pipeline needed?
- Any exceptions to the global CLAUDE.md coding rules for this project?
### 6. CONVENTIONS
- Naming style preferences (snake_case, camelCase, PascalCase, etc.)?
- Any domain-specific terminology to use consistently?
- Language for code comments and docs (English strongly recommended)?
---
1. PROJECT: name, purpose (1 sentence), target users
2. FEATURES: top 5–10 v1 features, what's out of scope
3. STACK: language, framework, DB, external APIs, dependency constraints
4. ARCH: runtime (local/cloud/Docker/embedded), scale, shape (monolith/micro/lib/CLI), existing code?
5. QUALITY: test coverage, lint/format tools, CI/CD, exceptions to global CLAUDE.md rules
6. CONVENTIONS: naming style, domain terms, comment language (English recommended)
## OUTPUT — PROJECT BRIEF
After gathering answers, produce this document exactly:
```
================================================================
PROJECT BRIEF
================================================================
PROJECT: <name>
PURPOSE: <one sentence>
USERS: <who>
LANG: <English/other>
PROJECT NAME : <name>
PURPOSE : <one sentence>
TARGET USERS : <who>
LANGUAGE : <English / other>
----------------------------------------------------------------
STACK
----------------------------------------------------------------
Language : <lang + version if specified>
Framework : <framework or "none">
Database : <db or "none">
External services : <list or "none">
Runtime target : <local / Docker / cloud / embedded / etc.>
Architecture : <monolith / microservices / lib / CLI / etc.>
Language : <lang+version>
Framework: <framework or none>
DB : <db or none>
Services : <list or none>
Runtime : <local/Docker/cloud/embedded>
Shape : <monolith/micro/lib/CLI>
----------------------------------------------------------------
CORE FEATURES (v1)
----------------------------------------------------------------
1. <feature>
2. <feature>
...
V1 FEATURES
1. <feature>
...
OUT OF SCOPE: <list>
OUT OF SCOPE
- <feature>
----------------------------------------------------------------
QUALITY
----------------------------------------------------------------
Tests : <strategy + minimum coverage>
Lint / Format : <tools>
CI/CD : <yes/no + details>
Tests : <strategy + coverage>
Lint : <tools>
CI/CD : <yes/no + detail>
----------------------------------------------------------------
CONVENTIONS
----------------------------------------------------------------
Naming : <style>
Comments : <style + language>
Doc format : <JSDoc / Doxygen / docstring / etc.>
Naming : <style>
Comments: <style + lang>
Docs : <JSDoc/Doxygen/docstring/etc>
----------------------------------------------------------------
EXCEPTIONS TO GLOBAL RULES
----------------------------------------------------------------
<list exceptions to ~/.claude/CLAUDE.md, or "none">
----------------------------------------------------------------
OPEN DECISIONS (if any remain)
----------------------------------------------------------------
<list anything still undecided that the designer must resolve>
================================================================
EXCEPTIONS TO GLOBAL RULES: <list or none>
OPEN DECISIONS: <list or none>
```
Do not proceed further. The PROJECT BRIEF is the only output
of this agent. The orchestrator will pass it to the next step.
Stop after BRIEF. Orchestrator handles next step.

227
agents/onboarder.md Normal file
View File

@ -0,0 +1,227 @@
---
name: onboarder
description: Onboard an existing project into claude-config. Generates CLAUDE.md, .claude/settings.json, .claudeignore, and optionally a GSD v2 ROADMAP.md. Use on repos not created via /init-project.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---
# ONBOARDER
## ROLE
Analyze an existing codebase and produce the full claude-config integration: CLAUDE.md, settings, .claudeignore. No feature changes. No refactoring.
## INPUTS REQUIRED
1. Project root directory (current working directory)
2. Optionally: `$ARGUMENTS` with hints ("Python FastAPI", "add GSD", etc.)
If called with no arguments → infer everything from the filesystem.
---
## PHASE 1 — DISCOVERY
Read and catalog (non-destructive, no writes yet):
```bash
# Monorepo detection (run first — changes how everything else is read)
ls apps/ packages/ workspaces/ services/ 2>/dev/null | head -10
cat pnpm-workspace.yaml 2>/dev/null | head -10 || true
cat turbo.json 2>/dev/null | head -10 || true
cat nx.json 2>/dev/null | head -5 || true
cat lerna.json 2>/dev/null | head -5 || true
# Stack detection (root level)
ls package.json pyproject.toml Cargo.toml go.mod pubspec.yaml 2>/dev/null
cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print('name:', d.get('name'), '| workspaces:', d.get('workspaces'), '| scripts:', list(d.get('scripts',{}).keys())[:6])" 2>/dev/null || true
cat pyproject.toml 2>/dev/null | head -20 || true
cat Cargo.toml 2>/dev/null | head -10 || true
# Structure
find . -maxdepth 3 -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/target/*' -not -path '*/.next/*' -not -path '*/dist/*' -not -path '*/build/*' | sort | head -80
# Existing config
ls .claude/ .claudeignore CLAUDE.md README.md .env.example 2>/dev/null
cat CLAUDE.md 2>/dev/null | head -40 || true
cat README.md 2>/dev/null | head -60 || true
# Test/lint commands
cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); [print(k,':',v) for k,v in d.get('scripts',{}).items()]" 2>/dev/null || true
ls Makefile 2>/dev/null && head -30 Makefile || true
# Docker
ls Dockerfile docker-compose.yml docker-compose.yaml 2>/dev/null
# Git history summary
git log --oneline -10 2>/dev/null || true
```
**Monorepo detection logic:**
After running the commands above, determine if this is a monorepo:
- Monorepo indicators: `apps/` or `packages/` with multiple sub-dirs, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `workspaces` key in root `package.json`.
**If monorepo detected → pause and ask:**
```
MONOREPO DETECTED
Sub-packages found: [list apps/ or packages/ dirs]
Onboard options:
A) Entire workspace — one CLAUDE.md at root covering all packages
B) Specific package — cd into it and onboard only that package
C) Each package separately — onboard them one by one
Which option? (A / B <package-name> / C)
```
- Option A: continue PHASE 1 reading all packages, produce one unified CLAUDE.md at root
- Option B (single package): onboard only the specified package
1. Print: "Onboarding <package-name> only (from <root>/<package-name>/)"
2. Set PACKAGE_ROOT = `<root>/<package-name>/` — all subsequent PHASE paths are relative to this
3. Run PHASE 1 discovery using PACKAGE_ROOT as the working directory
4. Run PHASE 2 interview scoped to this package only
5. Generate files at:
- `<PACKAGE_ROOT>/CLAUDE.md`
- `<PACKAGE_ROOT>/.claude/settings.json`
- `<PACKAGE_ROOT>/.claudeignore`
6. Do NOT touch the workspace root or other packages
7. PHASE 6 GSD v2 ROADMAP: generate at `<PACKAGE_ROOT>/ROADMAP.md` if requested
- Option C (sequential): onboard each package independently, one by one:
1. Build the package list from `apps/` or `packages/` subdirs
2. Print: "Onboarding N packages sequentially: [list]"
3. For each package (index i / total):
a. Print "── Package i/N: <package-name> ──"
b. Run PHASE 1 discovery from `<package>/` as root
c. Run PHASE 2 interview for this package only (skip already answered)
d. Generate `<package>/CLAUDE.md`, `<package>/.claude/settings.json`, `<package>/.claudeignore`
e. Print: "✅ <package> onboarded"
4. After all packages: print summary table of all onboarded packages
5. Ask once at the end: "Generate root-level ROADMAP.md linking all packages? (yes/skip)"
Note: Do NOT generate a root-level CLAUDE.md in Option C — each package has its own.
**If NOT monorepo:** continue normally.
---
## PHASE 2 — INTERVIEW (only missing info)
From the discovery, determine what is still unknown:
- Project name and purpose (if not in README or package.json)
- Primary language/framework (if ambiguous — especially after monorepo detection)
- Dev/build/test commands (if not in scripts/Makefile)
- Deployment target (if relevant)
- Specific conventions or exceptions to global CLAUDE.md rules
For monorepos (option A): also ask about the relationship between packages (shared lib? separate deploys? common DB?).
Ask only genuinely missing info in a single block. Skip what was found.
---
## PHASE 3 — GENERATE CLAUDE.md
Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`.
Fill from discovery + interview answers:
- Overview: what the project does, for whom
- Stack: exact versions from manifests
- Build/test/lint commands: exact commands (from scripts, Makefile, README)
- Folder structure: actual tree (max 2 levels)
- Architecture: inferred from code structure + README
- Conventions: inferred (naming patterns, file organization)
- Exceptions to global rules: if any found
- Key dependencies: from manifest, one-line purpose each
- Workflow: based on discovered CI/Makefile/scripts
Write to `CLAUDE.md` at project root.
---
## PHASE 4 — GENERATE .claude/settings.json
Read `~/.claude/templates/settings/settings.json`.
Keep only stack-relevant allow blocks:
- Node.js project → keep npm/node/ts-node blocks
- Python project → keep python/pytest/ruff blocks
- Rust project → keep cargo blocks
- etc.
Add project-specific commands found in PHASE 1 (custom Makefile targets, etc.).
Write to `.claude/settings.json`.
---
## PHASE 5 — GENERATE .claudeignore
Read `~/.claude/templates/settings/.claudeignore`.
Extend with project-specific ignores (e.g., large data dirs, vendor dirs, build outputs specific to this stack).
Write to `.claudeignore` at project root.
---
## PHASE 5b — .gitignore SAFETY CHECK
```bash
ls .gitignore 2>/dev/null
grep 'settings.local.json' .gitignore 2>/dev/null || echo "not found"
```
- **`.gitignore` exists AND contains `settings.local.json`** → nothing to do. ✅
- **`.gitignore` exists but does NOT contain `settings.local.json`** →
Append to existing `.gitignore`:
```
# claude-config — personal settings (never commit)
.claude/settings.local.json
```
Print: "📝 Added .claude/settings.local.json to existing .gitignore"
- **`.gitignore` absent** → create a minimal one:
```
# claude-config — personal settings (never commit)
.claude/settings.local.json
```
Print: "📝 Created .gitignore with .claude/settings.local.json entry"
Target path for `.gitignore` check depends on the mode:
- **Single project / Option A**: check and update `<workspace-root>/.gitignore`
- **Option B**: check and update `<PACKAGE_ROOT>/.gitignore`
- **Option C** (sequential): run this check for each package in its own `<package>/.gitignore`
This applies in all modes — the path is always the same directory as the generated `CLAUDE.md`.
---
## PHASE 6 — GSD v2 ROADMAP (optional)
Ask: "Generate a GSD v2 ROADMAP.md for multi-session feature management? (yes / skip)"
If yes:
- **First check: `command -v gsd`**
- If NOT found: print "⚠️ GSD v2 not installed — run: `npm install -g gsd-pi`
ROADMAP.md will be generated but `gsd init` cannot run now.
After installing: run `gsd` in your terminal → `/gsd auto`."
Generate ROADMAP.md anyway (it will be ready when GSD is installed).
- If found: generate ROADMAP.md then print "✅ Run `gsd` in terminal → `/gsd auto` to start."
- Read CLAUDE.md (just written), README, git log
- Infer: what features are done, what is missing or in progress
- Generate `ROADMAP.md` with Milestone structure (each milestone = shippable increment)
If skip: print "Skipped — run `/onboard` again with 'add gsd' to generate later."
---
## OUTPUT
```
ONBOARD COMPLETE: <project name>
STACK : <detected stack>
FILES WRITTEN:
✅ CLAUDE.md
✅ .claude/settings.json
✅ .claudeignore
[✅ ROADMAP.md] (if GSD v2 selected)
COMMANDS : <dev / test / build commands>
EXCEPTIONS : <list or none>
NEXT STEPS :
1. Review CLAUDE.md — correct any wrong inferences
2. bash ~/.claude/link.sh — verify symlinks OK
3. /plugin-check "<project type>" — configure plugins
4. /ship-feature "<next feature>" — start working
```

299
agents/plugin-advisor.md
View File

@ -1,6 +1,6 @@
---
name: plugin-advisor
description: Analyze the current project context and running plugins to recommend which plugins to enable or disable before starting work. Use as a gate before init-project and ship-feature.
description: Check active plugins vs project needs. Recommend enable/disable before starting work. Gate before init-project and ship-feature.
tools: Read, Bash, Glob, Grep
model: haiku
---
@ -8,134 +8,243 @@ model: haiku
# PLUGIN ADVISOR
## ROLE
Analyze project scope and active plugins.
Recommend enabling or disabling plugins based on what the work actually needs.
## GOAL
Prevent two failure modes:
1. Starting a complex project without the right plugins active (missing capabilities)
2. Running a simple task with heavy plugins active (wasted tokens)
Detect active plugins and project signals. Recommend enable/disable. Apply compatibility matrix. Block or warn as needed.
---
## PHASE 1 — DETECT ACTIVE PLUGINS
Run these commands to get the current state:
## PHASE 1 — DETECT
```bash
# List all installed and enabled plugins
# Claude Code plugins
claude plugin list 2>/dev/null || echo "plugin-list-unavailable"
# Check if GStack is installed
ls ~/.claude/skills/gstack/skills/ 2>/dev/null | wc -l || echo "0"
# GStack skills count (toggle CC plugin)
ls $HOME/.claude/skills/gstack/skills/ 2>/dev/null | wc -l || echo "0"
# Check if RTK hook is active
grep -l "rtk" ~/.claude/settings.json 2>/dev/null | head -1 || echo "rtk-not-configured"
# MCP servers
claude mcp list 2>/dev/null | grep -E "context7|ruflo" || echo "no-mcp"
# Check if Context7 MCP is configured
claude mcp list 2>/dev/null | grep context7 || echo "context7-not-configured"
# Standalone CLIs
command -v gsd &>/dev/null && gsd --version 2>/dev/null | head -1 || echo "gsd-not-installed"
command -v rtk &>/dev/null && rtk --version 2>/dev/null | head -1 || echo "rtk-not-installed"
command -v ruflo &>/dev/null && ruflo --version 2>/dev/null | head -1 || echo "ruflo-cli-not-in-path"
# Check if GSD is installed
ls ~/.claude/skills/ 2>/dev/null | grep gsd || echo "gsd-not-installed"
# Project signals (run from project root)
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null | head -5
grep -rl "next\|react\|vue\|prisma\|supabase" package.json 2>/dev/null | head -3 || true
find . -name "*.tsx" -o -name "*.jsx" 2>/dev/null | head -3 | wc -l
find . -name "docker-compose*" -o -name "Dockerfile" 2>/dev/null | head -3 | wc -l
# Monorepo detection (current dir + parent dirs for sub-package context)
ls apps/ packages/ services/ workspaces/ 2>/dev/null | head -5
ls pnpm-workspace.yaml turbo.json nx.json lerna.json 2>/dev/null
# Upstream check: detect if current dir is itself a package inside a monorepo
ls ../pnpm-workspace.yaml ../turbo.json ../nx.json ../../turbo.json ../../pnpm-workspace.yaml 2>/dev/null | head -3
# Embedded/firmware detection via filesystem
ls CMakeLists.txt platformio.ini 2>/dev/null
ls *.ld *.lds linker*.ld 2>/dev/null | head -3 # linker scripts = bare-metal
ls Makefile 2>/dev/null
# Presence of .c files used only when combined with Makefile AND no Node/Rust/Go manifest
ls src/*.c 2>/dev/null | head -3
ls package.json Cargo.toml go.mod pubspec.yaml setup.py pyproject.toml 2>/dev/null | head -1 # counterindicators (ecosystem present = not bare embedded)
```
---
## PHASE 2 — ANALYZE THE REQUEST
## PHASE 2 — ANALYZE $ARGUMENTS
From the user's description ($ARGUMENTS), extract:
Detect signals from the project description and filesystem scan:
**Project signals:**
- Has frontend UI? (React, Vue, HTML, mobile app, dashboard, landing page, design…)
- Has complex design needs? (design system, multiple variants, color/typography choices…)
- Has browser/QA needs? (test in browser, automated QA, screenshot…)
- Has deployment needs? (deploy, CI/CD, canary, production…)
- Has multi-session scope? (large feature, multi-day, cross-session continuity…)
- Uses fast-evolving libs? (Next.js, React, Prisma, Supabase, Tailwind, FastAPI…)
- Estimated complexity: small / medium / large / very-large
| Signal | How to detect |
|---|---|
| `frontend` | .tsx/.jsx files, React/Vue/Next/Svelte in deps |
| `mobile` | React Native / Expo in deps, `pubspec.yaml` present (Flutter), or "mobile"/"iOS"/"Android" in description |
| `monorepo` | `apps/` or `packages/` with >1 sub-dir, `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, or `workspaces` key in root `package.json`; **or** parent dir has `turbo.json`/`pnpm-workspace.yaml` (current dir is a sub-package) |
| `design-system` | tokens, theme files, storybook, design references |
| `deploy` | docker-compose, Dockerfile, CI config, cloud references |
| `browser-qa` | playwright, cypress, puppeteer in deps |
| `multi-session` | description says "multi-day", "large feature", "multiple sessions" |
| `fast-libs` | Next.js, React 18+, Prisma, Supabase, Drizzle, Expo SDK in deps |
| `multi-agent` | "orchestrate agents", "parallel workers", "swarm", >5 concurrent agents needed |
| `complex-arch` | multiple services, event bus, distributed system in description |
| `skill-creation` | "create a skill", "new skill", "custom skill", `/skill-creator` in description |
| `embedded` | "firmware", "bare-metal", "microcontroller", "STM32", "ESP32", "RTOS", "driver", "kernel", "bootloader" in description; **or** `platformio.ini` present; **or** linker script (`*.ld`, `*.lds`) present; **or** `Makefile` + `src/*.c` + no `package.json`/`Cargo.toml`/`go.mod`/`setup.py`/`pyproject.toml` (C project without standard ecosystems). Note: `.c` files with a Rust/Node/Go manifest = FFI binding, NOT embedded. |
| `simple` | single file, hotfix, quick script, no frontend, no deploy |
---
## PHASE 3 — PRODUCE RECOMMENDATION
Output this block exactly. Do not summarize — show the full table.
## PHASE 3 — OUTPUT
```
================================================================
PLUGIN CHECK
================================================================
ACTIVE: [plugin — status, one line each]
SIGNALS: [detected signals]
COST ESTIMATE: ~Xt passive tokens (all active plugins combined)
DETECTED ACTIVE PLUGINS
------------------------
✅ superpowers — core workflow (always keep active)
✅ security-guidance — security hook (always keep active)
✅ rtk — token compression (always keep active)
[one line per detected plugin]
❌ [plugin] — not installed / not active
RECOMMENDATIONS:
✅ KEEP : [plugin] — [reason]
⚡ ENABLE : [plugin] — [reason] — [install/enable cmd]
⚠️ DISABLE : [plugin] — [token cost saved, not needed here]
ℹ️ OPTIONAL: [plugin] — [marginal benefit, low priority]
🖥️ CLI : [gsd v2] — [run 'gsd' in terminal if multi-session]
PROJECT SIGNALS DETECTED
-------------------------
Frontend UI : yes / no
Complex design : yes / no
Browser QA : yes / no
Deployment : yes / no
Multi-session : yes / no
Fast-evolving libs: yes / no ([lib names])
Complexity : small / medium / large / very-large
RECOMMENDATIONS
---------------
[For each relevant plugin, one of:]
✅ KEEP ACTIVE : [plugin] — [one-line reason]
⚡ ENABLE NOW : [plugin] — [why it's needed] — [install command if not installed]
⚠️ DISABLE : [plugin] — [costs X tokens/session, not needed for this task]
ℹ️ OPTIONAL : [plugin] — [marginal benefit, your call]
BLOCKING ISSUES (must resolve before continuing)
-------------------------------------------------
[List only if a strongly-recommended plugin is missing/disabled]
[or write "none"]
================================================================
ACTION REQUIRED? [YES — resolve blocking issues first] / [NO — proceed]
================================================================
CONFLICTS: [plugin A ↔ plugin B — overlap on X] or none
BLOCKING: [issues] or none
ACTION REQUIRED? YES / NO
```
---
## DECISION MATRIX
## DECISION TABLE
| Signal | Plugin to enable | Plugin to disable |
| Signal | Enable / Use | Disable / Skip | Notes |
|---|---|---|---|
| `frontend` | frontend-design, ui-ux-pro-max | — | Both complement each other |
| `mobile` (React Native/Expo/Flutter) | frontend-design | gstack (no browser QA), Docker N/A | ui-ux-pro-max optional |
| `monorepo` | per-package plugin recommendations | avoid recommending gstack for whole repo if only one package has browser QA | Specify which plugin applies to which package |
| `design-system` | frontend-design, ui-ux-pro-max | — | High overlap but both useful |
| `deploy` + `browser-qa` | gstack | — | Full-product workflow |
| `multi-session` | gsd v2 CLI | — | Run `gsd` in terminal, not CC plugin |
| `fast-libs` | context7 | — | Doc freshness critical |
| `multi-agent` + `complex-arch` | ruflo (MCP) | — | Only if genuine swarm needed |
| `simple` / single-session | — | gsd, gstack, ruflo, ui-ux-pro-max | Saves ~3000-5000t |
| `embedded` / firmware | — | all toggles; superpowers optional | workflow: /analyze → edit or /ship-feature |
| backend/lib/CLI only | — | frontend-design, ui-ux-pro-max, gstack | ~3100t saved |
| small project / hotfix | — | gstack, ruflo, gsd | Overhead exceeds value |
**GSD v2 note:** `gsd-pi` is a standalone CLI (Pi SDK), not a Claude Code plugin. Zero passive token cost in CC sessions. Recommend when: feature > 1 day, multiple isolated context windows needed, crash recovery, cost tracking, or parallel workers. Usage: `gsd` in terminal → `/gsd auto`.
**Ruflo note:** `ruflo` is a heavy MCP server (310+ tools, ~500-1500t passive). Only recommend when the project explicitly requires coordinating 5+ specialized agents simultaneously or swarm/parallel-orchestration architecture. For standard multi-session work, GSD v2 is sufficient and lighter.
---
## COMPATIBILITY MATRIX
### Conflicts and overlaps
| Pair | Relation | Verdict |
|---|---|---|
| Frontend UI | frontend-design, ui-ux-pro-max | — |
| Complex design (system, variants) | gstack (/design-*) | — |
| Browser QA | gstack (/qa, /browse) | — |
| Deployment in scope | gstack (/ship, /canary) | — |
| Multi-session feature (days) | gsd | — |
| Fast-evolving libs | context7 | — |
| Backend/lib/CLI only, no frontend | — | frontend-design, ui-ux-pro-max, gstack |
| Single session | — | gsd |
| Simple fix or small task | — | gstack, gsd |
| frontend-design ↔ ui-ux-pro-max | ⚠️ Overlap | Both do UI styling. Keep both for design-heavy projects; drop ui-ux-pro-max for simple UIs. ~600t combined. |
| gstack ↔ gsd v2 | ✅ Complementary | GStack = full-product CC workflow. GSD v2 = multi-session CLI. Different scopes, no conflict. |
| gstack ↔ ruflo | ⚠️ Overlap | Both orchestrate multi-step workflows. GStack is CC-native; ruflo is MCP swarm. High combined overhead (~3250-4250t). Use one or the other. |
| gsd v2 ↔ ruflo | ⚠️ Overlap | GSD v2 = sequential session pipeline. Ruflo = parallel agent swarm. Pick one per project; ruflo only if genuinely parallel work needed. |
| superpowers ↔ gsd v2 | ✅ Complementary | Superpowers = single-session execution. GSD v2 = multi-session CLI orchestration. No conflict. |
| superpowers ↔ gstack | ✅ Complementary | Used together in /init-project and /ship-feature. Superpowers = engine, GStack = full-product skills. |
| superpowers ↔ ruflo | ⚠️ Overlap | Both can orchestrate agent sub-tasks. Together only for advanced hybrid setups. |
| context7 ↔ any | ✅ Independent | Doc lookup MCP, no workflow overlap. Always safe to combine. |
| skill-creator ↔ superpowers | ⚠️ Minor overlap | Superpowers can create skills too. Keep skill-creator only when actively building new skills. |
| frontend-design ↔ gstack | ✅ Complementary | GStack = deploy/QA layer; frontend-design = UI quality layer. Different concerns. |
| pr-review-toolkit ↔ superpowers | ✅ Complementary | superpowers:requesting-code-review and /pr-review-toolkit:review-pr cover different review styles. |
| rtk ↔ any | ✅ Independent | Hook-only token compression. Zero interaction with any plugin. |
| security-guidance ↔ any | ✅ Independent | Hook-only security rules. Zero interaction. |
### Recommended sets by project type
| Project type | Plugins ON | OFF | Passive cost |
|---|---|---|---|
| Backend API / microservice | superpowers, context7 (if fast libs) | 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 (unless parallel) | ~800t CC |
| Quick fix / hotfix | superpowers | all toggles | ~800t |
| Design system / component lib | superpowers, frontend-design, ui-ux-pro-max | gstack, ruflo, gsd | ~1600t |
| Fast-evolving libs (Next.js etc.) | superpowers, context7, frontend-design | ruflo | ~1200t |
| Enterprise multi-agent orchestration | superpowers, ruflo + gsd v2 (external) | skill-creator, pr-review-toolkit | ~2300t CC |
> security-guidance and rtk are ALWAYS ON (0 tokens) — omitted from cost estimates for clarity.
### Conditional rules
```
RULE: IF "mobile" signal (React Native/Expo/Flutter detected):
→ frontend-design ON (~200t) — mobile UI components
→ gstack OFF — no browser QA on mobile
→ Docker NOT relevant — no server-side containerization for mobile
→ ui-ux-pro-max OPTIONAL (~400t) — only if design system complexity is high
RULE: IF "monorepo" signal detected:
→ scan each top-level package individually for frontend/deploy/fast-libs signals
→ recommend plugins per-package, NOT for the whole repo
→ if only apps/web/ has frontend: enable frontend-design for web package only
→ if only apps/api/ has deploy: gstack only if apps/api/ has browser QA too
→ NOTE in output: "Plugin X recommended for apps/web/ — disable for apps/api/"
→ passive cost estimate = highest-cost package profile (other packages add nothing)
RULE: IF "frontend" signal OR .tsx/.jsx count > 0:
→ frontend-design ON (~200t)
→ ui-ux-pro-max ON if "design-system" signal (~400t additional)
RULE: IF "deploy" AND "browser-qa" signals:
→ gstack ON (~2750t) — full-product workflow
RULE: IF "multi-session" OR multi-day feature:
→ Recommend gsd v2 CLI: npm install -g gsd-pi → gsd → /gsd auto
→ Zero passive CC token cost
RULE: IF "fast-libs" (Next.js/React 18+/Prisma/Supabase/Drizzle):
→ context7 ON (~200t)
RULE: IF "multi-agent" AND "complex-arch":
→ ruflo MCP ON (~500-1500t)
→ IF gstack also ON: WARN overlap (~3250-4250t combined)
RULE: IF "simple" OR "hotfix":
→ Disable all toggles. ~800t base only.
RULE: IF "embedded" signal (firmware, bare-metal, microcontroller, or Makefile+C without Node/Rust/Go):
→ Disable ALL toggles including gstack, context7, ruflo, skill-creator
→ superpowers OPTIONAL: useful for initial design brainstorm on complex drivers,
but unnecessary for single-function patches — user decides
→ GSD v2 CLI: not recommended (sessions are short, tasks are atomic)
→ Recommend workflow: /analyze <file> → Edit direct (hotfix) or /ship-feature (multi-file)
→ NOTE: print "embedded project detected — minimal plugin footprint recommended"
RULE: IF gstack ON AND ruflo ON:
→ WARN: functional overlap on multi-step orchestration
→ Suggest: gstack for CC-native workflow, ruflo only if parallel swarm needed
RULE: IF skill-creator ON AND no `skill-creation` signal detected:
→ WARN: skill-creator active but no skill-creation signal (~100t saved if disabled)
→ Disable unless you're actively building or editing custom skills
RULE: IF `skill-creation` signal:
→ skill-creator ON (~100t)
→ superpowers ON — required for skill scaffolding
RULE: IF `browser-qa` signal (e2e tests, Playwright/Cypress/Puppeteer in deps):
→ gstack ON — browser automation and QA
→ context7 OPTIONAL (depends on framework version)
RULE: IF `design-system` signal (tokens, theme files, Storybook present):
→ frontend-design ON (~200t)
→ ui-ux-pro-max ON (~400t)
→ WARN if both are OFF with this signal: significant design gap
RULE: IF `complex-arch` signal (multiple services, event bus, distributed system):
→ ruflo MCP ON (~500-1500t)
→ gsd v2 CLI recommended for multi-session coordination
→ IF gstack also ON: WARN combined cost ~3250-4250t — consider disabling one
```
---
## THRESHOLDS
## BLOCK if
**Block and require action if:**
- Superpowers is not active (required by /init-project and /ship-feature orchestrators — install command: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`)
- Project has significant frontend AND frontend-design + ui-ux-pro-max are both disabled
- Project uses Next.js/React/Prisma/Supabase AND context7 is not configured
- Project is full-product (UI + deploy + QA) AND gstack is not installed
- Superpowers not active → install: `claude plugin marketplace add obra/superpowers-marketplace && claude plugin install --scope user superpowers@superpowers-marketplace`
- Significant frontend signal + frontend-design AND ui-ux-pro-max both off
- Full-product (UI+deploy+QA) + gstack not installed
**Warn but don't block if:**
- Heavy plugins active but not needed (just cost notice)
- GSD active for a simple single-session task
## WARN (no block)
---
- Active toggle plugins not needed for this task (dead passive cost)
- gstack ON + ruflo ON simultaneously (overlap, ~3250-4250t)
- ruflo ON with no multi-agent signal detected
- Multi-session feature + `gsd` CLI not installed → `npm install -g gsd-pi`
- Total passive cost > 5500t (~50% of Pro session budget)
- **Next.js/React 18+/Prisma/Supabase detected + context7 not configured**
→ Risk: Claude may generate code using outdated APIs (App Router changes frequently)
→ Fix: `claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key KEY`
→ Free key: https://upstash.com
→ Type "force" to proceed without context7 (not recommended for fast-evolving libs)
## IMPORTANT
This agent only reads and checks. It never modifies files.
If action is required, stop — wait for the user to enable/disable plugins.
If no action required, state clearly "proceed" so the orchestrator continues.
Never modify files. If action required → stop and wait. If not → say "proceed".

317
agents/readme-updater.md
View File

@ -1,320 +1,81 @@
---
name: readme-updater
description: Manage the project README in all lifecycle phases. Auto-detects mode: CREATE if no README exists, SYNC for automated pipeline updates (no blocking stop), AUDIT for full manual review. Called by /readme, init-project, and ship-feature.
description: Manage project README. Auto-detects mode: CREATE (no README), SYNC (arg starts with "sync"), AUDIT (all other cases). Called by /readme, init-project, ship-feature.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---
# README UPDATER
## ROLE
Single agent responsible for the README across the entire project lifecycle.
## MODES
## GOAL
Always produce a README that is immediately actionable on any platform,
accurate, and reflects the current state of the project.
First word of `$ARGUMENTS` determines mode. CREATE takes precedence if README.md missing.
---
- **CREATE** — README.md doesn't exist → build from scratch
- **SYNC** — first word is exactly `sync` → silent updates, no stop
- **AUDIT** — anything else (empty, description, "audit") → full diff + mandatory stop
## MODE DETECTION
## DOCKER DETECTION (run in all modes before writing)
Determine the operating mode from $ARGUMENTS and context:
**CREATE mode** — when `README.md` does not exist in the project root.
Build the README from scratch using available sources.
**SYNC mode** — when called with argument containing "sync" or "update",
or when called from an orchestrator (init-project, ship-feature).
Apply updates without blocking. No mandatory stop.
**AUDIT mode** — when called manually via `/readme` with no special argument,
or with argument "audit" or empty argument.
Full diff analysis with mandatory stop before applying changes.
---
## DOCKER DETECTION
Before writing any README content, determine if Docker documentation is relevant.
Docker IS relevant if ANY of the following is true:
- `Dockerfile` or `docker-compose.yml` exists in the project
- `CLAUDE.md` mentions: deploy, deployment, service, API, server, container, Docker
- The project type is: web app, API, backend service, microservice, SaaS
- The project has external dependencies: database, cache (Redis), message broker (Kafka/RabbitMQ)
Docker is NOT relevant if the project type is:
- Library / package (npm package, Python lib, Rust crate, Go module)
- CLI tool with no server component
- WordPress theme or plugin (deployed differently)
- Device driver or system plugin
- Mobile app (Flutter, React Native) — Docker is a stretch
Store this as: `DOCKER_RELEVANT = true/false`
Docker relevant if: Dockerfile or docker-compose.yml present, or CLAUDE.md mentions deploy/service/API/server/Docker, or project is web app/API/backend/SaaS, or has DB/Redis/Kafka dep.
Docker NOT relevant if: library, CLI (no server), mobile app, driver/plugin.
Store as `DOCKER_RELEVANT = true/false`.
---
## CREATE MODE
*Triggered when: `README.md` does not exist.*
Sources (in order): CLAUDE.md, folder structure (`find . -not -path '*/.git/*' -not -path '*/node_modules/*' ... | head -80`), package manifest, .env.example, Dockerfile/compose if present.
### Sources to read (in order):
1. `CLAUDE.md` (required)
2. `~/.claude/CLAUDE.md` (global rules, for context only)
3. Folder structure: `find . -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/target/*' | sort | head -80`
4. Package manifest: `package.json`, `Cargo.toml`, `pyproject.toml`, `pubspec.yaml`, `go.mod`, `composer.json`
5. `.env.example` if present
6. `Dockerfile` and `docker-compose.yml` if present
Generate sections: About (summary+objective+status), Prerequisites (per OS, exact cmds), Installation, Running (dev/prod/test/lint), Docker (only if DOCKER_RELEVANT), Project structure (2 levels), Configuration (all .env.example vars), Contributing (branch → test → commit → PR).
### README structure to generate:
Rules: exact runnable commands only, derive from CLAUDE.md, no placeholders.
Every command must be exact and runnable.
Never use placeholder examples — derive real commands from CLAUDE.md.
```markdown
# <Project Name>
> <one-line tagline>
## About
**Summary**: <2–3 sentences: what it does, what problem it solves>
**Objective**: <what success looks like for users>
**Status**: `in development`
## Prerequisites
List every tool with minimum version and purpose.
Organize by OS — only include steps that differ per OS.
If a tool installs identically on all platforms, use a single block.
### Windows
<winget commands or installer URLs — exact>
### Linux (Debian/Ubuntu)
<apt/curl commands — exact>
<if dnf/pacman differ meaningfully, add a note>
### macOS
<brew commands — exact>
## Installation
```bash
# Clone
git clone <repo-url>
cd <project-name>
# Install dependencies
<exact command — derived from CLAUDE.md build commands>
# Configure environment
cp .env.example .env
# Edit .env — required variables listed in Configuration section below
# Database setup (if applicable)
<exact migration/seed commands>
# Build (if applicable)
<exact build command>
```
## Running
```bash
# Development
<exact dev command>
# Production
<exact prod command>
# Tests
<exact test command>
# Lint / format (if configured)
<exact lint command>
```
## [Docker] — INCLUDE ONLY IF DOCKER_RELEVANT = true
```bash
# Build and start all services
docker compose up --build
# Start in background
docker compose up -d
# Stop services
docker compose down
# View logs
docker compose logs -f <service-name>
# Run tests in container
docker compose run --rm <app-service> <test-command>
# Production build only
docker build -t <project-name>:<tag> .
```
**Environment variables for Docker:**
Copy `.env.example` to `.env` before running.
The `docker-compose.yml` reads from `.env` automatically.
If the project has a database service in docker-compose.yml:
```bash
# Run migrations inside container
docker compose run --rm <app-service> <migration-command>
```
**Port mapping:**
<list ports exposed by docker-compose.yml with their purpose>
## Project structure
<folder tree — 2 levels deep — with one-line description per entry>
## Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
| <VAR_NAME> | yes/no | <value or "—"> | <what it does> |
<derive from .env.example — every variable documented>
## Contributing
```bash
# Create a branch
git checkout -b feature/<name>
# Run tests before committing
<test command>
# Commit and push
git add .
git commit -m "feat: <description>"
git push origin feature/<name>
```
Open a pull request against `main`.
```
Write to `README.md`. No mandatory stop — print confirmation and continue.
Output: `📄 README created — <N sections> [Docker: included/N/A]`. No stop.
---
## SYNC MODE
*Triggered when: called with "sync", or from init-project/ship-feature.*
Read: README.md, CLAUDE.md, git log (last 20), folder structure, manifests.
### What SYNC does:
1. Run DOCKER DETECTION
2. Read `README.md`, `CLAUDE.md`, git log (last 20 commits), folder structure, manifests
3. Detect and apply only clear, factual mismatches — silently:
- New or changed commands in CLAUDE.md not in README
- New env vars in `.env.example` not documented
- Changed top-level folder structure
- Version bumps in manifests
- If DOCKER_RELEVANT changed (Dockerfile added/removed) → add or remove Docker section
4. Add `## Recent changes` entry if 5+ commits since last README update and no changelog exists
Apply only clear factual mismatches (no prose rewrites, no speculation, no stops):
- Changed commands in CLAUDE.md not in README
- New .env.example vars undocumented
- Changed folder structure
- Version bumps in manifests
- Docker section added/removed if DOCKER_RELEVANT changed
- Add `## Recent changes` if 5+ commits since last README update and no changelog
### What SYNC does NOT do:
- Rewrite existing prose
- Add speculative content
- Stop and ask the user anything
- Modify sections that are still accurate
Print after completing:
`📄 README synced — <N changes applied / "no changes needed">`
Output: `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
---
## AUDIT MODE
*Triggered when: called via `/readme` with empty or "audit" argument.*
### Phase 1 — Read
README.md, CLAUDE.md, `git log --oneline -50`, `git diff HEAD~20..HEAD --stat`, folder structure, manifest, .env.example, Dockerfile/compose if present.
### PHASE 1 — GATHER CONTEXT
### Phase 2 — Status per section
✅ current | 📝 update | ➕ missing | ❌ remove
Read:
1. `README.md` — current state (if missing, switch to CREATE mode automatically)
2. `CLAUDE.md`
3. Git history: `git log --oneline -50`
4. Git diff vs last tag or `git diff HEAD~20..HEAD --stat`
5. Folder structure
6. Package manifest
7. `.env.example`
8. `Dockerfile`, `docker-compose.yml` if present
9. Run DOCKER DETECTION
Check: About still accurate, prereqs versions, install/run cmds, Docker section vs DOCKER_RELEVANT, structure vs reality, all .env vars documented.
### PHASE 2 — AUDIT
For each section, determine status:
| Status | Meaning |
|---|---|
| ✅ current | Accurate |
| 📝 update | Outdated |
| ➕ missing | Should be added |
| ❌ remove | No longer relevant |
Check specifically:
- About/Summary still matches project
- Prerequisites versions still accurate
- Missing tools
- Installation commands still work
- Running commands still accurate
- Docker section: present if DOCKER_RELEVANT=true, absent if DOCKER_RELEVANT=false
- Project structure matches reality
- Configuration: all .env.example vars documented, no obsolete vars
- Recent changes since last README update
### PHASE 3 — AUDIT REPORT + MANDATORY STOP
### Phase 3 — Report + MANDATORY STOP
```
================================================================
README AUDIT
================================================================
LAST MEANINGFUL COMMIT : <hash — message>
DOCKER : relevant (✅ / ❌) — section <present / missing / N/A>
STATUS SUMMARY
--------------
✅ current : <N sections>
📝 update : <N sections>
➕ missing : <N sections>
❌ remove : <N sections>
DETAIL
------
<per-section findings — specific, actionable>
================================================================
Proceed with update? (yes / select sections / cancel)
================================================================
LAST COMMIT : <hash — msg>
DOCKER : relevant ✅/❌ — section present/missing/N/A
SUMMARY : ✅<n> 📝<n> ➕<n> ❌<n>
DETAIL : <per-section findings>
Proceed? (yes / select sections / cancel)
```
**MANDATORY STOP — wait for user confirmation.**
### Phase 4 — Apply (after confirmation)
Surgical edits only. Preserve structure and tone. 📝 replace, ➕ insert, ❌ remove or mark deprecated.
### PHASE 4 — UPDATE (after confirmation)
### Phase 5 — Verify
Re-read. No broken markdown. Commands consistent with CLAUDE.md.
Apply all approved changes surgically:
- Preserve existing structure and tone
- For 📝: replace only outdated content
- For ➕: insert in logical order
- For ❌: remove or mark `> ⚠️ Deprecated: <reason>`
- Never rewrite the entire README
### PHASE 5 — VERIFY
Re-read the updated README.
Confirm no broken markdown, all commands consistent with CLAUDE.md.
---
## OUTPUT (all modes)
**CREATE:** `📄 README created — <N sections> [Docker: included / not applicable]`
**SYNC:** `📄 README synced — <N changes / "no changes needed"> [Docker: <status>]`
**AUDIT:** Full report → `📄 README updated — <summary>`
Output: `📄 README updated — <summary>`

385
agents/scaffolder.md
View File

@ -1,6 +1,6 @@
---
name: scaffolder
description: Create the empty skeleton of a project. Generates CLAUDE.md, settings, folder structure, config files, empty entry points, installs dependencies, and optionally adds Docker config if the project type warrants it. Does NOT implement any business logic or features.
description: Create empty project skeleton. Generates CLAUDE.md, settings, structure, config, empty entry points, installs deps, optional Docker. NO business logic.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
effort: high
@ -8,355 +8,116 @@ effort: high
# SCAFFOLDER
## ROLE
Create the empty skeleton of a project and make it buildable.
## GOAL
Deliver a project where:
- Folder structure and config files are in place
- CLAUDE.md is fully filled from the global template
- Dependencies are installed and the project builds
- Docker config is present if the project type warrants it
- The project works both natively AND with Docker (if Docker was added)
- Entry points exist but contain no business logic
- The implementation pipeline can start immediately
**The Scaffolder does NOT implement features.**
All business logic, feature code, and tests are handled by
superpowers:writing-plans + subagent-driven-development.
---
## INPUT REQUIRED
Deliver a buildable skeleton: structure + config + empty entry points. No features, no business logic.
## INPUTS REQUIRED
1. PROJECT BRIEF (from interviewer)
2. Approved DESIGN (from brainstorming)
3. `~/.claude/templates/project-CLAUDE.md`
4. `~/.claude/CLAUDE.md`
If any input is missing → STOP and report.
If any missing → STOP.
---
## PHASE 0 — DOCKER DECISION
Before creating any files, decide if Docker is relevant.
**Docker IS relevant** if ANY of these apply:
- Project type is: web app, API, backend service, microservice, SaaS
- Project has external runtime dependencies: database, Redis, Kafka, RabbitMQ, S3
- PROJECT BRIEF or DESIGN mentions: deploy, deployment, container, Docker, cloud
- The project is meant to be run as a persistent server/service
**Docker is NOT relevant** if the project is:
- A library / package (npm, pip, crate, Go module)
- A CLI tool with no server component
- A WordPress theme or plugin
- A device driver or system plugin
- A mobile app (Flutter, React Native)
- A C/C++ project without networked services
Store this decision as `DOCKER_RELEVANT = true/false`.
**If DOCKER_RELEVANT = true**, Docker config is added as a parallel option.
The project MUST still work natively without Docker.
Docker is an additional way to run it, not a replacement.
Docker relevant: web app/API/SaaS, external deps (DB/Redis/Kafka), BRIEF mentions deploy/Docker/cloud, persistent server/service.
Docker NOT relevant: library, CLI (no server), **mobile app (React Native, Expo, Flutter)**, driver.
Store: `DOCKER_RELEVANT = true/false`. If true → Docker is additional, project must still run natively.
---
## PHASE 1 — GENERATE PROJECT CLAUDE.md
## PHASE 1 — GENERATE CLAUDE.md
Read `~/.claude/templates/project-CLAUDE.md` in full.
Read `~/.claude/CLAUDE.md` to understand global rules.
Fill in every section from the PROJECT BRIEF and approved DESIGN.
No placeholders. No template examples left in.
Mark irrelevant sections as `N/A — <reason>`.
Required content:
- Project overview (2–4 sentences)
- Stack (language + version, framework, runtime, database)
- Build commands (exact, native)
- Test commands (exact)
- Lint/format commands (exact or N/A)
- Docker commands (if DOCKER_RELEVANT) — exact
- Folder structure (actual tree)
- Architecture (module responsibilities, data flow)
- Project conventions
- Exceptions to global rules (or "none")
- Key dependencies (name — purpose)
- Workflow expectations
Write to `CLAUDE.md` at the project root.
Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`.
Fill every section from BRIEF + DESIGN. No placeholders. Irrelevant sections → `N/A — <reason>`.
Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow.
Write to `CLAUDE.md` at project root.
---
## PHASE 2 — GENERATE SETTINGS
## PHASE 2 — SETTINGS
### a. `.claude/settings.json`
Read `~/.claude/templates/settings/settings.json`.
Adapt `allow` rules to this stack:
- Keep only blocks relevant to this stack
- Add stack-specific commands
- If DOCKER_RELEVANT: add `Bash(docker compose *)`, `Bash(docker build *)`
- Add project-specific `ask` rules
### b. `.claudeignore`
Read `~/.claude/templates/settings/.claudeignore`.
Extend with stack-specific exclusions.
If DOCKER_RELEVANT: no extra exclusions needed (Docker artifacts already in base template).
### c. Print:
```
⚙️ SETTINGS SETUP
.claude/settings.json created
.claudeignore created
Manual: copy ~/.claude/templates/settings/settings.local.json
→ .claude/settings.local.json (gitignore it, never commit)
```
**a. `.claude/settings.json`** — read `~/.claude/templates/settings/settings.json`, keep only relevant stack blocks, add stack-specific cmds, add docker cmds if DOCKER_RELEVANT.
**b. `.claudeignore`** — read `~/.claude/templates/settings/.claudeignore`, extend for stack.
**c. Print** confirmation of both files + manual note for settings.local.json.
---
## PHASE 3 — SCAFFOLD STRUCTURE
## PHASE 3 — SCAFFOLD FILES
Create every folder and file from the approved DESIGN.
### Universal
`CLAUDE.md`, `.gitignore` (stack-appropriate), `.env.example` (all vars described, no secrets), `.claude/settings.json`, `.claudeignore`.
### Universal required files:
| File | Content |
### Entry points
Empty structure only: imports + empty main/init. No logic.
### Stack files
**Node.js/TS**: `package.json` (scripts: dev/build/test/lint), `tsconfig.json` if TS, `.eslintrc`, `src/index.ts` (empty).
**React**: `package.json`, `vite.config.ts`, `src/main.tsx`, `src/App.tsx` (empty), `src/components/`, `index.html`.
**Python**: `pyproject.toml` or `requirements.txt`, `src/<pkg>/__init__.py`, `src/<pkg>/main.py` (empty).
**FastAPI/Flask/Django**: `requirements.txt` (pinned), `src/<pkg>/main.py` (app init only), `routes/` + `models/` (empty), `.env.example`, `alembic.ini` if SQLAlchemy.
**Rust**: `Cargo.toml`, `src/main.rs` or `src/lib.rs` (empty).
**C/C++**: `Makefile` (all/clean/fclean/re, -Wall -Wextra -Werror), `src/`, `include/`, `main.c/.cpp` (empty).
**React Native / Expo**: `package.json` (scripts: start/android/ios/test/lint), `tsconfig.json`, `app.json` (Expo config with name/slug/version/sdkVersion), `app/(tabs)/index.tsx` (empty tab), `app/_layout.tsx` (root layout, empty), `components/` (empty), `hooks/` (empty), `constants/Colors.ts` (empty), `.env.example`. No Docker. Install: `npx expo install`. Build check: `npx expo export --platform web --output-dir /tmp/expo-check --clear` (web build validates config without device).
**Flutter**: `pubspec.yaml` (sdk: '>=3.0.0 <4.0.0', deps: flutter sdk, flutter_lints), `analysis_options.yaml`, `lib/main.dart` (empty MaterialApp), `lib/src/` (features/, shared/, core/), `test/widget_test.dart` (empty). No Docker. Install: `flutter pub get`. Build check: `flutter analyze` (validates pubspec + dart syntax without device).
### Docker (only if DOCKER_RELEVANT)
`Dockerfile`: multi-stage build (builder → production), non-root user, EXPOSE, CMD. Adapt to stack.
`docker-compose.yml`: app service (build, ports, env_file), db/redis only if actually needed, named volumes.
`.dockerignore`: node_modules, .git, .env, dist/build/target, __pycache__.
Add `COMPOSE_PROJECT_NAME=<slug>` to `.env.example`.
---
## PHASE 4 — INSTALL DEPS
| Stack | Command |
|---|---|
| `CLAUDE.md` | Generated in Phase 1 |
| `.gitignore` | Stack-appropriate, comprehensive |
| `.env.example` | All env vars with description, no real secrets |
| `.claude/settings.json` | Generated in Phase 2 |
| `.claudeignore` | Generated in Phase 2 |
### Entry points and modules:
- Entry point files exist with minimal structure (imports + empty main/app init)
- Module/package files exist but are empty or have minimal declarations
- No business logic anywhere
### Stack-specific required files:
**Node.js / TypeScript**
```
package.json — name, scripts (dev/build/test/lint), dependencies
tsconfig.json — if TypeScript
.eslintrc — lint config
src/index.ts — empty entry point with comment
```
**React (frontend)**
```
package.json — scripts: dev, build, preview, test, lint
vite.config.ts — bundler config
src/main.tsx — minimal entry point
src/App.tsx — empty root component
src/components/ — empty folder
index.html — entry HTML
```
**Python**
```
pyproject.toml or requirements.txt
src/<package>/__init__.py
src/<package>/main.py — empty entry point
```
**FastAPI / Flask / Django**
```
requirements.txt — pinned dependencies
src/<pkg>/main.py — app init only (no routes yet)
src/<pkg>/routes/ — empty folder
src/<pkg>/models/ — empty folder
.env.example — DATABASE_URL, SECRET_KEY, etc.
alembic.ini — if using SQLAlchemy
```
**Rust**
```
Cargo.toml
src/main.rs or src/lib.rs — empty main / empty lib
```
**Go**
```
go.mod
cmd/<app>/main.go — empty main
internal/ — empty folder
```
**C / C++**
```
Makefile — targets: all, clean, fclean, re (-Wall -Wextra -Werror)
src/ — empty
include/ — empty
main.c or main.cpp — empty main
```
**PHP / WordPress Theme**
```
style.css — theme header (Name, Description, Version, etc.)
functions.php — empty theme setup
index.php — minimal template
```
**Flutter / Dart**
```
pubspec.yaml
lib/main.dart — minimal MaterialApp / CupertinoApp
lib/app/ — empty folders
```
### Docker config (ONLY if DOCKER_RELEVANT = true):
Create these files IN ADDITION to the native stack files above.
The project must still run without Docker.
**`Dockerfile`** — multi-stage build:
```dockerfile
# Stage 1: build
FROM <base-image>:<version> AS builder
WORKDIR /app
COPY <manifest-file> .
RUN <install-deps-command>
COPY . .
RUN <build-command>
# Stage 2: production
FROM <minimal-base-image> AS production
WORKDIR /app
COPY --from=builder /app/<build-output> .
EXPOSE <port>
CMD [<start-command>]
```
Adapt image, ports, and commands to the actual stack.
Use non-root user for security.
**`docker-compose.yml`** — all services:
```yaml
services:
app:
build: .
ports:
- "<host-port>:<container-port>"
env_file: .env
depends_on: [<db-service>] # only if DB present
# Add only services actually needed:
db: # if project uses a relational DB
image: postgres:16-alpine # or mysql:8 / mariadb:11 as appropriate
environment:
POSTGRES_DB: ${DB_NAME}
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- db_data:/var/lib/postgresql/data
redis: # only if project uses Redis
image: redis:7-alpine
volumes:
db_data:
```
**`.dockerignore`**:
```
node_modules/
.git/
.env
dist/
build/
target/
__pycache__/
*.pyc
.pytest_cache/
coverage/
```
After creating Docker files, add to `.env.example`:
```
# Docker (optional — only needed when using docker compose)
COMPOSE_PROJECT_NAME=<project-slug>
```
---
## PHASE 4 — INSTALL DEPENDENCIES
Install project dependencies so the build works.
This is mandatory — the build verification in Phase 5 requires installed deps.
Run the appropriate install command for the stack:
| Stack | Install command |
|---|---|
| Node.js / React / TypeScript | `npm install` |
| Python / FastAPI / Flask | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
| Rust | `cargo fetch` |
| Go | `go mod download` |
| Node.js/React/TS | `npm install` |
| React Native / Expo | `npx expo install` |
| Flutter | `flutter pub get` |
| PHP / Composer | `composer install` |
| C / C++ | No package manager — verify compiler is available: `gcc --version` or `clang --version` |
| Python | `pip install -r requirements.txt` or `uv pip install -r requirements.txt` |
| Rust | `cargo fetch` |
| C/C++ | verify: `gcc --version` or `clang --version` |
If the install command fails:
1. Read the error output
2. Fix the config file causing the failure (package.json, requirements.txt, etc.)
3. Retry
4. If it still fails after one fix attempt → report the error and stop
If DOCKER_RELEVANT = true, also verify Docker is available:
```bash
docker --version && docker compose version
```
If Docker is not installed, print a warning but do not fail — native install continues.
On failure: read error → fix config → retry once → if still failing: report and stop.
If DOCKER_RELEVANT: `docker --version && docker compose version` — failure is warning, not blocker.
---
## PHASE 5 — VERIFY SKELETON
## PHASE 5 — VERIFY BUILD
Run the build command on the empty project.
The project must compile/start even with no features.
Run build/check command from CLAUDE.md on empty project. Must succeed with no features.
```bash
# Native build
<build-command from CLAUDE.md>
```
| Stack | Verify command | Notes |
|---|---|---|
| Node.js/TS/React | `npm run build` | Must produce dist/ without error |
| React Native / Expo | `npx expo export --platform web --output-dir /tmp/expo-check --clear` | No device needed; validates config |
| Flutter | `flutter analyze` | No device needed; validates pubspec + Dart syntax |
| Python / FastAPI | start dev server, check port responds | |
| Rust | `cargo check` | Faster than full build for skeleton |
| C/C++ | `make` | Must produce binary |
If build fails:
1. Read the full error
2. Fix the issue (missing import, wrong path, syntax error in empty file, etc.)
3. Retry — maximum 2 attempts
4. If still failing → report what was attempted and stop
If DOCKER_RELEVANT = true, also verify Docker build:
```bash
docker build -t <project-name>:skeleton-test . --quiet
```
Docker build failure is a warning, not a blocker — native must pass.
On failure: read error → fix → retry max 2 times → if still failing: report and stop.
If DOCKER_RELEVANT: `docker build -t <n>:skeleton-test . --quiet` — failure is warning.
---
## OUTPUT
```
SKELETON COMPLETE: <project name>
FILES CREATED : <count>
DOCKER : included / not applicable — <one-line reason>
INSTALL : ✅ dependencies installed / ❌ <e>
BUILD (native) : ✅ passes / ❌ <e>
BUILD (docker) : ✅ passes / ⚠️ not verified / N/A
STRUCTURE:
<actual tree of what was created>
READY FOR IMPLEMENTATION PIPELINE:
- V1 features to implement : <N> features from PROJECT BRIEF
- Entry points ready : ✅
- Config files ready : ✅
- Dependencies installed : ✅ / ❌
- CLAUDE.md : ✅ complete
- README.md : handled by readme-updater (next step)
- Settings : ✅ .claude/settings.json + .claudeignore
SKELETON COMPLETE: <name>
FILES : <count>
DOCKER : included / N/A — <reason>
INSTALL : ✅ / ❌ <error>
BUILD : ✅ / ❌ <error>
DOCKER BUILD: ✅ / ⚠️ not verified / N/A
STRUCTURE: <tree>
READY: <N> v1 features | entry points ✅ | config ✅ | CLAUDE.md ✅ | README → readme-updater | settings ✅
```

176
agents/status-reporter.md Normal file
View File

@ -0,0 +1,176 @@
---
name: status-reporter
description: Consolidated project status — plugins, token budget, git state, build, tests, GSD milestone. Read-only snapshot. Use to orient quickly at session start or after a break.
tools: Read, Bash, Glob, Grep
model: haiku
---
# STATUS REPORTER
## ROLE
Produce a read-only consolidated status of the current project and Claude Code setup.
No modifications. No design. No proposals. Facts only.
---
## PHASE 1 — SETUP STATUS
```bash
# Config version
cat ~/.claude/version.txt 2>/dev/null || echo "unknown"
# Active plugins (from session-start detection)
command -v rtk &>/dev/null && echo "rtk: installed" || echo "rtk: missing"
command -v gsd &>/dev/null && gsd --version 2>/dev/null | head -1 || echo "gsd: not installed"
# Token estimate (passive)
# (approximate from known plugin costs)
```
Check `~/.claude/plugins/cache` for active marketplace plugins.
Check `~/.claude.json` for active MCP servers.
---
## PHASE 2 — PROJECT STATUS
```bash
# CLAUDE.md
ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
head -10 CLAUDE.md 2>/dev/null || head -10 .claude/CLAUDE.md 2>/dev/null || echo "no CLAUDE.md"
# Git state
git log --oneline -5 2>/dev/null || echo "not a git repo"
git status --short 2>/dev/null | head -10
git branch --show-current 2>/dev/null
# Last build/test status (best-effort — several possible sources)
# Try common CI output files
cat .last-build.log 2>/dev/null | tail -3
cat .last-test.log 2>/dev/null | tail -3
# Try pytest cache (Python projects) — parse JSON: {} = all passing, {nodeids:[...]} = failures
python3 -c "
import json, os
f = '.pytest_cache/v/cache/lastfailed'
if os.path.exists(f):
try:
d = json.load(open(f))
n = len(d.get('nodeids', []))
print('pytest: all passing' if n == 0 else f'pytest: {n} failing')
except: pass
" 2>/dev/null || true
# Try Jest/Vitest last run
cat coverage/coverage-summary.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print('Jest coverage:', d.get('total',{}).get('statements',{}).get('pct','?'), '%')" 2>/dev/null || true
# Fallback: if no result found, extract test command from manifest
# so output can show "run '<cmd>' to check" instead of "unknown"
if [ -f package.json ]; then
python3 -c "import json,sys; d=json.load(open('package.json')); print('test:', d.get('scripts',{}).get('test',''))" 2>/dev/null || true
fi
if [ -f pytest.ini ] || [ -f pyproject.toml ] || [ -f setup.cfg ]; then
echo "pytest: pytest (Python project detected)"
fi
if [ -f Cargo.toml ]; then
echo "rust: cargo test"
fi
if [ -f go.mod ]; then
echo "go: go test ./..."
fi
if [ -f composer.json ]; then
echo "php: ./vendor/bin/phpunit (or composer test)"
fi
```
**Building the Tests field:**
If any test result was found (pytest lastfailed, Jest coverage, log file):
→ `Tests: all passing` (pytest {} or Jest 100%) or `Tests: X failing (<file::test>)` or `Tests: coverage X%`
Note: pytest `.pytest_cache/v/cache/lastfailed` with empty `{}` means all tests passed last run.
If no result found but test command exists:
→ `Tests: run '<test-command>' to check`
If no test infrastructure found:
→ `Tests: N/A`
---
## PHASE 3 — GSD v2 STATUS (if .gsd/ exists)
```bash
# Check .gsd/ presence and contents
ls .gsd/ 2>/dev/null | head -10
# ROADMAP.md — milestone checklist (most reliable source)
cat .gsd/ROADMAP.md 2>/dev/null | head -60 || echo "no ROADMAP.md"
# Slice-level progress — GSD v2 uses ### headings for slices (not tasks)
# Slices done = ### headings with [x] marker
grep -c '^### .*\[x\]' .gsd/ROADMAP.md 2>/dev/null || echo "0"
# Slices total = all ### headings
grep -c '^### ' .gsd/ROADMAP.md 2>/dev/null || echo "0"
# Task-level count (informational only — not the primary progress metric)
# Done tasks: - [x], Total tasks: - [
grep -c '^\s*- \[x\]' .gsd/ROADMAP.md 2>/dev/null || echo "0"
grep -c '^\s*- \[' .gsd/ROADMAP.md 2>/dev/null || echo "0"
# Current milestone — tries slice-level first, falls back to task-level
# Primary: first ## heading with a ### slice without [x]
awk '/^## /{ms=$0} /^### /{if(index($0,"[x]")==0){print ms; exit}}' .gsd/ROADMAP.md 2>/dev/null
# Fallback (flat structure — tasks directly under ##, no ### slices):
# Scoped to ## Milestone headings only — avoids matching documentation lists
# Resets on any non-Milestone ## heading (e.g. ## Prerequisites, ## Notes)
awk '/^## [Mm]ilestone/{ms=$0} /^## / && !/[Mm]ilestone/{ms=""} /^- \[/{if(ms && index($0,"- [x]")==0){print ms" (flat)"; exit}}' .gsd/ROADMAP.md 2>/dev/null
# All ## headings for context
grep -E '^## ' .gsd/ROADMAP.md 2>/dev/null
# Any additional GSD state files
find .gsd/ -name "*.md" -not -name "ROADMAP.md" 2>/dev/null | head -5
```
**Reading the output:**
- If `ROADMAP.md` exists: derive progress at **slice level** (### headings), not task level.
Slices done = `### headings with [x]`. Slices total = all `### headings`.
Report as: "X/Y slices done" — this matches GSD v2's own progress dashboard.
The current milestone = first `## heading` with an unchecked `### slice`. If no `###` slices exist (flat structure with tasks directly under `##`), fall back to the first `## heading` with an unchecked `- [ ]` task (second awk command, marked with "(flat)"). If both return empty, all milestones are complete.
- If only `.gsd/` exists but no `ROADMAP.md`: GSD initialized but no roadmap yet.
Print: "GSD v2 initialized — no ROADMAP.md yet. Run `/gsd init` or `/gsd discuss` to create one."
- If `.gsd/` is absent: print "GSD v2 not initialized for this project."
- Never attempt to read `state.db` or binary files — print "N/A" if state unclear.
---
## OUTPUT FORMAT
```
PROJECT STATUS
══════════════════════════════════════
CONFIG
Version : v<N>
Plugins ON: <list> (~<X>t passive)
GSD v2 : installed / not installed
PROJECT
CLAUDE.md : found / missing
Stack : <from CLAUDE.md overview or "unknown">
Branch : <current git branch>
Uncommitted: <count> files / clean
Tests : <last known result — "passing" / "X failing" / "unknown">
RECENT COMMITS (last 5):
<hash> <message>
...
GSD v2
Status : initialized / not initialized
Milestone : <current milestone or "none">
Progress : <X/Y slices done or "N/A">
QUICK ACTIONS
/plugin-check "<stack>" — audit plugins
/ship-feature "<desc>" — ship next feature
/health — full diagnostic
```
Rules:
- Never propose changes or solutions.
- If any data is unavailable, print "N/A" — do not guess.
- Keep output under 40 lines.

158
doctor.sh
View File

@ -29,6 +29,9 @@ echo ""
# 1. Core symlinks
# ────────────────────────────────────────────────────────────
echo "── Symlinks ──"
# Expected: CLAUDE.md, settings.json, agents, skills, templates, hooks/session-start.sh
_EXPECTED_LINKS=7
_LINK_PASS=0
check_symlink() {
local name="$1"
@ -40,12 +43,13 @@ check_symlink() {
fi
if [ -L "$target" ]; then
# readlink -f is not available on macOS BSD — use -f with fallback
local real
real=$(readlink -f "$target" 2>/dev/null || readlink "$target")
real=$(readlink -f "$target" 2>/dev/null) || real=$(readlink "$target")
if [ ! -e "$real" ]; then
fail "~/.claude/$name → $real — BROKEN SYMLINK"
else
pass "~/.claude/$name"
pass "~/.claude/$name"; _LINK_PASS=$((_LINK_PASS + 1))
fi
else
warn "~/.claude/$name exists but is NOT a symlink (expected symlink to repo)"
@ -56,7 +60,11 @@ check_symlink "CLAUDE.md"
check_symlink "settings.json"
check_symlink "agents"
check_symlink "skills"
check_symlink "templates"
check_symlink "lib"
check_symlink "hooks/session-start.sh"
info "Symlinks: ${_LINK_PASS}/${_EXPECTED_LINKS} OK"
unset _EXPECTED_LINKS _LINK_PASS
echo ""
@ -65,16 +73,27 @@ echo ""
# ────────────────────────────────────────────────────────────
echo "── GStack submodule ──"
if [ -d "$REPO/skills-external/gstack" ] || [ -f "$REPO/skills-external/gstack/.git" ]; then
pass "Submodule present at skills-external/gstack"
GSTACK_DIR="$REPO/skills-external/gstack"
if [ -f "$GSTACK_DIR/.git" ] || [ -d "$GSTACK_DIR/.git" ]; then
pass "Submodule initialized at skills-external/gstack"
warn "GStack tracks branch = main (no commit hash pin). Review upstream before updating."
elif [ -d "$GSTACK_DIR" ]; then
warn "skills-external/gstack exists but submodule not initialized — run: git submodule update --init"
else
warn "Submodule not initialized — run: git submodule update --init"
warn "GStack submodule missing — run: git submodule update --init"
fi
if [ -L "$HOME/.claude/skills/gstack" ]; then
real=$(readlink -f "$HOME/.claude/skills/gstack" 2>/dev/null || readlink "$HOME/.claude/skills/gstack")
if [ -d "$real" ]; then
pass "Symlink OK → $real"
# Check for skills/ subdirectory (referenced by plugin-advisor PHASE 1)
gstack_skills_count=$(ls "$HOME/.claude/skills/gstack/skills/" 2>/dev/null | wc -l | tr -d ' ')
if [ "${gstack_skills_count:-0}" -gt 0 ]; then
pass "GStack: ${gstack_skills_count} skills available"
else
warn "GStack symlink OK but no skills/ subdirectory found — may need: cd skills-external/gstack && ./setup"
fi
else
fail "Symlink broken → $real"
fi
@ -149,6 +168,18 @@ else
info "Context7 MCP not configured (optional — needed for fast-evolving libs)"
fi
if detect_gsd; then
pass "GSD v2 installed ($(gsd --version 2>/dev/null | head -1 || echo 'gsd'))"
else
info "GSD v2 not installed (optional — run: npm install -g gsd-pi)"
fi
if detect_ruflo; then
pass "Ruflo MCP configured"
else
info "Ruflo MCP not configured (optional — enterprise multi-agent orchestration)"
fi
echo ""
# ────────────────────────────────────────────────────────────
@ -170,7 +201,17 @@ with open('$SETTINGS') as f:
d = json.load(f)
print(len(d.get('permissions',{}).get('deny',[])))
" 2>/dev/null || echo "?")
pass "Deny rules: $DENY_COUNT"
if [ "$DENY_COUNT" = "?" ]; then
warn "Could not parse deny count (python3 unavailable or JSON parse error)"
else
EXPECTED_DENY=100
if [ "$DENY_COUNT" -eq "$EXPECTED_DENY" ] 2>/dev/null; then
pass "Deny rules: $DENY_COUNT"
else
warn "Deny rules: $DENY_COUNT (expected $EXPECTED_DENY) — settings may have been manually modified"
fi
fi
else
fail "~/.claude/settings.json not found"
fi
@ -181,29 +222,66 @@ echo ""
# 6. Token budget estimate
# ────────────────────────────────────────────────────────────
echo "── Token budget estimate ──"
# Reference: Claude Code Pro plan ~11k tokens/5h session (session budget, not context window).
# Seuils: WARNING >15%, CRITICAL >30% of session budget.
TOTAL_CHARS=0
CLAUDE_MD_CHARS=$(wc -c < "$REPO/CLAUDE.md" 2>/dev/null || echo 0)
CLAUDE_MD_TOKENS=$((CLAUDE_MD_CHARS / 4))
# Skill descriptions
# Skill descriptions only (frontmatter description field — loaded passively at startup)
SKILL_DESC_CHARS=0
for f in "$HOME/.claude/skills/"*/SKILL.md; do
[ -f "$f" ] || continue
desc=$(sed -n 's/^description: //p' "$f" 2>/dev/null || true)
TOTAL_CHARS=$((TOTAL_CHARS + ${#desc}))
desc=$(grep "^description:" "$f" 2>/dev/null | head -1 | sed 's/^description: *//' )
SKILL_DESC_CHARS=$((SKILL_DESC_CHARS + ${#desc}))
done
SKILL_DESC_TOKENS=$((SKILL_DESC_CHARS / 4))
SKILL_COUNT=$(find "$HOME/.claude/skills/" -maxdepth 2 -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
# Agent descriptions
for f in "$HOME/.claude/agents/"*.md; do
[ -f "$f" ] || continue
desc=$(sed -n '/^---$/,/^---$/{ s/^description: //p }' "$f" 2>/dev/null || true)
TOTAL_CHARS=$((TOTAL_CHARS + ${#desc}))
done
# Plugin passive cost estimates (tokens)
PLUGIN_TOKENS=0
if detect_superpowers 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 800)); fi
if detect_gstack 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 2750)); fi
if detect_frontend_design 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 200)); fi
if detect_uiux_pro_max 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 400)); fi
if detect_context7 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 200)); fi
if detect_ruflo 2>/dev/null; then PLUGIN_TOKENS=$((PLUGIN_TOKENS + 1000)); fi
if [ "$TOTAL_CHARS" -gt 6000 ]; then
warn "Custom descriptions: ~${TOTAL_CHARS} chars (budget ~8000) — risk of truncation"
elif [ "$TOTAL_CHARS" -gt 4000 ]; then
info "Custom descriptions: ~${TOTAL_CHARS} chars (within budget, moderate margin)"
TOTAL_TOKENS=$((CLAUDE_MD_TOKENS + SKILL_DESC_TOKENS + PLUGIN_TOKENS))
SESSION_BUDGET=11000
PCT=$((TOTAL_TOKENS * 100 / SESSION_BUDGET))
echo ""
echo " CLAUDE.md: ~${CLAUDE_MD_TOKENS}t"
echo " Skill descriptions: ~${SKILL_DESC_TOKENS}t (${SKILL_COUNT} skills)"
echo " Plugin passive cost: ~${PLUGIN_TOKENS}t (active plugins)"
echo " ─────────────────────────────────────────"
info " Total: ~${TOTAL_TOKENS}t"
info " Session budget (Pro): ${SESSION_BUDGET}t"
info " Usage: ~${PCT}%"
echo ""
if [ "$PCT" -gt 30 ]; then
warn "CRITICAL: ${PCT}% of session budget — /plugin-check to disable unused plugins"
elif [ "$PCT" -gt 15 ]; then
warn "WARNING: ${PCT}% of session budget — consider disabling unused toggle plugins"
else
pass "Custom descriptions: ~${TOTAL_CHARS} chars (comfortable)"
pass "Budget: ${PCT}% (comfortable)"
fi
# Per-file breakdown (skill bodies — loaded on demand, shown for awareness)
if [ "$TOTAL_TOKENS" -gt 2000 ]; then
info "Skill/agent bodies (loaded on demand, >200t each):"
for f in "$HOME/.claude/skills/"*/SKILL.md "$HOME/.claude/agents/"*.md; do
[ -f "$f" ] || continue
size=$(wc -c < "$f" 2>/dev/null || echo 0)
tokens=$((size / 4))
if [ "$tokens" -gt 200 ]; then
label=$(basename "$(dirname "$f")" 2>/dev/null)
[ "$label" = "." ] && label=$(basename "$f")
info " ~${tokens}t ${label}"
fi
done
fi
echo ""
@ -228,11 +306,45 @@ else
warn "Skills missing disable-model-invocation: ${MISSING_DMI[*]}"
fi
# Check CRLF
# Check expected skills are present
EXPECTED_SKILLS=(
"analyze" "health" "init-project" "onboard" "plugin-check"
"readme" "refactor" "ship-feature" "status"
)
MISSING_SKILLS=()
for skill in "${EXPECTED_SKILLS[@]}"; do
if [ ! -f "$HOME/.claude/skills/${skill}/SKILL.md" ]; then
MISSING_SKILLS+=("${skill}/")
fi
done
if [ ${#MISSING_SKILLS[@]} -eq 0 ]; then
pass "All ${#EXPECTED_SKILLS[@]} expected skills present (analyze, health, init-project, onboard, plugin-check, readme, refactor, ship-feature, status)"
else
warn "Missing skills: ${MISSING_SKILLS[*]} — run: bash link.sh"
fi
# Check expected agents are present
EXPECTED_AGENTS=(
"analyzer" "interviewer" "plugin-advisor" "readme-updater"
"refactorer" "scaffolder" "onboarder" "status-reporter"
)
MISSING_AGENTS=()
for agent in "${EXPECTED_AGENTS[@]}"; do
if [ ! -f "$HOME/.claude/agents/${agent}.md" ]; then
MISSING_AGENTS+=("${agent}.md")
fi
done
if [ ${#MISSING_AGENTS[@]} -eq 0 ]; then
pass "All 8 agents present (analyzer, interviewer, plugin-advisor, readme-updater, refactorer, scaffolder, onboarder, status-reporter)"
else
warn "Missing agents: ${MISSING_AGENTS[*]} — run: bash link.sh"
fi
# Check CRLF — portable: grep -P not available on macOS BSD grep
CRLF_FILES=()
for f in "$REPO"/*.md "$REPO"/agents/*.md "$REPO"/skills/*/SKILL.md; do
[ -f "$f" ] || continue
if grep -qP '\r' "$f" 2>/dev/null; then
if grep -c $'\r' "$f" 2>/dev/null | grep -q "^[^0]"; then
CRLF_FILES+=("$(basename "$f")")
fi
done

75
hooks/session-start.sh
View File

@ -38,12 +38,8 @@ if [ -f "$_lib" ]; then
# shellcheck source=../lib/detect-plugins.sh
source "$_lib"
else
# Fallback: inline detection if lib is missing
detect_gstack() { [ -d "$HOME/.claude/skills/gstack" ]; }
detect_gsd() { ls "$HOME/.claude/skills/" 2>/dev/null | grep -qi "gsd"; }
detect_uiux_pro_max() { ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "ui-ux-pro-max"; }
detect_frontend_design() { ls "$HOME/.claude/plugins/cache/" 2>/dev/null | grep -qi "frontend-design"; }
detect_context7() { claude mcp list 2>/dev/null | grep -q "context7"; }
echo "⚠️ lib/detect-plugins.sh not found — config broken, run: bash link.sh"
exit 0
fi
unset _lib
@ -52,7 +48,7 @@ unset _lib
TOGGLE_ACTIVE=()
TOGGLE_INACTIVE=()
for plugin in gstack gsd uiux_pro_max frontend_design context7; do
for plugin in gstack uiux_pro_max frontend_design context7 ruflo; do
# Map function name to display name
case "$plugin" in
uiux_pro_max) display="ui-ux-pro-max" ;;
@ -71,6 +67,13 @@ done
ACTIVE_STR="${TOGGLE_ACTIVE[*]:-none}"
INACTIVE_STR="${TOGGLE_INACTIVE[*]:-none}"
# GSD v2 — standalone CLI (not a Claude Code plugin — shown separately)
if detect_gsd 2>/dev/null; then
GSD_STATUS="gsd v2 ✓"
else
GSD_STATUS="gsd v2 ✗ (npm install -g gsd-pi)"
fi
# Version detection: follow CLAUDE.md symlink back to repo, then read version.txt
_claude_real="$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null || true)"
if [ -n "$_claude_real" ]; then
@ -81,11 +84,63 @@ else
fi
unset _claude_real _repo_dir
# Quick passive token cost estimate (Pro session budget = ~11k tokens)
_passive_t=0
detect_superpowers 2>/dev/null && _passive_t=$((_passive_t + 800))
detect_gstack 2>/dev/null && _passive_t=$((_passive_t + 2750))
detect_frontend_design 2>/dev/null && _passive_t=$((_passive_t + 200))
detect_uiux_pro_max 2>/dev/null && _passive_t=$((_passive_t + 400))
detect_context7 2>/dev/null && _passive_t=$((_passive_t + 200))
detect_ruflo 2>/dev/null && _passive_t=$((_passive_t + 1000))
_budget_pct=$((_passive_t * 100 / 11000))
if [ "$_budget_pct" -gt 50 ]; then
TOKEN_WARN="⚠️ ~${_passive_t}t passif (${_budget_pct}% budget)"
elif [ "$_budget_pct" -gt 25 ]; then
TOKEN_WARN="~${_passive_t}t passif (${_budget_pct}% budget)"
else
TOKEN_WARN=""
fi
unset _passive_t _budget_pct
echo ""
echo "┌─ Toggle plugins ──────────────────────────────────┐"
printf "│ 🟢 ON : %-40s│\n" "$ACTIVE_STR"
printf "│ ⚫ OFF : %-40s│\n" "$INACTIVE_STR"
echo "┌─ Claude Code config ──────────────────────────────────┐"
printf "│ ✅ ON : %-40s│\n" "security-guidance rtk superpowers"
# Plugin display — all plugins shown, split across 2 lines if >4
_active_count=${#TOGGLE_ACTIVE[@]}
_inactive_count=${#TOGGLE_INACTIVE[@]}
if [ "$_active_count" -eq 0 ]; then
printf "│ 🟢 ON : %-40s│\n" "none"
elif [ "$_active_count" -le 4 ]; then
printf "│ 🟢 ON : %-40s│\n" "$ACTIVE_STR"
else
# Split: first 4 on line 1, rest on continuation line
_line1="${TOGGLE_ACTIVE[0]} ${TOGGLE_ACTIVE[1]} ${TOGGLE_ACTIVE[2]} ${TOGGLE_ACTIVE[3]}"
_rest=("${TOGGLE_ACTIVE[@]:4}")
_line2="${_rest[*]}"
printf "│ 🟢 ON : %-40s│\n" "$_line1"
printf "│ %-40s│\n" "$_line2"
unset _line1 _line2 _rest
fi
if [ "$_inactive_count" -eq 0 ]; then
printf "│ ⚫ OFF : %-40s│\n" "none"
elif [ "$_inactive_count" -le 4 ]; then
printf "│ ⚫ OFF : %-40s│\n" "$INACTIVE_STR"
else
_line1="${TOGGLE_INACTIVE[0]} ${TOGGLE_INACTIVE[1]} ${TOGGLE_INACTIVE[2]} ${TOGGLE_INACTIVE[3]}"
_rest=("${TOGGLE_INACTIVE[@]:4}")
_line2="${_rest[*]}"
printf "│ ⚫ OFF : %-40s│\n" "$_line1"
printf "│ %-40s│\n" "$_line2"
unset _line1 _line2 _rest
fi
unset _active_count _inactive_count
printf "│ 🖥️ CLI : %-40s│\n" "$GSD_STATUS"
[ -n "$TOKEN_WARN" ] && printf "│ 💰 %-44s│\n" "${TOKEN_WARN:0:44}"
printf "│ 📦 v%-45s│\n" "$CONFIG_VERSION"
echo "│ 💡 /plugin-check before starting a new project │"
echo "│ 🩺 /health to run full diagnostic │"
echo "└───────────────────────────────────────────────────┘"
echo ""
unset TOKEN_WARN

122
install-plugins.sh
View File

@ -18,7 +18,12 @@ REPO="$(cd "$(dirname "$0")" && pwd)"
# Log to file for post-mortem debugging (terminal output unchanged)
LOG_FILE="$REPO/install-$(date +%Y%m%d-%H%M%S).log"
exec > >(tee -a "$LOG_FILE") 2>&1
if touch "$LOG_FILE" 2>/dev/null; then
exec > >(tee -a "$LOG_FILE") 2>&1
info "Logging to $LOG_FILE"
else
warn "Cannot write log to $REPO — continuing without log file"
fi
# Load shared detection library
# shellcheck source=lib/detect-plugins.sh
@ -179,7 +184,15 @@ fi
if [ -d "$GSTACK_DIR" ]; then
info "Running GStack setup..."
cd "$GSTACK_DIR" && ./setup && cd - > /dev/null
if [ -x "$GSTACK_DIR/setup" ]; then
if (cd "$GSTACK_DIR" && ./setup) 2>/dev/null; then
: # setup succeeded
else
warn "GStack ./setup failed — submodule present but setup incomplete"
fi
else
warn "GStack ./setup not found or not executable — skipping"
fi
# Symlinks are handled by link.sh — verify it was run
if [ -L "$HOME/.claude/skills/gstack" ]; then
ok "GStack ready (submodule initialized, symlink OK)"
@ -209,34 +222,77 @@ else
cargo install --git https://github.com/rtk-ai/rtk
fi
fi
info "Configuring RTK PreToolUse hook (global)..."
rtk init -g --auto-patch
ok "RTK configured"
echo ""
# ============================================================
# STEP 4 — GSD
# ============================================================
echo "── Step 4: GSD — get-shit-done ─────────────────────────────"
echo ""
info "Installing GSD globally..."
GSD_VER=$(pinned_version "gsd")
if [ "$GSD_VER" != "latest" ]; then
info "Version $GSD_VER (pinned in plugins.lock.json)"
npx "get-shit-done-cc@$GSD_VER" --claude --global --auto
# Only init if not already configured (avoids overwriting custom RTK config)
if ! grep -q "rtk" "$HOME/.claude/settings.json" 2>/dev/null; then
info "Configuring RTK PreToolUse hook (global)..."
rtk init -g --auto-patch
ok "RTK configured"
else
info "Version: latest (consider pinning in plugins.lock.json)"
npx get-shit-done-cc --claude --global --auto
ok "RTK hook already present in settings.json — skipping init"
fi
ok "GSD installed"
echo ""
# ============================================================
# STEP 5 — MARKETPLACE PLUGINS (user scope, explicit)
# STEP 4 — GSD v2
# ============================================================
# GSD v2 (gsd-pi) is a standalone CLI built on the Pi SDK.
# It is NOT a Claude Code plugin — it runs as an external process ('gsd' command).
# Usage: run 'gsd' in your terminal from a project directory.
# Slash commands (/gsd auto, /gsd status, etc.) are internal to a GSD session.
echo "── Step 4: GSD v2 — gsd-pi ─────────────────────────────────"
echo ""
if command -v gsd &>/dev/null; then
ok "gsd already installed ($(gsd --version 2>/dev/null | head -1 || echo 'installed'))"
else
GSD_VER=$(pinned_version "gsd")
if [ "$GSD_VER" != "latest" ]; then
info "Installing gsd-pi@${GSD_VER} (pinned in plugins.lock.json)..."
npm install -g "gsd-pi@${GSD_VER}"
else
info "Installing gsd-pi@latest (consider pinning in plugins.lock.json)..."
npm install -g gsd-pi
fi
command -v gsd &>/dev/null && ok "GSD v2 installed ($(gsd --version 2>/dev/null | head -1))" \
|| err "GSD v2 install failed — check npm output above"
fi
echo ""
# ============================================================
# STEP 5 — RUFLO MCP (manual — requires npm install + MCP config)
# ============================================================
# Ruflo is an enterprise multi-agent orchestration MCP server (formerly claude-flow).
# 310+ MCP tools, 100+ agent types, WASM kernel, self-learning architecture.
# Use only for projects requiring complex multi-agent coordination.
# Default install ~340MB. Minimal: npm install -g ruflo@latest --omit=optional (~15s)
echo "── Step 5: Ruflo MCP ────────────────────────────────────────"
echo ""
if detect_ruflo; then
ok "Ruflo MCP already configured"
else
warn "Ruflo requires manual setup — cannot auto-install (enterprise tool)"
echo ""
echo " Steps:"
echo " 1. Install the package:"
echo " npm install -g ruflo@latest # full (~340MB)"
echo " npm install -g ruflo@latest --omit=optional # minimal"
echo ""
echo " 2. Register as MCP server in Claude Code:"
echo " claude mcp add --scope user ruflo -- npx ruflo mcp start"
echo ""
echo " 3. Verify:"
echo " claude mcp list | grep ruflo"
echo ""
echo " Or use the automated installer:"
echo " curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --full"
echo ""
fi
# ============================================================
# STEP 6 — MARKETPLACE PLUGINS (user scope, explicit)
# ============================================================
# All claude plugin install commands use --scope user to ensure
# they install to ~/.claude/plugins/ regardless of working directory.
echo "── Step 5: Marketplace plugins (scope: user) ────────────────"
echo "── Step 6: Marketplace plugins (scope: user) ────────────────"
echo ""
install_plugin() {
@ -273,7 +329,7 @@ echo ""
# ============================================================
# STEP 6 — CONTEXT7 MCP (manual — requires API key)
# ============================================================
echo "── Step 6: Context7 MCP ─────────────────────────────────────"
echo "── Step 7: Context7 MCP ─────────────────────────────────────"
echo ""
if claude mcp list 2>/dev/null | grep -q "context7"; then
ok "Context7 MCP already configured"
@ -281,7 +337,7 @@ else
warn "Context7 requires a free API key — cannot auto-install"
echo ""
echo " Steps:"
echo " 1. Get a free key at https://context7.com"
echo " 1. Get a free key at https://upstash.com"
echo " 2. Run:"
echo " claude mcp add --scope user context7 -- \\"
echo " npx -y @upstash/context7-mcp --api-key YOUR_KEY"
@ -296,23 +352,23 @@ echo "╔═══════════════════════
echo "║ Install Summary ║"
echo "╚══════════════════════════════════════════════════════════╝"
echo ""
echo " ALWAYS ON (installed at user scope, ~10 tokens/session each):"
echo " ALWAYS ON (installed at user scope):"
echo " ✅ security-guidance — PreToolUse security hook (0 tokens)"
echo " ✅ rtk — token compression hook (0 tokens)"
echo " ✅ superpowers — brainstorm/plan/implement/debug workflow"
echo " ✅ skill-creator — create skills from conversation"
echo " ✅ pr-review-toolkit — /pr-review-toolkit:review-pr"
echo ""
echo " TOGGLE (installed but start OFF — /plugin-check recommends when needed):"
echo " 🔄 gstack — ~/.claude/skills/gstack/ (→ submodule)"
echo " 🔄 gsd — ~/.claude/skills/ (npx)"
echo " 🔄 frontend-design — user scope"
echo " 🔄 ui-ux-pro-max — user scope"
echo " 🔄 context7 MCP — see Step 6 above"
echo " 🔄 gsd v2 — standalone CLI 'gsd' (gsd-pi, not a Claude Code plugin)"
echo " 🔄 skill-creator — create skills from conversation (~100 tokens)"
echo " 🔄 pr-review-toolkit — /pr-review-toolkit:review-pr (~300 tokens)"
echo " 🔄 frontend-design — user scope (~200 tokens)"
echo " 🔄 ui-ux-pro-max — user scope (~400 tokens)"
echo " 🔄 context7 MCP — see Step 7 above (~200 tokens)"
echo " 🔄 ruflo MCP — see Step 5 above (~500-1500 tokens, enterprise only)"
echo ""
echo " All plugins installed at: user scope (~/.claude/plugins/)"
echo " GStack at: ~/.claude/skills/gstack/ (symlink → submodule)"
echo ""
echo " → Restart Claude Code"
echo " → Run /reload-plugins"
echo " → Restart Claude Code — plugins load automatically"
echo ""

42
lib/detect-plugins.sh
View File

@ -24,20 +24,6 @@ detect_superpowers() {
return 1
}
detect_security_guidance() {
local cache_dir="$HOME/.claude/plugins/cache"
[ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "security-guidance"
}
detect_skill_creator() {
local cache_dir="$HOME/.claude/plugins/cache"
[ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "skill-creator"
}
detect_pr_review_toolkit() {
local cache_dir="$HOME/.claude/plugins/cache"
[ -d "$cache_dir" ] && ls "$cache_dir" 2>/dev/null | grep -qi "pr-review-toolkit"
}
# --- Toggle plugins ---
@ -46,7 +32,9 @@ detect_gstack() {
}
detect_gsd() {
ls "$HOME/.claude/skills/" 2>/dev/null | grep -qi "gsd"
# GSD v2 (gsd-pi) is a standalone CLI, not a Claude Code plugin.
# Detection: check for 'gsd' binary in PATH.
command -v gsd &>/dev/null
}
detect_frontend_design() {
@ -60,5 +48,27 @@ detect_uiux_pro_max() {
}
detect_context7() {
claude mcp list 2>/dev/null | grep -q "context7"
# Fast check: read ~/.claude.json (MCP config) without spawning the claude CLI
local cfg="$HOME/.claude.json"
if [ -f "$cfg" ]; then
grep -q "context7" "$cfg" 2>/dev/null && return 0
fi
# Fallback: ~/.mcp.json (project-scoped MCP config at user level)
local mcp="$HOME/.mcp.json"
if [ -f "$mcp" ]; then
grep -q "context7" "$mcp" 2>/dev/null && return 0
fi
return 1
}
detect_ruflo() {
# 1. Fast: check npm global binary
command -v ruflo &>/dev/null && return 0
# 2. Fast: check MCP config files (ruflo or ruvnet/claude-flow variants)
for _cfg in "$HOME/.claude.json" "$HOME/.mcp.json"; do
[ -f "$_cfg" ] && grep -qi "ruflo\|ruvnet\|claude-flow" "$_cfg" 2>/dev/null && return 0
done
# 3. Slow fallback: claude mcp list (only if fast checks fail, spawns subprocess)
command -v claude &>/dev/null && claude mcp list 2>/dev/null | grep -qi "ruflo" && return 0
return 1
}

50
link.sh
View File

@ -1,47 +1,57 @@
#!/usr/bin/env bash
# Symlink this repo into ~/.claude/
# Run once after cloning on a new machine.
set -euo pipefail
REPO="$(cd "$(dirname "$0")" && pwd)"
CLAUDE="$HOME/.claude"
CHANGED=0
mkdir -p "$CLAUDE"
# Core config files (plain files — ln -sf handles these correctly)
ln -sf "$REPO/CLAUDE.md" "$CLAUDE/CLAUDE.md"
ln -sf "$REPO/settings.json" "$CLAUDE/settings.json"
link_file() {
local src="$1" dst="$2"
if [ -L "$dst" ] && [ "$(readlink "$dst")" = "$src" ]; then
return # already correct
fi
ln -sf "$src" "$dst"
CHANGED=$((CHANGED + 1))
}
# Agents and skills — must handle the case where target exists
# as a real directory (ln -sf would create a link INSIDE the dir
# instead of replacing it)
for item in agents skills lib; do
link_file "$REPO/CLAUDE.md" "$CLAUDE/CLAUDE.md"
link_file "$REPO/settings.json" "$CLAUDE/settings.json"
for item in agents skills lib templates; do
target="$CLAUDE/$item"
if [ -L "$target" ]; then
# Stale symlink from a previous run — remove before recreating
if [ "$(readlink "$target")" = "$REPO/$item" ]; then
continue # already correct
fi
rm -f "$target"
elif [ -d "$target" ]; then
echo "⚠️ ~/.claude/$item is a real directory (not a symlink)."
echo " Rename or remove it, then re-run link.sh."
echo " Skipping $item to avoid data loss."
echo "⚠️ ~/.claude/$item is a real directory. Rename or remove it, then re-run link.sh."
continue
fi
ln -sf "$REPO/$item" "$target"
CHANGED=$((CHANGED + 1))
done
# Hooks
mkdir -p "$CLAUDE/hooks"
ln -sf "$REPO/hooks/session-start.sh" "$CLAUDE/hooks/session-start.sh"
link_file "$REPO/hooks/session-start.sh" "$CLAUDE/hooks/session-start.sh"
# GStack (submodule) — symlink into ~/.claude/skills/ (which points to repo/skills/)
# The submodule must be initialized first (done by install-plugins.sh)
if [ -d "$REPO/skills-external/gstack" ]; then
ln -sf "$REPO/skills-external/gstack" "$CLAUDE/skills/gstack"
echo "✅ GStack symlinked from submodule"
if [ -L "$CLAUDE/skills/gstack" ] && [ "$(readlink "$CLAUDE/skills/gstack")" = "$REPO/skills-external/gstack" ]; then
: # already correct
else
ln -sf "$REPO/skills-external/gstack" "$CLAUDE/skills/gstack"
CHANGED=$((CHANGED + 1))
fi
else
echo "⚠️ GStack submodule not found — run: git submodule update --init"
fi
echo "✅ Symlinks created in ~/.claude/"
if [ "$CHANGED" -eq 0 ]; then
echo "✅ All symlinks already up to date."
else
echo "✅ $CHANGED symlink(s) updated in ~/.claude/"
fi
echo " Next: bash install-plugins.sh"

15
plugins.lock.json
View File

@ -2,23 +2,22 @@
"_readme": "Pinned versions for reproducible installs. Update versions deliberately, then run install-plugins.sh.",
"rtk": {
"source": "https://github.com/rtk-ai/rtk",
"install_cmd": "cargo install --git https://github.com/rtk-ai/rtk --tag {version}",
"version": "v0.34.3",
"note": "Check latest at https://github.com/rtk-ai/rtk/releases before updating"
},
"gsd": {
"source": "npm:get-shit-done-cc",
"install_cmd": "npx get-shit-done-cc@{version} --claude --global --auto",
"version": "1.30.0",
"note": "Check latest at https://www.npmjs.com/package/get-shit-done-cc before updating"
"source": "npm:gsd-pi",
"version": "2.64.0",
"note": "Check latest at https://www.npmjs.com/package/gsd-pi before updating. GSD v2 is a standalone CLI (Pi SDK), not a Claude Code plugin. Run 'gsd' in terminal, not '/gsd' in Claude Code."
},
"gstack": {
"source": "https://github.com/garrytan/gstack.git",
"managed_by": "git submodule",
"note": "Version controlled by submodule pointer in .gitmodules. Update: git submodule update --remote"
},
"node": {
"minimum": "18",
"recommended": "22"
"ruflo": {
"source": "npm:ruflo",
"version": "3.5.58",
"note": "Enterprise multi-agent MCP server (formerly claude-flow). Requires manual MCP config after install. Check latest at https://www.npmjs.com/package/ruflo before updating."
}
}

41
settings.json
View File

@ -1,9 +1,9 @@
{
"_readme": "Global user settings — place at ~/.claude/settings.json. Applies to ALL projects. Never commit this file.",
"cleanupPeriodDays": 30,
"permissions": {
"defaultMode": "default",
"disableBypassPermissionsMode": "disable",
"disableAutoMode": "disable",
"deny": [
"Bash(rm -rf *)",
"Bash(rm -rf /*)",
@ -81,7 +81,30 @@
"Bash(more .env)",
"Bash(more .env.*)",
"Bash(grep * .env)",
"Bash(grep * .env.*)"
"Bash(grep * .env.*)",
"Bash(env)",
"Bash(printenv)",
"Bash(printenv *)",
"Bash(export *)",
"Bash(cp .env*)",
"Bash(cp **/.env*)",
"Bash(cp **/secrets/*)",
"Bash(mv .env*)",
"Bash(mv **/.env*)",
"Bash(mv **/secrets/*)",
"Bash(git add .env*)",
"Bash(git add **/.env*)",
"Bash(cp **/id_rsa*)",
"Bash(cp **/id_ed25519*)",
"Bash(cp **/.ssh/*)",
"Bash(source /dev/stdin)",
"Bash(mkfifo *)",
"Bash(python3 -c *)",
"Bash(node -e *)",
"Bash(xargs * .env*)",
"Bash(tar * .env*)",
"Bash(zip * .env*)",
"Bash(base64 .env*)"
],
"ask": [
"Bash(git push *)",
@ -98,8 +121,10 @@
"WebSearch",
"WebFetch",
"Bash(xargs *)",
"Bash(sed -i *)",
"Bash(sed -i'' *)"
"Bash(sed *)",
"Bash(git stash pop*)",
"Bash(git stash drop*)",
"Bash(git stash clear)"
],
"allow": [
"Bash(git status)",
@ -112,7 +137,10 @@
"Bash(git commit*)",
"Bash(git checkout *)",
"Bash(git switch *)",
"Bash(git stash*)",
"Bash(git stash)",
"Bash(git stash push*)",
"Bash(git stash list*)",
"Bash(git stash show*)",
"Bash(git tag*)",
"Bash(git show*)",
"Bash(ls *)",
@ -129,8 +157,6 @@
"Bash(pwd)",
"Bash(which *)",
"Bash(type *)",
"Bash(env)",
"Bash(printenv *)",
"Bash(whoami)",
"Bash(uname *)",
"Bash(mkdir -p *)",
@ -139,7 +165,6 @@
"Bash(mv *)",
"Bash(jq *)",
"Bash(yq *)",
"Bash(sed *)",
"Bash(awk *)",
"Bash(sort *)",
"Bash(uniq *)",

6
skills/analyze/SKILL.md
View File

@ -1,13 +1,13 @@
---
name: analyze
description: Deep factual code analysis — read-only, no solutions proposed
argument-hint: <code, file, or area to analyze>
description: Deep factual code analysis (read-only) or DEBUG mode (pass error/stack trace) — no solutions proposed, no file modifications
argument-hint: <file/area to analyze — OR paste error/stack trace for DEBUG mode>
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash
---
Load and follow strictly:
- .claude/agents/analyzer.md
- $HOME/.claude/agents/analyzer.md
Execute the ANALYZER agent on the following target:

17
skills/health/SKILL.md
View File

@ -6,13 +6,18 @@ disable-model-invocation: true
allowed-tools: Bash
---
Run the health check script and report findings to the user:
Run the health check script:
```bash
bash ~/.claude/doctor.sh
bash $HOME/.claude/doctor.sh 2>/dev/null || {
REPO=$(dirname "$(readlink "$HOME/.claude/CLAUDE.md" 2>/dev/null)" 2>/dev/null)
bash "$REPO/doctor.sh"
}
```
After displaying the output:
- If errors are found, suggest the specific fix commands shown in the output.
- If only warnings, note them but confirm the setup is functional.
- If all checks pass, confirm the setup is healthy.
After displaying the doctor.sh output:
- **CRITICAL token (>30%)** → suggest `/plugin-check` to disable unused plugins; list the heaviest ones.
- **WARNING token (>15%)** → note which toggle plugins are active and not needed.
- **Errors (symlinks, agents)** → show the exact fix command (`bash link.sh`).
- **Warnings only** → confirm setup is functional, note any action recommended.
- **All pass** → confirm healthy and operational.

395
skills/init-project/SKILL.md
View File

@ -8,343 +8,120 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
# ORCHESTRATOR: INIT PROJECT
## AGENTS AND SKILLS LOADED
Custom agents (this config):
- .claude/agents/plugin-advisor.md ← plugin configuration check
- .claude/agents/interviewer.md ← project questionnaire
- .claude/agents/analyzer.md ← risk/constraint analysis
- .claude/agents/scaffolder.md ← project skeleton (NO features, skeleton only)
Superpowers skills (design + implementation):
- superpowers:brainstorming ← architecture design
- superpowers:writing-plans ← v1 feature decomposition
- superpowers:subagent-driven-development ← isolated TDD implementation
- superpowers:requesting-code-review ← final review
- superpowers:finishing-a-development-branch ← cleanup + verification
---
## INITIAL REQUEST
## REQUEST
$ARGUMENTS
---
## WORKFLOW
## STEP 0 — PLUGIN CHECK
Load `$HOME/.claude/agents/plugin-advisor.md`. Feed request.
- ACTION REQUIRED → show RECOMMENDATIONS block, offer: A) fix plugins B) type "force". STOP.
- OK → `✅ Plugin check passed — [active plugins]`, continue.
---
### STEP 0 — PLUGIN CHECK
Load and follow: `.claude/agents/plugin-advisor.md`
Feed it the initial request above.
**If `ACTION REQUIRED: YES`:**
## STEP 1 — INTERVIEW
Before loading the interviewer, check for an existing CLAUDE.md:
```bash
ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
```
================================================================
⚠️ PLUGIN CHECK — ACTION REQUIRED
================================================================
[paste full RECOMMENDATIONS block]
----------------------------------------------------------------
A) Enable recommended plugins then re-run /init-project
B) Type "force" to proceed without them
================================================================
- **Found** (either `CLAUDE.md` or `.claude/CLAUDE.md`) → read it silently.
Pre-fill all interview answers already documented (stack, purpose, features, conventions).
Load `$HOME/.claude/agents/interviewer.md` and ask ONLY what is genuinely missing.
Print: "📄 Existing CLAUDE.md found — using as context."
- **Not found** → standard mode: load `$HOME/.claude/agents/interviewer.md`,
ask all unanswered questions.
In both cases: MANDATORY STOP until user answers remaining questions. Produce PROJECT BRIEF.
## STEP 2 — ANALYZE
Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack constraints, infra risks, open decisions. Produce ANALYSIS REPORT.
## STEP 3 — DESIGN
Invoke `superpowers:brainstorming` with BRIEF + ANALYSIS REPORT.
Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list.
## STEP 4 — VALIDATION GATE #1 ★ MANDATORY STOP
Present:
```
**STOP. Wait for user response.**
- Re-run → restart from STEP 0
- "force" → note missing plugins, continue to STEP 1
**If `ACTION REQUIRED: NO`:**
Print one line and continue:
`✅ Plugin check passed — [active plugins]`
---
### STEP 1 — INTERVIEWER
Load and follow: `.claude/agents/interviewer.md`
Identify what is already provided in the initial request.
Ask only what is genuinely missing. Single structured block of questions.
**MANDATORY STOP — do not continue until user has answered.**
Produce the PROJECT BRIEF. This is the single source of truth
for all subsequent steps.
---
### STEP 2 — ANALYZER
Load and follow: `.claude/agents/analyzer.md`
Analyze the PROJECT BRIEF:
- Existing repo or code to integrate
- Stack constraints and compatibility issues
- Infrastructure constraints
- Risks that could affect the design
- Open decisions from the PROJECT BRIEF
Produce an ANALYSIS REPORT.
---
### STEP 3 — ARCHITECTURE DESIGN
Invoke skill: `superpowers:brainstorming`
Feed it the PROJECT BRIEF + ANALYSIS REPORT.
Produce a complete DESIGN covering:
- Finalized tech stack with exact versions
- Complete folder structure (full tree)
- Module responsibilities and data flow
- Key interfaces and data models (signatures only — no implementation)
- Config and tooling setup
- Test strategy
- Any open decisions resolved with justification
- Prerequisites list (what must be installed on dev machine)
---
### STEP 4 — VALIDATION GATE #1 — ARCHITECTURE
**MANDATORY STOP — present to the user and wait for approval.**
```
================================================================
INIT PROJECT — ARCHITECTURE VALIDATION
================================================================
PROJECT SUMMARY
---------------
<3–5 line recap of what will be built>
STACK
-----
<finalized stack with versions>
PREREQUISITES TO INSTALL
-------------------------
<list of tools / runtimes / services with versions>
FOLDER STRUCTURE
----------------
<full tree from the DESIGN>
V1 FEATURES TO IMPLEMENT
-------------------------
<numbered list from PROJECT BRIEF — these will be implemented
in the pipeline AFTER the skeleton is scaffolded>
CONVENTIONS
-----------
<naming, doc style, test strategy>
EXCEPTIONS TO GLOBAL RULES
---------------------------
<list or "none">
================================================================
Approve this architecture? (yes / request changes)
================================================================
PROJECT : <3-5 line recap>
STACK : <versions>
PREREQS : <install list>
TREE : <folder tree>
V1 FEATURES: <numbered list>
CONVENTIONS: <naming, doc, test>
EXCEPTIONS : <list or none>
Approve? (yes / request changes)
```
Changes → back to STEP 3. Approved → continue.
IF changes → return to STEP 3.
IF approved → proceed.
## STEP 5 — SCAFFOLD
Load `$HOME/.claude/agents/scaffolder.md`. Pass: BRIEF + DESIGN + `~/.claude/templates/project-CLAUDE.md` + `~/.claude/CLAUDE.md`.
Creates: CLAUDE.md, settings, structure, config, empty entry points, .gitignore, .env.example. NO README, NO features.
Verify: `git init` + build passes.
---
## STEP 5b — CREATE README
Load `$HOME/.claude/agents/readme-updater.md`. README.md missing → CREATE mode auto. No stop.
### STEP 5 — SCAFFOLD SKELETON
Load and follow: `.claude/agents/scaffolder.md`
Pass to the scaffolder:
- Full PROJECT BRIEF
- Approved DESIGN
- `~/.claude/templates/project-CLAUDE.md`
- `~/.claude/CLAUDE.md`
The scaffolder creates:
1. `CLAUDE.md` — filled from global template, no placeholders
2. `.claude/settings.json` — adapted to this stack
3. `.claudeignore` — extended for this project
4. Complete folder structure
5. Config files (package.json, Cargo.toml, etc.)
6. Empty entry points and module files (structure only, no business logic)
7. `.gitignore`, `.env.example`
**The scaffolder does NOT create the README and does NOT implement any features.**
README is handled by readme-updater (STEP 5b).
Features are handled by the implementation pipeline (STEPs 6–9).
The scaffolder must verify: `git init` + build passes on empty project.
---
### STEP 5b — CREATE README
Load and follow: `.claude/agents/readme-updater.md`
Context: `README.md` does not exist yet → CREATE mode activates automatically.
The readme-updater reads `CLAUDE.md`, the folder structure, and manifests
to generate the full README (About, Prerequisites with OS-specific install
commands, Installation, Running, Project structure, Configuration, Contributing).
No stop required — prints confirmation and continues immediately.
---
### STEP 6 — PLAN V1 FEATURES
Invoke skill: `superpowers:writing-plans`
Using the PROJECT BRIEF v1 features list and the scaffolded skeleton as context:
- Break each v1 feature into granular tasks (2–5 min each)
- Each task must reference exact file paths from the scaffolded structure
- Each task must include: what to implement, expected behavior, verification steps
- Apply TDD: tests are written before implementation code
---
### STEP 7 — VALIDATION GATE #2 — IMPLEMENTATION PLAN
**MANDATORY STOP — present the plan to the user.**
## STEP 6 — PLAN
Invoke `superpowers:writing-plans` with BRIEF + skeleton.
Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
## STEP 7 — VALIDATION GATE #2 ★ MANDATORY STOP
```
================================================================
INIT PROJECT — IMPLEMENTATION PLAN VALIDATION
================================================================
SKELETON STATUS : ✅ build passes
V1 FEATURES : <N> features → <M> tasks
<numbered task list with file paths>
================================================================
Approve this plan and start implementation? (yes / request changes)
================================================================
INIT PROJECT — IMPLEMENTATION PLAN
SKELETON: ✅ build passes
FEATURES: <N> → <M> tasks
<numbered task list with paths>
Approve and start? (yes / request changes)
```
Changes → back to STEP 6. Approved → continue.
IF changes → return to STEP 6.
IF approved → proceed.
## STEP 8 — IMPLEMENT
Invoke `superpowers:subagent-driven-development`. Isolated subagents, TDD, 2-stage review per task.
---
## STEP 9 — ANALYZE
Load `$HOME/.claude/agents/analyzer.md`. Check: no regressions, no deviations, no stale scaffold, conventions respected.
### STEP 8 — IMPLEMENT V1 FEATURES
## STEP 10 — CODE REVIEW
Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding.
Invoke skill: `superpowers:subagent-driven-development`
## STEP 11 — FINISH
Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, no placeholders, initial commit ready.
Execute each task with isolated subagents.
Mandatory TDD: `superpowers:test-driven-development` applies.
Two-stage review per task: spec compliance → code quality.
## STEP 12 — SYNC README
Load `$HOME/.claude/agents/readme-updater.md` with arg `sync`. Detect drift, update cmds/vars/structure, add recent changes entry.
Each subagent works on a clean context with:
- The task description
- Relevant file paths
- PROJECT BRIEF context
- CLAUDE.md conventions
---
### STEP 9 — ANALYZE
Load and follow: `.claude/agents/analyzer.md`
Run the ANALYZER on the completed implementation:
- Verify no regressions
- Verify no plan deviations
- Verify no stale scaffold code left (empty files not yet populated)
- Verify conventions are respected
---
### STEP 10 — CODE REVIEW
Invoke skill: `superpowers:requesting-code-review`
Full review scope:
- Code quality vs CLAUDE.md conventions and global rules
- Security issues
- Missing or incomplete v1 features
- README accuracy
- Generated CLAUDE.md completeness (no placeholder remaining)
- Test coverage
Fix all CRITICAL issues before proceeding.
---
### STEP 11 — FINISH
Invoke skill: `superpowers:finishing-a-development-branch`
Verify:
- All tests pass
- Build is clean
- No leftover scaffold placeholders
- Initial commit prepared
---
### STEP 12 — SYNC README
Load and follow: `.claude/agents/readme-updater.md`
Context: call with argument "sync".
SYNC mode — no stop required. The readme-updater:
- Detects any drift between README and the implemented code
- Updates commands, env vars, folder structure if changed during implementation
- Adds a `## Recent changes` entry summarizing v1 features
- Prints one-line confirmation
## STEP 13 — GSD v2 INIT (optional)
If `multi-session` signal was detected in STEP 0 OR the project has >3 planned milestones:
Ask: "Initialize GSD v2 for multi-session management? (yes / skip)"
- `yes` →
1. First check: `command -v gsd` — if not found:
Print: "⚠️ GSD v2 not installed. Run `npm install -g gsd-pi` then re-run `/onboard add gsd` or `/ship-feature` to initialize later."
Do NOT attempt `gsd init`. Skip to RULES.
2. If `gsd` is in PATH: run `gsd init` in the project directory to create `.gsd/` and `ROADMAP.md`.
Populate ROADMAP.md with milestones from BRIEF (v1 features + any beyond-v1 items).
Print: "✅ GSD v2 initialized — run `gsd` in terminal then `/gsd auto` to work autonomously."
- `skip` → print: "GSD v2 skipped — use `/ship-feature` for individual features."
---
## RULES
- Never skip STEP 0 — plugin check is mandatory.
- Never skip STEP 1 — no assumptions about missing info.
- Never implement without explicit user approval at STEP 4.
- Never implement without explicit user approval at STEP 7.
- The scaffolder only creates the skeleton — zero business logic.
- All feature implementation goes through the subagent pipeline (STEP 8).
- Apply CLAUDE.md norms throughout.
- A broken skeleton or a broken build is not acceptable output.
- No skipping steps. No merged agent responsibilities.
- No implement without user approval at STEP 4 and STEP 7.
- Scaffolder = skeleton only, zero logic.
- Features → subagent pipeline only.
- Broken build = unacceptable output.
- Fix all CRITICAL review issues before proceeding.
- Stop if requirements unclear at any step.
---
## FINAL OUTPUT
```
================================================================
PROJECT INITIALIZED: <project name>
================================================================
LOCATION : <project root>
STACK : <finalized stack>
BUILD : ✅ / ❌ <e>
TESTS : ✅ <N> passing / ❌ <detail>
V1 FEATURES
-----------
✅ <feature>
✅ <feature>
⚠️ <feature> — partial: <reason>
REMAINING ISSUES
----------------
<IMPORTANT and MINOR issues, or "none">
QUICK START
-----------
<exact commands to run the project right now>
CLAUDE.md : ✅ complete
README.md : ✅ created (STEP 5b) + synced (STEP 12)
SETTINGS : ✅ .claude/settings.json + .claudeignore generated
================================================================
PROJECT INITIALIZED: <n>
LOCATION: <path> | STACK: <stack> | BUILD: ✅/❌ | TESTS: ✅<N>/❌
V1 FEATURES: ✅<f> / ⚠️<f> partial: <reason>
REMAINING ISSUES: <list or none>
QUICK START: <exact cmds>
CLAUDE.md ✅ | README ✅ | SETTINGS ✅
```

15
skills/onboard/SKILL.md Normal file
View File

@ -0,0 +1,15 @@
---
name: onboard
description: Onboard an existing project into claude-config — generates CLAUDE.md, settings, .claudeignore, optional GSD v2 ROADMAP. Use on repos not created via /init-project.
argument-hint: [optional hints: "Python FastAPI" | "add gsd" | "Next.js monorepo"]
disable-model-invocation: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
Load and follow strictly:
- $HOME/.claude/agents/onboarder.md
Run the ONBOARDER agent on the current working directory.
Additional hints from user (if any):
$ARGUMENTS

4
skills/plugin-check/SKILL.md
View File

@ -1,13 +1,13 @@
---
name: plugin-check
description: Audit active plugins vs project needs. Recommends enable/disable actions.
argument-hint: [project description or feature to build]
argument-hint: [ex: "React + FastAPI" or "Rust CLI, no frontend"]
disable-model-invocation: true
allowed-tools: Read, Bash, Glob, Grep
---
Load and follow strictly:
- .claude/agents/plugin-advisor.md
- $HOME/.claude/agents/plugin-advisor.md
Analyze active plugins and the following context,
then produce the full PLUGIN ADVISOR REPORT:

2
skills/readme/SKILL.md
View File

@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---
Load and follow strictly:
- .claude/agents/readme-updater.md
- $HOME/.claude/agents/readme-updater.md
Execute the README UPDATER on this project.

2
skills/refactor/SKILL.md
View File

@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---
Load and follow strictly:
- .claude/agents/refactorer.md
- $HOME/.claude/agents/refactorer.md
Execute the REFACTORER agent on the following target:

224
skills/ship-feature/SKILL.md
View File

@ -8,176 +8,112 @@ allowed-tools: Read, Write, Edit, Bash, Grep, Glob
# ORCHESTRATOR: SHIP FEATURE
## AGENTS AND SKILLS LOADED
Custom agents (this config):
- .claude/agents/plugin-advisor.md ← plugin configuration check
- .claude/agents/analyzer.md ← post-implementation verification
Superpowers skills:
- superpowers:brainstorming
- superpowers:writing-plans
- superpowers:subagent-driven-development
- superpowers:requesting-code-review
- superpowers:finishing-a-development-branch
---
## FEATURE REQUEST
## REQUEST
$ARGUMENTS
---
## WORKFLOW
---
### STEP 0 — PLUGIN CHECK (mandatory gate)
Load and follow: `.claude/agents/plugin-advisor.md`
Feed it the feature request above as context for signal detection.
The advisor will:
1. Detect which plugins are currently active
2. Analyze the feature description for signals
3. Produce a recommendation table
**If the advisor output says `ACTION REQUIRED: YES`:**
Print this block and STOP COMPLETELY:
## STEP 0 — PLUGIN CHECK
Load `$HOME/.claude/agents/plugin-advisor.md`. Feed request.
- ACTION REQUIRED → show RECOMMENDATIONS, offer: A) fix plugins B) type "force". STOP.
- OK → `✅ Plugin check passed — [active plugins]`, continue.
## STEP 0b — PROJECT CONTEXT CHECK
Verify the project has a `CLAUDE.md` and print a brief orientation summary:
```bash
ls CLAUDE.md .claude/CLAUDE.md 2>/dev/null | head -1
git branch --show-current 2>/dev/null || echo "not a git repo"
git log --oneline -3 --format="%h %<(50,trunc)%s" 2>/dev/null || true
ls .gsd/ROADMAP.md 2>/dev/null | head -1
```
================================================================
⚠️ PLUGIN CHECK — ACTION REQUIRED
================================================================
- **CLAUDE.md found** → read it silently, then print orientation header (informational, not a gate):
```
📋 PROJECT CONTEXT
Project : <name from CLAUDE.md>
Stack : <stack from CLAUDE.md>
Branch : <current git branch>
Recent : <last 3 commit messages>
GSD : <current milestone if .gsd/ROADMAP.md exists, else "not initialized">
```
Continue to STEP 1.
- **Not found** →
Print: "⚠️ No CLAUDE.md found in this directory.
This project has not been onboarded into claude-config.
Run `/onboard` first to generate CLAUDE.md and project settings,
then re-run `/ship-feature`."
STOP.
[paste the full RECOMMENDATIONS block from the advisor]
## STEP 1 — BRAINSTORM
Invoke `superpowers:brainstorming`. Refine request into validated design via Socratic questioning. Don't proceed until design approved.
----------------------------------------------------------------
Options:
A) Enable the recommended plugins, then re-run /ship-feature
B) Type "force" to proceed without the recommended plugins
(you will miss capabilities — see warnings above)
================================================================
## STEP 2 — PLAN
Invoke `superpowers:writing-plans`. Break design into tasks (2-5 min each). Each task: exact file paths, full code, verification steps.
## STEP 3 — VALIDATION GATE ★ MANDATORY STOP
```
Wait for user response.
- If user re-runs `/ship-feature` → start from STEP 0 again
- If user types "force" → note missing plugins and continue to STEP 1
**If the advisor output says `ACTION REQUIRED: NO`:**
Print one line and continue immediately:
```
✅ Plugin check passed — [active plugins in one line]
```
---
### STEP 1 — BRAINSTORM
Invoke skill: `superpowers:brainstorming`
Refine the feature request into a validated design through
Socratic questioning. Do not proceed until the design is approved.
---
### STEP 2 — PLAN
Invoke skill: `superpowers:writing-plans`
Break the approved design into granular tasks (2–5 min each).
Each task must have: exact file paths, complete code, verification steps.
---
### STEP 3 — VALIDATION GATE
**MANDATORY STOP — present the plan to the user.**
```
================================================================
SHIP FEATURE — VALIDATION GATE
================================================================
FEATURE : <name>
TASKS : <count>
FEATURE: <n> | TASKS: <count>
<numbered task list>
================================================================
Approve and execute? (yes / request changes)
================================================================
```
Changes → back to STEP 2. Approved → continue.
IF changes → return to STEP 2.
IF approved → proceed.
## STEP 4 — IMPLEMENT
Invoke `superpowers:subagent-driven-development`. Isolated subagents. 2-stage review per task: spec compliance → code quality.
---
## STEP 4b — ERROR RECOVERY (if STEP 4 fails)
If a subagent returns a build error, failing test, or type error:
1. Load `$HOME/.claude/agents/analyzer.md` in DEBUG MODE on the exact error output.
Produce: root cause hypotheses (ordered), affected files, what NOT to touch.
2. Present gate:
```
SHIP FEATURE — ERROR IN STEP 4
TASK : <task name that failed>
ERROR : <one-line summary>
HYPOTHESES:
1. [HIGH] <cause> — evidence: <…>
2. [MED] <cause> — evidence: <…>
OPTIONS :
A) Apply fix for hypothesis 1 and re-run this task
B) Skip this task and continue with remaining tasks
C) Abort feature — preserve work done so far
```
3. Wait for user choice. Do NOT auto-fix. Do NOT proceed without explicit approval.
4. If A → apply minimal fix, re-run STEP 4 for the failed task only. Max 2 retry attempts.
If still failing after 2 → fall back to options B or C.
If B → before skipping: scan remaining task list for tasks that depend on the failed task
(look for references to the same file or function in subsequent tasks).
If dependents found → present: "Tasks [N, M] depend on the skipped task.
Skip them too? (yes / keep and accept partial implementation)"
If no dependents → skip cleanly and continue.
### STEP 4 — IMPLEMENT
Invoke skill: `superpowers:subagent-driven-development`
## STEP 5 — ANALYZE
Load `$HOME/.claude/agents/analyzer.md`. Check: no regressions, no stale code, no plan deviations.
Execute each task with isolated subagents.
Two-stage review per task: spec compliance → code quality.
## STEP 6 — CODE REVIEW
Invoke `superpowers:requesting-code-review`. Fix all CRITICAL before proceeding.
---
## STEP 7 — FINISH
Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, ready to merge.
### STEP 5 — ANALYZE (custom)
Load and follow: `.claude/agents/analyzer.md`
Run the ANALYZER on the produced implementation.
Verify no regressions, no stale code, no plan deviations.
---
### STEP 6 — CODE REVIEW
Invoke skill: `superpowers:requesting-code-review`
Dispatch the code-reviewer agent on the full implementation.
Fix any CRITICAL issues before proceeding.
---
### STEP 7 — FINISH BRANCH
Invoke skill: `superpowers:finishing-a-development-branch`
Verify all tests pass, cleanup, prepare for merge.
---
### STEP 8 — SYNC README
Load and follow: `.claude/agents/readme-updater.md`
Context: call with argument "sync".
SYNC mode — no stop required. The readme-updater:
- Detects any drift between README and the new feature
- Updates commands, env vars, folder structure if changed
- Adds a `## Recent changes` entry with the shipped feature
- Prints one-line confirmation
## STEP 8 — SYNC README
Load `$HOME/.claude/agents/readme-updater.md` with arg `sync`. Update cmds/vars/structure, add recent changes entry.
---
## RULES
- Never skip STEP 0 — plugin check is mandatory.
- Never skip brainstorming.
- Never implement without explicit user approval of the plan.
- Keep subagents isolated — no shared context between tasks.
- Apply CLAUDE.md norms throughout.
- No skipping steps. No merged agent responsibilities.
- No implement without user approval at STEP 3.
- Subagents isolated — no shared context between tasks.
- Fix all CRITICAL review issues before proceeding.
- Stop if requirements unclear at any step.
- STEP 4 errors → STEP 4b gate required before any fix. Never auto-patch a failing subagent.
---
## FINAL OUTPUT
```
================================================================
FEATURE SHIPPED: <name>
================================================================
TASKS COMPLETED : <N>/<N>
TESTS : ✅ passing / ❌ <detail>
REVIEW : APPROVED / CHANGES REQUIRED
REMAINING ISSUES (IMPORTANT/MINOR):
- <issue or "none">
================================================================
FEATURE SHIPPED: <n>
TASKS: <N>/<N> | TESTS: ✅/❌ | REVIEW: APPROVED/CHANGES REQUIRED
REMAINING ISSUES: <list or none>
```

14
skills/status/SKILL.md Normal file
View File

@ -0,0 +1,14 @@
---
name: status
description: Consolidated project snapshot — plugins active, token cost, git state, recent commits, GSD v2 milestone progress. Read-only. Run at session start or after a break.
argument-hint: (no arguments needed)
disable-model-invocation: true
allowed-tools: Read, Bash, Glob, Grep
---
Load and follow strictly:
- $HOME/.claude/agents/status-reporter.md
Produce the full PROJECT STATUS report for the current working directory.
$ARGUMENTS

65
templates/project-CLAUDE.md
View File

@ -1,74 +1,105 @@
# <PROJECT NAME> — CLAUDE.md
# This file was generated by /init-project.
# It is the single source of truth for Claude in this repository.
# Global rules live in ~/.claude/CLAUDE.md — this file extends or
# overrides them for this specific project.
# Generated by /init-project. Single source of truth for Claude in this repo.
# Global rules: ~/.claude/CLAUDE.md — this file extends or overrides them.
---
## Project overview
<!-- FILL: 2–4 sentences. What does this project do and for whom. -->
<!-- What it does and for whom. 2-4 sentences. -->
<!-- Ex: REST API for managing food delivery orders. Exposes CRUD endpoints consumed by a React frontend. Single-tenant, deployed on a VPS via Docker Compose. -->
---
## Stack
<!-- FILL: language + version, framework, runtime, database, key services -->
<!-- language+version, framework, runtime, database, key services -->
<!-- Ex: Python 3.12 / FastAPI / PostgreSQL 16 / Redis 7 / Docker Compose -->
---
## Build commands
<!-- FILL: exact commands to build the project -->
<!-- Exact commands — native and Docker if applicable -->
<!-- Ex:
Native : uvicorn src.main:app --reload
Docker : docker compose up --build
Build : docker build -t myapp .
-->
---
## Test commands
<!-- FILL: exact commands to run tests -->
<!-- Ex: pytest src/tests/ -v --cov=src -->
---
## Lint / format commands
<!-- FILL: exact commands, or N/A -->
<!-- Ex: ruff check . && black --check . && mypy src/ -->
<!-- Or: N/A -->
---
## Folder structure
<!-- FILL: actual tree of the project -->
<!-- Actual tree — fill after scaffolding -->
<!-- Ex:
src/
main.py — app init, lifespan hooks
routes/ — one file per resource
models/ — SQLAlchemy models
schemas/ — Pydantic schemas
services/ — business logic
tests/
conftest.py
test_orders.py
-->
---
## Architecture
<!-- FILL: module responsibilities, data flow, key design decisions -->
<!-- Module responsibilities, data flow, key design decisions -->
<!-- Ex: Request → router → service (business logic) → repository (DB) → response.
Auth: JWT validated in a FastAPI dependency injected at router level. -->
---
## Project conventions
<!-- FILL: naming style, file organization, patterns specific to this project -->
<!-- Naming, file organization, patterns specific to this project -->
<!-- Ex: snake_case everywhere. Route files named after the resource (orders.py, users.py).
All DB access goes through repository classes, never direct in routes. -->
---
## Exceptions to global rules
<!-- FILL: explicit overrides of ~/.claude/CLAUDE.md, or write "none — global rules apply" -->
<!-- Explicit overrides of ~/.claude/CLAUDE.md, or: -->
<!-- none — global rules apply -->
---
## Key dependencies
<!-- FILL: library name — purpose, one line each -->
<!-- library — purpose, one line each -->
<!-- Ex:
fastapi — web framework
sqlalchemy — ORM
alembic — DB migrations
pydantic — validation/serialization
pytest — test framework
ruff — linter
-->
---
## Workflow expectations
<!-- FILL: how Claude should behave in this repo:
e.g. always run tests after modification, never modify unrelated files,
ask before large refactors, etc. -->
<!-- How Claude should behave in this repo -->
<!-- Ex: Always run pytest after any model/service change.
Never modify migration files — generate new ones with alembic revision.
Ask before touching the auth dependency or JWT logic. -->

106
templates/settings/SETTINGS.md
View File

@ -1,69 +1,4 @@
# Claude Code — Settings Reference
## Where each file goes
```
~/.claude/
├── settings.json ← home-settings.json (renamed) — global, NEVER commit
│
mon-projet/
└── .claude/
├── settings.json ← settings.json — project rules, commit to git
└── settings.local.json← settings.local.json — personal, gitignored
```
Add to your project `.gitignore`:
```
.claude/settings.local.json
```
---
## Precedence (highest → lowest)
```
managed-settings.json system-wide, cannot be overridden
└── CLI flags --allowedTools, --disallowedTools (session only)
└── settings.local.json personal local
└── settings.json project (team)
└── ~/.claude/settings.json global user
```
**DENY always wins over ALLOW, regardless of level.**
---
## What goes where
| Rule type | File |
|---|---|
| Deny secrets, SSH, rm -rf, sudo | `~/.claude/settings.json` |
| Deny git push --force, curl\|bash | `~/.claude/settings.json` |
| Ask git push, docker run, deploy | `~/.claude/settings.json` |
| Ask package managers (brew, apt) | `~/.claude/settings.json` |
| Allow git read-only, ls, cat, grep | `~/.claude/settings.json` |
| Allow npm/cargo/make/pytest... | `.claude/settings.json` (project) |
| Ask psql, mysql, redis-cli | `.claude/settings.json` (project) |
| Allow specific WebFetch domains | `.claude/settings.local.json` |
| Personal additionalDirectories | `.claude/settings.local.json` |
---
## defaultMode values
| Value | Behavior | When to use |
|---|---|---|
| `default` | Prompts on first use of each tool | Normal development |
| `acceptEdits` | Auto-accepts file edits, prompts for Bash | Trusting sessions |
| `plan` | Read-only — Claude plans, cannot execute | Code review, audit |
| `bypassPermissions` | Skips all prompts — **dangerous** | CI/CD only, sandboxed env |
Disable bypass permanently (set in `~/.claude/settings.json`):
```json
{ "permissions": { "disableBypassPermissionsMode": "disable" } }
```
---
# Claude Code — Settings Rule Syntax
## Rule syntax
@ -83,14 +18,10 @@ Disable bypass permanently (set in `~/.claude/settings.json`):
"Write(**/*.key)" // deny writing any .key file
```
### WebFetch
### WebFetch / WebSearch
```json
"WebFetch(domain:docs.rs)" // specific domain only
"WebFetch" // all web fetches (no sub-pattern)
```
### WebSearch
```json
"WebFetch" // all web fetches
"WebSearch" // no sub-patterns supported
```
@ -99,32 +30,27 @@ Disable bypass permanently (set in `~/.claude/settings.json`):
"Agent(explorer)"
"Skill(deploy *)"
"mcp__github__*" // all tools from github MCP server
"mcp__playwright__navigate"
```
---
## defaultMode values
| Value | Behavior | When to use |
|---|---|---|
| `default` | Prompts on first use of each tool | Normal development |
| `acceptEdits` | Auto-accepts file edits, prompts for Bash | Trusting sessions |
| `plan` | Read-only — Claude plans, cannot execute | Code review, audit |
| `bypassPermissions` | Skips all prompts — **dangerous** | CI/CD only, sandboxed env |
## Security notes
- `Read(**/.env)` only blocks the Read tool.
`Bash(cat .env)` bypasses it unless you also deny that Bash command.
→ Use `.claudeignore` for hard file exclusion.
- `disableBypassPermissionsMode: "disable"` prevents switching to
bypass mode mid-session — set it in `~/.claude/settings.json`.
- Prefer `ask` over `allow` for anything touching external systems
(git push, deploy, database commands, package install).
- `deny` rules in `~/.claude/settings.json` cannot be overridden
by project-level `allow` rules — deny always wins globally.
---
- `Read(**/.env)` only blocks the Read tool. `Bash(cat .env)` bypasses it unless separately denied.
→ Use `.claudeignore` for hard file exclusion regardless of tool.
- `disableBypassPermissionsMode: "disable"` prevents switching to bypass mode mid-session.
- Prefer `ask` over `allow` for anything touching external systems.
- `deny` in `~/.claude/settings.json` cannot be overridden by project-level `allow` — deny always wins.
## managed-settings.json (enterprise)
Cannot be overridden by any user or project setting.
| OS | Path |
|---|---|
| Windows | `C:\ProgramData\ClaudeCode\managed-settings.json` |

9
templates/settings/settings.json
View File

@ -1,5 +1,4 @@
{
"_readme": "Project-level settings — commit this file. Extends ~/.claude/settings.json. Only put project-specific rules here.",
"permissions": {
@ -53,19 +52,21 @@
"Bash(docker ps*)",
"Bash(docker images*)",
"Bash(docker logs *)",
"Bash(docker stop *)",
"Bash(docker rm *)",
"Bash(node *)",
"Bash(ts-node *)",
"Bash(tsx *)",
"Bash(npx *)",
"Bash(norminette*)"
],
"ask": [
"Bash(npx *)",
"Bash(docker stop *)",
"Bash(docker rm *)",
"Bash(make deploy*)",
"Bash(npm run deploy*)",
"Bash(cargo publish*)",

1
templates/settings/settings.local.json
View File

@ -1,5 +1,4 @@
{
"_readme": "Personal local overrides — DO NOT commit. Add .claude/settings.local.json to .gitignore. Highest priority after CLI flags.",
"permissions": {

87
update-all.sh
View File

@ -30,13 +30,29 @@ fi
# ── 2. Update GStack submodule ──
echo ""
echo "── Updating GStack submodule..."
if git submodule update --remote skills-external/gstack 2>/dev/null; then
if [ -d "skills-external/gstack" ]; then
cd skills-external/gstack && ./setup 2>/dev/null && cd "$REPO"
ok "GStack updated"
warn "GStack tracks branch = main (no commit hash). Review upstream commits before updating."
echo ""
printf " Proceed with GStack update? [y/N] "
read -r _gstack_confirm
if [[ "$_gstack_confirm" =~ ^[Yy]$ ]]; then
if git submodule update --remote skills-external/gstack 2>/dev/null; then
if [ -d "skills-external/gstack" ]; then
if [ -x "skills-external/gstack/setup" ]; then
if (cd skills-external/gstack && ./setup) 2>/dev/null; then
ok "GStack updated"
else
warn "GStack ./setup failed — submodule updated but setup did not complete"
fi
else
warn "GStack ./setup not found or not executable — skipping"
ok "GStack submodule pointer updated"
fi
fi
else
warn "GStack submodule update failed — run: git submodule update --init"
fi
else
warn "GStack submodule update failed — run: git submodule update --init"
info "GStack update skipped"
fi
# ── 3. Update RTK (if pinned version available) ──
@ -68,11 +84,68 @@ else
warn "Cargo not available — skipping RTK"
fi
# ── 4. Refresh symlinks ──
# ── 4. Update GSD v2 ──
echo ""
echo "── Updating GSD v2 (gsd-pi)..."
if command -v gsd &>/dev/null; then
GSD_VER=""
if [ -f "$REPO/plugins.lock.json" ] && command -v python3 &>/dev/null; then
GSD_VER=$(python3 -c "
import json
with open('$REPO/plugins.lock.json') as f:
d = json.load(f)
print(d.get('gsd',{}).get('version',''))
" 2>/dev/null || true)
fi
if [ -n "$GSD_VER" ] && [ "$GSD_VER" != "latest" ]; then
info "Pinned version: $GSD_VER"
npm install -g "gsd-pi@${GSD_VER}" 2>/dev/null \
&& ok "GSD v2 updated to $GSD_VER" \
|| warn "GSD v2 update failed"
else
info "No pinned version — installing latest"
npm install -g gsd-pi 2>/dev/null \
&& ok "GSD v2 updated (latest)" \
|| warn "GSD v2 update failed"
fi
else
warn "GSD v2 not installed — skipping (run: npm install -g gsd-pi)"
fi
# ── 5. Update Ruflo MCP (if installed) ──
echo ""
echo "── Updating Ruflo MCP..."
if command -v ruflo &>/dev/null || detect_ruflo; then
RUFLO_VER=""
if [ -f "$REPO/plugins.lock.json" ] && command -v python3 &>/dev/null; then
RUFLO_VER=$(python3 -c "
import json
with open('$REPO/plugins.lock.json') as f:
d = json.load(f)
print(d.get('ruflo',{}).get('version',''))
" 2>/dev/null || true)
fi
if [ -n "$RUFLO_VER" ] && [ "$RUFLO_VER" != "latest" ]; then
info "Pinned version: $RUFLO_VER"
npm install -g "ruflo@${RUFLO_VER}" 2>/dev/null \
&& ok "Ruflo updated to $RUFLO_VER" \
|| warn "Ruflo update failed"
else
npm install -g ruflo@latest 2>/dev/null \
&& ok "Ruflo updated (latest)" \
|| warn "Ruflo update failed"
fi
else
info "Ruflo not installed — skipping"
fi
# ── 6. Refresh symlinks ──
echo ""
echo "── Refreshing symlinks..."
bash "$REPO/link.sh"
# ── 5. Run doctor ──
# ── 7. Run doctor ──
echo ""
bash "$REPO/doctor.sh"

2
version.txt
View File

@ -1 +1 @@
1.0.0
3.2.1