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;--settingsfalse beats local true;/reload-pluginsworks in-pand reloads skills + hooks mid-session after a settings edit, pack.mcp.jsonservers need a new session; claude.ai connectors DO load under-pnow (changed since 2026-10-25),--strict-mcp-configdrops them per conversation; a pack.mcp.jsonHTTP server is registered asplugin:<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.jsondeniedMcpServers:[{serverName:"claude.ai <Name>"}]drops the named connectors (199 → 192 tools for Gmail + Higgsfield AI) anddisableClaudeAiConnectors:truedrops all nine (26 tools, model-router kept); the same two keys via--settingswork per conversation; aserverUrlwildcard matches no connector (no URL exposed);disableClaudeAiConnectorsis any-source-true; the native/mcptoggle writesdisabledMcpServersper project into~/.claude.json(untested, interactive only). Docs, not measured:/reload-pluginsre-readsenabledPluginsfrom every settings file;--plugin-dirloads a pack as<name>@inlinefor one session; the skills-dir id is the manifestname. - Spikes 1b/1c/2b 2026-11-01 (headless): a pack manifest
defaultEnabled:falseis OFF with nothing written (local or--settingstrue turns it on); the typed short slash/<skill>on a pack skill expands like/<pack>:<skill>; in a--settingsconversation/reload-pluginsre-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 bydeniedMcpServersin every profile except design, web, web-full, full, max; launchercc <name> [profile]as a function inlib/cc.shsourced from~/.bashrc(user step), exportingCLAUDE_PROFILE,CLAUDE_PROFILE_SETTINGS,TMPDIRand runningclaude --settings; approach A = tracked packsskills/pack-<n>/(relative symlinks intoskills-external/, five real dirs moved), profiles as literal settings fragmentslib/profiles/<n>.json;profile.sh current --plainis 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](plandocs/superpowers/plans/2026-11-01-phase5-profiles-packs.md, user answers):lib/tests/higgsfield.test.shis 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 excludeslib/tests/fixtures/,docs/,.claude/, CHANGELOG, MIGRATION; gstack./setupis skipped with a warn ("run make link first") whenskills/gstackis not the helper tree, never run-then-clean. Defaults accepted by silence:profile.sh -C <dir>;--plainkeysflag=,model-source=,mcp-off=,connector:*=denied,plugin:<id>=; new fileslib/pack-census.sh,lib/gstack-removed.list, suites profile/cc/pack-census/statusline; impeccable = pack symlink toskills-external/impeccablemoved there by the installer (not tracked, nogit mv);~/.bashrcuser step removesdtach_claude+alias ccand sourceslib/cc.sh;deniedMcpServersunion documented (cc x webover adevproject keeps the connectors denied). - Floor-guard
[gated 2026-11-02](user): the four shellcheck suppressions are authorized with their reasons:lib/profile.sh:2SC2016 (file-wide; the jq programs quote$varon purpose),lib/cc.shSC2016,SC1003 (the innerbash -cexpands$HOMEitself;'^\'is dtach's detach key),lib/pack-census.sh:2SC2088 (~/.claude/skillsis a grep pattern, not a path),lib/tests/cc.test.shSC1091 (sources a fixture); the plan file's code samples mirror them. The five deleted suiteslib/tests/{profile-default,profile-set-managed,profile-census,gstack-removed,toggle-external-repo-resolution}.test.shtested the retired symlink mechanism; their live checks moved tolib/tests/profile.test.sh(set/current/unset semantics, default profile) andlib/tests/pack-census.test.sh(fragment invariants, retired gstack names, old-layout citers). - STEP 6 code review
[gated 2026-11-02](user):backend.jsonandweb-full.jsonare dropped (they were byte-identical todev.jsonandfull.json, socurrentnamed 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 equalenabledPlugins+ deny set.higgsfield-websitesstays in pack-higgsfield (OFF by default, ON inmaxonly; amends BDR-109, recorded in the phase 5 BDR).lib/cc.shkeepsset -a; . ~/.claude/.envasdtach_claudedid (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.jsonread 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=SC2086at 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.mdor.gitbelow$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): commit08ae797adds 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
- 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). [gated 2026-11-02]Pack layout: nine packsskills/pack-{design,scroll3d,seo,web-validate,gstack-dev,gstack-browser,gstack-design,higgsfield,extras}/with a manifest whosenameis the folder, 55 skill entries (relative symlinks intoskills-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.shandlib/profiles/*.profilegone; 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[gated 2026-11-02]Profiles: nine fragmentslib/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.shverbs 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 --plainkeys 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[gated 2026-11-02]Launcher:lib/cc.shdefinescc <name> [profile]; unknown profile → list + rc 2 and no session; with a profileclaude --settings lib/profiles/<profile>.jsonruns withCLAUDE_PROFILE,CLAUDE_PROFILE_SETTINGSandTMPDIR=$HOME/.cache/claude-tmpexported through systemd-run + dtach; without a profile plainclaude, TMPDIR still set,.envsourced. 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[gated 2026-11-02]Gates and hooks readprofile.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, remedyprofile.sh set web(orenable design) +/reload-plugins, orcc <name> webwhen source=flag; statusline showsprofile: <n>/<n> (conv)/?; the banner row shows the profile ornone (full), try /plugin-check; no/profile design,GATE-BLOCK,show --plainorskill_statusleft 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[gated 2026-11-02]No user-scope write anywhere outside the installers' install-time enable: noclaude plugin enable|disableand notoggle-externalunder lib/, hooks/, skills/, agents/;profile.shandcc.shnever 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[gated 2026-11-02]The branch is green and clean:make testall suites green; shellcheck clean and ≤ 80 columns on lib/profile.sh, lib/cc.sh, lib/pack-census.sh, lib/design-tool-gate.sh;settings.jsonchanges on the branch limited toenv.SLASH_COMMAND_TOOL_CHAR_BUDGET(no UI write, nomodel, noenabledPluginsdrift committed);doctor.shexits 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[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.jsonlist different packs and tool counts (higgsfield tools 0 vs 158); two projects with different local profiles differ;enable seo+/reload-pluginsmakes/seoand/pack-seo:seoresolve in a flagless conversation;current --plaintiming recorded against the 50 ms target; listing budget value and per-profile name-only counts in CHANGELOG.[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,.bashrcguarded source line and alias removal, per-projectset); README/USAGE/ARCHITECTURE/CLAUDE.global.md name notoggle-external.sh,skills-disabledorprofile-reset; the deniedMcpServers union is documented in/profileand 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 (
envonly, 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