From c6fb2e42191a5247ea87fb74e95788d8de07bd95 Mon Sep 17 00:00:00 2001 From: bchanot Date: Tue, 6 Oct 2026 16:00:41 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20global=20sync=20before=202.0.0=20?= =?UTF-8?q?=E2=80=94=20components,=20slash=20table,=20profiles,=20GSD=203.?= =?UTF-8?q?0.0,=20migration=20guide,=20package-install=20guard?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 24 +++++++---- CHANGELOG.md | 5 ++- MIGRATION.md | 43 +++++++++++++++--- Makefile | 6 +-- README.md | 79 +++++++++++++++++++++------------- USAGE.md | 40 +++++++++-------- templates/settings/SETTINGS.md | 6 ++- 7 files changed, 134 insertions(+), 69 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 434a70c..a063658 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fcc8e1..590dff4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/MIGRATION.md b/MIGRATION.md index c63ba88..1c4f8ce 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -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. diff --git a/Makefile b/Makefile index fd551bc..2141a32 100644 --- a/Makefile +++ b/Makefile @@ -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) diff --git a/README.md b/README.md index 578f702..c49dfa9 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/USAGE.md b/USAGE.md index 86087d3..b6ae6ad 100644 --- a/USAGE.md +++ b/USAGE.md @@ -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/.md` (voir `_TEMPLATE.md`). ### Pattern D — Hotfix / bugfix · ~200-800t @@ -340,7 +344,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/.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/.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//-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. --- diff --git a/templates/settings/SETTINGS.md b/templates/settings/SETTINGS.md index 6cedb68..dadeaf8 100644 --- a/templates/settings/SETTINGS.md +++ b/templates/settings/SETTINGS.md @@ -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`.