Files
claude/.claude/tasks/contracts/2026-11-01-phase5-profiles-packs-1300.md
T

17 KiB

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).
  • Pass B 2026-11-01 [gated] (plan docs/superpowers/plans/2026-11-01-phase5-profiles-packs.md, user answers): lib/tests/higgsfield.test.sh is kept, trimmed to the skills-external sync and CLI probes (spec said delete); the "no citer left" census covers hooks lib agents skills rules templates mods, root *.sh, CLAUDE.global.md, README, USAGE, ARCHITECTURE, Makefile, plugins.lock.json, .gitignore and excludes lib/tests/fixtures/, docs/, .claude/, CHANGELOG, MIGRATION; gstack ./setup is skipped with a warn ("run make link first") when skills/gstack is not the helper tree, never run-then-clean. Defaults accepted by silence: profile.sh -C <dir>; --plain keys flag=, model-source=, mcp-off=, connector:*=denied, plugin:<id>=; new files lib/pack-census.sh, lib/gstack-removed.list, suites profile/cc/pack-census/statusline; impeccable = pack symlink to skills-external/impeccable moved there by the installer (not tracked, no git mv); ~/.bashrc user step removes dtach_claude + alias cc and sources lib/cc.sh; deniedMcpServers union documented (cc x web over a dev project keeps the connectors denied).
  • Floor-guard [gated 2026-11-02] (user): the four shellcheck suppressions are authorized with their reasons: lib/profile.sh:2 SC2016 (file-wide; the jq programs quote $var on purpose), lib/cc.sh SC2016,SC1003 (the inner bash -c expands $HOME itself; '^\' is dtach's detach key), lib/pack-census.sh:2 SC2088 (~/.claude/skills is a grep pattern, not a path), lib/tests/cc.test.sh SC1091 (sources a fixture); the plan file's code samples mirror them. The five deleted suites lib/tests/{profile-default,profile-set-managed,profile-census,gstack-removed,toggle-external-repo-resolution}.test.sh tested the retired symlink mechanism; their live checks moved to lib/tests/profile.test.sh (set/current/unset semantics, default profile) and lib/tests/pack-census.test.sh (fragment invariants, retired gstack names, old-layout citers).
  • STEP 6 code review [gated 2026-11-02] (user): backend.json and web-full.json are dropped (they were byte-identical to dev.json and full.json, so current named the wrong profile and the advisor looped); nine profiles remain (full, max, minimal, dev, design, web, seo, qa, audit), the advisor maps backend → dev and web-full → full, and the census forbids two fragments with equal enabledPlugins + deny set. higgsfield-websites stays in pack-higgsfield (OFF by default, ON in max only; amends BDR-109, recorded in the phase 5 BDR). lib/cc.sh keeps set -a; . ~/.claude/.env as dtach_claude did (accepted risk, recorded in the BDR). Also ruled by the controller: the project root for the local file follows Claude Code's rule (git common dir root when inside a repo, else the dir; shared .claude/settings.json read from the session dir); the profile-name match considers only the connector names a fragment manages; profile and session names are allowlisted ^[a-z0-9][a-z0-9-]*$.
  • Floor-guard 2 [gated 2026-11-02] (user): the two # shellcheck disable=SC2086 at lib/tests/cc.test.sh:62 and lib/tests/profile.test.sh:147 are authorized (test loops that word-split an argument string on purpose). Wording fix of the STEP 6 ruling: outside a git repo the root is the nearest ancestor holding .claude/, CLAUDE.md or .git below $HOME (the walk the suite tests), not the bare dir. Criterion 3's deny set reads minimal, dev, seo, qa, audit (backend dropped).
  • Scope note [gated 2026-11-02] (user ask in this run): commit 08ae797 adds one TODO item to .claude/tasks/TODO.md (model-router: ask before routing to Fable, queued after the phase 5 merge). .claude/tasks/ is a durable registry, outside the implementation scope; it is authorized and not part of the phase 5 diff under review.
  • 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. [gated 2026-11-02] Pack layout: nine packs skills/pack-{design,scroll3d,seo,web-validate,gstack-dev,gstack-browser,gstack-design,higgsfield,extras}/ with a manifest whose name is the folder, 55 skill entries (relative symlinks into skills-external/ or the four moved dirs seo, geo, web-validate, site-motion), no skill listed twice, none of the nine retired gstack names; skills-disabled/, .active-profile, lib/toggle-external.sh and lib/profiles/*.profile gone; the census (lib/pack-census.sh) finds no reader of the old layout in the contract scope (hooks lib agents skills rules templates mods, root *.sh, CLAUDE.global.md, README, USAGE, ARCHITECTURE, Makefile, plugins.lock.json, .gitignore; excluded: lib/tests/fixtures/, docs/, .claude/, CHANGELOG, MIGRATION). CHECK: cd /home/bchanot/Documents/claude && out=$(bash lib/pack-census.sh 2>&1) && printf '%s\n' "$out" | grep -q '^PACKS OK 9 packs 55 skills' && [ ! -e skills-disabled ] && [ ! -e .active-profile ] && [ ! -e lib/toggle-external.sh ] && [ -z "$(ls lib/profiles/*.profile 2>/dev/null)" ] && [ -L skills/model-router ] && echo PACKS-OK EXPECT: PACKS-OK EVIDENCE: MET exit=0 marker-found :: PACKS-OK
  3. [gated 2026-11-02] Profiles: nine fragments lib/profiles/{full,max,minimal,dev,design,web,seo,qa,audit}.json (amended [gated 2026-11-02]: backend and web-full dropped as duplicates) with the invariants of lib/profiles/README.md (same key set; model-router and security-guidance true; example-skills and brightdata false; both higgsfield connectors denied on exactly minimal, dev, backend, seo, qa, audit; full = manifest defaults); lib/profile.sh verbs list/show/current [--plain]/set/unset/enable/disable/diff with the merge, refusal (rc 2, nothing written), union, walk-up and timing semantics of the suite; current --plain keys as the plan § Task 3 states. CHECK: cd /home/bchanot/Documents/claude && [ "$(ls lib/profiles/*.json | wc -l)" = 9 ] && a=$(make test suite=lib/tests/profile.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'FAIL=0' && echo PROFILE-OK EXPECT: PROFILE-OK EVIDENCE: MET exit=0 marker-found :: PROFILE-OK
  4. [gated 2026-11-02] Launcher: lib/cc.sh defines cc <name> [profile]; unknown profile → list + rc 2 and no session; with a profile claude --settings lib/profiles/<profile>.json runs with CLAUDE_PROFILE, CLAUDE_PROFILE_SETTINGS and TMPDIR=$HOME/.cache/claude-tmp exported through systemd-run + dtach; without a profile plain claude, TMPDIR still set, .env sourced. CHECK: cd /home/bchanot/Documents/claude && a=$(make test suite=lib/tests/cc.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'FAIL=0' && echo CC-OK EXPECT: CC-OK EVIDENCE: MET exit=0 marker-found :: CC-OK
  5. [gated 2026-11-02] Gates and hooks read profile.sh current --plain: design-tool-gate.sh needs pack-design, pack-gstack-design and ui-ux-pro-max on plus the 21st CLI signed in, remedy profile.sh set web (or enable design) + /reload-plugins, or cc <name> web when source=flag; statusline shows profile: <n> / <n> (conv) / ?; the banner row shows the profile or none (full), try /plugin-check; no /profile design, GATE-BLOCK, show --plain or skill_status left in lib/design-gate.md, skills/feat, skills/bugfix, agents/plugin-advisor.md. CHECK: cd /home/bchanot/Documents/claude && a=$(make test suite="lib/tests/design-tool-gate.test.sh lib/tests/statusline.test.sh" 2>&1) && printf '%s\n' "$a" | grep -q 'all suites green' && ! grep -rqn '/profile design|GATE-BLOCK|show design --plain|skill_status' lib/design-gate.md skills/feat skills/bugfix agents/plugin-advisor.md && echo GATES-OK EXPECT: GATES-OK EVIDENCE: MET exit=0 marker-found :: GATES-OK
  6. [gated 2026-11-02] No user-scope write anywhere outside the installers' install-time enable: no claude plugin enable|disable and no toggle-external under lib/, hooks/, skills/, agents/; profile.sh and cc.sh never touch ~/.claude/settings.json. CHECK: cd /home/bchanot/Documents/claude && ! grep -rqn --exclude-dir=fixtures 'claude plugin enable|claude plugin disable|plugin enable|plugin disable' lib hooks skills agents --include='.sh' --include='.md' && ! grep -q 'settings.json' lib/cc.sh && echo NO-USER-SCOPE (amended [gated 2026-11-02], user: --exclude-dir=fixtures — lib/tests/fixtures/*.md are append-only registry snapshots that predate the branch; the /profile prohibition sentence is reworded without the literal.) EXPECT: NO-USER-SCOPE EVIDENCE: MET exit=0 marker-found :: NO-USER-SCOPE
  7. [gated 2026-11-02] The branch is green and clean: make test all suites green; shellcheck clean and ≤ 80 columns on lib/profile.sh, lib/cc.sh, lib/pack-census.sh, lib/design-tool-gate.sh; settings.json changes on the branch limited to env.SLASH_COMMAND_TOOL_CHAR_BUDGET (no UI write, no model, no enabledPlugins drift committed); doctor.sh exits 0 (warns allowed). CHECK: cd /home/bchanot/Documents/claude && t=$(make test 2>&1) && printf '%s\n' "$t" | grep -q 'all suites green' && shellcheck lib/profile.sh lib/cc.sh lib/pack-census.sh lib/design-tool-gate.sh && [ "$(LC_ALL=C awk 'length($0) > 80' lib/profile.sh lib/cc.sh lib/pack-census.sh lib/design-tool-gate.sh lib/profile-state.jq | wc -l)" = 0 ] && [ "$(git diff develop...HEAD -- settings.json | grep '^[-+] ' | grep -v 'SLASH_COMMAND_TOOL_CHAR_BUDGET|ENABLE_STOP_REVIEW' | wc -l)" = 0 ] && bash doctor.sh >/dev/null 2>&1 && echo BRANCH-OK EXPECT: BRANCH-OK EVIDENCE: MET exit=0 marker-found :: BRANCH-OK
  8. [gated 2026-11-02] Proof recorded (plan Task 12, judged by the verifier from the executor's report and CHANGELOG): two concurrent conversations in one project under --settings dev.json / web.json list different packs and tool counts (higgsfield tools 0 vs 158); two projects with different local profiles differ; enable seo + /reload-plugins makes /seo and /pack-seo:seo resolve in a flagless conversation; current --plain timing recorded against the 50 ms target; listing budget value and per-profile name-only counts in CHANGELOG.
  9. [gated 2026-11-02] Docs: MIGRATION.md holds the "Profiles and packs (2026-11)" section (amended [gated 2026-11-02], user: no version number pre-empted; the CHANGELOG bullets live under [Unreleased], the number is set at release-candidate) (user-scope restore, old-layout cleanup by enumeration, .bashrc guarded source line and alias removal, per-project set); README/USAGE/ARCHITECTURE/CLAUDE.global.md name no toggle-external.sh, skills-disabled or profile-reset; the deniedMcpServers union is documented in /profile and USAGE. CHECK: cd /home/bchanot/Documents/claude && grep -q 'Profiles and packs' MIGRATION.md && grep -q 'lib/cc.sh' MIGRATION.md && ! grep -rqn 'toggle-external|skills-disabled|profile-reset' README.md USAGE.md ARCHITECTURE.md CLAUDE.global.md && grep -qi 'union' skills/profile/SKILL.md && echo DOCS-OK EXPECT: DOCS-OK EVIDENCE: MET exit=0 marker-found :: DOCS-OK

FILE SCOPE (final, STEP 3)

  • skills/pack-*/ (new: manifests + symlinks; moved: seo, geo, web-validate, site-motion)
  • lib/profile.sh, lib/profile-state.jq (new), lib/profiles/.json (new) + README.md, lib/profiles/.profile (deleted)
  • lib/cc.sh (new), lib/pack-census.sh (new), lib/pack-census-fragments.jq (new), lib/gstack-removed.list (new), lib/gstack-removed.sh, lib/toggle-external.sh (deleted), lib/higgsfield-skills.sh
  • lib/design-tool-gate.sh, lib/design-gate.md, lib/plugin-gate.md, agents/plugin-probe.md, agents/plugin-advisor.md, agents/client-handover-writer.md
  • skills/profile/SKILL.md + test-prompts.json, skills/onboard/SKILL.md, skills/plugin-check/SKILL.md, skills/feat/SKILL.md + test-prompts.json, skills/bugfix/SKILL.md
  • hooks/session-start.sh, hooks/statusline.sh, lib/detect-plugins.sh, doctor.sh, lib/doctor-vendored.sh, lib/doctor-skills.sh, link.sh, Makefile, .gitignore
  • install-plugins.sh, update-all.sh, plugins.lock.json, settings.json (env only, Task 13)
  • lib/skill-routing-census.py, mods/model-router/routing.json
  • lib/tests/: profile.test.sh, cc.test.sh, pack-census.test.sh, statusline.test.sh (new), fixtures/pack-census-old-citers.sh (new), design-tool-gate.test.sh, doctor-vendored.test.sh, higgsfield.test.sh, effort-routing.test.sh, model-routing.test.sh, seo-geo-contract.test.sh, plan-challenger.test.sh, doctrine-citers.test.sh, lib/seo-data/seo-data.test.sh; deleted: profile-default, profile-set-managed, profile-census, gstack-removed, toggle-external-repo-resolution
  • CLAUDE.global.md, README.md, USAGE.md, MIGRATION.md, ARCHITECTURE.md, CHANGELOG.md, rules/web-building.md
  • Working tree only (never committed): flat symlinks and skills-disabled/ removed, impeccable moved to skills-external/impeccable, settings.json user-scope enabledPlugins restored