cc-os/docs/plans/b2-profile-overlays.md

B2: per-profile plugin-enablement overlays — shipped + measured

Task: B2 in system-prompt-profiles-tasks.md · 2026-07-08 · Depends on C3 findings (c3-spike-findings.md)

Pre-check result: enabledPlugins DEEP-MERGES

The open item from C3 is resolved empirically (transcript skill_listing inspection, two headless haiku runs): a --settings <overlay.json> file's enabledPlugins is merged key-by-key into ~/.claude/settings.json — only the plugins explicitly set false disappear (baseline 64 skills → 61, exactly the 3 skills of the 2 disabled plugins); unlisted plugins and all hooks are unaffected. Diff-only overlays are safe.

Shipped

~/.claude/profiles/ (see its README.md):

• cc-os-design.json — disables rails-ui-component, api-wrapper, invoice-ninja, creative-team, dev-team
• client-dev.json — disables creative-team, invoice-ninja, arch-refactor
• brainstorm.json — disables all 9 coding/client plugins (adds ruby-lsp, codex, git-context, arch-refactor)

Usage: claude --settings ~/.claude/profiles/<name>.json. Never combine with a --setting-sources list that omits user (silent plugin/hook drop — see vault note claude-code-setting-sources-silent-plugin-drop).

Measured savings (headless haiku, empty dir, 2026-07-08)

Run	Context tokens	Delta vs baseline
baseline (no overlay)	29,045	—
cc-os-design (5 plugins off)	29,013	−32
brainstorm (9 plugins off)	28,413	−632

Honest verdict: token savings are marginal.

Follow-on: YAGNI tool deny (2026-07-08, same session)

Transcript sweep of all sessions since 2026-06-01 (tool_use counts across ~/.claude/projects/**/*.jsonl): heavy use of Bash (7.7k) / Read (4.2k) / Edit (2.1k) / Agent (1.3k) / Write (1.2k); zero-or-one lifetime calls to Workflow, Artifact, SendUserFile, ReportFindings — all of which ship full schemas up front (not deferred).

Measured (headless haiku, empty dir): disallowing Workflow alone −5,982 tokens (its schema ≈ the whole system-prompt text); all four −6,509. A permissions.deny block in a settings file removes the schemas identically to --disallowedTools (22,532 vs 22,536).

Applied globally to ~/.claude/settings.json: "permissions": {"deny": ["Workflow", "Artifact", "SendUserFile", "ReportFindings"]} — ~6.5k saved every session, no flags needed. Revert by deleting the entry (needed if "ultracode"-style Workflow orchestration is ever wanted). This delivers the "--tools restriction is the real lever" prediction from the assessment; A1/A2's remaining value is now just the interactive-Fable confirmation. The assessment's "~4.8k user stack" is dominated by hooks/memsearch injection and per-plugin fixed listings, not by the skill descriptions the overlays remove — ToolSearch deferral already made plugin skills cheap. The remaining value of profiles is focus (no irrelevant slash commands/agents offered in a brainstorm session), not context cost. This further deprioritizes Wave 3 (aliases: trivial, do when friction is felt) and Group D (dropped), and shifts remaining token-diet attention to the memsearch injection (~1.5–3.9k/session, needs upstream fix — see b3-memsearch-injection-review.md).