540 lines
52 KiB
Markdown
540 lines
52 KiB
Markdown
# claude-config
|
||
|
||
One repo that turns Claude Code into a reproducible engineering system —
|
||
skills, agents, hooks, plugins, and per-project memory, versioned and
|
||
symlinked into `~/.claude/`. Clone it on any machine, run one command,
|
||
and every project gets the same assistant with the same rules.
|
||
|
||
## What it is
|
||
|
||
Not a collection of prompts — an operating layer on top of Claude Code:
|
||
|
||
- **Skills** (`/feat`, `/bugfix`, `/ship-feature`, `/seo`, `/tour`…) are the
|
||
entry points: each one encodes a complete workflow, from quick fix to
|
||
full feature pipeline with validation gates.
|
||
- **Agents** are the execution units skills dispatch to — each pinned to
|
||
the cheapest model that can do the job (haiku collects, sonnet executes,
|
||
opus judges and runs the session, Fable plans and runs the merge gates).
|
||
- **Hooks and permissions** are deterministic guardrails: gitflow enforced
|
||
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 (nothing pushed in a repo the user puts
|
||
in manual-push mode, where a PreToolUse hook also refuses Claude's own
|
||
`git push`), `main`/`develop` undeletable by a reference-transaction hook,
|
||
package and archive extraction into system directories refused by a
|
||
PreToolUse hook (here or on a VM over ssh), 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, journal, evals) — what a session
|
||
learns, the next session knows.
|
||
|
||
## How it works
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
`link.sh` symlinks the repo into `~/.claude/`, so editing here updates the
|
||
live config — and `git log` is the audit trail of your entire setup.
|
||
Day to day:
|
||
|
||
```bash
|
||
/onboard # bring an existing repo into the framework
|
||
/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
|
||
```
|
||
|
||
## Why it's good
|
||
|
||
- **Reproducible.** One clone rebuilds the whole environment; versions are
|
||
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, 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.
|
||
|
||
---
|
||
|
||
Everything below is the reference manual — model routing, components,
|
||
commands, settings, secrets, maintenance.
|
||
|
||
---
|
||
|
||
## Agent model routing (model-tiering v2)
|
||
|
||
Doctrine: the main loop runs on the `opus` session model; the model-router rows
|
||
lift it to Fable for main-loop reflection ONLY: brainstorm, plan, contract,
|
||
audit judgment, loop decisions. The main loop writes no code outside a skill run (the router's guard
|
||
redirects it to a skill); the fresh gates run as dispatched agents on the `audit` row. The
|
||
Fable/Opus model floor is enforced by a blocking gate (`lib/model-gate.md`) at
|
||
the entry of the 17 reflection skills (the orchestrators, `/analyze`,
|
||
`/guardrails` and `/a11y`): the skill calls the model-router `route` tool and
|
||
its answer, which names the model id the main loop runs on, is the witness. A
|
||
non-Fable/Opus id or the mod off stops the skill (`/route on` resumes the
|
||
mod). Nothing dispatched inherits silently: typed agents run on their
|
||
model-router row, their
|
||
`model:` frontmatter being the off-state floor; built-ins get an explicit
|
||
`model=` at every call site.
|
||
|
||
| Agent | Model | Tier |
|
||
|---|---|---|
|
||
| feater, hotfixer, bugfixer | sonnet (pinned) | executors — code from a closed plan (feat), fix from a closed diagnosis (bugfix), fix-bundle appliers |
|
||
| verifier | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) |
|
||
| security-auditor | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) |
|
||
| commit-changer, release-executor, code-cleaner | sonnet (pinned) | dispatched execution — grouping+commit / release prep span / approved cleanup (audit + approval gates stay in the dispatcher) |
|
||
| onboarder, scaffolder, refactorer, validator-analyzer, plugin-probe | sonnet (pinned) | workers — config generation, scaffold, refactor, deterministic W3C/WCAG runner, mechanical plugin probe |
|
||
| status-reporter | haiku (pinned) | mechanical collector |
|
||
| analyzer, plan-challenger, plugin-advisor | opus (pinned) | dispatched judgment — pre-plan analysis, 3-lens adversarial plan challenge (`/ship-feature` STEP 2b), plugin-fit reasoning |
|
||
| seo-analyzer, geo-analyzer | opus pin (judge mode); collect/template spans dispatched `model="sonnet"` | 3-mode audit pipelines — judgment fail-closed on opus, mechanical collect + templating on sonnet |
|
||
| doc-syncer | sonnet pin; audit mode dispatched `model="opus"` | two-mode: audit (drift judgment, opus) / patch (mechanical apply, sonnet) |
|
||
| handover-doc-writer | sonnet pin; synthesize mode dispatched `model="opus"` | two-mode: synthesize (opus) / render (sonnet) — client deliverable |
|
||
| interviewer, client-handover-writer | unpinned (inline-load = the main loop's model) | they ARE the main loop — a frontmatter pin would be inert |
|
||
| Explore, Plan (built-in) | model-router mod: Explore → sonnet/medium, Plan → opus/xhigh, set at spawn; an explicit `model=` on the call wins; mod off: inherit session | built-ins routed per phase by the mod |
|
||
|
||
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; `/client-handover`'s nested skill-runner
|
||
children are dispatched `model:"fable"` (they carry reflection).
|
||
|
||
## Effort routing (BDR-107, BDR-108)
|
||
|
||
Second axis of the same table: how hard each phase thinks. Session default
|
||
`high`. The live source is `mods/model-router/routing.json`, tracked with the
|
||
model-router mod (below): the phase table and one phase row per repo skill
|
||
and agent, each phase naming a tier and an effort level
|
||
(`plan` best/xhigh, `reflect` best/high, `orchestrate` best/medium,
|
||
`escalate` best/max, `judge` big/xhigh, `audit` best/xhigh, `implement` work/medium, `write`
|
||
work/high, `verify` work/xhigh, `explore` work/medium, `apply` work/low,
|
||
`mechanical` cheap/low). The `model:` and `effort:` frontmatter of every
|
||
typed agent and user-invoked skill stays as the off-state floor, kept equal
|
||
to the rows by the census `lib/tests/effort-routing.test.sh` (a best-tier
|
||
row floors on the tier's second alias, opus, since Fable is credit-gated; a
|
||
row changed through the first-use dialog passes with a `WARN floor drift` line
|
||
until its frontmatter follows): low
|
||
appliers, medium executors, high writers, xhigh judgment and gates;
|
||
`/status` low … `/ship-feature`
|
||
xhigh. The vendored externals (design stack, superpowers, agent-skills,
|
||
MengTo scroll skills, 21st) get their level from their row only.
|
||
Orchestrators declare each phase through the `mcp__model-router__route`
|
||
tool (`lib/effort-shift.md`): `orchestrate` at a dispatch span, `reflect`
|
||
or `plan` when reflection resumes, `apply` at the bookkeeping tail,
|
||
`escalate` at the verify-secure caps. Model pins stay tier aliases
|
||
(`sonnet`, `opus`, `haiku`, `fable`): the latest version of a tier is also
|
||
the cheapest or same-priced, so the quality/price trade-off is tier ×
|
||
effort, never version. Transcript audit `python3 lib/effort-audit.py`.
|
||
|
||
### model-router mod
|
||
|
||
`mods/model-router/` is a Claude Code mod (a function-hooks plugin) that applies this table per request. It loads in every session through the tracked symlink `skills/model-router`, as `model-router@skills-dir`.
|
||
|
||
- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`; `audit` is an agent row, never typed) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` (typed with a name, bare, or picked in the `/model` picker, it asks the scope: this project, this conversation, everywhere) or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. Before main runs on a model, the one it moves to or the one it keeps (the session's own model included), the mod probes it with one small completion bounded to 8 seconds; the step (and `/route show`, the route tool's answer) waits for it. A timeout or an error marks the model down (reason `probe`, held for `cooldownMinutes` like any breaker hold) and the decision is taken again once. A model already marked down is never probed, and a model that answered is not probed again, `/clear` included, until it is marked down. When a lower model stands in for its tier's head held down (Opus for Fable on a best-tier phase), the phase's own effort goes one notch up: `reflect` xhigh, `plan` max, `orchestrate` high, `escalate` stays max. An effort asked explicitly (`/route ... effort=`, the `route` tool's `effort`) or set by a floor is never raised. `/route show` and the route tool's answer print the level with `(opus stands in for fable)`; the verbose transition line names `stand-in` as a cause.
|
||
- Sub-agents: a routed agent gets its row's model at spawn, within its tier and only upward from its frontmatter model, and the row's effort on every step. Explicit `model` / `effort` params on the Agent call win; a project-defined agent of the same name keeps its own definition. Built-ins: Explore runs on sonnet/medium, Plan on opus/xhigh. A built-in `general-purpose` agent that main spawns with no `model` param, while main runs below the session model (a downgrade or a breaker fallback), starts on the session model instead of inheriting the lower one; it is not pinned when the session model is marked down, for a fork, a workflow or a nested spawn, or when a project or user definition shadows the built-in. Other agent types are never pinned this way: the hook cannot see their frontmatter model.
|
||
- Write guard: a main-loop Edit, Write or NotebookEdit of a code file is redirected with "model-router: code is written inside a skill run…" until a skill ran on the main loop in the session (typed or loaded by the model), a phase was declared this turn, or a typed `/route` holds. Free paths: `.md`, `.txt`, the project's `.claude/` except `worktrees/`, and `docs/`. Sub-agents write freely. `/route clear`, `/route off` and `/clear` re-arm the guard; `/route off` also turns it off, and `"enabled": false` in `~/.claude/model-router.json` turns the router and the guard off. A `/model` hand pick does not open it, and a `register.ts` reload resets it.
|
||
- Levers inside a run: `ultrathink` in a prompt sets the turn's minimum effort; `/route effort=max` holds until `/route clear`. Keyword prompt rules (`plan`, `design`, `architecture`… take plan's effort; `why`, `review`, `audit`… reflect's), `ultrathink` and a main Agent dispatch (the derived `orchestrate` route, held until its background agents end) set the turn's effort only, never a model: they never lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a hand pick (`/model`, picker). The built-in `/effort` is not a lever inside a run, rows and routes outrank it.
|
||
- `/model` scope: a pick in the `/model` picker is held first (the engine prints that a hook blocked it), then the same question as `/model <name>` comes. A bare `/model` opens the router's model, variant and scope dialog: fable, opus or sonnet, then Standard or `[1m]`, then the scope, the current model included; `Other model (native picker)` opens the native picker (haiku goes through it or `/model haiku`) and Esc changes nothing. A pick while another dialog is open is refused with `answer the open dialog first`. The picker's Default, an unknown name or a headless run go native, no question. A model chosen in that dialog (a hand pick) always switches: no cold-read cap, no `mainUpgrade` or `mainModelSwitch` flag. A hand pick marked down keeps main where it is until it is back. A native switch (the `/config` Model row included) or `/clear` drops a hand pick; a typed `/route model=` keeps the caps.
|
||
- Prompt classifier: a plain prompt typed in the composer (12 characters or more, not a slash command) that no keyword rule, skill, run slot, `/route` or floor covers is sent to the engine's small fast model, one call, bounded to 3 seconds (the prompt waits for it, typically under a second). The label (`design`, `analysis`, `coding`, `bookkeeping`, `chat`) maps to plan, reflect, implement or apply (`chat` routes nothing), and the turn takes that phase's route: its effort becomes the turn's default, and its model may move the main loop, never above the session model. A `coding` or `bookkeeping` guess moves main down only when `mainModelSwitch` is on and the cold read fits `downgradeMaxTokens`; an `ultrathink` floor in the same turn raises the effort only, the guess's model holds. No dialog opens and no file is written. The route is gone at the end of the turn, a later route call or typed skill replaces it, and a `/effort` you type between turns drops the guess for that turn only. A typed best-tier skill holds its run slot across turns, so nothing is classified there until `/route clear`. Long prompts are sampled (first 500 and last 1500 code points), so pasted text at the end can steer one turn's route. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). Never in a sub-agent, mid-turn or under `-p`. Off per session with `/route classify off`, per machine with `"classify": false`. The status line reads `route: classifier <phase>`; `/route verbose on` adds the transition line.
|
||
- `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `ask-tier on|off` (the ask before Fable, below), `forget <name|all|projects>` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model=<alias|id> effort=<level>`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run <phase>`) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`) and `ask-tier:` (`best`, `best (paused this session)` or `off`). The model sets routes through a `route` tool.
|
||
- First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (fable, opus, sonnet, haiku, each shown with the tier it heads), then the effort among those the phases on that model use (shipped table: fable medium, high, xhigh or max; sonnet low, medium, high or xhigh; opus and haiku have one level each, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus a hint when the main loop holds back a downgrade: `/route switch on` when the switch is off, the cap hold (`held: downgrade skipped: cold read <n> tokens over <cap>`) when the cold read is over `downgradeMaxTokens`. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent.
|
||
- Ask before Fable: before a route lifts the main loop, or sends a rowed agent, onto Fable from another model, the mod asks once per span. The question names the origin (a skill, typed or loaded by the model, an agent, the `route` tool or `/route`), the phase with its `about` line, and the model and effort the step would run on. `Fable` runs it; `Opus instead (big tier)` runs the span through the `big` tier at the phase's own effort, offered only while Opus is up so the label stays true; `Stop asking this session` pauses the question until `/clear`. A best-tier skill the model loads counts as a skill row, and an agent type gets one answer per session. Nothing is asked in a headless (`-p`) run or inside a sub-agent, a dismissed dialog runs Fable, and no answer is written (`confirmed` included). No question comes when the decision would not land on Fable (`mainUpgrade` off, a cold-read cap, the context window, Fable marked down); when such a Fable hold or cap lapses later, main upgrades without asking, as the breaker already does. `askTier` in routing.json (`best`, or `false` to turn it off) is set by `/route ask-tier on|off`, and the machine config wins.
|
||
- Only a first-use dialog answer, `/route ask on|off`, `/route ask-tier on|off` or `/route forget` writes `routing.json`, never the model. Writes are serialized, capped at 64 KiB, and refused when the file is missing (it is never created). Each write leaves the config repo dirty; a toast reminds you to commit it from there. The one other write: `/model <name>`, the bare `/model` dialog or a `/model` picker pick → This project writes the full id as `model` into the session root's `.claude/settings.local.json` (created if absent, keep it gitignored; refused when `.claude` or the file is a link, or the file is over 64 KiB or not a JSON object). Remove its `model` key to undo.
|
||
- The spinner suffix and the status line under the prompt show the route in force; the status line adds ` · switch off` when the downgrade switch is off.
|
||
|
||
Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`, `askTier`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` fable>opus>sonnet, `big` opus>fable>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: the largest cold read a main-loop upgrade may cost), `downgradeMaxTokens` (default 120000: the same cap for a downgrade; the cold read is the context minus what the target model's prompt cache already holds, taken from main's last step on that model within the prompt-cache TTL, forgotten by `/clear` and `/route reload`. The TTL follows the engine's `cache_ttl` (5 or 60 minutes) carried by main's model-switch events, is 60 minutes until the first one and survives `/clear`. The context also counts the prompt just submitted, which the engine's usage may not include yet: code points / 3 of its text, its context entries and a typed skill's body, summed and added at the turn's first main step unless usage already grew by half of it. A `document` attachment makes the size unknown, and an unknown context size blocks the switch; the step, `/route show`, the first-use dialog and the toast read the same adjusted size), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `true`: the main loop may move down to a cheaper model; a value that is not a boolean turns it off and says so), `classify` (default `true`; `false` stops the prompt classifier on that machine), `probe` (default `true`: the model main runs on, moved to or kept, is tried once, 8 seconds at most, before main is sent to it; `false` skips the probe on that machine; a non-boolean value is ignored and said; `/route show` prints `probe:`), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine), `askTier` (overrides routing.json's `askTier` on that machine; `best` or `false`, any other value reads `best` and is said once). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files.
|
||
|
||
Limits: a main-loop switch re-reads cold the part of the context the target model's cache does not hold; a switch whose cold read is over its cap (`upgradeMaxTokens` up, `downgradeMaxTokens` down) is skipped (a `/model` hand pick is exempt) and main keeps its model, and a downgrade also needs `mainModelSwitch`. The prompt estimate is conservative (3 code points per token), so a long pasted prompt can hold back a switch that would have fit. The `/config` Model row still writes user `settings.json` with no scope question; a hand pick is dropped at `/clear`; a scope dialog never answered has no timeout. The hooks send full model ids, so the `models` table has to follow new model versions. A probe costs one small completion per model main runs on, the session's own model included, repeated only after that model is marked down, and holds that step up to 8 seconds when the model does not answer.
|
||
|
||
### Memory capture (memory mod)
|
||
|
||
`mods/memory/` is a second Claude Code mod. It watches Bash failures and milestones so that `/capitalize` starts from what really happened, not from recollection. Writing a registry stays a model draft, your approval and `lib/memory.sh`; the mod never writes one.
|
||
|
||
- Records: a Bash result whose text starts `Exit code N` and whose last line (the first line and the rtk trailer dropped) is an error line. That line must hold a letter and an error-shaped word, else the failure is dropped (no earlier line is tried): a word such as error, fatal, cannot, No such, denied, failed, unexpected, traceback, or a shellcheck code (SC1234); otherwise nothing is stored. The entry is stored redacted: `KEY=value` secrets, Stripe, AWS, GitHub, Slack, SendGrid and Supabase keys, private key blocks, JWTs, Bearer and `Authorization: Basic|token` values, `user:pass@` URLs, `-u`/`--user user:pass` and `--password`; also the Anthropic, OpenAI, GitLab, Google and npm key prefixes and `github_pat_`, `--token`/`--api-key`/`--secret` flags, API-key headers (`X-Api-Key`, `api-key`, `apikey`, any name ending in `api-key` or `api_key`), `PRIVATE-TOKEN`, `Cookie` and `Set-Cookie` headers (to the end of the line), `--cookie` values and `curl -b` cookies, JSON and `key: value` password/token/secret/api-key pairs whose key may carry a prefix or suffix (`access_token`, `db_password`), and a 40-hex token as URL user. Residual: `user:p@ss@host` becomes `<redacted>@ss@host`, so the password's tail after its own `@` stays. Permission refusals, guard redirects and tool_use errors are never captured. A sub-agent failure is marked `(sub-agent)`.
|
||
- Milestones: a successful `feat` or `fix` commit (plain `-m` or heredoc form), a `gitflow.sh finish` (not `finish chore`), a `make test ...` command red then green. Milestones are recorded on the main loop only: sub-agent commits and finishes are ignored.
|
||
- Store: the plugin's `$.store`, keyed by project root: the 3 most recent sessions per project, 50 failures per session, 2 KiB per entry, 1 MiB for the whole store. It survives `/clear`. The store is the plugin's JSON file under the Claude configuration directory (observed here as `~/.claude/plugins/store/memory_skills-dir-<hash>.json`, an engine layout, not fixed by this repo); delete it to wipe the captures.
|
||
- Note: one context line, `memory: <kind> <label> — <n> new failure mode(s) this session; /capitalize when ready.`, at the first composer prompt after a milestone. Never per turn, never at Stop, never in a sub-agent.
|
||
- Tool: `mcp__memory__memory_pending` (deferred: a skill loads it once with `ToolSearch("select:mcp__memory__memory_pending")`). `/capitalize`, `/close` and the CAPITALIZE steps of `/feat`, `/bugfix`, `/hotfix`, `/ship-feature` and `/commit-change` call it first. It lists this session's milestones, then the failures as `NEW` or `known <ID>` (word 4-grams matched against the backticked spans of BLK and LRN entries, superseded ones excluded through `lib/memory.sh index`; when that reader is unavailable every entry is matched and the `index:` line ends `status reader unavailable`), earlier sessions marked. Every text it returns is data. It never writes a registry and never calls `lib/memory.sh`.
|
||
- Recall: the mod hands registry entries back at the moment they matter. A prompt typed in the composer (never a slash command, at least 5 content words, stop words excluded) triggers it when it is the first of a context (start, `/clear`, `/compact`), comes after 30 minutes idle, or holds a design or analysis word (plan, architecture, design, why, explain, analyse, review, audit and their French forms). BM25 ranks the live BDR, LRN and BLK entries, one haiku call keeps at most 3, bounded to 5 seconds. The context block `memory recall:` carries one line per entry (ID, title, lesson), at most 1500 characters per turn, each entry once per context. Any failure or timeout injects nothing.
|
||
- Known error: a Bash failure whose key matches a live BLK or LRN entry attaches `memory: known <ID> <title> — <lesson>` to the tool answer, once per ID per context, from the same 1500-character budget. Sub-agents get this channel only.
|
||
- Digest: `hooks/session-start.sh` prints `memory digest:` on `startup`, `clear` and `compact` (never `resume`) in a project that has `.claude/memory/`: up to 3 open BLK from `memory.sh index blocker` (the rest counted, upstream ones counted), up to 3 unchecked Actionable TODO items, the last journal line, 800 characters at most. When the cap bites, TODO lines drop first, then nothing else. Without `timeout` and `jq` it prints only from a terminal.
|
||
- Recall switch: `{"enabled": true, "recall": false}` in `~/.claude/memory.json` cuts the injections (recall and known-error line) and keeps capture. Each injection is logged under the `l:<root>` store key (last 200 records, 64 KiB), never shown; phase 4d reads it.
|
||
- Recall residuals: measured on 14 days of this repo's transcripts, precision is 54 to 61 % against a 64 % bar, so recall ships on and switchable, and the log decides. The router's classifier label is not used. EVAL entries are not recalled. Each failing command that matches an entry spawns one `memory.sh index`. The haiku bound drops the recalls that answer slower than 5 seconds.
|
||
- Off switch: `{"enabled": false}` in `~/.claude/memory.json`, read at the first event of a session, so it applies at the next session or after `/reload-plugins`. Off, the tool answers `memory capture is off (~/.claude/memory.json)`. A switch file that cannot be read, or whose `enabled` is not a boolean, keeps capture on and logs one line.
|
||
- Residuals: cross-process writes are unverified (two concurrent sessions: last writer wins). Non-Bash failures are not captured. `-b` counts as curl's cookie flag only when `curl` opens its command segment, after optional env assignments, `sudo`, `rtk` or `$(`: `time curl -b …` keeps its cookies. 40-hex Gitea tokens are kept by design: they look like commit SHAs. A session root that moves with `/cd` or a worktree move hides earlier captures of the same repo from /capitalize. A bare `gitflow.sh finish` on a chore branch counts as a milestone. Measured at 83 % noise before the error-shaped filter over 14 days of this repo's transcripts; the filter keeps every useful sample and cuts captures by two thirds (`.claude/tasks/plans/2026-11-03-memory-capture-spike/NOISE.md`).
|
||
|
||
---
|
||
|
||
## Install notes
|
||
|
||
All scripts use their own location to find the repo — run them from anywhere.
|
||
The plugins step logs to `install-YYYYMMDD-HHMMSS.log`.
|
||
The installers fill `skills-external/`; the packs under `skills/pack-*/` link it, on or off per project (`bash ~/.claude/lib/profile.sh set <profile>` from the project, then `/reload-plugins`) or per conversation (`cc <name> <profile>`). `cc` is a shell function from `lib/cc.sh`: add `[ -f "$HOME/.claude/lib/cc.sh" ] && . "$HOME/.claude/lib/cc.sh"` to `~/.bashrc` (`make doctor` warns until it is there).
|
||
|
||
**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
|
||
the `find-docs` skill alone (the generated `rules/context7.md` is purged by
|
||
design; if you run `ctx7 setup` manually, delete that rule or re-run `make plugin`).
|
||
A once-per-session `ctx7-reminder` hook nudges toward it when the current project
|
||
carries fast-moving libs (`lib/fast-libs.sh`) — a scoped second surface, a
|
||
refinement of the single-surface rule, not a reversal.
|
||
|
||
```bash
|
||
ctx7 login # optional: OAuth / API key for higher rate limits
|
||
```
|
||
|
||
---
|
||
|
||
## Installed components
|
||
|
||
| 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** | Git submodule (per profile) | Product workflow skills: plan reviews, design, browser QA, security (`cso`), `health`. Linked by pack-gstack-dev, pack-gstack-browser and pack-gstack-design; 9 broken or doctrine-breaking skills are denylisted in `lib/gstack-removed.list`. | [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** | 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** | 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. 8 skills in `skills-external/21st-*`, linked by pack-design and pack-extras (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`, 61 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`.
|
||
|
||
Graphify installs via **pipx/PyPI only, never npm/npx**: a different publisher
|
||
squats the same `graphifyy` name on npm (version-shadowing shim re-exporting
|
||
a different package, ships its own conflicting `graphify` bin) — see
|
||
`plugins.lock.json`'s `graphifyy` note.
|
||
|
||
---
|
||
|
||
## Slash commands
|
||
|
||
| Command | Description |
|
||
|---|---|
|
||
| `/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: CLAUDE.md, settings, .claudeignore, path rules, archetype audits, report and a sequenced TODO backlog. `/onboard split` moves the path-bound sections of an existing CLAUDE.md into `.claude/rules/` (loaded on Read of a matching file) |
|
||
| `/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) |
|
||
| `/analyze` | Deep factual analysis of code before any modification |
|
||
| `/refactor` | Improve code quality without changing behavior |
|
||
| `/code-clean` | Dead code removal, style/norm enforcement |
|
||
| `/doc` | Documentation audit and sync — detect stale docs, patch |
|
||
| `/seo` | Full SEO/GEO audit — real Search Console + CrUX field data when a Google account is connected (`make seo-connect`) |
|
||
| `/impeccable` | Design verbs (audit, polish, bolder…) + deterministic anti-slop detector (`npx impeccable detect`) |
|
||
| `/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 (auto-push mode, tag on your go; manual push mode: one `! git push --atomic` command you run) |
|
||
| `/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` |
|
||
| `/status` | Consolidated project snapshot — plugins, git, GSD milestone |
|
||
| `/skills-perso` | List personal (user-created) skills |
|
||
| `/audit-delta` | Recurring audit of changes since last run (norms, bugs, dead code, security) |
|
||
| `/capitalize` | Flush uncapitalized context + reconcile TODO before /clear or /compact (`--ritual` adds the end-of-session reflection) |
|
||
| `/prune-memory` | Curate and compress the .claude/memory/ registries |
|
||
| `/reconcile` | Confront declared status (TODO, registries) against real git/fs state — surface stale items |
|
||
| `/pdf-translate` | Translate a PDF to another language, output as HTML (via Vision) |
|
||
| `/explain-diff` | Explain a diff, commit, branch or PR as one self-contained HTML page (background, intuition, code walkthrough, 5-question quiz), saved outside the repo |
|
||
| `/guardrails` | Audit the six baseline guardrails (hosting, Supabase RLS, SMS/email consent, cloud functions, injection, browser exposure) plus API hygiene (auth, CORS, secrets, password storage): deterministic scanner, then judgment, report in `.claude/audits/GUARDRAILS.md`. Then proposes fixes, applies the ones you accept and re-scans to prove each one. `--live <url you own>` adds a read-only probe that confirms a hole from outside (routes, CORS, rate limit, and against a production build: source maps served, error bodies, sensitive keys) |
|
||
| `/a11y` | Accessibility baseline: keyboard reachability with a visible focus, an alt on every image, a label on every field. Deterministic scanner, Tab walk on `--live`, report in `.claude/audits/A11Y.md`, fixes proposed with the wording as your choice, applied on acceptance and re-scanned to prove them. Full WCAG → `/web-validate` |
|
||
| `/close` | End-of-session ritual — alias for `/capitalize --ritual` (dedup + TODO reconcile + 3-question reflection) |
|
||
| `/harden` | Web hardening audit — HTTPS/TLS, HSTS, CSP, security headers |
|
||
| `/web-validate` | W3C HTML/CSS validity + WCAG 2.1 conformance audit (keyboard/alt/label basics → /a11y) |
|
||
| `/geo` | GEO-only audit — AI-search visibility (ChatGPT, Perplexity, Claude, Gemini…) |
|
||
| `/client-handover` | Final project delivery — audits + branded deliverable (Markdown / HTML / PDF) |
|
||
| `/profile` | Set this project's pack profile (`set <n>`, `enable <pack>`), show the effective one (`current`) |
|
||
| `/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) |
|
||
| `/route` | model-router mod: show or set the main-loop route (show, clear, off, on, reload, pending, ask on\|off, <phase>, model=… effort=…, switch on\|off, classify on\|off, verbose on\|off: transitions only) |
|
||
|
||
> This table lists personal skills. `/seo` and `/geo` (pack-seo), `/web-validate`
|
||
> (pack-web-validate) and `/site-motion` (pack-design) live in packs: a profile that
|
||
> leaves the pack off hides them (`/profile current`). Gstack skills (investigate,
|
||
> review, retro, office-hours, cso…) and marketplace plugins add many more; run
|
||
> `/skills-perso` to list your hand-written skills, or browse `skills/` and
|
||
> `skills/pack-*/skills/`.
|
||
|
||
---
|
||
|
||
## Three core workflows
|
||
|
||
### From scratch — `/init-project`
|
||
|
||
```
|
||
/plugin-check "description" # configure plugins (also runs as STEP 0)
|
||
/init-project "description" # interview → scaffold → implement → review
|
||
/ship-feature "next feature" # ship feature by feature
|
||
```
|
||
|
||
### Existing project — `/onboard`
|
||
|
||
```
|
||
cd my-existing-project/
|
||
/onboard # generates CLAUDE.md + settings + .claudeignore
|
||
/plugin-check "project type"
|
||
/ship-feature "next feature"
|
||
```
|
||
|
||
### New feature — `/ship-feature`
|
||
|
||
```
|
||
/ship-feature "feature description"
|
||
# → 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: 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.
|
||
|
||
---
|
||
|
||
## Settings and permissions
|
||
|
||
Settings follow a hierarchy (highest priority first):
|
||
|
||
```
|
||
managed-settings.json → enterprise (cannot be overridden)
|
||
CLI flags → session only
|
||
.claude/settings.local.json → personal machine overrides (gitignored)
|
||
.claude/settings.json → project rules (committed)
|
||
~/.claude/settings.json → global user rules (this repo)
|
||
```
|
||
|
||
DENY always wins over ALLOW at any level. `.claudeignore` applies independently.
|
||
|
||
Templates for per-project settings are in `templates/settings/`. Copy them with `/onboard` or manually:
|
||
```bash
|
||
CONF="$(dirname "$(readlink ~/.claude/CLAUDE.md)")"
|
||
cp "$CONF/templates/settings/settings.json" .claude/settings.json
|
||
cp "$CONF/templates/settings/.claudeignore" .claudeignore
|
||
```
|
||
|
||
See [`templates/settings/SETTINGS.md`](templates/settings/SETTINGS.md) for the full rule syntax reference (rule types, patterns, `defaultMode` values).
|
||
|
||
---
|
||
|
||
## Adding an MCP server that needs a secret
|
||
|
||
`claude mcp add <name> --env KEY=VALUE ...` writes `VALUE` **literally** into
|
||
`~/.claude.json` (or the project's `.mcp.json`) — if you pass the real secret
|
||
on that command line, it materializes as a second plaintext copy outside
|
||
`~/.claude/.env`, invisible to the repo's `.gitignore`/allowlist reach (this
|
||
bit us once).
|
||
|
||
Claude Code expands `${VAR}` and `${VAR:-default}` in `mcpServers` config —
|
||
in `env`, `command`, `args`, `url`, and `headers` — for both project (`.mcp.json`)
|
||
and user (`~/.claude.json`) scope. Use that instead of a literal value:
|
||
|
||
```bash
|
||
# single-quoted so bash doesn't expand it; Claude Code expands it at
|
||
# launch, reading the var from its own process environment:
|
||
claude mcp add <name> --scope user --env 'API_KEY=${SOME_API_KEY}' -- <command>
|
||
```
|
||
|
||
The var still has to exist in the **environment of the process that starts
|
||
`claude`** — sourcing `~/.claude/.env` into your everyday interactive shell
|
||
would defeat the point (every subprocess, every stray `env`/`printenv`, would
|
||
then see it). Wrap the `claude` command instead: a `claude()` shell function
|
||
that sources `~/.claude/.env` into a subshell and `exec`s the real binary, so
|
||
the var reaches `claude` and its children only, never the ambient shell.
|
||
|
||
This config registers no MCP server today. The pattern stays documented for
|
||
the next one that needs a secret.
|
||
|
||
There is no `claude mcp add` flag that writes the reference form for you —
|
||
the `${VAR}` syntax has to be typed by hand (or via a wrapper script), same as
|
||
above.
|
||
|
||
### SEO data layer (`/seo` FULL) — Google OAuth + CrUX keys
|
||
|
||
The same `~/.claude/.env` also feeds `lib/seo-data`, which pulls real Google
|
||
Search Console and Chrome UX Report data into `/seo` FULL audits. Add these
|
||
three vars (template with the GCP console steps in `.env.example`):
|
||
|
||
```bash
|
||
# OAuth Desktop client — GCP console → APIs & Services → Credentials →
|
||
# OAuth client (Desktop). Consent scope: webmasters.readonly only.
|
||
GOOGLE_OAUTH_CLIENT_ID=<your-client-id.apps.googleusercontent.com>
|
||
GOOGLE_OAUTH_CLIENT_SECRET=<your-client-secret>
|
||
# CrUX + PageSpeed API key — GCP console → Credentials → API key,
|
||
# restricted to those two APIs. https://developer.chrome.com/docs/crux/api
|
||
CRUX_API_KEY=<your-crux-api-key>
|
||
```
|
||
|
||
Then run the one-time consent flow: `make seo-connect` (per-label token
|
||
store, multi-site safe). Missing credentials never break an audit — `/seo`
|
||
degrades gracefully to anonymous PageSpeed lab data.
|
||
|
||
### 21st.dev CLI
|
||
|
||
`@21st-dev/cli` (bin `21st`) is the 21st.dev integration; it replaced the
|
||
former Magic MCP server this config used to register. Same endpoint, one
|
||
browser login, no API key, and nothing loaded into a session that isn't using
|
||
it:
|
||
|
||
```bash
|
||
npm i -g @21st-dev/cli
|
||
21st login # browser flow, token saved in ~/.config/21st
|
||
```
|
||
|
||
`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
|
||
publishing skills `-registry`, `-design-sync` and `-video`. `21st-ui-build`
|
||
and `21st-cli-use` sit in pack-design (on under `full`, `design` and
|
||
`web`). `-ui-explore`, `-ui-review` and `-ai` sit in pack-extras (on
|
||
under `max`, or after `bash ~/.claude/lib/profile.sh enable extras` in the project). `-registry`,
|
||
`-design-sync` and `-video` stay unlinked in `skills-external/`.
|
||
|
||
The pack is machine-owned and gitignored. It cannot be installed the way
|
||
upstream documents it (`21st install-skill`, i.e. `21st skills install
|
||
--global`): that writes into `~/.claude/skills/`, and the installer refuses to
|
||
follow a symlink anywhere on that path, while `~/.claude/skills` is itself a
|
||
symlink to this repo's `skills/`. So the install runs under a throwaway `HOME`
|
||
and the result is moved into `skills-external/21st-*`, where
|
||
the pack symlinks reach it.
|
||
|
||
The permission gate is now one `autoMode.soft_deny` entry covering the
|
||
outward-facing verbs (`21st publish*`, `submit`, `edit`, `delete`,
|
||
`remove-from-catalog`, `profile set|upload`), because publishing a component
|
||
puts it on a public listing under your account. That tier rather than `ask`:
|
||
an ask prompt can be clicked through by reflex, and the soft_deny also covers
|
||
scripted forms.
|
||
|
||
### Static rule limits
|
||
|
||
`ask` rules raise a permission prompt under `defaultMode: auto` (headless
|
||
bench `.claude/tasks/plans/2026-11-02-phase2-bench/`, confirmed interactively
|
||
on 2026-11-02). The matcher sees through `&&`, `;`, `|`, `env`, `timeout`,
|
||
`xargs` and simple assignments. The phase 2 rules ask on `sh -c` and its flag
|
||
forms (`sh -ec`, `bash -lc`, `dash -c`), a bare `bash` or `sh` fed by a
|
||
heredoc, process substitution (`bash <(…)`) and the absolute shells `/bin/sh`,
|
||
`/bin/bash`, `/usr/bin/sh`, `/usr/bin/bash`, `/usr/bin/env sh|bash`. A script
|
||
piped into a shell (`… | bash -s`) is already refused by the deny
|
||
`Bash(* | bash -*)`. A sourced `gitflow_finish` and `git -C <dir> merge`
|
||
escape the static rules. The matcher cannot see `$(…)` in command position, a
|
||
quoted literal argument or an inline interpreter: those rest on the
|
||
auto-mode classifier (`autoMode.soft_deny`, "Static rule blind spots"). The
|
||
rtk hook passes any command its registry asks about or denies through
|
||
unrewritten, so the native rules judge it as typed.
|
||
|
||
### Higgsfield CLI
|
||
|
||
`@higgsfield/cli` (bins `higgsfield` and `higgs`) generates images, video,
|
||
audio and brand media from the terminal. One browser login, no API key.
|
||
Generation spends account credits.
|
||
|
||
```bash
|
||
npm i -g @higgsfield/cli
|
||
higgsfield auth login # browser flow
|
||
```
|
||
|
||
`make plugin` does both (Step 8.6 installs the CLI, then offers the login in
|
||
an interactive terminal) and clones the skills of
|
||
[higgsfield-ai/skills](https://github.com/higgsfield-ai/skills) into
|
||
`skills-external/higgsfield-*`. `make update` refreshes the skills, and the
|
||
CLI when npm installed it; `make doctor` reports the CLI and its session.
|
||
The copies are machine-owned and gitignored. They follow upstream `main`,
|
||
so a prompt change arrives with no diff to review, and a skill that
|
||
upstream removes keeps its last local copy.
|
||
|
||
The pack is off by default and on in `max` only. It costs nothing until
|
||
you ask for it:
|
||
|
||
```bash
|
||
bash ~/.claude/lib/profile.sh enable higgsfield # from the project, then /reload-plugins
|
||
bash ~/.claude/lib/profile.sh disable higgsfield
|
||
```
|
||
|
||
The pack (`skills/pack-higgsfield/skills/`) holds the 8 `higgsfield-*`
|
||
skills.
|
||
|
||
`higgsfield-websites` is one of them. It helps with landing pages inside the
|
||
design stack (assets, references), and `higgsfield website
|
||
create|deploy|publish` stays unused. Claude runs `bash ~/.claude/lib/profile.sh enable higgsfield` on
|
||
a named media ask, then `/reload-plugins` (Skill routing in `CLAUDE.global.md`) and checks the price
|
||
with `higgsfield generate cost` before a paid run.
|
||
|
||
The skills are cloned, not installed with `npx skills add`: that installer
|
||
links every skill into `~/.claude/skills` on each refresh, which would undo
|
||
the off-by-default state.
|
||
|
||
After the first login, select a workspace once: `higgsfield workspace list`,
|
||
then `higgsfield workspace set <id>`. Until then the account commands answer
|
||
"No workspace selected", even though the session is active.
|
||
|
||
The package ships its binary through a postinstall script. If npm holds that
|
||
script back, `higgsfield` exists on PATH and fails at once; reinstall with
|
||
`npm install -g --allow-scripts=@higgsfield/cli @higgsfield/cli`.
|
||
|
||
---
|
||
|
||
## Diagnostic and maintenance
|
||
|
||
```bash
|
||
# Terminal
|
||
bash doctor.sh # full diagnostic (symlinks, plugins, permissions, token budget)
|
||
bash update-all.sh # update all components (CLI, plugins, submodules, symlinks)
|
||
|
||
# Claude Code
|
||
/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
|
||
|
||
# Makefile (from repo directory)
|
||
make install # bootstrap: CLI + auth + symlinks + plugins
|
||
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 [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" dir=/path/to/project # activate a skill profile (web/seo/full/max/design/dev/qa/audit/minimal)
|
||
make profile-list # list skill profiles
|
||
make profile-current dir=/path/to/project # effective profile of this project and conversation
|
||
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`), packs (census), profiles, Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency, git hooks (global core.hooksPath + generated githooks/), mods (loading link and `@skills-dir` state), scratchpad (TMPDIR quota), Higgsfield CLI and session, seo-data layer, auto memory (`autoMemoryEnabled` false in `settings.json`, leftover files under `~/.claude/projects/*/memory/`).
|
||
|
||
---
|
||
|
||
## Going further
|
||
|
||
[`USAGE.md`](./USAGE.md) — workflows and skill decision tree ·
|
||
[`ARCHITECTURE.md`](./ARCHITECTURE.md) — layout and principles ·
|
||
[`CHANGELOG.md`](./CHANGELOG.md) — version history ·
|
||
[`MIGRATION.md`](./MIGRATION.md): upgrade guides ·
|
||
[`templates/settings/SETTINGS.md`](templates/settings/SETTINGS.md): permission tiers and guardrails
|
||
|
||
## License
|
||
|
||
MIT, see [LICENSE](./LICENSE).
|