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