@bglocation/tune-context 1.0.0

package/skills/caveman/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: caveman
+description: Terse caveman output mode — drop articles/filler/pleasantries, fragments OK, no tool-call narration or decorative tables. ~65% fewer output tokens. Invoke to compress responses; suspend for safety warnings and irreversible-action confirmations.
+---
+
+# Caveman mode
+
+Terse output to cut **output** tokens (~65%). Output is uncached and ~4–5× the
+price of input, so this is a real cost lever — not just style.
+
+## Rules
+- Drop articles (a/an/the), filler (just/really/basically/simply), pleasantries.
+- Fragments OK. Short synonyms. No tool-call narration, no decorative
+  tables/emoji.
+- Technical terms exact; code blocks unchanged; standard acronyms (DB/API) fine.
+- Never invent abbreviations.
+- Pattern: `[thing] [action] [reason]. [next step].`
+
+## Suspend (clarity wins)
+- Security warnings; irreversible-action confirmations.
+- Multi-step sequences where compression breeds ambiguity.
+
+Resume after clarity is achieved. Terseness never trims a required safety
+confirmation or a real caveat.
+
+Source: <https://github.com/JuliusBrussee/caveman>

package/skills/cdd/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: cdd
+description: Comment-Driven Development — write the contract (what/why, inputs/outputs, side effects, edge cases) in comments before the code. The contract becomes the test assertions (CDD↔AAA) and, embedded with the symbol, improves semantic retrieval. Use when writing or reviewing non-trivial functions/classes.
+---
+
+# Comment-Driven Development (CDD)
+
+Write the **contract in comments before the implementation**. The comment states
+WHY and the contract; the code states HOW.
+
+## The contract, before the code
+Order:
+1. A comment describing the unit's purpose — what it does, inputs/outputs, side
+   effects, edge cases, invariants.
+2. The code beneath it.
+
+The comment **never paraphrases the code**. It captures the intent and constraints
+the code cannot show on its own.
+
+## Contract = test assertions (CDD ↔ AAA)
+What the comment promises is what the tests assert. The contract is the source of
+the Arrange-Act-Assert cases: each promised behavior, edge case, and invariant
+becomes an assertion. If the comment and the tests disagree, one of them is wrong.
+
+## Comments that retrieve well (CDD ↔ RAG)
+Chunkers embed the leading comment together with the symbol, so the comment lands
+in the symbol's embedding vector. Comment and code are **complementary halves of
+one vector**: the code already supplies the HOW vocabulary (identifiers, calls) for
+free, so the comment must add only what the code cannot express — the domain-level
+WHAT/WHY, in the words someone would *search* with.
+
+**Litmus test** before writing a comment: *"does this sentence contain any word not
+already in the code below?"* If not, it is a paraphrase — zero retrieval signal,
+noise for the reader. Rewrite it as contract, or drop it.
+
+## Example
+```ts
+// BAD (paraphrase — no new signal):
+// Loops through refresh tokens and checks the exp field against now.
+
+// GOOD (contract — domain WHAT/WHY):
+// Rejects expired user sessions: a refresh token past its expiry must never mint a
+// new access token (security invariant). Returns the still-valid sessions; throws
+// AuthError on a tampered token.
+function pruneSessions(tokens: RefreshToken[]): Session[] { … }
+```
+
+The good comment adds searchable concepts ("expired session", "refresh token
+reuse", "security invariant") that the code's identifiers don't; the tests assert
+exactly those.

package/skills/phase-workflow/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: phase-workflow
+description: End-of-phase context hygiene. Use when finishing a development/testing/docs phase or switching to an unrelated task — writes a compact state-doc and prompts for /compact (phase boundary) or /clear (new task). The reset itself stays a user action.
+---
+
+# Phase workflow — end-of-phase context hygiene
+
+Run at a phase boundary (development → testing → docs) or when switching to an
+unrelated task. Compaction is **user-initiated** (`/compact` / `/clear` are
+client commands — the model can't invoke them); this skill prepares for it so
+nothing important is lost.
+
+## Procedure
+1. **Write / update a state-doc** — a compact snapshot of what matters going
+   forward: decisions made, open threads, the current path/plan, and the next
+   step. Keep it short; it becomes the seed of the next context.
+2. **Choose the reset:**
+   - Same session, thread closed → **`/compact`** (summarizes history, keeps
+     continuity).
+   - New, unrelated task → **`/clear`** (fresh context; the old task's files and
+     diffs are dead weight).
+3. **Run the reset yourself** — the model cannot invoke `/compact` / `/clear`.
+
+## Automated backing (hooks)
+Once the tune-context hooks are installed, a `PreCompact` hook writes the
+state-doc before any compaction and a `SessionStart` (matcher `compact`) hook
+re-injects it after — so the state-doc survives even an auto-compaction
+(mechanism confirmed; see the configurator epic).

package/skills/token-efficiency/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: token-efficiency
+description: Token-saving working methods — prefer semantic search over grep, read only what you need, delegate broad searches to subagents, keep context lean. Use before broad code exploration, when reading large files, or as a session's context grows.
+---
+
+# Token efficiency
+
+Cut context (input) and output tokens without losing correctness. Apply before
+broad exploration and as a session grows.
+
+## 1. Search by meaning, not by text
+When a semantic-search MCP is available (`search_codebase` from
+code-search-mcp), prefer it over broad `grep -r` / `find` for conceptual
+"where/why is X" questions, then read **only** the returned spans. Keep `grep`
+for exact string/symbol lookups. Broad text search pulls whole files into
+context; semantic search returns just the relevant span. Narrow with a `segment`
+filter when you know which side you need (code vs docs).
+
+## 2. Read narrow
+- After a search hit, read only the returned range (`get_chunk`, or a ranged
+  read around the line span) — not the whole file.
+- After edits, read `git diff`, not a re-read of the changed files.
+- Never re-read a file already in context. The cheapest token is the one you
+  don't carry forward.
+
+## 3. Delegate — and right-size the model
+When answering needs sweeping many files (naming-convention hunts, "where is
+everything about X"), delegate to the **`explore-cheap`** subagent (read-only, on
+a cheap model): it burns its own context and returns the conclusion, so the main
+session pays for the answer, not the search. For a judgment second-pass before
+committing non-trivial changes, use **`reviewer`** (a strong model). Right-size:
+cheap model for mechanical search, strong for judgment.
+
+## 4. Comments that retrieve well (CDD ↔ RAG synergy)
+Chunkers embed the leading comment together with the symbol, so a contract-first
+comment (see the `cdd` skill) literally lands in the embedding vector. Write
+comments in the domain vocabulary someone would *search* with — better contracts
+→ better retrieval → fewer missed reads.
+
+## 5. Context hygiene
+- `/compact` after a work thread closes (keeps the thread, drops raw detail);
+  `/clear` between independent tasks. See the `phase-workflow` skill.
+- Old turns ride along as input on every later request — don't carry dead weight.
+
+## 6. Measure, don't believe
+If the tool logs usage (`.rag/usage.jsonl` → `rag-usage`), review it
+periodically: is semantic search actually replacing grep? Promote or drop levers
+on data, not faith.
+
+## In a new project
+Set up semantic search proactively — `npx -p @bglocation/code-search-mcp
+rag-init`, then build the index — so this lever exists from the start.

package/skills/tune-context/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: tune-context
+description: Configure this project for token-efficient Claude Code use — detect the stack, existing MCP servers and wiki, then generate a lean project CLAUDE.md, wire the doctrine skills, and set up permissions. Run once per repo; idempotent.
+disable-model-invocation: true
+---
+
+# tune-context — configure a repo for token efficiency
+
+Three phases, in order: **detect → generate → verify**. Gather facts before
+writing anything. Templates live in `${CLAUDE_SKILL_DIR}/templates/`.
+
+## Managed blocks — how idempotency actually works
+Everything you generate into an existing file goes **inside markers**:
+
+```
+<!-- >>> tune-context (managed) >>>   … generated …   <!-- <<< tune-context (managed) <<< -->
+```
+
+Rules: replace **only** what is between the markers; never touch anything outside
+them; if the markers are absent in an existing file, insert a fresh block rather
+than rewriting the file. For JSON (`.mcp.json`, `settings.json`) there are no
+markers — merge key-by-key and preserve every existing key. This is what makes a
+second run a no-op.
+
+**Delta only, never duplicate.** If the existing hand-written CLAUDE.md already
+covers the template's content (build/test/lint, architecture, conventions), the
+managed block carries **only what is missing** — usually just pointers to the
+doctrine skills — not a second copy of hand-written sections. When in doubt, add
+less: a thin pointer beats a duplicate.
+
+---
+
+## 1. Detect (read-only)
+
+**Stack.** Package manager and languages (`package.json`, `pyproject.toml`,
+`go.mod`, `Cargo.toml`, …); the real build / test / lint commands (script names,
+not guesses); monorepo vs single project (workspaces, `packages/`, `apps/`).
+
+**Existing MCP servers — check every scope** (do not assume only `.mcp.json`):
+
+| Scope | Where |
+|---|---|
+| project | `./.mcp.json` |
+| user | `~/.claude.json` → top-level `mcpServers` |
+| local | `~/.claude.json` → `["<abs project path>"].mcpServers` |
+| gating | `settings.json`: `enabledMcpjsonServers`, `disabledMcpjsonServers`, `allowedMcpServers`, `deniedMcpServers` |
+
+If `CLAUDE_CONFIG_DIR` is set, `.claude.json` lives there instead of `~`.
+
+**Classify each server** — this is what turns "a server exists" into a rule:
+
+| Type | Rule to write into the project CLAUDE.md |
+|---|---|
+| semantic code search | search by meaning, read only returned spans |
+| wiki / docs | look up docs through this MCP, don't paste pages |
+| database | schema and queries through the MCP, don't dump tables |
+| VCS / issues | PR and issue state through the MCP, not full `git log` |
+| unknown | inspect its tools; if any returns whole pages/tables, prefer the narrow variant |
+
+**Wiki / docs location** — decides the lever:
+- local markdown tree (`wiki/`, `docs/`) or a clonable git wiki → **RAG segment**
+- hosted SaaS (Confluence, Notion) → **its own MCP** (RAG cannot index it)
+- a few canonical pages → just a **pointer** in CLAUDE.md
+
+**Existing config.** Note whether `./CLAUDE.md`, `.claude/settings.json`,
+`.mcp.json`, `rag.config.json` already exist — you will merge, never clobber.
+For `settings.json` also check `hooks.PreCompact` / `hooks.SessionStart` /
+`hooks.PostToolUse` / `hooks.SubagentStart` for an entry already calling
+`pre-compact-snapshot.mjs` / `session-start-reinject.mjs` / `adoption-log.mjs`
+(idempotency: skip if present — `adoption-log.mjs` is registered under both
+`PostToolUse` and `SubagentStart`) and `permissions.allow` for entries already
+covering the detected build/test/lint commands.
+
+---
+
+## 2. Generate (idempotent, never clobber)
+
+1. **Project `./CLAUDE.md`** from `${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.project.tmpl`.
+   Fill the slots from detection; delete the slot guide comment; keep the managed
+   markers. If the file exists, replace only the managed block — hand-written
+   content outside it survives untouched.
+2. **User `~/.claude/CLAUDE.md`** from `${CLAUDE_SKILL_DIR}/templates/CLAUDE.md.user.tmpl`
+   — only if it is missing or clearly untuned. Never overwrite a user-tuned file
+   without asking.
+3. **Doctrine skills** — ensure `token-efficiency`, `caveman`, `cdd` and
+   `phase-workflow` are present in `~/.claude/skills/` (they ship with this tool).
+4. **`.mcp.json`** — **merge**. Add a semantic-search server only if none was
+   detected in any scope. Preserve every existing server and key.
+5. **Hooks** — ensure `~/.claude/hooks/pre-compact-snapshot.mjs`,
+   `~/.claude/hooks/session-start-reinject.mjs` and `~/.claude/hooks/adoption-log.mjs`
+   exist (they ship with this tool, installed once user-level — same as the
+   doctrine skills in step 3). Merge into `settings.json` from
+   `${CLAUDE_SKILL_DIR}/templates/settings.json.tmpl`: append the `PreCompact`
+   (matcher `"*"`, docs: omit or `*` = every trigger), `SessionStart`
+   (matcher `"compact"`), `PostToolUse` (matcher `"*"`) and `SubagentStart`
+   (matcher `"*"`) entries **only if an entry calling that script isn't already
+   there** — treat each hook array as a set keyed by `command`, not a value to
+   overwrite.
+   - `PreCompact` writes a mechanical git/branch/status snapshot per-project to
+     `~/.claude/tune-context/state/`; `SessionStart(compact)` reads it back via
+     `additionalContext`. Filesystem/git facts only — not decisions/open threads
+     (a hook has no model access).
+   - `adoption-log.mjs` is registered under **both** `PostToolUse` (every tool
+     call) and `SubagentStart` (subagent spawns — these are NOT PostToolUse tools,
+     they fire their own event carrying `agent_type`). It appends one line per
+     event to `~/.claude/tune-context/adoption.jsonl` — which lever the model
+     reached for (RAG vs grep, Skill, subagent, re-reads). Read it with
+     `eval/adoption-report.mjs` (the `rag-usage` analog). Behavioral proxy only:
+     no token cost (needs OTEL `claude_code.cost.usage` + a collector) and no
+     caveman (an output style, not a tool call).
+6. **`settings.json` permissions** — merge `permissions.allow`: the project's
+   safe, frequent commands (build/test/lint, `git status`/`diff`/`log`) and
+   `mcp__<server>__<tool>` for detected servers. Union with the existing array
+   (dedupe, never remove entries). Never add blanket `Bash(*)` or bypass modes.
+7. **Wiki** — wire the lever chosen in detection (segment / MCP note / pointer).
+
+Keep the generated CLAUDE.md **thin**: headings and pointers only. Depth belongs
+in skills — that is the whole point of this setup.
+
+---
+
+## 3. Verify (before reporting done)
+
+- Every command written into CLAUDE.md **actually exists** (check the script names
+  you found; don't trust the template).
+- Every internal link resolves to a real file.
+- Skill descriptions still fit the listing budget (a handful of skills, each
+  description one or two sentences).
+- If a semantic-search MCP is configured, it answers a probe query.
+- Hook scripts referenced in `settings.json` exist and are executable
+  (`node ~/.claude/hooks/pre-compact-snapshot.mjs` under empty stdin `{}`
+  should exit 0 without throwing; same for `adoption-log.mjs`).
+- **The merge actually landed — don't just trust step 5 ran.** Re-read the
+  target `settings.json` (the same file you merged into) and parse it: confirm
+  `hooks.PreCompact`, `hooks.SessionStart`, `hooks.PostToolUse` and
+  `hooks.SubagentStart` each contain an entry whose `command` references the
+  expected script (`pre-compact-snapshot.mjs` / `session-start-reinject.mjs` /
+  `adoption-log.mjs` twice, for `PostToolUse` and `SubagentStart`). Copying the
+  hook scripts to `~/.claude/hooks/` is not sufficient — a real prior incident
+  had the scripts present and executable while `settings.json` had **no**
+  `hooks` key at all, so the hooks silently never fired. Scripts-exist and
+  entries-are-registered are two different, both-required checks.
+- **Idempotency:** a second run would produce no changes.
+
+Report what you created, what you merged, and anything you deliberately skipped.
+
+---
+
+## Rules
+
+- **Never clobber.** Merge into existing config. If a conflict cannot be merged
+  safely, stop and report it instead of guessing.
+- **RAG is optional.** Everything here works without a semantic-search MCP —
+  detect it, never assume it.
+- **Facts over guesses.** Read the manifests; do not invent commands.
+- **Thin always-on.** If content is deep enough to need sections, it belongs in a
+  skill, not in CLAUDE.md. `@import` does not save tokens — it is inlined in full.

package/skills/tune-context/templates/CLAUDE.md.project.tmpl

@@ -0,0 +1,39 @@
+<!-- >>> tune-context (managed) >>>
+     Regenerated by /tune-context. Edit freely OUTSIDE this block — content
+     outside the markers is never touched. -->
+# CLAUDE.md — {{PROJECT_NAME}}
+
+{{ONE_LINE_WHAT_THIS_IS}}
+
+## Build / test / lint
+```bash
+{{BUILD_CMD}}
+{{TEST_CMD}}
+{{LINT_CMD}}
+```
+{{RUN_NOTES}}
+
+## Working methods (token-saving)
+{{MCP_RULES}}
+Depth lives in skills: `token-efficiency`, `cdd`, `phase-workflow` (and
+`/caveman` for terse output) — not in this file.
+
+## Architecture
+{{ARCHITECTURE_BULLETS}}
+
+## Conventions that bite
+{{CONVENTIONS}}
+
+<!-- <<< tune-context (managed) <<< -->
+
+<!--
+Slot guide (delete after filling):
+  PROJECT_NAME          package/repo name
+  ONE_LINE_WHAT_THIS_IS one sentence, what the project is
+  BUILD_CMD/TEST_CMD/LINT_CMD  verified commands (must actually exist)
+  RUN_NOTES             how to run locally, if non-obvious
+  MCP_RULES             one line per detected MCP server (see tune-context skill)
+  ARCHITECTURE_BULLETS  3-6 lines, module -> responsibility
+  CONVENTIONS           only rules that bite (things that break if ignored)
+Keep this file thin: headings + pointers. Depth goes into skills.
+-->

package/skills/tune-context/templates/CLAUDE.md.user.tmpl

@@ -0,0 +1,23 @@
+# CLAUDE.md (user) — token-efficient defaults
+
+Cross-project defaults. **Depth lives in skills** (loaded on demand), not here —
+keep this file thin.
+
+## Working methods (token-saving)
+- **Search by meaning, not text.** Prefer a semantic-search MCP
+  (`search_codebase`) over broad `grep`/`find` for "where/why is X"; read only
+  the returned spans. Full playbook: `token-efficiency` skill.
+- **Read narrow.** Ranged reads; `git diff` after edits; never re-read a file
+  already in context.
+- **Delegate broad searches** to an Explore/subagent — it burns its own context
+  and returns the conclusion.
+- **Terse by default;** `/caveman` for maximum compression. (Suspend for safety
+  and irreversible-action confirmations.)
+- **Contracts-first** (`/cdd`): write the contract in comments before the code; it
+  becomes the test assertions and improves retrieval.
+- **Phase hygiene:** `/phase-workflow` at phase boundaries (state-doc +
+  `/compact`); `/clear` between unrelated tasks.
+- **New project:** set up semantic search (`rag-init`) proactively.
+
+Skills carry the full playbook: `token-efficiency`, `caveman`, `cdd`,
+`phase-workflow`.

package/skills/tune-context/templates/settings.json.tmpl

@@ -0,0 +1,58 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/pre-compact-snapshot.mjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/session-start-reinject.mjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\""
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash({{BUILD_CMD}}:*)",
+      "Bash({{TEST_CMD}}:*)",
+      "Bash({{LINT_CMD}}:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ]
+  }
+}