Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(core): retrofit agentsmd-audit to the ADR-0020 context contract

Browse Source 
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
This commit is contained in:
Defame1297
2026-08-30 15:06:49 +00:00
parent e42c055294
commit f0526b310d
4 changed files with 22 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
plugins/core/.apm/skills/agentsmd-audit/README.md
View File

@@ -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. 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 ## Files
| File | Purpose | | File | Purpose |

26
plugins/core/.apm/skills/agentsmd-audit/SKILL.md
View File

@@ -1,20 +1,11 @@
--- ---
name: agentsmd-audit name: agentsmd-audit
description: > description: >
Use when the user wants to review a repo's AGENTS.md file, says "audit this Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to "is this AGENTS.md safe to commit" — or after a hand-edit outside
know if AGENTS.md is safe to commit — even if they don't use the word `agentsmd-author`. Reports secrets, structure and drift; never edits.
"audit". Also invoke proactively after agentsmd-author creates or updates Not for CLAUDE.md or provider files -> `provider-adapter-author`.
AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a Not writing AGENTS.md -> `agentsmd-author`.
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.
allowed-tools: Bash Read allowed-tools: Bash Read
metadata: metadata:
category: docs category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
- governance-secrets-hard-prohibition - governance-secrets-hard-prohibition
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - 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. - Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- 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.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. - 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 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
bash scripts/validate-drift.sh <repo-root> bash scripts/validate-drift.sh <repo-root>
``` ```
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 ## Step 2 — Report

3
plugins/core/skills/agentsmd-audit/README.md
View File

@@ -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. 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 ## Files
| File | Purpose | | File | Purpose |

26
plugins/core/skills/agentsmd-audit/SKILL.md
View File

@@ -1,20 +1,11 @@
--- ---
name: agentsmd-audit name: agentsmd-audit
description: > description: >
Use when the user wants to review a repo's AGENTS.md file, says "audit this Use when the user wants a repo's AGENTS.md audited — "audit this AGENTS.md",
AGENTS.md", "check my AGENTS.md", "is this AGENTS.md any good", or wants to "is this AGENTS.md safe to commit" — or after a hand-edit outside
know if AGENTS.md is safe to commit — even if they don't use the word `agentsmd-author`. Reports secrets, structure and drift; never edits.
"audit". Also invoke proactively after agentsmd-author creates or updates Not for CLAUDE.md or provider files -> `provider-adapter-author`.
AGENTS.md, or after a hand-edit made outside agentsmd-author. Audits a Not writing AGENTS.md -> `agentsmd-author`.
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.
allowed-tools: Bash Read allowed-tools: Bash Read
metadata: metadata:
category: docs category: docs
@@ -23,14 +14,13 @@ metadata:
- context7-websites-agents-md - context7-websites-agents-md
- context7-agentsmd-agents-md - context7-agentsmd-agents-md
- governance-secrets-hard-prohibition - governance-secrets-hard-prohibition
version: "0.1.1" version: "0.1.2"
--- ---
## Gotchas ## 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. - 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. - Never inspect or mention provider-specific adapter files (`CLAUDE.md`, `.cursor/rules/*.mdc`, `copilot-instructions.md`, etc.) — that's out of scope.
- 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.
- Gather findings internally; don't narrate PASS/FAIL per check as you go — surface them only in the final report. - 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 ## Step 1 — Run the validators
@@ -41,7 +31,7 @@ bash scripts/validate-structure.sh <repo-root>
bash scripts/validate-drift.sh <repo-root> bash scripts/validate-drift.sh <repo-root>
``` ```
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 ## Step 2 — Report