claude-code-kit 0.61.0__tar.gz → 0.63.0__tar.gz

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "claude-kit",
       "source": "./",
       "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker): install CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json, then run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.",
-      "version": "0.61.0",
+      "version": "0.63.0",
       "license": "MIT",
       "keywords": ["sdlc", "agents", "orchestration", "quality-gates", "workflow", "scaffold", "cookiecutter"]
     }

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-kit",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC config (no app code, no Docker). `claude-kit init` asks ordered questions and installs CLAUDE.md + .claude/ (rules, the profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates with working memory and a self-improving learnings loop.",
   "author": {
     "name": "Arjunsingh Yadav",

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/CHANGELOG.md

@@ -4,6 +4,121 @@ All notable changes to claude-kit are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project uses
 [semantic versioning](https://semver.org/).
 
+## [0.63.0] — 2026-07-16
+
+**Catalog fix — the `auditor` agent can finally get the MCP server it depends on.** The `auditor`
+agent (enterprise profile) drives its entire audit workflow — navigate, snapshot, screenshot,
+performance trace, console inspection — through the **Chrome DevTools MCP**, but `catalog/mcp.yaml`
+only offered `playwright`, so a user who installed the auditor had **no catalog option** to enable
+the server it requires. This surfaced during a full-lifecycle SDLC coverage audit (external /
+black-box testing vertical). Pure data change — no `resolve()` branches, no new agents/skills
+(golden rule #7).
+
+### Added
+
+- **`chrome-devtools` MCP server** in `catalog/mcp.yaml` — stdio, pinned to
+  `chrome-devtools-mcp@1.6.0` (the official Google Chrome DevTools MCP; referenced, not vendored,
+  like every other catalog server). Selectable via `claude-kit init` / `list-options`; writes into
+  the project `.mcp.json` + `.mcp.lock.json` when chosen. Carries the same toxic-flow annotation
+  discipline as `playwright` (untrusted-content on any loaded page · egress to arbitrary URLs —
+  point it only at trusted dev/staging targets).
+
+### Changed
+
+- `docs/install.md` MCP-integrations list now enumerates Chrome DevTools (the canonical full list
+  stays `claude-kit list-options`).
+
+### Not adopted (deliberately)
+
+- **No auto-wiring of `chrome-devtools` to the auditor agent or the enterprise profile.** MCP
+  servers stay user-selected and opt-in across the whole catalog — a browser MCP is a real egress
+  surface, so the user makes the trust decision. The fix closes the *availability* gap (the server
+  is now offerable); it does not silently enable a browser in anyone's project.
+- **The deeper external/black-box testing gaps stay open for an owner decision** — no gate spawns
+  the `auditor` (it remains available-but-not-gated), and there is still no page-performance-budget
+  enforcement, visual-regression, or synthetic uptime probe. Those are enforcement-design choices
+  (they change what blocks a pipeline), tracked in the SDLC coverage audit alongside the existing
+  user-gated backlog; this release deliberately ships only the self-contained catalog correctness fix.
+
+## [0.62.0] — 2026-07-15
+
+**OSS-adoption wave 3 — the two L-sized consolidation items that close out the implement-now
+backlog from the 1,345-repo scan** (waves 1–2 = 0.60.0/0.61.0 below). Same discipline: everything
+re-derived as stack-agnostic prose; referenced, never vendored. With this release the scan's
+20-item implement-now backlog is **fully shipped**; the remaining 10 ideas are user-gated
+(listed under "Not adopted" in the 0.60.0 entry) and await an owner decision.
+
+### Added
+
+- **`context-engineering` skill consolidation pass** (merges 8 verified proposals):
+  - **Five primitives** (was four) — new "Think in code" primitive: when the question is
+    aggregation over data, one throwaway script that prints only the answer replaces the
+    thousand lines the agent would otherwise read (from `gsd-build/get-shit-done`).
+  - **Content-type-aware compression recipes** in Tool-output offloading — JSON arrays keep
+    first/last few + 100% of errors/outliers/relevant matches; logs keep errors/failures/summary
+    and drop PASSED noise; search results keep exact + diverse hits; diffs keep hunks only — with
+    a **~200-token floor** below which compression costs more than it saves, and the
+    **reversible-marker discipline**: full original to a file, inline marker with the dropped-item
+    count + retrieval path — a compression the agent can't undo is a deletion (Apache-2.0
+    `headroomlabs-ai/headroom`).
+  - **"Retrieval discipline: read symbols, not files"** — a three-rung ladder: symbol-level
+    retrieval first (harness LSP / IDE / the `serena` MCP fragment; one atomic go-to-definition
+    replaces the 8–12-step open-scroll-grep dance), semantic search + code-graph navigation
+    second, grep only for exhaustive literal jobs; prefer chunks that *define* a symbol over ones
+    that mention it (MIT `oraios/serena` · `MinishLab/semble`).
+  - **"Making the budget visible"** (native statusline API; `jarrodwatts/claude-hud` referenced)
+    and **"Observable symptoms of subagent context pressure"** (silent partial completion,
+    increasing vagueness, skipped protocol steps — verify handoffs against the task's
+    **must-haves, not file existence**), echoed in the orchestrator's rotate-before-degradation
+    bullet.
+  - **Tribal-standards sub-step** in the comprehension pipeline — the four-part tribal test (new
+    dev guesses wrong / corrected in review / has a why / stable) and the one-pattern-at-a-time
+    elicitation loop (from `buildermethods/agent-os`).
+- **`tool-design` rule expansion pass** (merges 7 verified proposals; 9.7k → 17.2k chars):
+  - **§9 Anchor edits to content, not position** — content hash captured at read, re-verified at
+    apply, fail fast with a drift report (fuzzy recovery opt-in only); a byte-identical edit
+    returns "the bug is elsewhere" and N consecutive no-ops is a hard error (MIT
+    `can1357/oh-my-pi`).
+  - **§10 Write the tool description like an API contract** — surface not machinery; the six-part
+    anatomy (purpose, input grammar, 3–8 worked examples, agent-owned failure shapes, WRONG/RIGHT
+    pairs, recap); evidence-based pruning — "the model could infer this" is necessary but never
+    sufficient to cut a line (MIT `gsd-build/get-shit-done`).
+  - **§11 Errors an agent can parse — and denials an agent can act on** — success/error envelope
+    split, wire-stable category IDs with exit codes derived from category, actionable hint
+    carrying the exact recovery command, never branch on an upstream `code == 0` (MIT
+    `larksuite/cli`); plus the **deny-message rubric**: every denial states CASE A (redirect —
+    name the approved route) or CASE B (policy — stop, don't route around).
+  - **§1 pre-run MCP audit** (schema cost compounds per-turn × per-subagent;
+    `enabledMcpjsonServers`/`disabledMcpjsonServers` carry a server without loading it —
+    `mksglu/context-mode`, referenced) and **§4 "Compress at the source"** (compact modes first:
+    failures-only, `--quiet`/`--porcelain`, JSON + selector, dedup-with-count, one-line success
+    acks — Apache-2.0 `rtk-ai/rtk`) + the reversible-compression marker (producer-side twin of
+    the context-engineering rule).
+- **`docs/influences.md`** gains the 1,345-repo OSS adoption scan row (sources, licenses, and the
+  0.60.0–0.62.0 landing map).
+
+### Changed
+
+- **`guard-kubectl-delete.sh`** deny message gains the explicit CASE B clause the new §11 rubric
+  requires: "a human operator must run it directly — do not work around this guard." (The kit's
+  other three guards already named their approved routes; content-only edit, hook registry
+  untouched.)
+- **`agents/orchestrator.md`** rotate-before-degradation bullet now names the three context-
+  pressure symptoms and requires handoff verification against must-haves, not file existence.
+
+### Not adopted (deliberately)
+
+- **The 10 user-gated backlog items remain gated** (Stop-hook guard, warn-context-flood hook,
+  DESIGN.md template, marketplace split, skills export target, React perf overlay, visual-report
+  skill, detect-correction hook, org skill-governance rule, whole-payload compression pass) —
+  each changes kit behavior, scope, or structure in a way the owner should decide, not a scan.
+  Full rationale in the 0.60.0 entry.
+- **Vendoring any scanned code** — every adoption in waves 1–3 is re-derived prose with source
+  attribution; `rtk`, `claude-hud`, `context-mode`, `serena`, and `semble` are referenced or
+  wired as opt-in MCP fragments, never copied in.
+- **Renumbering `tool-design` sections** — the new material lands as §9–§11 after the existing
+  §1–§8 so cross-references from other rules/skills stay stable.
+
 ## [0.61.0] — 2026-07-15
 
 **OSS-adoption wave 2 — nine more items from the 1,345-repo scan backlog** (wave 1 = 0.60.0 below).

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-kit
-Version: 0.61.0
+Version: 0.63.0
 Summary: Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop.
 Project-URL: Homepage, https://github.com/ajyadav013/claude-kit
 Project-URL: Repository, https://github.com/ajyadav013/claude-kit
@@ -149,7 +149,7 @@ claude-kit init --defaults      # non-interactive: React + Python/FastAPI + Post
 | 📐 **Rules & skills** | **25** stack-agnostic core rules + **105** context-activated skills (57 core + 48 stack-collection), pulled into context on demand |
 | 🧱 **Stacks & overlays** | A stack-agnostic core + **13** overlay rule files (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands and path-scoped to load only when you touch matching files |
 | 🛠️ **Hooks & guards** | **18** event hooks — deterministic safety guards and advisory warnings — that no-op gracefully without `jq` |
-| 📦 **Distribution & lifecycle** | Plugin **and** pip from one source, **22** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
+| 📦 **Distribution & lifecycle** | Plugin **and** pip from one source, **23** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
 
 Profiles (`lean` · `standard` · `enterprise`), team scopes, autonomy levels, and org capability
 packs decide how much of this actually installs — see

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/README.md

@@ -116,7 +116,7 @@ claude-kit init --defaults      # non-interactive: React + Python/FastAPI + Post
 | 📐 **Rules & skills** | **25** stack-agnostic core rules + **105** context-activated skills (57 core + 48 stack-collection), pulled into context on demand |
 | 🧱 **Stacks & overlays** | A stack-agnostic core + **13** overlay rule files (React · FastAPI · Go · Postgres · Mongo) wired to your exact commands and path-scoped to load only when you touch matching files |
 | 🛠️ **Hooks & guards** | **18** event hooks — deterministic safety guards and advisory warnings — that no-op gracefully without `jq` |
-| 📦 **Distribution & lifecycle** | Plugin **and** pip from one source, **22** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
+| 📦 **Distribution & lifecycle** | Plugin **and** pip from one source, **23** ready MCP fragments (version-pinned), edit-preserving `upgrade`, and a root `AGENTS.md` at init so non-Claude agents share the same standards |
 
 Profiles (`lean` · `standard` · `enterprise`), team scopes, autonomy levels, and org capability
 packs decide how much of this actually installs — see

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/agents/orchestrator.md

@@ -581,9 +581,12 @@ become blockers — don't just wait at the next join:
   hand it a pre-planned buffer task (investigation, doc refresh, test hardening, design validation).
   Keep a small buffer list ready when you spawn the lanes (see the sprint plan's extra-tasks list).
 - **Context exhaustion → rotate before degradation.** Watch each long-running agent's commit cadence
-  and output quality as a proxy for context budget. Rotate in a fresh agent *before* quality decays,
-  capturing state to working memory first — see the Agent Capacity & Replacement guidance in the
-  `sprint` skill and `.claude/rules/agent-resilience.md`. Don't run one agent until it falls over.
+  and output quality as a proxy for context budget. The observable pressure symptoms (per the
+  `context-engineering` skill): silent partial completion, increasing vagueness, skipped protocol
+  steps. Rotate in a fresh agent *before* quality decays, capturing state to working memory first —
+  and verify the rotated-out agent's handoff against the task's **must-haves, not file existence**.
+  See the Agent Capacity & Replacement guidance in the `sprint` skill and
+  `.claude/rules/agent-resilience.md`. Don't run one agent until it falls over.
 - **Critical-path slippage → re-balance.** If the slowest lane *on the critical path* slips, pull a
   parallelizable task forward onto a free agent, or flag the slip — don't silently absorb it into a
   blown join.

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/catalog/mcp.yaml

@@ -72,6 +72,15 @@ servers:
       type: stdio
       command: npx
       args: ["-y", "@playwright/mcp@0.0.77"]
+  chrome-devtools:
+    label: "Chrome DevTools (live-page audit: a11y/perf/Core Web Vitals/console/responsive — powers the `auditor` agent)"
+    # The `auditor` agent (enterprise profile) drives its whole workflow — navigate, snapshot, screenshot,
+    # performance trace, console — through this server; without it the agent has no browser to inspect.
+    # toxic-flow legs: untrusted-content (ANY loaded page) · egress (navigates arbitrary URLs) — browser-grade; point it only at trusted dev/staging targets.
+    config:
+      type: stdio
+      command: npx
+      args: ["-y", "chrome-devtools-mcp@1.6.0"]
   docs:
     label: "Docs / Context7 (live library docs)"
     # toxic-flow legs: untrusted-content (fetched pages) · egress (hosted endpoint)

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/docs/influences.md

@@ -31,6 +31,7 @@ non-duplicative gaps**, minimally and catalog-wired.
 | **[google](https://github.com/google) org review** (all 2,881 repos) | Reproducible-build verification & source-level missing-patch detection; secure-by-construction injection defense; archive-extraction & ReDoS hardening; multi-party authorization / breakglass; coverage-guided & continuous fuzzing; parameterized + semantic-equality + parallel/flaky testing; compile-time logic-bug & license-header lint layers + deterministic block sorting; multi-window burn-rate alerting & log rate-limiting; long-document extraction; prompt-as-code; statistical browser benchmarking; durable atomic writes; record-replay API testing; first-party SecOps MCP servers | Prose extensions across `security-and-hardening` (reproducible-build · missing-patch · secure-by-construction · archive · ReDoS), `human-in-the-loop` (MPA/breakglass), `testing` (fuzzing · parameterized · semantic-equality · parallel/flaky), `linting-and-formatting` (logic-bug + license-header layers · block sorting), `devops-observability` (burn-rate · log rate-limit), `context-engineering` (long-doc extraction), `reasoning-techniques` (prompt-as-code), `performance-optimization` (statistical benchmarking), `tool-design` (durable atomic writes), `api-integration` (record-replay) + **4 first-party SecOps MCP fragments** (Chronicle SIEM · GTI · SCC · SOAR) — **0 new agents/skills/rules** (from oss-rebuild · vanir · safe-active-record/mug · safearchive · re2 · building-secure-and-reliable-systems · patrick · go-cmp · atheris/honggfuzz/clusterfuzzlite · gtest-parallel · error-prone · addlicense · keep-sorted · prometheus-slo-burn · flogger · langextract · dotprompt · tachometer · renameio · test-server · mcp-security) | `0.51.0` |
 | **[facebook](https://github.com/facebook) (Meta) org review** (all 168 repos) | Interprocedural taint / data-flow security analysis (source→sink across functions); continuous A/B performance-regression CI gate; defense-in-depth agent-sandbox enforcement (argument validation + OS-level backstop) | Prose extensions to `linting-and-formatting` (taint/data-flow layer), `devops-observability` (perf-regression gate), `agent-guardrails` (§4 layered sandbox enforcement) — **0 new agents/skills/rules** (from pyre-check/Pysa · mariana-trench · FAI-PEP · mcpguard-dynamic; the org is mostly libraries/frameworks, so the verify pass *dropped* the rest — `DNE-TaaC`, `mbt`, plus already-covered `infer`/`mariana-trench`-as-tool, `fbt`, `memlab`, …) | `0.52.0` |
 | **[Netflix](https://github.com/Netflix) · [aws](https://github.com/aws) · [apple](https://github.com/apple) org review** (all **1,214** repos) | Service-level resilience the kit lacked entirely — stability patterns (timeout/retry-budget/circuit-breaker/bulkhead) + adaptive concurrency limiting, chaos engineering, and bounded-clock distributed time; failure-domain-aware progressive rollout; deterministic simulation testing; a formal RFC process (working-backwards + API bar-raiser); continuous usage-based least-privilege | The **new `resilience-engineering` rule** (chaos + stability patterns + bounded clocks, from `Netflix/concurrency-limits` · `Netflix/chaosmonkey` · `aws/clock-bound`); plus prose extensions to `devops-observability` (failure-domain rollout, from `aws/zone-aware-controllers-for-k8s`), `testing` (deterministic simulation testing, from `apple/foundationdb`), `spec-driven-development` (RFC track, from `aws/aws-cdk-rfcs`), and `security-and-hardening` (continuous least-privilege, from `Netflix/repokid`) — **1 new rule, 0 new agents/skills** (the orgs are overwhelmingly SDKs/CLIs/services, so the survey kept only 7 of 1,214) | `0.53.0` |
+| **1,345-repo OSS adoption scan** (39 provenance-tagged searches across the AI/Claude/MCP/context ecosystem; 76 verified adoption ideas → 30-item backlog) | Agent-config supply-chain vetting + toxic-flow legs taxonomy; hidden-Unicode detection; content-type-aware **reversible** output compression (~200-token floor) + "think in code" (from Apache-2.0 `headroomlabs-ai/headroom` · `gsd-build/get-shit-done`; deterministic shell-side companion `rtk-ai/rtk`, referenced); symbol-first retrieval ladder (from MIT `oraios/serena` · `MinishLab/semble`); budget-visible statusline HUDs (`jarrodwatts/claude-hud`, referenced); tribal-standards elicitation (from `buildermethods/agent-os`); evidence-based test nagging + falsifiability eval discipline (from `maxritter/pilot-shell`); colocated skill evals (from `darkrishabh/agent-skills-eval`) | Waves across `dependency-verification` (vetting canon), `catalog/mcp.yaml` (+5 fragments → 22, all leg-annotated), `validator.py` (Unicode scan + INFO channel), **new `check_cross_references.py` CI gardener**, `context-engineering` (compression recipes · 5th primitive · retrieval ladder · budget visibility · pressure symptoms · tribal test), `tool-design`, `evals` §9–10 + `eval-harness`, `agent-guardrails` §3/§4, orchestrator VALIDATE, consolidate-learnings Promote, and ~10 more files — **0 new agents/skills, 1 new CI script** | `0.60.0`–`0.62.0` |
 
 > Each adoption is detailed in the [CHANGELOG](../CHANGELOG.md) — including, for every review, what we
 > deliberately **did not** add because the kit already covered it.

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/docs/install.md

@@ -76,7 +76,7 @@ config — nothing else:
 3. **Backend language** (default: Python; `none` for frontend-only projects) → **backend framework** (default: FastAPI)
 4. **Database** (PostgreSQL · MongoDB · `none`)
 5. **SDLC profile** (`lean` · `standard` · `enterprise`)
-6. **Optional MCP integrations** (GitHub · Jira/Linear · Azure DevOps · Postgres/Mongo · Playwright · Docs/MS Learn · Azure · Wassette · Sentry · Repowise · the Google security suite — full list: `claude-kit list-options`) — a
+6. **Optional MCP integrations** (GitHub · Jira/Linear · Azure DevOps · Postgres/Mongo · Playwright · Chrome DevTools · Docs/MS Learn · Azure · Wassette · Sentry · Repowise · the Google security suite — full list: `claude-kit list-options`) — a
    project-root `.mcp.json` is written **only** if you select any (env placeholders, never secrets)
 7. **Learning capture** (`session-end-catchup` default · `session-end` · `per-task` · `off`) — how often
    the background learnings job runs. *Privacy note:* it reads your session transcript + changed files

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/hooks/scripts/guard-kubectl-delete.sh

@@ -33,6 +33,7 @@ if printf '%s' "$CMD" | tr -d '"\047\134' | tr ';|&' '\n\n\n' \
   echo "BLOCKED: 'kubectl delete' is disabled by claude-kit -- destructive deletes must not run from an agent session." >&2
   echo "  Use a reversible alternative: 'kubectl scale --replicas=0' to stop a workload, 'kubectl rollout undo' to roll back," >&2
   echo "  or remove the resource from the Git/Helm source and let the pipeline reconcile." >&2
+  echo "  If a true delete is genuinely required, a human operator must run it directly -- do not work around this guard." >&2
   echo "  Read-only checks still work ('kubectl auth can-i delete <res>', 'kubectl get/describe'). (guard-kubectl-delete.sh)" >&2
   exit 2
 fi

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "claude-code-kit"
-version = "0.61.0"
+version = "0.63.0"
 description = "Cookiecutter-style scaffolder for an autonomous Claude Code SDLC configuration (no app code, no Docker). Asks ordered questions and installs CLAUDE.md + .claude/ (rules, the chosen profile's agents/skills, hooks, artifact templates) + optional .mcp.json; run /sdlc to drive spec → review → build → test → security → ship through profile-aware quality gates, working memory, and a self-improving learnings loop."
 readme = "README.md"
 requires-python = ">=3.9"

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/rules/tool-design.md

@@ -17,6 +17,16 @@ costs ~nothing until invoked, and composes — its output can pipe into the next
 persistent MCP server when you genuinely need stateful sessions, pushed events, or auth the agent
 can't hold; otherwise prefer a script the agent runs.
 
+**Audit what's actually loaded before a substantial run.** A persistent server's cost is not paid
+once — its schema re-enters context **every turn, for every subagent** that inherits the config, so
+one unused server taxes an entire fan-out multiplicatively. The harness exposes per-project switches
+(`enabledMcpjsonServers` / `disabledMcpjsonServers` in settings) precisely so a project can *carry* a
+server in `.mcp.json` yet keep it out of context until a task needs it. Make the audit a pre-run
+habit: list what's enabled, disable what this run won't use, re-enable on demand.
+
+> Pre-run MCP audit pattern from [`mksglu/context-mode`](https://github.com/mksglu/context-mode).
+> Referenced, not vendored.
+
 ## 2. Progressive disclosure
 
 Don't dump every capability up front. Expose a **name + one-line description**; load full usage only
@@ -36,6 +46,21 @@ the task — see `.claude/skills/context-engineering`.
 - **Single grep-friendly errors.** Emit failures as one line (`ERROR <reason>`) the agent can scan for.
 - **Pre-compute summaries** so the agent reasons from a compact signal, not raw output.
 - **Offer a fast/sampled mode** for tight iteration loops where full output isn't needed.
+- **Compress at the source — ask for less before trimming what came back.** Most tools already have a
+  compact mode; make it the one the agent reaches for first: failures-only test output, `--quiet` /
+  `--porcelain` / summary flags, JSON narrowed by a selector instead of a full dump, repeated lines
+  deduplicated to one line with a count, and a **one-line acknowledgement for success** (a passing
+  step needs "OK" and a number, not its full log). Filtering after the fact still paid for the tokens;
+  the compact flag never emits them.
+- **Make every compression reversible.** When a tool truncates, samples, or dedups, it must write the
+  full original to a file and leave an inline marker carrying the dropped-item **count** and the
+  **retrieval path** — never silently drop items. A compression the agent can't undo is a deletion.
+  (The consumer-side twin of this rule lives in `.claude/skills/context-engineering`.)
+
+> Source-side compaction (compact flags, dedup-with-count, one-line success acks) adapted from the
+> Apache-2.0 [`rtk-ai/rtk`](https://github.com/rtk-ai/rtk); the reversible-marker discipline from the
+> Apache-2.0 [`headroomlabs-ai/headroom`](https://github.com/headroomlabs-ai/headroom). Re-derived in
+> prose; not vendored.
 
 ## 5. Structured output for machine consumption
 
@@ -121,6 +146,78 @@ between *looks* atomic and *is* durable:
 > Apache-2.0 [`alibaba/loongsuite-js`](https://github.com/alibaba/loongsuite-js) hook instrumentation.
 > Re-derived in prose; not vendored.
 
+## 9. Anchor edits to content, not position
+
+A tool that edits files on an agent's behalf must verify it is editing **what the agent last saw**,
+not whatever now sits at the same coordinates. Line numbers and byte offsets go stale the moment a
+formatter, a hook, or a parallel agent touches the file — and a stale-anchor edit silently corrupts
+the one thing the agent believed it controlled.
+
+- **Capture a content hash at read time; re-verify at apply time.** When the agent reads the region it
+  intends to edit, record a hash (or the exact text) of that region. On apply, re-hash: on mismatch,
+  **fail fast with a report of what changed** — never apply to drifted content. The agent then
+  re-reads and re-anchors; anything smarter (fuzzy re-matching) is a conservative, opt-in recovery
+  mode, never the default.
+- **Treat a no-op edit as a signal, not a success.** If applying an edit produces byte-identical
+  output, the premise behind the edit was wrong — return "no change made; the bug is likely elsewhere"
+  instead of a success code. **N consecutive no-op edits is a hard error**: the agent is spinning on a
+  false belief about the file, and every hollow "success" reinforces it.
+
+> Hash-anchored edits and the no-op escalation guard adapted (stack-agnostic) from the MIT-licensed
+> [`can1357/oh-my-pi`](https://github.com/can1357/oh-my-pi). Re-derived in prose; not vendored.
+
+## 10. Write the tool description like an API contract, not an implementation tour
+
+The description is the only part of your tool the model reads before deciding to call it. It is a
+prompt, and it deserves prompt-quality authoring.
+
+- **Describe the surface, not the machinery.** What the tool does, takes, and returns — never how it
+  works inside. Internals the agent can't act on are pure token cost, and worse, they invite the
+  agent to reason about (and route around) the implementation.
+- **Six-part anatomy** for any non-trivial tool: (1) a one-sentence **purpose**; (2) the **input
+  grammar** — exact shapes, defaults, units; (3) **3–8 worked examples** spanning easy to edge case
+  (one example is a special case the model overfits to; zero is a guess); (4) the **failure shapes the
+  agent owns** — which errors it should handle itself, and how; (5) **WRONG/RIGHT anti-pattern pairs**
+  for misuse you have actually observed; (6) a one-line **recap** of the contract.
+- **Prune on evidence, never on inferability.** "The model could infer this" is necessary but never
+  sufficient to cut a line — check history (`git blame` / log) first: description lines are often
+  load-bearing fixes for a failure someone already debugged. Cut only what you can show never fires.
+
+> Description anatomy and evidence-based pruning adapted (stack-agnostic) from the MIT-licensed
+> [`gsd-build/get-shit-done`](https://github.com/gsd-build/get-shit-done). Re-derived in prose; not
+> vendored.
+
+## 11. Errors an agent can parse — and denials an agent can act on
+
+§4 makes errors single-line and grep-able; this section fixes their **content**. An agent recovers
+from a failure exactly as well as the error message lets it.
+
+- **Split the envelope.** Success and error must be structurally distinguishable — distinct exit
+  codes, or a status field in structured output — never left for the agent to infer from prose.
+- **Wire-stable category, free informational text.** Give every failure a short **category ID** that
+  retry logic can branch on (`NOT_FOUND`, `PERMISSION`, `CONFLICT`, …) and keep it stable across
+  releases; the human-readable message may change freely. Derive exit codes from the category, not
+  ad hoc per call site.
+- **Actionable hint with the exact recovery command.** "Auth expired — run `<tool> login`" lets the
+  agent self-recover in one step; "authentication error" starts a guessing loop.
+- **Never surface an upstream success flag as your own.** A wrapper that reports success because the
+  transport returned `code == 0` while the payload carries an error teaches the agent the operation
+  worked. Branch on the payload's own contract, not the carrier's.
+
+**Deny messages are error messages.** When a hook or permission layer blocks a call, its text is
+consumed by an agent, and a bare "blocked" produces either a retry loop or silent abandonment. Every
+denial is one of two cases — say which:
+
+- **CASE A — redirect.** The *goal* is fine; the *route* is wrong. Name the approved route:
+  "Direct DB writes are blocked — apply schema changes via a migration file."
+- **CASE B — policy denial.** The goal itself is out of bounds. Say so, name the policy, and tell the
+  agent to stop rather than route around: "Force-push to a shared branch is not permitted (branch
+  protection). Do not retry; ask a human if you believe this is wrong."
+
+> Error-envelope discipline (categories, hints, exit codes from category, the `code == 0` trap)
+> adapted (stack-agnostic) from the MIT-licensed [`larksuite/cli`](https://github.com/larksuite/cli).
+> Re-derived in prose; not vendored.
+
 ## Rules
 
 1. **Design for the agent, not a human dashboard** — text-first, token-aware, self-describing.
@@ -132,6 +229,13 @@ between *looks* atomic and *is* durable:
    over-dispatching and over-sourcing burn budget without returning it (§7).
 6. **Design the tool *set* for orchestration** — discoverable registry, plan-before-execute, concurrent
    independent calls, durable cross-turn state written atomically (tmp-write-then-rename) (§8).
+7. **Anchor edits to content** — hash at read, re-verify at apply, fail fast on drift; a byte-identical
+   edit means "the bug is elsewhere", and repeated no-ops are a hard error (§9).
+8. **The description is a prompt** — surface not machinery, six-part anatomy, prune only on evidence
+   (§10).
+9. **Errors carry category + hint** — split envelope, wire-stable category IDs, exact recovery
+   command; deny messages state CASE A (redirect: name the approved route) or CASE B (policy: stop,
+   don't route around) (§11).
 
 ## Relationship to other rules
 

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/skills/context-engineering/SKILL.md

@@ -148,9 +148,21 @@ window earns less attention than the front (the lost-in-the-middle curve, at sca
 flooding thresholds in Anti-Patterns (>5,000 lines is a smell; aim for <2,000 *focused* lines per
 task). When you cross these, compact or split the work — don't push on and hope.
 
+**Making the budget visible.** You can't manage a number you can't see: surface live context usage in
+the session UI where the harness supports it — Claude Code's statusline API can render tokens-used /
+%-of-window (community HUDs such as `claude-hud` build on it; referenced, not bundled). A visible
+percentage turns the ~40% threshold from a vibe into a trigger you actually act on.
+
+**Observable symptoms of subagent context pressure.** A subagent near its budget rarely *says* so —
+it *shows* it: **silent partial completion** (reports done, delivered half), **increasing vagueness**
+(precise `file:line` claims fade into "the relevant files"), and **skipped protocol steps** (stops
+running the verification it ran on earlier items). Treat these as a *context* signal, not a
+competence signal: rotate or replace the worker, and verify what it handed back against the task's
+**must-haves — not mere file existence** (a file existing proves nothing about its completeness).
+
 ## Advanced: progressive disclosure, compaction, offloading
 
-Four primitives keep long runs coherent:
+Five primitives keep long runs coherent:
 
 - **Progressive disclosure** — don't load everything up front. Expose names + one-line descriptions and
   load full detail only on use (how skills and well-designed tools work — see
@@ -162,7 +174,19 @@ Four primitives keep long runs coherent:
   critical work, not only when forced.
 - **Tool-output offloading** — don't dump large tool/command output into context. Keep a few signal
   lines inline and write the full output to a file the agent can open if needed (mirror of the output
-  rules in `.claude/rules/tool-design.md`).
+  rules in `.claude/rules/tool-design.md`). Compress **content-type-aware**, not blindly:
+  - JSON arrays → first ~3 + last ~2 items, **plus 100% of errors**, outliers, and task-relevant matches;
+  - test/CI logs → keep errors, failures, and the summary line; drop the `PASSED` noise;
+  - search results → the exact hits plus a few *diverse* ones, never 500 near-duplicates;
+  - diffs → hunks only, never surrounding whole files;
+  - under **~200 tokens, don't compress at all** — the bookkeeping costs more attention than it saves.
+
+  Make every compression **reversible**: write the full original to a file and leave an inline marker
+  carrying the dropped-item **count** plus the **retrieval path** — never silently drop items. A
+  compression the agent can't undo is a deletion.
+- **Think in code** — when the answer is *computable*, write one **throwaway script that prints only
+  the answer** (a count, a list of names, a pass/fail) instead of reading raw data into context and
+  reasoning over it. Five lines of script replace the thousand lines they read. Delete it after.
 - **Priority-based composition** — when assembling a prompt/context that may exceed the budget, assign
   each piece a **priority** rather than packing in fixed order, and when the total would overflow, drop
   the **lowest-priority** pieces first instead of truncating blindly at the end (which lops off whatever
@@ -176,7 +200,37 @@ Four primitives keep long runs coherent:
 > Compaction: tips for long-running agents." Paraphrased for this kit. The priority-based composition
 > primitive is a stack-agnostic adaptation of the MIT
 > [`microsoft/vscode-prompt-tsx`](https://github.com/microsoft/vscode-prompt-tsx) (priority-tree prompt
-> pruning under token budget); re-derived in prose, not vendored.
+> pruning under token budget); re-derived in prose, not vendored. The content-type compression recipes,
+> the ~200-token floor, and the reversible-marker rule are a stack-agnostic adaptation of the Apache-2.0
+> [`headroomlabs-ai/headroom`](https://github.com/headroomlabs-ai/headroom); "think in code" follows the
+> throwaway-script discipline in [`gsd-build/get-shit-done`](https://github.com/gsd-build/get-shit-done).
+> A deterministic companion exists for the compression recipes: **rtk** proxies common shell commands
+> through a PreToolUse hook and applies them before output ever reaches context (the harness's built-in
+> file/search tools bypass such proxies — it covers shell output only). Referenced, not bundled.
+
+### Retrieval discipline: read symbols, not files
+
+Order retrieval from precise-and-cheap to broad-and-expensive — most tasks never need the bottom rung:
+
+1. **Symbol-level first.** Resolve the *definition* or *references* of the symbol you actually care
+   about — via the harness's LSP tooling, the IDE, or a symbol-level MCP server (the optional
+   `serena` fragment in `catalog/mcp.yaml`). One atomic "go to definition" replaces the 8–12-step
+   open-scroll-grep-open-again dance, and returns tens of relevant lines instead of whole files.
+2. **Semantic search → navigate, don't browse.** Use search to locate the right `file:line`, then
+   expand along the code graph (callers, callees, imports — "find related"), not by opening sibling
+   files on speculation.
+3. **`grep` is for exhaustive literal jobs** — renames, string audits, count-every-occurrence — where
+   completeness beats precision. It is the wrong tool for "understand this feature".
+
+Prefer chunks that **define** a symbol over chunks that merely *mention* it, and down-weight tests,
+shims, and examples unless they are the task. Published symbol-retrieval benchmarks reach ~94% recall
+within a ~2k-token budget when tuned this way — precision at retrieval time is what keeps the session
+out of the degradation zone.
+
+> Symbol-first retrieval and the atomic-call rationale follow the MIT
+> [`oraios/serena`](https://github.com/oraios/serena); the define-over-mention ranking and
+> recall-at-budget framing follow [`MinishLab/semble`](https://github.com/MinishLab/semble).
+> Re-derived in prose; not vendored.
 
 ## Context Packing Strategies
 
@@ -268,6 +322,12 @@ org convention, not fixed by this kit) with a single root index and linked detai
 2. **Discover patterns inductively.** Read broadly and surface recurring structures. Apply the
    **3+-occurrences rule**: any structure that appears in three or more places is a *pattern* and
    earns a `patterns/` doc. Don't pre-decide the list — let the code reveal it.
+   - **Document tribal standards.** Some load-bearing conventions live only in heads. When a
+     recurring pattern has no written source, apply the four-part **tribal test**: would a new
+     developer guess wrong? does the team correct violations in review? is there a *why* behind it?
+     is it stable? Four yeses ⇒ it earns a `patterns/` doc. Elicit the *why* from the human **one
+     pattern at a time** (ask about one, write it down, move on) — never batch a questionnaire; the
+     tenth answer in a batch is a shrug, the tenth answer asked alone is a paragraph.
 3. **Map modules.** Enumerate every module (not just the obvious ones), grouped by role
    (core / supporting / infrastructure / utility); write the module map into `index.md`.
 4. **Map features & architecture.** Group entry points into features; map dependencies, data flows,

{claude_code_kit-0.61.0 → claude_code_kit-0.63.0}/src/claude_kit/__init__.py

@@ -7,4 +7,4 @@ Docker): ``claude-kit init`` asks ordered questions and lays down ``CLAUDE.md``
 as a plugin. Extensibility is data-driven via the ``catalog/`` (stacks, profiles, MCP).
 """
 
-__version__ = "0.61.0"
+__version__ = "0.63.0"