docs(spec): phase 5 profiles and packs design + contract clarifications

This commit is contained in:
bchanot committed 2026-11-01 20:25:31 +01:00
1 parent a526bc792a
commit 2c08307c20
2 files changed
+338

No files matched your search

@@ -0,0 +1,25 @@
# CONTRACT — phase5-profiles-packs
## REQUEST (verbatim — IMMUTABLE)
Phase 5 of the context mod queue (BDR-125): per-project and per-conversation profiles, native packs. Full definition in .claude/tasks/TODO.md lines 73-84 (facts measured 2026-10-24/25, user answers 2026-10-25, packs as skills-dir plugins `skills/pack-<name>/`, profiles `lib/profiles/<name>.json` with `enabledPlugins` + `model`, `profile.sh set` writes `.claude/settings.local.json`, per-conversation `claude --settings`, detection via /plugin-check, mid-skill pack gates, listing budget after the packs, proof with concurrent conversations and canaries, cleanup list). User instruction for this run: run the FOUR SPIKES first, before any plan or design: (1) nested skills in a pack (a skills-dir plugin with `skills/<skill>/SKILL.md` loads each skill once, short name and `<plugin>:<name>`); (2) `/reload-plugins` after a settings change loads a pack mid-session; (3) claude.ai connectors per project (interactive only; they do not load under `-p`); (4) higgsfield MCP in a pack `.mcp.json`. Each spike = a measured fact in a scratch project, headless where possible, interactive where the user must run the probe. Only then brainstorm and plan. CLI 2.1.316. Default model opus; Fable credits exhausted: pin verifier, security-auditor and challengers on opus.
## CLARIFICATIONS
- Spike facts 2026-11-01 (headless, CLI 2.1.316; scratchpad p5/FACTS.md, copied into the plan): skills-dir packs load ON by default; nested skills listed once as `<pack>:<skill>`, both names invoke; `--settings` false beats local true; `/reload-plugins` works in `-p` and reloads skills + hooks mid-session after a settings edit, pack `.mcp.json` servers need a new session; claude.ai connectors DO load under `-p` now (changed since 2026-10-25), `--strict-mcp-config` drops them per conversation; a pack `.mcp.json` HTTP server is registered as `plugin:<pack>:<server>` and needs an interactive OAuth login.
- Spike 3 closed 2026-11-01 (measured F0-F5 + docs settings-reference): per project, `.claude/settings.local.json` `deniedMcpServers:[{serverName:"claude.ai <Name>"}]` drops the named connectors (199 → 192 tools for Gmail + Higgsfield AI) and `disableClaudeAiConnectors:true` drops all nine (26 tools, model-router kept); the same two keys via `--settings` work per conversation; a `serverUrl` wildcard matches no connector (no URL exposed); `disableClaudeAiConnectors` is any-source-true; the native `/mcp` toggle writes `disabledMcpServers` per project into `~/.claude.json` (untested, interactive only). Docs, not measured: `/reload-plugins` re-reads `enabledPlugins` from every settings file; `--plugin-dir` loads a pack as `<name>@inline` for one session; the skills-dir id is the manifest `name`.
- Spikes 1b/1c/2b 2026-11-01 (headless): a pack manifest `defaultEnabled:false` is OFF with nothing written (local or `--settings` true turns it on); the typed short slash `/<skill>` on a pack skill expands like `/<pack>:<skill>`; in a `--settings` conversation `/reload-plugins` re-reads neither the flag file nor a local true over a flag false, so a pack OFF by flag only comes back through a relaunch.
- Brainstorm answers 2026-11-01 (user): no profile = `full` (packs ON, connectors present, as today); gstack split in three packs (dev / browser / design); both higgsfield connectors denied by `deniedMcpServers` in every profile except design, web, web-full, full, max; launcher `cc <name> [profile]` as a function in `lib/cc.sh` sourced from `~/.bashrc` (user step), exporting `CLAUDE_PROFILE`, `CLAUDE_PROFILE_SETTINGS`, `TMPDIR` and running `claude --settings`; approach A = tracked packs `skills/pack-<n>/` (relative symlinks into `skills-external/`, five real dirs moved), profiles as literal settings fragments `lib/profiles/<n>.json`; `profile.sh current --plain` is the single truth for gates, hooks and statusline (supersedes BDR-024); a backend/dev profile still gets the design proposal mid-skill (`set web` / `enable design` + `/reload-plugins`, or relaunch when the source is the flag); listing budget measured last. Spec: `docs/superpowers/specs/2026-11-01-phase5-profiles-packs-design.md` (sections 1-9 approved in chat).
- Design-derived criteria are appended at STEP 3 `[gated]`.
## ACCEPTANCE CRITERIA
1. The four spikes are recorded as measured facts (method, command, result) in the plan file, and the ones that changed since 2026-10-25 are named (connectors under `-p`).
2. (design-derived criteria pending STEP 3)
## FILE SCOPE (seed from the read-before; final at STEP 3)
- lib/profile.sh, lib/profiles/*, lib/toggle-external.sh, lib/gstack-removed.sh, lib/higgsfield-skills.sh
- skills/pack-*/ (new), skills/profile/SKILL.md, skills/plugin-check/SKILL.md
- agents/plugin-probe.md, agents/plugin-advisor.md, lib/plugin-gate.md, lib/design-gate.md, lib/design-tool-gate.sh
- hooks/session-start.sh, hooks/statusline.sh, lib/detect-plugins.sh, doctor.sh, lib/doctor-vendored.sh
- install-plugins.sh, update-all.sh, link.sh, Makefile, settings.json (`enabledPlugins`, `env`)
- mods/model-router/routing.json
- lib/tests/profile-*.test.sh, gstack-removed.test.sh, toggle-external-repo-resolution.test.sh, higgsfield.test.sh, design-tool-gate.test.sh, effort-routing.test.sh, model-routing.test.sh, seo-geo-contract.test.sh, lib/skill-routing-census.py
- CLAUDE.global.md, README.md, USAGE.md, MIGRATION.md, ARCHITECTURE.md, CHANGELOG.md
@@ -0,0 +1,313 @@
# Phase 5: profiles per project and per conversation, native packs
Date 2026-11-01. Branch `feature/phase5-profiles-packs`. Contract
`.claude/tasks/contracts/2026-11-01-phase5-profiles-packs-1300.md`.
Measured facts: scratchpad `p5/FACTS.md` (copied into the plan).
Supersedes BDR-030, BDR-079, part of BDR-101; amends BDR-024/025, BDR-109.
## 0. Intent
One `~/.claude` serves every project and every open conversation. Today the
heavy skill groups (design, gstack, seo, higgsfield, 21st…) are switched
globally: a `skills/` ↔ `skills-disabled/` symlink move plus user-scope
`claude plugin enable|disable`, driven by `lib/profile.sh` and a
`.active-profile` marker. Switching for one project changes every other open
session, and the listing of ~124 skills costs context in every conversation.
After this phase the heavy groups are skills-dir plugins (packs) switched by
`enabledPlugins`: per project through `.claude/settings.local.json`, per
conversation through `claude --settings <profile>.json`. Two conversations in
the same project can hold different packs. Nothing is ever written to the
user scope. The global symlink mode is deleted.
Decisions already taken with the user (2026-10-25 and 2026-11-01): no
profile = `full` (packs ON, as today); gstack split in three packs;
higgsfield connectors denied outside design/web profiles; launcher
`cc <name> [profile]` in `lib/cc.sh`; approach A (tracked packs, profile
fragments, exported flag).
## 1. Packs
A pack is `skills/pack-<n>/` with `.claude-plugin/plugin.json`
(`"name": "pack-<n>"`, `defaultEnabled` as below) and `skills/<s>/` entries.
Claude Code loads it as `pack-<n>@skills-dir`; its skills are listed once as
`pack-<n>:<s>`; `Skill(<s>)`, `Skill(pack-<n>:<s>)`, typed `/<s>` and
`/pack-<n>:<s>` all resolve (spikes 1, 1c). A pack with
`defaultEnabled: false` is OFF with nothing written anywhere (spike 1b).
Each `skills/pack-<n>/skills/<s>` is either a relative symlink
`../../../skills-external/<s>` (or `../../../skills-external/gstack/<s>` for
gstack, a submodule) committed to git, or the skill's real directory moved
with `git mv` from `skills/<s>` (seo, geo, web-validate, site-motion,
impeccable). Installers (`install-plugins.sh`, `update-all.sh`,
`lib/higgsfield-skills.sh`, the gstack and 21st installers) fill
`skills-external/` only; they never create or move a symlink in `skills/`.
| Pack | Skills | Default |
|---|---|---|
| design | impeccable, emil-design-eng, frontend-design, design-motion-principles, 21st-ui-build, 21st-cli-use, site-motion | ON |
| scroll3d | scroll-world-storytelling, build-threejs-scroll-worlds, scroll-scrubbed-visual-sequence, scroll-scrubbed-word-reveal, scroll-progress-timeline | ON |
| seo | seo, geo | ON |
| web-validate | web-validate | ON |
| gstack-dev | review, investigate, codex, cso, health, freeze, unfreeze, retro, spec, skillify, office-hours, plan-eng-review, plan-ceo-review, plan-devex-review, document-release | ON |
| gstack-browser | browse, open-gstack-browser, setup-browser-cookies, scrape, qa, qa-only, benchmark, canary | ON |
| gstack-design | design-review, design-consultation, design-html, plan-design-review | ON |
| higgsfield | the 8 `higgsfield-*` skills | OFF |
| extras | diagram, make-pdf, 21st-ai, 21st-ui-explore, 21st-ui-review | OFF |
Core stays flat in `skills/`: the personal skills, the vendored superpowers
set, the agent-skills trio, `model-router` (already a skills-dir plugin),
`darwin-skill`. Agents stay global. `lib/gstack-removed.sh` keeps naming the
nine gstack skills retired by BDR-117; none of them enters a pack.
`skills-disabled/` is deleted. `.gitignore` loses its ~100 `skills/<x>` lines
(the pack symlinks are tracked) and the `skills-disabled/` line;
`skills-external/*` stays ignored except the vendored entries and the gstack
submodule. A pack symlink whose target is absent: red in `make test` and in
doctor when the pack is ON by manifest; a doctor warning when the pack is
OFF and its installer has not run.
## 2. Profiles
`lib/profiles/<n>.json` is a literal settings fragment, usable verbatim as
`claude --settings <file>`. `dev.json` in full:
```json
{
"enabledPlugins": {
"model-router@skills-dir": true,
"pack-design@skills-dir": false,
"pack-scroll3d@skills-dir": false,
"pack-seo@skills-dir": false,
"pack-web-validate@skills-dir": false,
"pack-gstack-dev@skills-dir": true,
"pack-gstack-browser@skills-dir": false,
"pack-gstack-design@skills-dir": false,
"pack-higgsfield@skills-dir": false,
"pack-extras@skills-dir": false,
"ui-ux-pro-max@ui-ux-pro-max-skill": false,
"security-guidance@claude-code-plugins": true,
"pr-review-toolkit@claude-code-plugins": false,
"example-skills@anthropic-agent-skills": false,
"brightdata-plugin@synced": false
},
"deniedMcpServers": [
{"serverName": "claude.ai higgsfield"},
{"serverName": "claude.ai Higgsfield AI"}
]
}
```
A profile may add `"model": "<alias>"` as a third key.
Every profile lists every pack and every managed plugin (`model-router`,
`ui-ux-pro-max@ui-ux-pro-max-skill`, `security-guidance@claude-code-plugins`,
`pr-review-toolkit@claude-code-plugins`, `example-skills@…`,
`brightdata-plugin@synced`) explicitly, so a profile set after another leaves
nothing behind. `model-router` and `security-guidance` are true in every
profile, `minimal` included; `example-skills` and `brightdata-plugin` are
false in every profile. `model` is optional; no shipped profile carries one
(the key exists for the user's own profiles). `deniedMcpServers` names both
higgsfield connectors in every profile except design, web, web-full, full
and max, where the key is absent. Descriptions live in
`lib/profiles/README.md`, not in the JSON.
| Profile | Packs ON (plus core) | ui-ux-pro-max | pr-review-toolkit |
|---|---|---|---|
| full | all except higgsfield, extras | on | off |
| max | all | on | on |
| minimal | none | off | off |
| dev, backend | gstack-dev | off | off |
| design | design, scroll3d, gstack-design, gstack-browser | on | off |
| web | design, scroll3d, web-validate, gstack-design, gstack-browser, gstack-dev | on | off |
| web-full | web + seo | on | off |
| seo | seo, web-validate, gstack-browser, gstack-dev | off | off |
| qa | gstack-browser, web-validate | off | off |
| audit | seo, web-validate, gstack-dev, gstack-browser | off | on |
A project with no profile runs the manifest defaults, which equal `full`
minus the connector deny (higgsfield connectors present, as today).
### `lib/profile.sh` verbs
- `list`: names + one-line description from the README.
- `show <n>`: the fragment's packs ON/OFF, denied connectors, model; a pack
named in the fragment with no `skills/pack-<n>/` directory is marked
`missing`.
- `current [--plain]`: the effective state of THIS project and conversation.
Reads, in precedence order, `$CLAUDE_PROFILE_SETTINGS` (the `--settings`
file exported by `cc`), `.claude/settings.local.json`,
`.claude/settings.json`, `~/.claude/settings.json`, merging per key
(higher source wins, `disableClaudeAiConnectors` any-source-true); then
`disabledMcpServers` for this project path in `~/.claude.json`. Matches
the effective packs + denies against the fragments: a match prints the
profile name, else `custom`; `disabledMcpServers` non-empty prints
`custom (off: <names>)`. `--plain` prints one `key=value` per line:
`profile=<n>|custom|none`, `source=flag|local|default`,
`pack-<n>=on|off` for every pack, `plugin:<id>=on|off` for every managed
plugin, `connector:<name>=denied` per denied connector, `model=<m|->`.
`--plain` is the single truth for every gate, hook and statusline
(supersedes BDR-024 `show --plain`). Limit: `source=flag` is known only
through the variable `cc` exports; a `claude --settings` launched by hand
reads as `local` or `default` (said in USAGE).
- `set <n>`: merges the fragment's `enabledPlugins`, `deniedMcpServers` and
`model` (when present) into `.claude/settings.local.json`, keeping every
other key (`permissions`, a `/model` project write…). Refuses outside a
project root (no `CLAUDE.md` and no `.git`), on an unreadable or invalid
local JSON (rc 2, file untouched), on an unknown profile (list + rc 2).
Prints what changed and `/reload-plugins` as the next step.
- `unset`: removes from the local file the `enabledPlugins` ids and the
`deniedMcpServers` names any fragment manages; removes `model` only when
the local value equals the model of the profile `current` detects.
- `enable <pack>` / `disable <pack>`: one `enabledPlugins` id in the local
file, same refusals as `set`.
- `diff <n>`: the effective state against the fragment, per key.
Removed: `apply`, `reset`, `gstack on|off`, `show --plain`, `.active-profile`,
`DEFAULT_PROFILE`, every symlink move, every `claude plugin enable|disable`.
## 3. `lib/cc.sh` launcher
`cc <name> [profile]` replaces `dtach_claude` in `~/.bashrc`; the user adds
`. ~/.claude/lib/cc.sh` to `.bashrc` (documented in MIGRATION.md, checked by
doctor). Without a profile it does what `dtach_claude` does today. With one:
1. `lib/profiles/<profile>.json` absent → print the list, return 2, no
session.
2. Export `CLAUDE_PROFILE=<profile>`,
`CLAUDE_PROFILE_SETTINGS=$HOME/.claude/lib/profiles/<profile>.json`,
`TMPDIR=$HOME/.cache/claude-tmp` (created; exported with or without a
profile; closes BLK-021 / TODO line 145).
3. `systemd-run --user --scope` + `dtach -c "$HOME/.dtach/<name>"` + the
`.env` sourcing, then `exec claude --settings "$CLAUDE_PROFILE_SETTINGS"`.
The scope inherits the exported variables; the test proves it.
`lib/tests/cc.test.sh` runs `cc` with PATH shims for `systemd-run`, `dtach`
and `claude` (each shim drops its own options, execs the command that
follows, and the last records argv + env to a
file): asserts the `--settings` path, the three variables, rc 2 on an unknown
profile and no `claude` call in that case.
A `--settings` conversation is frozen: the flag is read once at startup and
`/reload-plugins` keeps it (spike 2b). A pack OFF in the flag file cannot be
turned on in that conversation; the remedy is `cc <name> <other profile>`.
## 4. Gates, hooks, detection
- `lib/design-tool-gate.sh`: needs `pack-design=on`, `pack-gstack-design=on`
and `plugin:ui-ux-pro-max@ui-ux-pro-max-skill=on` from `current --plain`;
the `21st login` SIGN-IN check stays. INCOMPLETE with `source=flag` →
"relaunch: `cc <name> web`"; otherwise → "`bash ~/.claude/lib/profile.sh set
web` (or `enable design`), then `/reload-plugins`". No `skills/` file check.
- `lib/plugin-gate.md`, `agents/plugin-advisor.md`, `agents/plugin-probe.md`:
probe = `current --plain`; the advisor maps its canonical profile to a
`lib/profiles` name; PROPOSED CHANGES = `profile.sh set <n>` or
`enable <pack>`, written only on consent, never user scope; in a
`--settings` conversation a missing pack is reported as "relaunch", never
written.
- `lib/design-gate.md`: the same remedy text; `/profile design` becomes the
two forms above.
- `hooks/session-start.sh`: one line `profile: <n> (local|conv)` or
`profile: none (full) · /plugin-check proposes one`. The banner hint
"/plugin-check before starting a new project" is deleted.
- `hooks/statusline.sh`: reads `current --plain`, shows `<n>` and `(conv)`
when `source=flag`. One call per refresh, no network, under 50 ms.
- `doctor.sh`: pack symlink targets (red ON / warn OFF), every manifest
parses and its `name` equals the folder, every profile JSON parses and
names only existing packs, `~/.bashrc` sources `lib/cc.sh`,
`settings.json` `model` is `opus`.
- `skills/profile/SKILL.md`: rewritten around `set`/`enable`/`disable`/
`current`, the relaunch rule, and "a `--settings` file edited mid-session
has no effect".
- `make profile*` targets follow the verbs; `profile-reset` is deleted.
## 5. Listing budget (last task, after the proof)
Re-run the ctxprobe bench (2026-10-25: 124 skills, 46 name-only at the
default budget; 60000 → 0 name-only for +5.7k tokens) on `full` and `dev`.
Names are longer now (`pack-gstack-browser:open-gstack-browser`), so the
number is measured again. Set `SLASH_COMMAND_TOOL_CHAR_BUDGET` in
`settings.json` `env` to the smallest value leaving 0 name-only on `full`;
record the cost per profile in CHANGELOG.
## 6. Cleanup and registers
Deleted: `skills-disabled/` (24 symlinks, `git rm` on literal paths),
`lib/toggle-external.sh`, `lib/tests/higgsfield.test.sh`,
`lib/tests/toggle-external-repo-resolution.test.sh`,
`lib/profiles/*.profile`, `.active-profile`, the `.gitignore` `skills/<x>`
block, the banner hint.
Rewritten: `lib/profile.sh`, `skills/profile/SKILL.md`, `lib/plugin-gate.md`,
`lib/design-gate.md`, `lib/design-tool-gate.sh`, `agents/plugin-probe.md`,
`agents/plugin-advisor.md`, `install-plugins.sh`, `update-all.sh`,
`lib/higgsfield-skills.sh`, the gstack and 21st installers,
`hooks/session-start.sh`, `hooks/statusline.sh`, `doctor.sh`, `Makefile`,
`lib/skill-routing-census.py` (adds the glob
`skills/pack-*/skills/*/SKILL.md`), the tests `profile-census`,
`profile-default`, `profile-set-managed`, `gstack-removed`,
`design-tool-gate`, and `design-toolchain-reminder` and `gstack-links` where
they read the old layout.
Docs: CLAUDE.global.md (the "toggle-external.sh enable higgsfield" lines
become "`bash ~/.claude/lib/profile.sh enable higgsfield`, then
`/reload-plugins`"; the higgsfield routing and the "max only" note on
21st-ai/ui-explore/ui-review stay), README, USAGE, MIGRATION (the `.bashrc`
line), ARCHITECTURE, CHANGELOG. Every citer of a changed rule, label or
path is patched in the same commit (doctrine-citers census).
Registers: one phase-5 BDR superseding BDR-030 (gstack on demand via
symlinks), BDR-079 (`set` symmetric on externals and MCPs) and BDR-101 for
the mechanism (full by default stays the policy, the manifest is the
mechanism); amends BDR-024/025 (`show --plain` → `current --plain`) and
BDR-109 (the two higgsfield toggles → pack OFF + `enable`; the npm CLI
unchanged). BDR-126/127/132 stay: `/model` project scope writes the same
`model` key of `settings.local.json`; `profile.sh set` replaces it only when
the profile carries one; `current` prints the source.
## 7. Proof
Hermetic, `make test`:
- `profile.sh set` merges and keeps other keys, refuses invalid JSON,
refuses outside a project root; `current` on the four precedence levels
and on `disabledMcpServers`; `enable`/`disable`/`unset`.
- `cc.sh` with the fake `claude` (§3).
- Pack census: every pack dir has a manifest whose `name` is the folder,
every symlink resolves or is on an OFF pack, no skill listed twice across
packs and core, the nine retired gstack skills absent, zero citations of
`~/.claude/skills/<moved skill>` for the five moved skills, zero of
`skills-disabled/` or `toggle-external.sh` outside CHANGELOG, MIGRATION,
`.claude/memory/` and `.claude/tasks/` (append-only history).
- `design-tool-gate` driven by `current --plain` fixtures.
- Routing: every row of `mods/model-router/routing.json` still names a skill
present in core or a pack. Verified first in the plan: a headless canary on
`turnMain.source` shows whether the harness reports `pack-x:skill` or
`skill`; rows gain the long name if needed.
Headless canaries, scratchpad, kept out of the repo:
- Two concurrent conversations in one project (`--settings dev.json` and
`web.json`) list different skills and different tools (higgsfield denied
in dev).
- Two projects with a different local profile.
- `enable` + `/reload-plugins` in a conversation without a flag.
- Both slash forms on a real pack skill (`/seo`, `/pack-seo:seo`).
- A dangling pack symlink does not break the pack's other skills.
Interactive, the user: `/context` on `full`, `dev`, `web` once (numbers to
CHANGELOG); `cc <name> web` on a real project.
## 8. Errors
Unknown profile → list + rc 2, nothing written, no session. Pack named in a
profile without a directory → `show` marks `missing`, doctor warns, `set`
still writes (the CLI ignores an unknown plugin id). Dangling symlink on an
ON pack → red test, red doctor. `--settings` file edited mid-session → no
effect, said in `/profile` and USAGE. Unreadable `settings.local.json` →
`set`/`enable` refuse, never overwrite. `~/.claude.json` unreadable →
`current` prints `disabledMcpServers=unknown` and goes on.
## 9. Out of scope
Skill routing (deferred). A pack `.mcp.json` for higgsfield (spike 4: the
connector already serves it; a pack server would duplicate its tools).
Managed-settings and `--plugin-dir` flows. The faunosteo integration.