interscribe

keep priority P3 effort S wave 3

What it does: Confirmed against files: a skill-only plugin (v0.1.1, no MCP/hooks/commands/agents) with one skill skills/interscribe/SKILL.md and two deterministic shell helpers (scripts/audit-docs.sh for wc-based line/token metrics + budget flags, scripts/find-duplicates.sh for normalized H2 heading-overlap detection). It enforces one convention: CLAUDE.md = Claude Code config only; AGENTS.md = all project knowledge; docs/ = deep reference linked from AGENTS.md. Three modes — audit (5 checks: boundary classification, token budget, duplication, staleness, depth >100-line sections; emits A-F health score), refactor (fully automatic, git-diff-reviewable restructuring: move violations CLAUDE.md→AGENTS.md, extract oversized sections to docs/ with backlinks, dedup with pointers, fix stale refs), and consolidate (cross-hierarchy global→project→subproject dedup, keep at highest common ancestor, flag contradictions). Deterministic metrics in shell, semantic judgment delegated to the LLM. Has structural pytest tests and a docs/canon/ convention. Progressive disclosure already implemented via SKILL.md + SKILL-compact.md.

Rationale: This is a mature, tightly-scoped, single-purpose plugin that is directly validated by the strongest 2026 SOTA signals. The “context engineering as an optimization problem” finding (Meta Context Engineering; “most agent failures are context failures, not model failures”; context rot) and the token-economics finding (“the token bill comes due”, agents spending ~80% of tokens just finding things, every session-start token must be actionable) are exactly the problem interscribe attacks: keeping CLAUDE.md/AGENTS.md lean, non-redundant, and correctly partitioned so session-start context is minimal and high-signal. The harness-engineering finding explicitly names “AGENTS.md/CLAUDE.md as persistent project memory” and the memory-integrity finding endorses “human-auditable, version-controlled memory (git-tracked markdown) over opaque auto-updating stores” — interscribe’s git-diff-reviewable, deterministic-shell-plus-LLM design is squarely on that recommended path. The architecture follows the agreed-upon “thin skill orchestrating deterministic scripts” pattern: shell handles what shell does well (counts, overlap), LLM handles semantics. Progressive disclosure (SKILL.md + SKILL-compact.md) is already in place, matching the SKILL.md-standard finding. It does one job, does it well, and its job is rising in importance. This is the textbook “mature plugin = keep” case; reserve modernize/deprecate for real gaps, and the gaps here are minor.

SOTA gap: Two frontier ideas it lacks, neither severe: (1) Deterministic guardrail enforcement. The harness-engineering SOTA (“anything that must happen every time should be a deterministic hook, not something you hope the model remembers”) and interscribe’s own AGENTS.md “Known Constraints” both admit the boundary rule is “a convention, not a hard constraint — interscribe reports and fixes violations but can’t prevent them from being reintroduced.” A PreToolUse/Stop hook that warns when project knowledge is written into CLAUDE.md would turn a one-shot audit into continuous enforcement — and interwatch already proves the hook-on-doc-access pattern works in this ecosystem. (2) Grammar-constrained / deterministic-skeleton structured output for the audit report (Pre3/IterGen/deterministic-skeleton + LLM-island finding): the audit currently emits free-text Markdown, so its health score and violation list can’t be reliably machine-consumed by interwatch or a CI gate. A StructuredOutput-style JSON contract for the audit would let interwatch trigger interscribe:audit on structural drift (an integration the AGENTS.md already aspires to but hasn’t wired up). Note: the multi-agent/orchestration/memory-graph SOTA cluster is NOT a real gap here — this is a deterministic doc-linter, and fan-out/agent-memory machinery would be overkill (the 15x-token caveat applies).

Redundancy: Boundaries are clean and the plugin’s own AGENTS.md “Integration Points” table already disambiguates them correctly. interdoc GENERATES AGENTS.md from code (and does CLAUDE.md harmonization); interscribe RESTRUCTURES existing docs — adjacent, not overlapping (run interdoc first, interscribe after). One soft overlap: interdoc lists “CLAUDE.md harmonization” in its description, which brushes against interscribe’s boundary-enforcement — worth a one-line note in each AGENTS.md clarifying that interscribe owns the boundary rule and interdoc defers to it. intermem GRADUATES memory facts INTO AGENTS.md/CLAUDE.md (a writer); interscribe cleans up after (a restructurer) — complementary. interwatch DETECTS drift and dispatches generators; interscribe is a candidate dispatch target it doesn’t yet call. /review-doc scores content quality vs interscribe’s structural quality. /distill applies progressive disclosure to skills vs interscribe to project docs. No merge candidate — each has a distinct verb (generate / graduate / detect / restructure).

Actions:

Add an optional deterministic guardrail hook (PreToolUse or Stop) that flags when Edit/Write adds project-knowledge-shaped content to a CLAUDE.md — turning the one-shot audit into continuous enforcement, mirroring interwatch’s doc-access hook pattern. This closes the plugin’s own stated ‘can’t prevent reintroduction’ constraint.
Add a —json / structured-output mode to audit that emits the health score + violations as a machine-parseable contract (deterministic-skeleton + LLM-island style), so interwatch and CI gates can consume it. Then wire the interwatch→interscribe:audit-on-structural-drift integration the AGENTS.md already names as aspirational.
Fix stale internal references: AGENTS.md says ‘Current Version: 0.1.0’ (plugin.json is 0.1.1) and ‘Components: … 3 scripts’ while PHILOSOPHY.md/SKILL.md count 2 helper scripts (find-duplicates + audit-docs; bump-version is release tooling) — interscribe should pass its own staleness check. Also reconcile the README/AGENTS script-count discrepancy.
Add a one-line cross-reference in both interscribe and interdoc AGENTS.md clarifying that interscribe owns the CLAUDE.md/AGENTS.md boundary rule and interdoc’s ‘CLAUDE.md harmonization’ should defer to it, eliminating the only soft redundancy.