From f0526b310df7bcb96bb79f304319aeef55155490 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 15:06:49 +0000 Subject: [PATCH] refactor(core): retrofit agentsmd-audit to the ADR-0020 context contract Description 944 -> 322 chars, Gotchas 36% -> 22%. The composition note moves to README.md. Restores the hand-edit trigger, which a clean-context audit found had no other caller: agentsmd-author owns the post-authoring invocation, but a hand-edit has no author skill in the loop, so nothing invoked the audit at all. It survived only in README.md, which neither the router nor the invoked agent loads. That is the path on which a human pastes a credential into AGENTS.md. The first pass dropped it against a measured budget of '~9 spare chars'. The real cost was ~49, and 250 is the SUGGESTION tier, not a ceiling -- the gate fails at 400. Ships at 322 with one advisory line. Names the three audit dimensions in the capability clause, recovering routing for 'does my AGENTS.md leak credentials', and qualifies the 'is this AGENTS.md safe to commit' phrasing, whose pronoun had no antecedent inside the quoted string. Refs #99 --- .../core/.apm/skills/agentsmd-audit/README.md | 3 +++ .../core/.apm/skills/agentsmd-audit/SKILL.md | 26 ++++++------------- plugins/core/skills/agentsmd-audit/README.md | 3 +++ plugins/core/skills/agentsmd-audit/SKILL.md | 26 ++++++------------- 4 files changed, 22 insertions(+), 36 deletions(-) diff --git a/plugins/core/.apm/skills/agentsmd-audit/README.md b/plugins/core/.apm/skills/agentsmd-audit/README.md index d863d94..658df6f 100644 --- a/plugins/core/.apm/skills/agentsmd-audit/README.md +++ b/plugins/core/.apm/skills/agentsmd-audit/README.md @@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any Provide the path to the repo root to audit when invoking. +Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a +hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. + ## Files | File | Purpose | diff --git a/plugins/core/.apm/skills/agentsmd-audit/SKILL.md b/plugins/core/.apm/skills/agentsmd-audit/SKILL.md index d8a4a34..8d578d4 100644 --- a/plugins/core/.apm/skills/agentsmd-audit/SKILL.md +++ b/plugins/core/.apm/skills/agentsmd-audit/SKILL.md @@ -1,20 +1,11 @@ --- name: agentsmd-audit description: > - Use when the user wants to review a repo's AGENTS.md file, says "audit this - AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to - know if AGENTS.md is safe to commit — even if they don't use the word - "audit". Also invoke proactively after agentsmd-author creates or updates - AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a - target repo's AGENTS.md file(s) — root and any nested monorepo files — for - embedded secrets/credentials, structural completeness against the - agents.md common-sections checklist, and drift (referenced commands or - paths that no longer resolve against the repo). Produces a compact - findings report (findings only, no PASS noise) with Why and Fix per - finding. Do not use to audit CLAUDE.md, .cursor/rules, or other - provider-specific adapter files — that's provider-adapter-author's - self-contained concern. Do not use to fix or write AGENTS.md content — use - agentsmd-author instead. + Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md", + "is this AGENTS.md safe to commit" — or after a hand-edit outside + `agentsmd-author`. Reports secrets, structure and drift; never edits. + Not for CLAUDE.md or provider files -> `provider-adapter-author`. + Not writing AGENTS.md -> `agentsmd-author`. allowed-tools: Bash Read metadata: category: docs @@ -23,14 +14,13 @@ metadata: - context7-websites-agents-md - context7-agentsmd-agents-md - governance-secrets-hard-prohibition - version: "0.1.1" + version: "0.1.2" --- ## Gotchas - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found. -- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's. -- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. +- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. ## Step 1 — Run the validators @@ -41,7 +31,7 @@ bash scripts/validate-structure.sh bash scripts/validate-drift.sh ``` -Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. +Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. ## Step 2 — Report diff --git a/plugins/core/skills/agentsmd-audit/README.md b/plugins/core/skills/agentsmd-audit/README.md index d863d94..658df6f 100644 --- a/plugins/core/skills/agentsmd-audit/README.md +++ b/plugins/core/skills/agentsmd-audit/README.md @@ -14,6 +14,9 @@ Runs a single combined pass across every AGENTS.md file in a repo (root and any Provide the path to the repo root to audit when invoking. +Also invoke it proactively after `agentsmd-author` creates or updates an AGENTS.md, or after a +hand-edit made outside `agentsmd-author` — the audit is what confirms the result is safe to commit. + ## Files | File | Purpose | diff --git a/plugins/core/skills/agentsmd-audit/SKILL.md b/plugins/core/skills/agentsmd-audit/SKILL.md index d8a4a34..8d578d4 100644 --- a/plugins/core/skills/agentsmd-audit/SKILL.md +++ b/plugins/core/skills/agentsmd-audit/SKILL.md @@ -1,20 +1,11 @@ --- name: agentsmd-audit description: > - Use when the user wants to review a repo's AGENTS.md file, says "audit this - AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to - know if AGENTS.md is safe to commit — even if they don't use the word - "audit". Also invoke proactively after agentsmd-author creates or updates - AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a - target repo's AGENTS.md file(s) — root and any nested monorepo files — for - embedded secrets/credentials, structural completeness against the - agents.md common-sections checklist, and drift (referenced commands or - paths that no longer resolve against the repo). Produces a compact - findings report (findings only, no PASS noise) with Why and Fix per - finding. Do not use to audit CLAUDE.md, .cursor/rules, or other - provider-specific adapter files — that's provider-adapter-author's - self-contained concern. Do not use to fix or write AGENTS.md content — use - agentsmd-author instead. + Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md", + "is this AGENTS.md safe to commit" — or after a hand-edit outside + `agentsmd-author`. Reports secrets, structure and drift; never edits. + Not for CLAUDE.md or provider files -> `provider-adapter-author`. + Not writing AGENTS.md -> `agentsmd-author`. allowed-tools: Bash Read metadata: category: docs @@ -23,14 +14,13 @@ metadata: - context7-websites-agents-md - context7-agentsmd-agents-md - governance-secrets-hard-prohibition - version: "0.1.1" + version: "0.1.2" --- ## Gotchas - Always run all three checks — this skill does a single combined pass, not staged/gated passes. Don't skip structure or drift checks just because a secrets FAIL was found. -- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. If one exists and duplicates AGENTS.md content, that's `provider-adapter-author`'s concern, not this skill's. -- A missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. +- Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope. - Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. ## Step 1 — Run the validators @@ -41,7 +31,7 @@ bash scripts/validate-structure.sh bash scripts/validate-drift.sh ``` -Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. +Each script walks the repo for every `AGENTS.md` file (root and nested, excluding `.git`, `node_modules`, `vendor`, and similar) and prints `FAIL`/`INFO`/`SUGGESTION` lines with `Why`/`Fix` (or `Note`) per finding. A nonzero exit means at least one FAIL was found in that dimension. If a script cannot execute (`python3` unavailable, Bash denied), fall back to manual review: scan for real-looking credentials, check common sections are present, and spot-check a few referenced commands/paths by hand. Grade a manual finding the way the scripts grade theirs: a missing common section (e.g. no "Security" heading) is informational, not a failure — not every repo needs every section from the checklist. Only flag a FAIL when the file is empty, entirely unfilled placeholder text, or contains a real embedded secret/stale reference. ## Step 2 — Report