Files
claude/docs/superpowers/specs/2026-10-29-context-diet-design.md
T

7.1 KiB
Raw Blame History

Phase 1 — native context diet (design)

Contract: .claude/tasks/contracts/2026-10-28-context-diet-1944.md (the acceptance criteria live there). Queue: BDR-125, TODO bullet "Phase 1, native context diet: no mod". Approved in chat 2026-10-29 (A = 200 chars, B = extend the census).

Goal

Cut the always-on context loaded by every session, without a mod: each section moves to the native carrier that fires when it is needed (path rule, hook, lib Read by our skills, setting). Nothing is lost: every moved text is reachable where it serves. Estimate: −2 to −2.5k tokens per session (baseline 2026-10-28: 30.5k total, Memory files 9.6k, System prompt 4.4k, Custom agents 2.6k).

Carriers

Source (develop 017a28b) Carrier Always-on residue
auto-memory system section "autoMemoryEnabled": false (settings.json) none
CLAUDE.global.md § Design work — full toolchain (tiered by scope) appended verbatim to rules/web-building.md (same UI globs) Skill-routing line points to it; design hook one-liner says Read it
CLAUDE.global.md § graphify usage body hooks/session-start.sh, free lines after the box, only when <repo root>/graphify-out/graph.json exists ## graphify + the 200-file threshold rule
CLAUDE.global.md § Public websites — never SPA + rules/default-language.md lib/architecture-defaults.md (verbatim, H1 of the language rule demoted to H2) one line under # Architecture decisions naming Rust default, never SPA, /api/v1, the lib path
CLAUDE.global.md § Web APIs — always versioned rules/rest-api.md § Versioning (full text, replaces "Not repeated here"; the § Naming example becomes /api/v1/tasks); the lib carries a one-line summary + pointer named in the architecture line
rules/secure-by-default.md §4 Supabase, §6 Cloud functions bodies rules/supabase.md (**/supabase/**, **/*supabase*.*), rules/cloud-functions.md (**/functions/**, **/serverless.*, **/firebase.json), bullets verbatim the two headings stay, one line each (critical rule + pointer)
agents/*.md description: (23 tracked) trimmed at the source to ≤ 200 chars n/a

rules/default-language.md is deleted. The always-on rule set becomes exactly writing-style.md + secure-by-default.md.

Exact visible strings

  • CLAUDE.global.md, under # Architecture decisions (replaces the intro and the two sections): New project, scaffolding, stack brainstorm or whole-project rewrite: Rust by default, a public site is never a SPA (Astro; Next.js when SSR is needed), every web API versioned /api/v1/from day one. Read~/.claude/lib/architecture-defaults.md before proposing a stack.
  • CLAUDE.global.md Skill routing: Design / UI (build, system, audit, polish) → Read ~/.claude/rules/web-building.md § "Design work" first (the quotes end the label for the extended census; plan challenge 2026-10-29).
  • CLAUDE.global.md § graphify keeps, after the threshold: With a graph (graphify-out/graph.json): graphify query before raw grep, graphify update . after code edits; the session banner prints the rest. (sub-agents load CLAUDE.md, never the SessionStart output).
  • Design hook stdout: Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix. (one line).
  • secure-by-default.md §4: - RLS on every table, never a service_role or secret key client-side. Full domain: rules/supabase.md (loads on Supabase files). §6: - Max instances and a timeout on every function, never a self-trigger. Full domain: rules/cloud-functions.md (loads on function files).

Readers of the lib

init-project (interviewer row, STEP 3 brainstorm input, STEP 5 scaffolder brief), agents/interviewer.md, agents/scaffolder.md, ship-feature STEP 1 (when the feature picks a language, framework or API shape), onboard STEP 6 (audit briefs), audit-delta conformity axis. agents/seo-analyzer.md cites the lib for "public sites are never SPAs". /refactor is not edited (no whole-project mode; the always-on line covers it).

Hook fixes (user scope additions, pass A)

  • design-toolchain-reminder.sh skips <agent-message turns (857 of 2,779 logged fires) like it skips <task-notification>.
  • Its suite runs every call under a temp HOME (1,770 logged fires were suite prompts); the exact one-liner is asserted.

Auto memories

One decision entry into robin_petier's registry (LAN dev server: never start unprompted, detached form on ask, a server found running = user-started → ask before killing), via memory.sh -C, on a chore/* branch of that repo, text shown to the user first. The other four are dropped (already in registries, or contrary to doctrine). The user removes the auto-memory dirs by hand. lib/doctor-automem.sh + suite: doctor warns while any ~/.claude/projects/*/memory/ holds a file.

Proofs

  • New suite lib/tests/user-rules.test.sh: every rules/*.md frontmatter parses (one-line JSON paths: or none); the always-on set is exactly writing-style + secure-by-default; flip controls (two-line paths:, an extra always-on file).
  • Census extension (lib/tests/doctrine-citers.test.sh): citations of rules/<f>.md § Label and lib/<f>.md § Label resolve against that file's headings; flip-tested.
  • New suite for the session-start graphify branch (graph present / absent).
  • lib/tests/doctor-automem.test.sh (empty → silent, one file → warn, count).
  • Controller proof (journaled, not in make test): project-rules.sh -C <project> matches <glob> per new glob in a real project; one headless session per moved path rule whose prompt names the Read tool, logged path_glob_match (faunosteo supabase, game supabase/functions, a UI file); /context after vs baseline.

Cleanup and citers

lib/project-rules.sh:22-23 comment (engine matching is gitignore-style: trailing /** dropped, any depth, hidden dirs included; evidence InstructionsLoaded globs: ["rules"] on .claude/rules/*.md); .claude/rules/rules-maintenance.md (always-on exception list, the "always-on doctrine stays in CLAUDE.global.md" sentence, matching note); lib/design-gate.md:48 (stale "+motion / +static" citation); lib/project-archetypes/rest-api-node.md:58; CLAUDE.global.md Higgsfield line; hooks/session-start.sh BDR-031 comment; TODO.md phase 1 checked + follow-ups. CLAUDE.global.md ends ≤ 320 lines.

Out of scope

/refactor edits; the four vendored impeccable-* agents; the per-repo memory v2 upgrade pass; settings.json model/theme lines written by the user's /model (left uncommitted, user decides).

Risks

  • autoMemoryEnabled: false may also affect the analyzer's memory: project: checked during the proof, not promised.
  • Engine glob semantics differ from compgen: the static suite proves parsing only; loading is proved by the logged sessions.
  • **/functions/** also fires in non-cloud functions/ dirs (≈80 tokens of noise there), accepted.
  • gitflow finish refuses while the user's settings.json hunks are uncommitted (this branch changes settings.json): the user commits or stashes them first; never a checkout of the live file.