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

docs: global sync before 2.0.0 — components, slash table, profiles, GSD 3.0.0, migration guide, package-install guard

Browse Source
This commit is contained in:
bchanot
2026-10-06 16:00:41 +02:00
parent a84aaaabbd
commit c6fb2e4219
7 changed files with 134 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE.md
+15 -9
View File
@@ -9,20 +9,26 @@ Repo layout and structural principles. Command workflows live in
claude-config/
├── CLAUDE.global.md # Global coding preferences — deployed as ~/.claude/CLAUDE.md
├── CLAUDE.md # Project-scope instructions (this repo only)
├── settings.json # Global permissions (deny / ask / allow rules)
├── README.md / USAGE.md / ARCHITECTURE.md / CHANGELOG.md / MIGRATION.md
├── version.txt # Current release version
├── .env.example # Placeholder template for ~/.claude/.env (secrets never committed)
├── settings.json # Global permissions (deny / ask / allow) + autoMode classifier tiers
├── install.sh # Bootstrap: Claude Code CLI + auth + submodules + link + plugins
├── install-plugins.sh # One-shot installer: prerequisites + all plugins
├── link.sh # Symlinks this repo into ~/.claude/
├── install-plugins.sh # One-shot installer: prerequisites + all plugins + default profile
├── link.sh # Symlinks this repo into ~/.claude/, sets git's global core.hooksPath
├── doctor.sh # Setup diagnostic
├── update-all.sh # One-command update for all components
├── Makefile # Unified entry point: make install / doctor / update
├── plugins.lock.json # Version pinning for non-marketplace dependencies
├── hooks/ # Session start, statusline, RTK rewrite + ctx7 + design-toolchain reminders
├── Makefile # Unified entry point: make install / doctor / update / test (make help)
├── plugins.lock.json # Version pinning for non-marketplace dependencies and vendored skills
├── hooks/ # Claude Code hooks: session start, statusline, RTK rewrite, ctx7 + design-toolchain reminders, attention notify, unpushed-work guard
├── githooks/ # Generated git hooks (pre-commit, post-commit, post-merge, reference-transaction), git's global core.hooksPath
├── .githooks/ # This repo's own copy of the same hooks
├── rules/ # Rule files deployed to ~/.claude/rules (path-scoped or always-on)
├── agents/ # Execution units called by skills (never invoked directly)
├── skills/ # Entry points invoked via /skill-name
├── skills-external/ # Vendored skill packs (gstack submodule + installer-fetched design packs)
├── skills-external/ # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored)
├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, deploy runbook, gitignore)
└── lib/ # Shared shell libs (gitflow, profiles, commit helpers, archetypes, tests)
└── lib/ # Shared libs: gitflow, profiles, vendoring, effort pins, gates, archetypes, tests
```
## Architecture principles
@@ -30,4 +36,4 @@ claude-config/
- `skills/` = entry points you invoke via `/skill-name`
- `agents/` = execution units called by skills (never invoked directly by user)
- `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually
- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly.
- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go.
CHANGELOG.md
+4 -1
View File
@@ -2,10 +2,12 @@
All notable changes to claude-config will be documented in this file.
Format follows [Keep a Changelog](https://keepachangelog.com/).
Format follows [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
Upgrading from 1.x: see [MIGRATION.md](./MIGRATION.md#upgrading-an-existing-machine-to-200).
### Added
- **Higgsfield pack, off by default**: `make plugin` installs the `@higgsfield/cli` CLI (Step 8.6) and clones the skills of higgsfield-ai/skills into `skills-external/higgsfield-*` through the new `lib/higgsfield-skills.sh`; `make update` refreshes the skills, and the CLI when npm installed it; `make doctor` reports the CLI and its session without ever warning. The pack belongs to no profile: `lib/toggle-external.sh enable higgsfield` links the seven allowlisted media skills, `enable higgsfield-websites` the landing-page aid, and no `profile set` or `make link` re-enables either. `CLAUDE.global.md` routes explicit media-generation asks to it. Hermetic suite `lib/tests/higgsfield.test.sh`.
- **Effort round (BDR-108)**: every skill carries an entry level next to its model pin. `lib/effort-pins.txt` (map) + `lib/effort-pins.sh` (idempotent re-apply after the last vendoring step of `install-plugins.sh` and `update-all.sh`) replace the hardcoded brainstorming/writing-plans loop and extend the pins to the design stack (high, one level per stack since the last loaded wins), superpowers, agent-skills and the 21st pack; `skills-perso` low, `pdf-translate` medium, `site-motion` high; doctrine: the design stack loads paired with the first Read (a lone Skill call applies nothing). Model pins stay tier aliases: the latest version of a tier is also the cheapest or same-priced, so the quality/price trade-off is tier × effort, never version. `lib/effort-audit.py` prints thinking coverage per scope (sub-agent records carry no thinking count on ~90 % of requests: EVAL-037's "executors stay cheap" was a measurement gap, not a finding).
@@ -220,6 +222,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
seeded like a real tree (gstack off, nothing linked).
### Changed
- Default session model `claude-fable-5-1` (settings.json `model`).
- **`full` = everything the other profiles carry** (user rule: full does
what every specialized profile does), minus the 9 removed gstack
skills, the 21st generation/review trio and one named exception
MIGRATION.md
+36 -7
View File
@@ -1,4 +1,6 @@
# Migration guide — `.claude/` restructure (2026-04-23)
# Migration guides
## `.claude/` restructure (2026-04-23)
The claude-config layout moved task tracking, memory registries, and audit
reports out of scattered roots (`tasks/`, `SEO.md`, `HARDEN.md`, etc.) into
@@ -9,7 +11,7 @@ claude-config skills and were onboarded before this change.
---
## TL;DR — full migration in one block
### TL;DR — full migration in one block
Run from the project root. Inspect the output before committing.
@@ -62,6 +64,8 @@ done
# .claude/memory/learnings.md (LRN-XXX format) then delete LESSONS.legacy.md
# 6. Update .gitignore - see "Gitignore patch" section below
# (`bash ~/.claude/lib/gitflow.sh reconcile` appends only the missing
# template lines and never rewrites project rules.)
# 7. Update CLAUDE.md - see "CLAUDE.md patch" section below
@@ -72,7 +76,7 @@ git check-ignore -v .claude/memory/decisions.md .claude/tasks/TODO.md 2>&1
---
## Gitignore patch
### Gitignore patch
If your project's `.gitignore` contains a bare `.claude/` rule, it will ignore
every memory/tasks/audit file you just created. Replace that line with:
@@ -84,9 +88,13 @@ every memory/tasks/audit file you just created. Replace that line with:
!.claude/memory/
!.claude/audits/
!.claude/settings.json
!.claude/deploy/
# These stay ignored (per-machine state)
.claude/settings.local.json
.claude/agent-memory/
.claude/gstack/
.claude/deploy/PENDING.json
.claude/deploy/NEXT.sh
```
Verify after edit:
@@ -101,7 +109,7 @@ git check-ignore .claude/settings.local.json .claude/agent-memory/
---
## CLAUDE.md patch
### CLAUDE.md patch
If your project's `CLAUDE.md` references `tasks/LESSONS.md` / `tasks/TODO.md`,
update the `## Session start`, `## Workflow`, `## After code changes`, and
@@ -126,7 +134,7 @@ Add a new section referencing the registries (full template in
---
## What gets committed vs ignored
### What gets committed vs ignored
| Path | Committed? | Reason |
|------|-----------|--------|
@@ -134,12 +142,14 @@ Add a new section referencing the registries (full template in
| `.claude/memory/*.md` | ✅ yes | Shared decisions/learnings/blockers |
| `.claude/audits/*.md` | ✅ yes | Snapshot of project state — version-able |
| `.claude/settings.json` | ✅ yes | Shared project config |
| `.claude/deploy/*.md` | ✅ yes | Deploy runbook + incidents |
| `.claude/settings.local.json` | 🚫 no | Per-machine overrides |
| `.claude/agent-memory/` | 🚫 no | Per-session agent state |
| `.claude/deploy/PENDING.json`, `NEXT.sh` | 🚫 no | Per-deploy transient state |
---
## Post-migration sanity check
### Post-migration sanity check
```bash
# 1. No legacy tasks/ dir left
@@ -161,10 +171,29 @@ All four checks should be clean before committing the migration.
---
## If anything goes wrong
### If anything goes wrong
- The migration block only uses `mv`, not `rm` — nothing is deleted.
- Old `LESSONS.md` is preserved as `LESSONS.legacy.md` — review it, copy
meaningful entries into `.claude/memory/learnings.md` (with `LRN-XXX` IDs),
then delete.
- To undo: `git checkout .` before commit.
---
## Upgrading an existing machine to 2.0.0
2.0.0 removes components that 1.x installed. `make plugin` installs their replacements; the leftovers go by hand.
```bash
git pull --recurse-submodules
make plugin # vendors the 7 superpowers skills (Step 8e), installs the Higgsfield and 21st CLIs (8.6, 8.7), re-runs link.sh (10), applies the default profile (11)
claude plugin uninstall superpowers@superpowers-marketplace # once, if the plugin is still cached
make doctor
```
- **Superpowers**: the plugin is gone. Its 7 wired skills are vendored at v6.4.1 and always on. The 8 other skills and the session-start injection are not replaced.
- **Magic MCP**: replaced by the `21st` CLI (`21st login`, no API key). If 1.x registered the `magic` server, remove it from `~/.claude.json` and drop `MAGIC_API_KEY` from `~/.claude/.env`. Nothing reads them any more.
- **Git hooks in every repo**: `link.sh` sets git's global `core.hooksPath` to `~/.claude/githooks`. Every repo on the machine now gets the gitflow pre-commit guard and pushes each commit as it lands. For a foreign clone: `git config gitflow.protect false` and `git config gitflow.autopush false`.
- **Default profile**: a machine with no profile selected now runs `full`. Check with `make profile-current`. Nine gstack skills (`ship`, `land-and-deploy`, `setup-deploy`, `autoplan`, `context-save`, `learn`, `careful`, `guard`, `design-shotgun`) left every profile and are denylisted.
- **Higgsfield**: installed, off by default. Nothing to do until you enable it.
Makefile
+3 -3
View File
@@ -1,7 +1,7 @@
.PHONY: help install plugin link doctor update new-skill profile profile-list profile-current profile-reset onboard test scan-secrets seo-connect
help: ## Show available commands
@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf " make %-14s %s\n", $$1, $$2}'
@grep -E '^[a-zA-Z_-]+:.*##' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf " make %-16s %s\n", $$1, $$2}'
install: ## First-time setup: install Claude Code + auth + symlinks + plugins
bash install.sh
@@ -41,7 +41,7 @@ test: ## Run deterministic tests hermetically (one: make test suite=lib/tests/x.
*) bash "$$t" || fail=1 ;; \
esac; done; exit $$fail
scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude (job7 backstop). Extra repos: make scan-secrets repos="path1 path2"
scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude. Extra repos: make scan-secrets repos="path1 path2"
@command -v gitleaks >/dev/null 2>&1 || { echo "gitleaks not installed — https://github.com/gitleaks/gitleaks"; exit 1; }
@mkdir -p .audit
@fail=0; \
@@ -59,7 +59,7 @@ scan-secrets: ## Gitleaks sweep: this repo's history + ~/.claude (job7 backstop)
profile: ## Run profile.sh (usage: make profile cmd="set design")
@bash lib/profile.sh $(cmd)
profile-list: ## List skill profiles (design, dev, qa, audit, minimal)
profile-list: ## List skill profiles (audit, backend, design, dev, full, max, minimal, qa, seo, web, web-full)
@bash lib/profile.sh list
profile-current: ## Show the active profile (label + match)
README.md
+49 -30
View File
@@ -16,18 +16,19 @@ Not a collection of prompts — an operating layer on top of Claude Code:
the cheapest model that can do the job (haiku collects, sonnet executes,
opus judges, the session model only reflects).
- **Hooks and permissions** are deterministic guardrails: gitflow enforced
by a pre-commit hook, every commit pushed by post-commit and post-merge
hooks, `main`/`develop` undeletable by a reference-transaction hook,
by a pre-commit hook in every repo (`make link` points git's global
`core.hooksPath` at `~/.claude/githooks`), every commit pushed by
post-commit and post-merge hooks, `main`/`develop` undeletable by a reference-transaction hook,
deny-first permission rules, secrets kept in `~/.claude/.env` and
never in config files.
- **Templates and memory** seed every project with persistent registries
(decisions, learnings, blockers) — what a session learns, the next
session knows.
(decisions, learnings, blockers, journal, evals) — what a session
learns, the next session knows.
## How it works
```bash
git clone --recurse-submodules https://github.com/bchanot/claude
git clone --recurse-submodules https://git.bchanot.fr/bchanot/claude
cd claude
make install # CLI + auth + symlinks + plugins (pinned in plugins.lock.json)
make doctor # verify everything
@@ -39,7 +40,7 @@ Day to day:
```bash
/onboard # bring an existing repo into the framework
/ship-feature "…" # brainstorm → plan → adversarial challenge → TDD → review → merge
/ship-feature "…" # brainstorm → plan → adversarial challenge → TDD → verify + security gates → review → merge on your go
/feat "…" # same idea, 1-5 files, no ceremony
/close # flush decisions and learnings to memory before quitting
make update # keep CLI, plugins, and submodules current
@@ -51,8 +52,9 @@ make update # keep CLI, plugins, and submodules current
locked, `make doctor` proves it works.
- **Cost-shaped.** Model tiering routes reflection to the big model and
execution to cheap ones — the expensive context does only what it must.
- **Safe by default.** Protected branches, ask-before-run on risky tools,
parameterized secrets: the guardrails are code, not good intentions.
- **Safe by default.** Protected branches, deny rules and auto-mode soft/hard blocks on
risky tools, transfer and mirror tools denied outright, parameterized
secrets: the guardrails are code, not good intentions.
- **It compounds.** Memory registries, audit skills, and doc-sync keep every
project's knowledge growing across sessions instead of evaporating.
@@ -68,7 +70,7 @@ commands, settings, secrets, maintenance.
Doctrine: the session model (Fable) does main-loop reflection ONLY —
brainstorm, plan, contract, audit judgment, gates, loop decisions — enforced
by a blocking gate (`lib/model-gate.md` + `lib/model-check.sh`) at the entry
of the 13 reflection orchestrators. Nothing dispatched inherits silently:
of the 15 reflection skills (the orchestrators plus `/analyze`). Nothing dispatched inherits silently:
typed agents carry a frontmatter pin, built-ins get an explicit `model=` at
every call site.
@@ -90,7 +92,7 @@ The pure-execution skills `/doc`, `/status`, `/commit-change`,
`/release-candidate` **dispatch** their agent (instead of inline-loading it)
so the pin takes effect and the work leaves the big session model; `/hotfix`
was split like `/feat` (reflection inline + gate, `hotfixer` executor) and so
joins the gated group (13th); `/client-handover`'s nested skill-runner
joins the gated group; `/client-handover`'s nested skill-runner
children are dispatched `model:"fable"` (they carry reflection).
## Effort routing (BDR-107, BDR-108)
@@ -100,7 +102,7 @@ Second axis of the same table: how hard each phase thinks. Session default
appliers, medium executors, high judgment, xhigh challengers and gates; none
on haiku, which rejects the parameter). Every user-invoked skill carries an
entry level (`/status` low … `/ship-feature` xhigh); the vendored externals
(design stack, superpowers, agent-skills, 21st) get theirs from
(design stack, superpowers, agent-skills, MengTo scroll skills, 21st) get theirs from
`lib/effort-pins.txt`, re-applied by `lib/effort-pins.sh` after every
vendoring step. Orchestrators shift per phase through the `effort-low` …
`effort-max` skills (`lib/effort-shift.md`, always sent with another tool
@@ -116,6 +118,7 @@ never version. Census `lib/tests/effort-routing.test.sh`; transcript audit
All scripts use their own location to find the repo — run them from anywhere.
The plugins step logs to `install-YYYYMMDD-HHMMSS.log`.
The last step applies the default profile, `full`, when none is selected, and re-applies an existing selection.
**Optional — Context7** (fast doc lookup for React / Next.js / Prisma…): the plugins
step installs the `ctx7` CLI and wires it into Claude Code. The doc-fetch surface is
@@ -136,14 +139,21 @@ ctx7 login # optional: OAuth / API key for higher rate limits
| Component | Type | Description | Docs |
|---|---|---|---|
| **Superpowers skills** | Vendored (7, always on) | brainstorming, writing-plans, subagent-driven development, TDD, code review request, git worktrees, writing-skills — pinned v6.4.1 in plugins.lock.json, no plugin, no session injection | [obra/superpowers](https://github.com/obra/superpowers) |
| **GStack** | Plugin (toggle) | Full-product workflow: UI + design + deploy + browser QA. Skip for backend/CLI projects. | [garrytan/gstack](https://github.com/garrytan/gstack) |
| **GStack** | Git submodule (per profile) | Product workflow skills: plan reviews, design, browser QA, security (`cso`), `health`. Linked per profile; 9 broken or doctrine-breaking skills are denylisted in `lib/gstack-removed.sh`. | [garrytan/gstack](https://github.com/garrytan/gstack) |
| **GSD v2** | External CLI | Multi-session orchestration: crash recovery, cost tracking, parallel workers, context-fresh execution. | [gsd-build/gsd-2](https://github.com/gsd-build/gsd-2) |
| **RTK** | Plugin (always on) | Code rewrite hook. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
| **security-guidance** | Plugin (always on) | Security hook. Zero passive cost. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
| **RTK** | CLI + hook (always on) | Rust Token Killer: the `hooks/rtk-rewrite.sh` PreToolUse hook rewrites Bash commands through `rtk` to cut output tokens. Zero passive cost. | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) |
| **security-guidance** | Plugin (always on) | Security hook. Regex layer and commit/push review on; the Stop-time diff review is off (`ENABLE_STOP_REVIEW=0`). | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
| **ui-ux-pro-max** | Plugin (toggle) | Design system, color/typography choices. Enable for design-heavy projects. | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
| **Context7** | Plugin (toggle) | Fast-evolving libs doc lookup (Next.js, React, Prisma...). Works anonymously; optional `ctx7 login` raises rate limits. | [context7.com](https://context7.com/) |
| **Context7** | CLI (`ctx7`) | Doc lookup for fast-evolving libs (Next.js, React, Prisma...), used through the `find-docs` skill. Works anonymously; optional `ctx7 login` raises rate limits. | [context7.com](https://context7.com/) |
| **pr-review-toolkit** | Plugin (toggle) | Multi-agent PR review. | [anthropics/claude-code](https://github.com/anthropics/claude-code) |
| **Graphify** | Python CLI | Codebase → knowledge graph → navigable wiki. Helps Claude map and search projects efficiently. | [pypi: graphifyy](https://pypi.org/project/graphifyy/) |
| **21st.dev** | External CLI + skill pack | Component catalog and UI generation (`21st`), browser login, no API key. 7 skills in `skills-external/21st-*`, linked per profile (see the 21st.dev CLI section). | [npm: @21st-dev/cli](https://www.npmjs.com/package/@21st-dev/cli) |
| **Higgsfield** | External CLI + skill pack (off by default) | Image, video, audio and brand media generation, metered credits (see the Higgsfield CLI section). | [higgsfield-ai/skills](https://github.com/higgsfield-ai/skills) |
| **Semgrep** | Python CLI (pinned) | SAST engine behind the security gate (`security-auditor`). | [pypi: semgrep](https://pypi.org/project/semgrep/) |
| **Impeccable** | npm CLI + skill (pinned) | Deterministic anti-slop detector (`npx impeccable detect`, 45 rules) and the `/impeccable` design verbs. | [npm: impeccable](https://www.npmjs.com/package/impeccable) |
| **Design skills** | Vendored | `emil-design-eng`, `frontend-design` (Anthropic example-skills), `design-motion-principles`: UI polish, anti-slop build, motion. | [emilkowalski/skill](https://github.com/emilkowalski/skill) · [kylezantos/design-motion-principles](https://github.com/kylezantos/design-motion-principles) |
| **agent-skills** | Vendored (commit-pinned) | `observability-and-instrumentation`, `deprecation-and-migration`, `ci-cd-and-automation`. | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) |
| **MengTo scroll skills** | Vendored (commit-pinned) | Five scroll-choreography skills: `scroll-world-storytelling`, `build-threejs-scroll-worlds`, `scroll-scrubbed-visual-sequence`, `scroll-scrubbed-word-reveal`, `scroll-progress-timeline`. | [MengTo/Skills](https://github.com/MengTo/Skills) |
Versions are pinned in `plugins.lock.json`. To update: edit the file, then re-run `install-plugins.sh`.
@@ -160,7 +170,7 @@ a different package, ships its own conflicting `graphify` bin) — see
|---|---|
| `/init-project` | Initialize a complete project from scratch (full orchestrator, 12+ steps) |
| `/ship-feature` | Ship a feature end-to-end with validation gates (full orchestrator) |
| `/onboard` | Onboard an existing project — generate CLAUDE.md, settings, .claudeignore |
| `/onboard` | Onboard an existing project: CLAUDE.md, settings, .claudeignore, archetype audits, report and a sequenced TODO backlog |
| `/feat` | Small feature implementation (1-5 files, lightweight) |
| `/bugfix` | Structured bug fix with root cause investigation |
| `/hotfix` | Quick fix for superficial bugs (typos, CSS, config — max 2 files) |
@@ -173,7 +183,7 @@ a different package, ships its own conflicting `graphify` bin) — see
| `/commit-change` | Smart commit grouping from staged/unstaged changes |
| `/gitflow` | Gitflow branch operations — bootstrap main+develop, start a typed branch, directed merge |
| `/release-candidate` | Cut a versioned release — finalize version.txt + CHANGELOG, merge develop→main, tag, push |
| `/deploy` | Run a project's deploy from its committed runbook — instantiate the delta, resume cold |
| `/deploy` | Compose the deploy checklist from a project's committed runbook (delta only); you run it, the skill resumes cold on your report |
| `/graphify` | Codebase knowledge graph — navigation for large-scope tasks |
| `/plugin-check` | Check active plugins vs project needs — recommend enable/disable |
| `/health` | Code quality dashboard (gstack) — setup diagnostic is `make doctor` |
@@ -191,6 +201,8 @@ a different package, ships its own conflicting `graphify` bin) — see
| `/client-handover` | Final project delivery — audits + branded deliverable (Markdown / HTML / PDF) |
| `/profile` | Activate a skill profile (web / seo / web-full / full / max / backend / design / dev / qa / audit / minimal) (default: full) |
| `/tour` | Grouped all-axes sweep — cleanup + security + reconcile + doc, fix and loop until clean |
| `/site-motion` | Site-level motion: scroll engine choice, page transitions, pin/scrub sequencing across a page or Astro route (design stack) |
| `/effort-low` … `/effort-max` | Effort shifters the orchestrators send per phase; type `/effort-max` to re-run a stuck turn at maximum |
> This table lists personal skills. Gstack skills (investigate, review, retro,
> office-hours, cso…) and marketplace plugins add many more — run
@@ -221,13 +233,15 @@ cd my-existing-project/
```
/ship-feature "feature description"
# → STEP 0: plugin check
# → STEP 1-2: brainstorm + plan (superpowers)
# → STEP 0: plugin check, project context, contract
# → STEP 1-2: brainstorm + plan (vendored superpowers skills)
# → STEP 2b: adversarial plan-challenge (3 lenses, report-only)
# → STEP 3: validation gate — user approval required
# → STEP 4-7: implement (TDD) → review → capitalize (memory)
# → STEP 8: sync README (doc-sync)
# → STEP 9: finish (merge / PR)
# → STEP 4: implement (TDD)
# → STEP 5: verify + secure (fresh verifier and security-auditor gates)
# → STEP 6-7: review → capitalize (memory)
# → STEP 8: doc sync (public docs, committed before finish)
# → STEP 9: finish, `gitflow finish` into develop on your explicit go
```
For small features (1-5 files), use `/feat` instead — no orchestration overhead.
@@ -241,7 +255,7 @@ Settings follow a hierarchy (highest priority first):
```
managed-settings.json → enterprise (cannot be overridden)
CLI flags → session only
.claude/settings.local → personal machine overrides (gitignored)
.claude/settings.local.json → personal machine overrides (gitignored)
.claude/settings.json → project rules (committed)
~/.claude/settings.json → global user rules (this repo)
```
@@ -326,9 +340,10 @@ npm i -g @21st-dev/cli
`make plugin` does both (Step 8.7 installs the CLI, then offers the login in
an interactive terminal) and installs the skill pack that drives it:
`21st-ui-build`, `-ui-explore`, `-ui-review`, `-cli-use`, `-ai`, plus the two
publishing skills `-registry` and `-design-sync`. The five design skills
follow the active profile: they are on under `full`, the default profile,
and under `design`, `web` and `web-full`. The two publishing skills,
publishing skills `-registry` and `-design-sync`. Of the five design skills, `21st-ui-build` and
`21st-cli-use` follow the active profile: on under `full`, the default profile, and under `design`,
`web` and `web-full`. The other three, `-ui-explore`, `-ui-review` and
`-ai`, are on under `max` only. The two publishing skills,
`-registry` and `-design-sync`, are in no profile and stay parked until
`bash lib/toggle-external.sh enable 21st` turns on all seven.
@@ -413,7 +428,7 @@ bash doctor.sh # full diagnostic (symlinks, plugins, permissions, t
bash update-all.sh # update all components (CLI, plugins, submodules, symlinks)
# Claude Code
/health # gstack code-quality dashboard (doctor.sh -> make doctor)
/health # gstack code-quality dashboard (setup diagnostic: make doctor)
/status # project snapshot (plugins, git, GSD milestone)
/plugin-check "description" # audit plugin config vs project needs
@@ -423,7 +438,9 @@ make plugin # install plugins only
make link # create/update symlinks into ~/.claude/
make doctor # diagnostic
make update # update Claude Code, config, submodules, plugins, and verify
make test # run deterministic tests (lib/tests/*.test.sh + lib/seo-data/*.test.sh + lib/gitflow-test.sh + lib/tests/run-*.sh)
make test [suite=lib/tests/x.test.sh] # hermetic deterministic tests: every suite, or one
make scan-secrets [repos="…"] # gitleaks sweep of this repo's history and ~/.claude, reports in .audit/ (never committed)
make help # list make targets
make onboard # onboard an existing project (run from its dir)
make seo-connect # connect a Google account for /seo FULL (OAuth consent)
make profile cmd="set X" # activate a skill profile (web/seo/web-full/full/max/backend/design/dev/qa/audit/minimal)
@@ -433,7 +450,7 @@ make profile-reset # go to the default profile (full)
make new-skill name=myskill # scaffold agent + skill files
```
`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency.
`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency, git hooks (global core.hooksPath + generated githooks/), scratchpad (TMPDIR quota), Higgsfield CLI and session, seo-data layer.
---
@@ -441,4 +458,6 @@ make new-skill name=myskill # scaffold agent + skill files
[`USAGE.md`](./USAGE.md) — workflows and skill decision tree ·
[`ARCHITECTURE.md`](./ARCHITECTURE.md) — layout and principles ·
[`CHANGELOG.md`](./CHANGELOG.md) — version history.
[`CHANGELOG.md`](./CHANGELOG.md) — version history ·
[`MIGRATION.md`](./MIGRATION.md): upgrade guides ·
[`templates/settings/SETTINGS.md`](templates/settings/SETTINGS.md): permission tiers and guardrails
USAGE.md
+22 -18
View File
@@ -83,7 +83,7 @@ Tu veux...
│ → /prune-memory ← curer / compresser les registres .claude/memory/
│
└─ Quelque chose ne marche pas ?
→ /health ← diagnostic complet (symlinks, plugins, permissions, token budget)
→ make doctor ← diagnostic d'installation (symlinks, plugins, permissions, hooks, token budget)
```
### Règle de décision simplifiée
@@ -122,7 +122,7 @@ Tu veux...
| Changer profil skills | `/profile` |
| Audit/polish design (anti-slop) | `/impeccable` |
| Sweep groupé tous axes (nettoyage + sécu + reconcile + doc) | `/tour` |
| Rien ne marche | `/health` |
| Rien ne marche | `make doctor` (terminal) |
---
@@ -147,10 +147,10 @@ Tu veux...
| `/commit-change` | Commits bien structurés | Groupe les changements par unité logique |
| `/gitflow` | Opérations de branches gitflow | Bootstrap main+develop, branche typée, merge dirigé |
| `/release-candidate` | Couper une release versionnée (develop en avance sur main) | Finalise version.txt + CHANGELOG, merge develop→main, tag, push |
| `/deploy` | Déployer via le runbook du projet | Instancie le delta depuis le dernier deploy, reprend à froid |
| `/deploy` | Déployer via le runbook du projet | Instancie le delta depuis le dernier deploy, reprend à froid ; tu exécutes la checklist, Claude ne déploie jamais |
| `/graphify` | Navigation codebase large-scope | Knowledge graph, pour tâches multi-fichiers |
| `/skills-perso` | Lister ses skills personnels | Skills créés dans ~/.claude/skills/ |
| `/health` | Quand quelque chose ne fonctionne pas | Lance doctor.sh |
| `/health` | Tableau de bord qualité du code (gstack) | Le diagnostic d'installation est `make doctor` |
| `/status` | Reprendre après une pause | Snapshot : plugins, git, GSD milestone |
| `/audit-delta` | Audit récurrent du delta depuis le dernier run | Axes : conformité / bugs / dead code / sécurité |
| `/capitalize` | Avant /clear ou /compact | Flush contexte non capitalisé + réconcilie .claude/tasks/TODO.md |
@@ -181,7 +181,7 @@ audits avec fix), xhigh pour l'architecture et l'audit avant validation
(`/ship-feature`, `/onboard`, `/analyze`). Les orchestrateurs décalent
ensuite le niveau par phase (`lib/effort-shift.md`), et `/effort-max` tapé à
la main relance un tour bloqué au maximum. Les skills externes vendorés
(pile design, superpowers, 21st) reçoivent leur niveau de
(pile design, superpowers, agent-skills, skills scroll MengTo, 21st) reçoivent leur niveau de
`lib/effort-pins.txt`. Un skill chargé seul par Claude n'applique pas son
niveau : il doit partir avec un autre appel d'outil dans le même message.
@@ -220,9 +220,9 @@ Hotfix/quick fix → tout OFF (skills superpowers vendorisés, toujours
# → STEP 1 : interview (skip si prompt complet)
# → STEP 4 : ★ GATE — valider l'architecture
# → STEP 7 : ★ GATE — valider le plan d'implémentation
# → STEP 8-10 : implémentation TDD + review
# → STEP 10b-c: capitalize mémoire + sync README (avant finish)
# → STEP 11 : finish (merge / commit initial)
# → STEP 8-10 : implémentation TDD + gates verify/sécurité + review
# → STEP 10b-c: capitalize mémoire + sync docs publiques (avant finish)
# → STEP 11 : finish, `gitflow finish` vers develop sur ton feu vert explicite
# 3. Features suivantes
/ship-feature "description de la feature"
@@ -240,7 +240,7 @@ Hotfix/quick fix → tout OFF (skills superpowers vendorisés, toujours
# Dans un terminal (depuis le dossier projet) :
gsd # démarrer une session
/gsd init # initialise .gsd/ + ROADMAP (une fois, à la demande)
/gsd init # initialise .gsd/ + milestones (une fois, à la demande)
/gsd auto # mode autonome, walk away
# Pour suivre :
@@ -274,9 +274,12 @@ cd mon-projet-existant/
| 1 | Archetype detection (scan ~/.claude/lib/project-archetypes/*.md) | archétype SELECTED + implications auto |
| 1b | Gate monorepo (A/B/C si détecté) | mode choisi |
| 2 | Config baseline (onboarder agent) | CLAUDE.md, settings.json, .claudeignore, .claude/tasks/ + .claude/memory/ + .claude/audits/ |
| 2.5| Lib d'animation (`motion`), proposée, opt-in | dépendance si acceptée |
| 2.6| Gitflow init (main + develop, hooks) | branches + .githooks/ |
| 3 | Interview deep = business minimum (users, deadlines, équipe, légal, perfs) + adaptative par archétype | brief enrichi |
| 3.5| ctx7 doc audit — fast-libs détectées, cache pré-fetché si besoin | .ctx7-cache/ |
| 4 | Graphify (proposé dès 200 fichiers code, l'utilisateur décide) | graphify-out/GRAPH_REPORT.md |
| 4.5| Espace d'audit + contexte archétype | .onboard-audit/archetype-context.md |
| 5 | Analyze read-only (analyzer agent) | .onboard-audit/analyze.md |
| 6 | Audits parallèles selon archétype : | .onboard-audit/*.md (9 fichiers max) |
| | — dette tech (general-purpose, audit read-only) |
@@ -287,6 +290,7 @@ cd mon-projet-existant/
| | — performance (Lighthouse ou static bundle audit) |
| | — accessibilité (axe ou static a11y audit) |
| 7 | Synthèse structurée dans .claude/audits/ | ONBOARD_REPORT, AUDIT_GOOD, AUDIT_ISSUES, AUDIT_PROPOSALS |
| 7b | Challenge adversarial des propositions avant la gate | AUDIT_PROPOSALS.md challengé |
| 8 | Validation gate utilisateur | choix A/B/C/D/E |
| 9 | Backlog .claude/tasks/TODO.md séquencé avec /skill recommandé par tâche | .claude/tasks/TODO.md |
@@ -308,7 +312,7 @@ cat .claude/audits/ONBOARD_REPORT.md
# Multi-session (GSD) : gsd init à la main — voir docs gsd-pi
```
**Archétypes supportés (P1)** : static-html, wordpress, nextjs-app-router, astro-static, react-spa, rest-api-node, rest-api-python, cli-tool, library, dotfiles-meta.
**Archétypes supportés** : astro-static, cli-tool, data-notebook, desktop-electron, docker-compose-infra, dotfiles-meta, drupal, firmware-embedded, game-engine-native, ghost, library, mobile-expo, mobile-flutter, nextjs-app-router, react-spa, rest-api-node, rest-api-python, shopify, static-html, strapi, terraform-infra, web-game, woocommerce, wordpress.
Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voir `_TEMPLATE.md`).
### Pattern D — Hotfix / bugfix · ~200-800t
@@ -340,7 +344,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voi
```
# Feature simple, pas d'orchestration lourde
/feat "ajouter un endpoint GET /api/v1/users/:id/stats"
# → planning léger, implémentation directe, tests
# → plan + challenge, exécuteur `feater`, gates fraîches verifier + sécurité
# Pas de brainstorming superpowers, pas de gate de validation
```
@@ -351,7 +355,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voi
| Scope | Feature complète, multi-fichiers | 1-5 fichiers max |
| Orchestration | Pipeline superpowers complet | Planning léger, direct |
| Gate de validation | Oui | Non |
| Code review auto | Oui (superpowers) | Non |
| Code review auto | Oui (superpowers) | Gates verifier + security-auditor |
| Tokens estimés | ~1500-3000t | ~300-600t |
---
@@ -530,7 +534,7 @@ Convention: snake_case Python, camelCase TypeScript."
**Workflow long avec GSD v2 :**
```
# Après /init-project, on initialise GSD à la demande (plus auto-bootstrappé).
# Le ROADMAP.md généré par `gsd init` contiendra :
# Les roadmaps de milestone (`.gsd/milestones/<ID>/<ID>-ROADMAP.md`) contiendront :
# Milestone 1: Boutique in-app + Stripe
# Milestone 2: PvP + matchmaking
# Milestone 3: Leaderboard + saisons
@@ -538,7 +542,7 @@ Convention: snake_case Python, camelCase TypeScript."
# Dans un terminal :
cd cardforge/
gsd # démarre session GSD
/gsd init # crée .gsd/ + ROADMAP (à la demande — plus auto à l'init)
/gsd init # crée .gsd/ + milestones (à la demande — plus auto à l'init)
/gsd auto # GSD travaille sur Milestone 1 de façon autonome
# → research Stripe API + docs
# → plan décomposé en tâches
@@ -556,7 +560,7 @@ gsd # démarre session GSD
gsd
/gsd quick "Implémenter la boutique in-app avec Stripe"
# ou
/gsd auto # si ROADMAP.md est déjà à jour
/gsd auto # si la roadmap du milestone est à jour
```
---
@@ -876,7 +880,7 @@ PROJECT STATUS
CONFIG
Version : v2.5.0
Plugins ON: context7 (~200t), skills superpowers vendorisés (toujours actifs, 0 t passif)
GSD v2 : installed (2.64.0)
GSD v2 : installed (3.0.0)
PROJECT
CLAUDE.md : found
@@ -951,13 +955,13 @@ Updated: Slice 4 plan — Payment Element instead of CardElement
Continue? (yes)
```
GSD v2 met à jour le plan dans `.gsd/ROADMAP.md` sans perdre le travail déjà fait.
GSD v2 met à jour le plan dans la base GSD (`.gsd/gsd.db`) sans perdre le travail déjà fait.
#### Ce que ce workflow démontre
- **`/status`** est le point d'entrée naturel après une pause — snapshot complet en 1 commande.
- **GSD v2 `step mode`** est préférable à `auto` après une longue pause — permet de vérifier que les décisions sont toujours valides.
- **`.gsd/ROADMAP.md`** est la source de vérité du progress — parsé par `/status` et par GSD lui-même.
- **La base GSD (`.gsd/gsd.db`)** est la source de vérité du progress; `/status` la lit via `gsd headless query`.
- **`/gsd discuss`** permet de modifier l'architecture en cours de route sans recommencer depuis zéro.
---
templates/settings/SETTINGS.md
+5 -1
View File
@@ -112,6 +112,10 @@ arbitrary code execution (`Bash(*)`, wildcarded interpreters such as
`permissions.allow` says. `awk` and `echo` pass through a static rule; `node`
cannot.
### Package installs
Global npm installs run their install scripts with your rights on the whole machine. `npm install -g`, `npm i -g` and their `--global` spellings are in `permissions.deny`. An `autoMode.soft_deny` entry catches every other spelling (a flag after the package name, `npm add -g`) and holds the install until you name the package in the current turn, after Claude states its publisher, age, download volume, install scripts and known advisories. A second `soft_deny` entry covers `npx`, `pnpm dlx` and `yarn dlx` of a package absent from the manifest and lockfile. Project-local scripts and declared packages pass through `autoMode.allow`.
### Scope of intent
A `soft_deny` clears on the user's instruction, and this config scopes that to
@@ -124,7 +128,7 @@ no separate setting for this.
- `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.
- Prefer `autoMode.soft_deny` over `allow` for anything touching external systems.
- `deny` in `~/.claude/settings.json` cannot be overridden by project-level `allow` — deny always wins.
- Under `defaultMode: auto`, `ask` does not raise a prompt (see above). A destructive
command belongs in `deny` or in `autoMode.soft_deny`, not in `ask`.