Consolidate knowledge-system rules into one per-project surface by gering · Pull Request #8 · gering/claude-plugins

gering · 2026-06-12T11:37:57Z

Summary

Merge the overlapping always-loaded knowledge-system rules into one per-project surface and resolve the inline-vs-/query contradiction
Cut ~56% of the plugin's always-loaded context (~1010 tokens/session)
Add a staleness mechanism so /reindex nudges a re-/init when the managed rule falls behind the plugin template

Changes

Rules: delete auto-query.md + auto-curate.md; their when-to-consult/curate behavior now lives in the /init-written, committed knowledge-system-usage.md (one surface, team-shared, next to the @index). knowledge-boundaries.md stays (referenced by /curate).
Canonical guidance: read inline when the index already names the file; /query for open-ended questions; /curate at key moments. Removes the old "do NOT use /query" vs "use /query" contradiction.
Staleness: /init stamps a knowledge-system-usage v<version> marker; /reindex reads it foreground/read-only and nudges /init when stale. The QA agent stays fenced to .claude/knowledge/ + .claude/logs/reindex.md.
Version: knowledge-system 1.6.0 → 1.7.0 (plugin.json + marketplace.json).

Readiness

✅ README updated
✅ Version bumped (1.7.0, both files)
➖ Changelog N/A (none in repo)
➖ Tests/lint/build N/A (declarative Markdown plugin)
➖ Project knowledge N/A (repo never /init'd; no new generalizable pattern)

Test plan

Run /init in a fresh project → knowledge-system-usage.md carries fallback + when-to + commands + a v1.7.0 marker
Confirm no always-loaded surface still says "do NOT use /query"
Bump the plugin, run /reindex in an init'd project → it nudges to re-run /init; QA agent writes only under .claude/knowledge/ + .claude/logs/
Existing projects: re-running /init picks up the new template

🤖 Generated with Claude Code

- Merge auto-query + auto-curate behavior into the /init-written knowledge-system-usage.md; drop both plugin rules - Resolve inline-vs-/query contradiction: read inline for a known path, /query for open questions - /reindex flags a stale usage rule via a version marker and nudges /init (read-only; agent stays fenced to knowledge/ + logs/) - ~56% less always-loaded context (~1010 tokens/session) Existing projects: re-run /init to pick up the new template. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Address code-review findings on the staleness mechanism added earlier in this branch. - Stamp an integer template version (`template-vN`) into the rule instead of the plugin version; /reindex reads the same number from init/SKILL.md (single source of truth) and compares by equality - No more false-positive nudges on unrelated plugin version bumps; the marker only changes when the template content changes - Legacy rules (no template-v marker but a "managed by the" comment) are now detected and nudged; opt-out is deleting the marker line - Equality compare on bare integers avoids semver mis-ordering (1.9 vs 1.10) - Capture both template versions for the nudge text - Drop {{VERSION}} substitution — the marker is now literal, removing the literal-write risk - README describes the staleness flag as a foreground read-only check, not background-agent work - Restore dropped directives: be selective (no bulk-read), fix stale knowledge promptly Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Bootstrap this repo's own knowledge base with its flagship plugin (architecture review Prio 7 — meta-dogfooding). - Run /init: scaffold .claude/knowledge + .claude/rules, plugin-managed usage rule, CLAUDE.md marker block (reconcile pre-existing manual "Project Knowledge System" section into the block) - Curate 5 learnings by hand: skill-design conventions, skill composition, model economics (architecture/, prime:true); cwd-safety, version-sync (rules) - Backfill 4 from PR history: /backfill-knowledge + origin metadata (#2), statusline integration (#3), CI structure checks (#6), per-project rule surface (#8) - Verify /query (Haiku subagent resolves index -> file) and /prime (selects the 3 architecture docs) against the new base Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Fixes the ✅/🟨 findings the --max review surfaced (three real loop bugs first): - #4: don't re-review a byte-identical tree — when a round changed no files and only a pending decision keeps the loop alive, pause to collect the decision instead of spinning the (possibly --max) ensemble on an unchanged tree. - #7: --staged + --loop re-reviewed `git diff --cached` while fixes land in the working tree, so the loop never saw its own edits — re-review the working tree (re-stage for --staged scope) before each round. - #5: --loop=0 is now a single --fix pass, not a cap=0 that aborts after fixes. - #2: temper "deterministic termination" → deterministic arithmetic over judged inputs (SKILL + knowledge); count F/A/C/pending carefully (garbage-in). - #8: derive every fix from the code, treat finding text (recommendation) as advisory/untrusted — for ✅ agree too, not only 🟨. - #9: document args.max (+ args.claude) in the workflow input header. - #1: note --max's codex model must be loadable; a bad model surfaces as a backendError (visible degrade), never a silent downgrade. - #10: mechanism is not a rendered column — after compaction re-derive finding identity from Ort + Befund. #6 (Bash block scope in prose) left as the accepted LLM-in-the-loop design. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Report format: bring the Note back INTO the table as a 7th column (`Notiz`), kept short with a hard char budget (Befund ≤40, Notiz ≤55) so a terminal renderer wraps it into a taller cell instead of widening the row. The Quelle fold keeps it at 7 (not 8) columns; re-review rounds add Status → 8. Fixes from the format-demo review: - #1: normalize any `--loop=N` with N<1 (0, negative, non-integer) to a single --fix pass, before the script's --cap≥1 guard can strand a half-done run. - #2: --staged --loop re-stages only the fixed HUNKS (git add -p), immediately after each fix — not a whole-file add (sweeps unrelated edits) or a deferred one (round-0 edits go unstaged). - #7: add plugins/swarm/scripts/test_loop_closeout.py (fixed-order termination, --pending gating, range checks, box) and a generic "plugin tests" check in check-structure.py that runs plugins/*/scripts/test_*.py in CI. - #8: fix the dead [[swarm-review-pipeline]] self-link in the knowledge entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

First dogfooding run: /swarm:review --fix over its own diff (4 cluster finders + codex + grok-4.5 + composer; 13 findings, 5 cross-family consensus). Fixes the agreed findings: - Keep validly tagged off-cluster lens prefixes: validate against the global lens set, not the finder's subset — coercion could flip kind and route a real defect through the applicability verifier (#1, consensus critical) - Verify design clusters even with cross-family consensus: agreement attests agreement, not repo-grounded applicability (externals cannot open repo files); defect consensus stays auto-accepted (#2) - Untagged external findings ('unspecified' lens) no longer vote in the cluster-kind derivation (#3) - Derive CANDIDATE_LENSES from LENS_CLUSTERS — one list, no unchecked mirror; DRIFT WARNING on the SKILL.md external-prompt copy (#4, #9) - Finder prompt: "issue (defect or substantive improvement)" + all lens prefixes; external prompt lead covers design improvements too (#5, #6) - pr-post.py owns design-row ordering + [lens] prefixing via optional kind/lens row fields, unit-tested; SKILL.md step 5 passes rows through verbatim (#13) - Doc sync: balance-spec finder count, README canonical cluster names + preset teaser wording, knowledge-index line trimmed (#8, #10, #11, #12) Declined: #7 (per-cluster dilutes per-lens depth) — deliberate, documented cost/coverage trade-off; --max is the depth profile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

Second dogfooding round at the deepest profile (/swarm:review --max --fix: per-lens split live — gate pruned style, 10 xhigh finders + codex gpt-5.6-sol@xhigh + grok-4.5 + composer; 24 findings, 10 consensus). Fixes the agreed findings: - Never auto-accept an all-untagged consensus cluster: no tagged lens backs it, so it is verified like a solo. Verify/auto-accept now derive from ONE needsVerify predicate (structural exactly-once partition); kind vote in clearer every-form (#1, consensus critical; #21, #22) - Design verifier sees the finding's recommendation — the proposal the applicability rubric actually tests — and carries an escape hatch: a genuine defect mis-filed under a design lens is not refuted away (#12, #3); "solo" dropped from verifier prompts (#4) - Untagged findings from multi-lens cluster finders fall back to 'unspecified' (safe defect bucket), not lenses[0] (#7); merge-agent free-text lens validated, majority-member fallback (#9) - Improvement invitation scoped to design finder units — defect-lens finders stay defect-only (#8); merge prompt clusters by issue, not only defect (#13); schema descriptions generalized for design findings (#14) - LENS_BRIEF startup assertion (#6); gate prompt interpolates LENS_CLUSTERS.design (#19); new test_lens_sync.py guards all lens mirrors: SKILL HDR prompt, LENS_BRIEF, pr-post DESIGN_LENSES (#5) - Workflow assigns stable finding num (defects first, shared sequence); presenter/pr-post render it verbatim (#20) - pr-post.py: design lens is the backup kind signal when the handoff drops kind (explicit defect still wins); single-pass partition (#17, #24) - Balance: REFUTED is its own segment (refuted ⊄ solo since design consensus can be refuted) (#2); LOCKED design-table column precedence in --loop rounds clarified (#11); "verifies solos" doc sweep across manifests/README/knowledge (#4); cluster failure-isolation trade-off documented (#10); knowledge index line trimmed (#15) Declined: #16 (JS test harness for sandbox code; lens-sync test covers the drift class), #18 (gate-fail under --max runs all lenses — the documented never-silently-narrower degrade), #23 (micro-opt vs readability). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0126cGxsBYxqgEFH4AcpriNk

Address the agreed findings from the local swarm review: - agent-registry grok probe: add a `gtimeout` fallback so `grok models` is time-bounded on stock macOS (only gtimeout ships there), not just where GNU `timeout` exists (#1). - grok availability: a failed/unreachable `grok models` fetch is now inconclusive (trust auth, soft note) rather than "unavailable" — a network hiccup no longer wrongly blocks launch. Fetch status rides the function's exit code, since a command-substitution subshell can't carry a global flag back (#6). - agent-registry resolve: reject control chars in `--session`, closing the newline→forged-`argv=`-line injection through the launch protocol (#2). - kickoff SKILL manual (non-herdr) block: shell-quote each argv word (the codex/grok bootstrap prompt is one word with spaces) instead of space-joining (#3); and persist a picker "save as default" on the manual path too, not only the herdr path (#4). - plugin.json: refresh the stale description (dropped the wrong lifecycle verbs, mention worker-agent choice) (#8). Not changed (reviewed, disagreed): /continue's claude-only resume is a documented degradation; README model-id duplication is accepted human-facing docs; the CHANGELOG paragraph matches the repo's entry style. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC

- default get now VALIDATES the committed value against the registry: a stale/ removed/attacker-supplied name (from a cloned repo) reads as "no default" → picker, instead of routing or bricking every no-flag kickoff (#1). kickoff also announces a non-claude project default before launch — visibility, not a prompt, so a committed default can't silently route your code off-Claude (#1 security). - grok probe: when neither `timeout` nor `gtimeout` exists, skip `grok models` and return inconclusive (trust auth) rather than risk an unbounded call that hangs the picker (#2). - kickoff argument grammar: `--agent` consumes the next token as its value, so it isn't mistaken for the task name (#4). - agent-registry.sh committed executable (100755), matching herdr-launch.sh, so the documented direct invocation works (#5). - kickoff "Critical" note: step 12 → step 13 cross-ref (launch was renumbered) (#6). - `supports=` comment marked RESERVED/not-yet-consumed (a seed for the orchestration design), not "already driving" degradation (#7). - herdr-launch bad-mode usage string shows the launch arity incl. [agent-selector] (#8). - continue reopen: note reworded to match behavior (`claude -c` IS always sent) and the codex/grok caveat surfaced inline in the success report (#3). Not changed (reviewed): README model-id duplication (accepted human-facing docs), CHANGELOG paragraph (matches repo style); per-task worker persistence for a true per-CLI resume stays a later idea. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NjTKpmBkXxxYkn7orMfZCC