chore: purge transient planning artifacts (BDR-065)
This commit is contained in:
1 parent
9cd9591f11
commit
7fb64ac3b2
2 files changed
-1995
No files matched your search
File diff suppressed because it is too large.
Load diff
@@ -1,313 +0,0 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user