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
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