Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
3c47828
docs(claude-config): add audit-instructions Brief (topic slice for #800)
kyle-sexton Jul 21, 2026
4a2bb83
docs(claude-config): fold research corrections into audit-instruction…
kyle-sexton Jul 21, 2026
8fce94b
docs(claude-config): add audit-instructions plan (stress-tested draft)
kyle-sexton Jul 21, 2026
c823631
feat(claude-config): add audit-instructions skill (catalog + scanner …
kyle-sexton Jul 21, 2026
8bc4c1d
docs(claude-config): mark audit-instructions phases 1-3 done
kyle-sexton Jul 21, 2026
39210b3
test(claude-config): add audit-instructions evals
kyle-sexton Jul 21, 2026
11012d7
docs(claude-config): mark audit-instructions phase 4 done
kyle-sexton Jul 21, 2026
64068b6
feat(claude-config): integrate audit-instructions (0.8.0)
kyle-sexton Jul 21, 2026
ec2e3c3
docs(claude-config): mark audit-instructions phase 5 done
kyle-sexton Jul 21, 2026
4299707
fix(claude-config): reconcile setup skill notes with fourth skill
kyle-sexton Jul 21, 2026
0d2911a
docs(claude-config): prune audit-instructions topic slice
kyle-sexton Jul 21, 2026
21b1b86
feat(naming): fold running-retro tournament lessons into name-it-better
kyle-sexton Jul 21, 2026
560d7ac
docs(topics): flip boris-video-absorption Phase 8 to DONE after medle…
kyle-sexton Jul 21, 2026
7688ae7
chore: declare shell: bash on every skill with dynamic-context inject…
kyle-sexton Jul 21, 2026
9533a14
chore: sync standards components (#873)
melodic-standards-sync[bot] Jul 21, 2026
391cd2e
docs(claude-config): add audit-instructions Brief (topic slice for #800)
kyle-sexton Jul 21, 2026
7d9e734
docs(claude-config): fold research corrections into audit-instruction…
kyle-sexton Jul 21, 2026
f0c8686
docs(claude-config): add audit-instructions plan (stress-tested draft)
kyle-sexton Jul 21, 2026
6c94c95
feat(claude-config): add audit-instructions skill (catalog + scanner …
kyle-sexton Jul 21, 2026
a564fb2
docs(claude-config): mark audit-instructions phases 1-3 done
kyle-sexton Jul 21, 2026
4992e97
test(claude-config): add audit-instructions evals
kyle-sexton Jul 21, 2026
a19ae79
docs(claude-config): mark audit-instructions phase 4 done
kyle-sexton Jul 21, 2026
311210d
feat(claude-config): integrate audit-instructions (0.8.0)
kyle-sexton Jul 21, 2026
5a24684
docs(claude-config): mark audit-instructions phase 5 done
kyle-sexton Jul 21, 2026
7630946
fix(claude-config): reconcile setup skill notes with fourth skill
kyle-sexton Jul 21, 2026
bed4950
docs(claude-config): prune audit-instructions topic slice
kyle-sexton Jul 21, 2026
7c8e1a7
feat(claude-config): supersede audit-model-fit with audit-instruction…
kyle-sexton Jul 21, 2026
22a7be5
merge: absorb pre-rebase branch history without rewrite (tree unchang…
kyle-sexton Jul 21, 2026
25c4de1
fix(claude-config): tighten audit-instructions fallback + inventory p…
kyle-sexton Jul 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/standards/runner-policy/policy.json
Original file line number Diff line number Diff line change
Expand Up @@ -403,6 +403,15 @@
"selectorResultInput": "prerequisite-result",
"allowedInputs": ["runner", "prerequisite-result", "exempt-authors"],
"allowedSecrets": {}
},
"melodic-software/ci-workflows/.github/workflows/issue-triage-label.yml@c5e729c0af0e55ffed4675ec85c1b57356fef79e": {
"routing": "runner-input",
"runnerInput": "runner",
"allowedInputs": ["runner", "label", "label-prefix"],
"allowedSecrets": {},
"allowedCallerPermissions": {
"issues": "write"
}
}
},
"canonicalSelectorInputs": {
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ user opts in with `/plugin enable`; an existing install is never flipped by cata

- [`desktop-notification`](plugins/desktop-notification) — Alert you when Claude Code needs input — an audible terminal bell, an OSC 9 terminal notification, and an OS-native toast (macOS/Linux) on permission and idle prompts.
- [`playbooks`](plugins/playbooks) — Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); skill-authoring — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).
- [`claude-config`](plugins/claude-config) — Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-model-fit (instruction surfaces swept for model-hobbling constraints newer models no longer need).
- [`claude-config`](plugins/claude-config) — Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs).
- [`claude-memory`](plugins/claude-memory) — Keeps a repo's Claude Code memory layer healthy and under your control, against criteria derived from official Claude Code documentation. The audit skill checks the instruction/memory layer (CLAUDE.md, CLAUDE.local.md, .claude/rules/, auto-memory) with a deterministic script-backed spine plus judgment-tier checks. The stateless skill inspects, disables, and (confirm-gated) purges Claude-written auto memory across all settings scopes.
- [`claude-ops`](plugins/claude-ops) — Claude Code operations toolkit. Seven skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view — queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort and a repo-pull + marketplace-refresh launch step), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
- [`skill-quality`](plugins/skill-quality) — Skill-authoring QA tooling: a static contract checker that runs eighteen deterministic checks over a Claude Code skill (frontmatter, listing-budget cap, trigger-keyword preservation, line caps, broken internal refs, markdownlint, gotchas surface, evals presence, precompute opportunity) and a bundled evals.json schema for validation. Runs against any repo's skills directory via the convention-resolution ladder — no baked layout.
Expand Down
7 changes: 6 additions & 1 deletion docs/topics/boris-video-absorption/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,14 +200,19 @@ Files (home slice, not repo):
- **Sanity Check:** CI green on PR; `gh pr view` shows mergeable; all
phase tags [DONE].

### Phase 8: trial run (post-merge validation) [TODO]
### Phase 8: trial run (post-merge validation) [DONE]

- After plugins update, run the enriched flow end-to-end on a real UI
change in a consumer repo: config surface resolved + reported,
recording produced per key, gap report exercised (remove a prereq
deliberately), evidence table carries session artifacts.
- **Sanity Check:** recording artifact exists on disk; gap report emitted
on induced prereq failure; operator reviews the recording.
- Ran 2026-07-21 in medley (identity-server login-page change, Aspire
orchestrator, local-only): all sanity checks passed, plus the
prompt-over-config precedence bonus assertion (explicit headed
instruction beat the local overlay's `browser_mode: headless`).
Evidence stayed on disk (gitignored) in the consumer repo.

## Blast radius

Expand Down
4 changes: 2 additions & 2 deletions plugins/architecture/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "architecture",
"version": "0.3.4",
"description": "Scans an existing codebase for module-level architecture friction \u2014 shallow modules, seam leaks, and locality gaps \u2014 using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and runs an interview loop on the selected candidate before handing off for planning.",
"version": "0.3.5",
"description": "Scans an existing codebase for module-level architecture friction shallow modules, seam leaks, and locality gaps using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and runs an interview loop on the selected candidate before handing off for planning.",
"author": {
"name": "Melodic Software",
"email": "info@melodicsoftware.com"
Expand Down
8 changes: 8 additions & 0 deletions plugins/architecture/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
All notable changes to the `architecture` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.3.5]

### Changed

- Skills with `!` dynamic-context injections now declare `shell: bash` explicitly, per
the pinned precompute convention — bash-only pipelines must not fall through to a
PowerShell host.

## [0.3.4]

### Changed
Expand Down
1 change: 1 addition & 0 deletions plugins/architecture/skills/improve/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description: "Scan an existing codebase for module-level friction and architectu
argument-hint: "[action] (e.g., deepening)"
user-invocable: true
disable-model-invocation: false
shell: bash
---

## Pre-computed context
Expand Down
12 changes: 10 additions & 2 deletions plugins/bug-report/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "bug-report",
"version": "0.5.1",
"version": "0.5.2",
"description": "Produces a structured five-field bug report — title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location — from an informal defect description. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.",
"author": {
"name": "Melodic Software",
"email": "info@melodicsoftware.com"
},
"license": "MIT",
"keywords": ["bug", "bug-report", "defect", "triage", "issue", "workflow", "skill"],
"keywords": [
"bug",
"bug-report",
"defect",
"triage",
"issue",
"workflow",
"skill"
],
"userConfig": {
"output_dir": {
"type": "directory",
Expand Down
8 changes: 8 additions & 0 deletions plugins/bug-report/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
All notable changes to the `bug-report` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.5.2]

### Changed

- Skills with `!` dynamic-context injections now declare `shell: bash` explicitly, per
the pinned precompute convention — bash-only pipelines must not fall through to a
PowerShell host.

## [0.5.1]

### Changed
Expand Down
1 change: 1 addition & 0 deletions plugins/bug-report/skills/write/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description: "Produce a structured 5-field bug report (title, steps to reproduce
argument-hint: "[--file] [--quick|--full] [--no-survey] <bug description>"
user-invocable: true
disable-model-invocation: false
shell: bash
---

## Pre-computed context
Expand Down
17 changes: 14 additions & 3 deletions plugins/claude-config/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "claude-config",
"version": "0.8.0",
"description": "Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-model-fit (instruction surfaces swept for model-hobbling constraints newer models no longer need).",
"version": "0.9.0",
"description": "Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs).",
"author": {
"name": "Melodic Software",
"email": "info@melodicsoftware.com"
},
"license": "MIT",
"keywords": ["settings", "configuration", "hooks", "plugins", "permissions", "automation", "audit", "maintenance", "skill", "instructions", "model-fit"]
"keywords": [
"settings",
"configuration",
"hooks",
"plugins",
"permissions",
"automation",
"audit",
"maintenance",
"skill",
"instructions"
]
}
43 changes: 43 additions & 0 deletions plugins/claude-config/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,49 @@
All notable changes to the `claude-config` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.9.0]

### Added

- **`audit-instructions` skill** (`/claude-config:audit-instructions`). A read-only audit of the
locally-owned Claude Code instruction surfaces — user + project `CLAUDE.md`, `.claude/rules`,
skill bodies, agent definitions, prompt-type hooks, output styles — for instructions current
models no longer need: prior-model workarounds, over-prescriptive scaffolding, bare prohibitions,
reasoning-echo directives, and approach-pinning example blocks. It ships an eleven-check catalog
(`reference/criteria.md`) cited to current official prompting doctrine, tiers every finding
mechanical vs behavioral, and packages proposed removals/rewrites as human-gated diffs — never
auto-applied. An advisory grep-only scanner (`scripts/instruction-scan.sh`) seeds the mechanical
tier. It partitions with `claude-memory`'s `audit` skill: on memory-layer surfaces it runs only
the model-era checks and routes hygiene findings there; on non-memory surfaces the full catalog
applies. Upstream-owned plugin-cache and managed-materialization findings route to the owning
repository rather than being edited in place.

### Fixed

- Corrected stale `claude-memory` skill-name references (`health` → its current name `audit`)
across the plugin's skills and README — the `audit`, `audit-automation-gaps`, and
`audit-permission-grants` route-out notes and the README's instruction-layer and migration
sections. The `claude-memory` memory-layer skill was renamed `health` → `audit`; the old
`/claude-memory:health` invocation no longer resolves.

### Removed

- **`audit-model-fit` skill superseded by `audit-instructions`.** Both audits answer the same
question — locally-owned instruction surfaces vs current model capability — and repo doctrine
admits only one skill per question. `audit-instructions` carries the fuller catalog (eleven checks
I1–I11 with authority tags and evidence tiers), the `claude-memory` hygiene partition, and the
adversarial fresh-context verify pass, so it strictly covers `audit-model-fit`'s four checks and
supersedes it. Both were built concurrently from the same underlying issue (#800); `audit-model-fit`
(added in 0.8.0 below) is removed here.

## [0.8.1]

### Changed

- Skills with `!` dynamic-context injections now declare `shell: bash` explicitly, per
the pinned precompute convention — bash-only pipelines must not fall through to a
PowerShell host.

## [0.8.0]

### Added
Expand Down
45 changes: 22 additions & 23 deletions plugins/claude-config/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,16 @@ Code configuration healthy. Each skill answers a different question about the sa
| `/claude-config:audit` | Are the configuration FILES (`settings.json`, `settings.local.json`, `.mcp.json`, hooks, plugins, permissions) correct against upstream truth? |
| `/claude-config:audit-automation-gaps` | Is the configured automation SET the right set — are there genuine gaps, judged against the enforcement hierarchy? |
| `/claude-config:audit-permission-grants` | Are the permission GRANTS (`allowed-tools`, `permissions.allow`) portable and durable — do they survive auto mode, work across machines, and live where they can take effect? |
| `/claude-config:audit-model-fit` | Do the instruction SURFACES (CLAUDE.md, skill bodies, agents, rules, prompt-type hooks) still fit the current model or do they carry constraints a newer, more capable model no longer needs? |
| `/claude-config:audit-instructions` | Are the INSTRUCTIONS you wrote (CLAUDE.md, rules, skill bodies, agents, hooks, output styles) still earning their context cost against current model capability, or is prior-model scar tissue holding the model back? |

The instruction/memory layer's *health* (`CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/`, auto-memory)
is audited by the `health` skill in the separate `claude-memory` plugin (see "Migrating from
`claude-config-audit`" below if you relied on the old `memory-health` skill here). `audit-model-fit`
reads the same instruction surfaces but asks a different question — model *fit*, not health: are their
constraints still earning their place on a newer model?
The instruction/memory-layer *hygiene* question (is `CLAUDE.md` too long, well-placed, free of
inferable content) is owned by the `audit` skill in the separate `claude-memory` plugin;
`audit-instructions` here owns the distinct *capability* question (do these instructions still fit
what current models need) and routes memory-layer hygiene findings to `claude-memory:audit`. See
"Migrating from `claude-config-audit`" below if you relied on the old `memory-health` skill here.

All default to report-only; mutations (`--fix`, `--implement`) require explicit opt-in and per-item
user approval. `audit-permission-grants` and `audit-model-fit` are report-only (the former's remediation
is operator-manual; the latter is human-gated by design — it proposes diffs, never applies them).
user approval. `audit-permission-grants` is report-only (its correct remediation is operator-manual).

## What each skill does

Expand Down Expand Up @@ -67,23 +66,23 @@ Report-only.
/claude-config:audit-permission-grants settings # permissions.allow only
```

### audit-model-fit
### audit-instructions

Sweeps the local instruction surfaces (user + project `CLAUDE.md`, skill `SKILL.md` bodies + context
files, agent definitions, `.claude/rules/**`, prompt-type hooks and output styles) for deterministic
constraints that hobble newer, more capable models: bare prohibitions with no rationale,
over-prescriptive step lists, over-constraining example blocks (kept to 3–5, not banned), and stale
model-era workarounds. Each candidate is measured against "would removing this cause Claude to make
mistakes?" A deterministic scan flags the grep-able smells; the judgment stays in the skill body.
Report-only and human-gated — it proposes diffs, never applies them. Findings inside
`melodic-software/standards`-managed materializations route upstream rather than being edited in place.
Distinct from `skill-quality:check` (structure), `docs-hygiene:compress` (token brevity), and `audit`
(config-file correctness).
Audits instruction *content* against current model capability — a different question from the
sibling audits (config-file correctness) and from `skill-quality:check` (structural lint) or
`docs-hygiene:compress` (token brevity). It sweeps the locally-owned surfaces (user + project
`CLAUDE.md`, `.claude/rules`, skill bodies, agent definitions, prompt-type hooks, output styles)
against an eleven-check catalog cited to current official prompting doctrine, running a fresh
read-only subagent per surface, then a fresh-context verify pass that re-judges every removal
proposal before it is surfaced. Findings are tiered mechanical vs behavioral and delivered as a
report plus proposed diffs — report-only, never auto-applied. On memory-layer surfaces it runs only
the model-era checks and routes hygiene findings to the `claude-memory` plugin's `audit` skill (with
a documented fallback when it is not installed); upstream-owned plugin-cache and managed-file
findings route to the owning repository rather than being edited in place.

```shell
/claude-config:audit-model-fit # sweep all instruction surfaces
/claude-config:audit-model-fit claude-md # CLAUDE.md only
/claude-config:audit-model-fit skills # skill bodies + context files only
/claude-config:audit-instructions # audit every locally-owned surface
/claude-config:audit-instructions skills # one surface (claude-md|rules|skills|agents|hooks|output-styles)
```

## Consumer conventions
Expand All @@ -106,7 +105,7 @@ automatically at your next session — no action needed for `audit`, `audit-auto
`audit-permission-grants`.

The `memory-health` skill did **not** move to `claude-config` — it was extracted into the new,
separate `claude-memory` plugin (as `health`). The rename only rewrites the `claude-config-audit`
separate `claude-memory` plugin (now its `audit` skill). The rename only rewrites the `claude-config-audit`
plugin key; it does not enable additional plugins, so `claude-memory` is not installed for you
automatically. If you used `/claude-config-audit:memory-health`, install it explicitly:

Expand Down
3 changes: 2 additions & 1 deletion plugins/claude-config/skills/audit-automation-gaps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description: "Audit a repo's Claude Code automation landscape (hooks, MCP server
argument-hint: "[--recommend-only] [--implement] [category] — category: hooks|mcp|skills|subagents|scheduled|all (default: all)"
user-invocable: true
disable-model-invocation: false
shell: bash
---

## Pre-computed context
Expand Down Expand Up @@ -31,7 +32,7 @@ This skill is self-contained. Where a phase names an adjacent capability — a r
implementation-planning skill, a work-item tracker, an outcome verifier — treat it as optional: if
your setup provides an equivalent, use it; otherwise follow the inline guidance, which stands on its
own. Adjacent skills cover neighboring questions: the sibling `audit` skill (are the config FILES
correct?) and the `health` skill in the `claude-memory` plugin (is the instruction layer healthy?).
correct?) and the `audit` skill in the `claude-memory` plugin (is the instruction layer healthy?).

## Arguments

Expand Down
Loading
Loading