12 KiB

Raw Blame History

name: protocol-audit description: Audit .github/copilot-instructions.md files for protocol consistency across the invocation-point repo and its dependency tree (discovered at runtime via own-dep-repos walking). Two file types are recognized by content — primary (full numbered AI AGENT CORE PROTOCOL) and inherit (reference-only: blockquote pointer to the canonical protocol, no duplicated numbered rules). The skill applies the appropriate invariant set per type. Use when the user asks to "audit protocol", "check instruction consistency", "verify repo rules", "check cross-repo drift", or after modifying the AI AGENT CORE PROTOCOL in any repo. Produces a per-file × invariant table with concrete patch suggestions; does NOT modify any file without explicit consent. compatibility: Designed for Claude Code and GitHub Copilot (VS). Requires read access to the invocation-point repo + all its transitive own-dep-repos. metadata: author: Fullepi

Protocol Audit

Verify that all .github/copilot-instructions.md files registered in references/REPOS.md share a consistent AI AGENT CORE PROTOCOL ecosystem. Primary files contain the full numbered protocol; inherit files reference the canonical protocol without duplicating the numbered rules.

Before you start

This skill READS files and REPORTS findings. It MUST NOT modify any file. Patch suggestions are surfaced as diffs for the user to review and approve. Follow Rule #5 (or equivalent) from the active repo's copilot-instructions.md.

Step 1 — Discover the audit set (runtime walk)

Determine the invocation-point repo from the active workspace context (the repo containing the user's currently-active session).

Walk the dependency tree:

Read the invocation-point repo's .github/copilot-instructions.md @repo block.
For each own-dep-repos entry, resolve the path relative to the repo root and read that dep's @repo block.
Continue transitively until no new deps are found.
Audit set = {invocation-point repo} ∪ {all walked deps}.

Classify each file by content inspection (no central registry of files):

Primary — contains the 🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT) header → full invariant set.
Inherit — contains follows the AI Agent Core Protocol defined in <HOST> blockquote AND lacks the primary header → reduced invariant set.
Unknown — matches neither → record as UNKNOWN, flag for manual review.

Read references/REPOS.md for framework-side metadata only: canonical protocol host designation, the framework's own file table (typically a single row — AyCode.Core), and any known issues. Per the Framework-First Design Principle, that file lists only ACCORE; consumer participation in the audit is auto-discovered through the walk above. The skill does not hardcode any repo / project names.

Effective audit scope per invocation:

From AyCode.Core (Layer 0) → audits only AyCode.Core.
From a higher-layer repo → audits invocation-point + full transitive dep tree below it.

Step 2 — Read each instruction file

For each entry in both tables, read <abs-path>\.github\copilot-instructions.md once. Record the full text keyed by the logical name and file type (primary / inherit). If a file is empty (0 bytes), record as EMPTY and still run the size-sensitive invariants (expected: all fail).

Do NOT re-read a file that is already in your LOADED_DOCS list (per Rule #3 of the active repo's protocol).

Step 3 — Run invariant checks by file type

Each invariant yields PASS / FAIL / N/A (not-applicable-to-this-type) and, on FAIL, an evidence snippet.

3A — Common invariants (applied to ALL 8 files)

C1. @repo block has all 5 required fields Inside the @repo { ... } block, the keys name, prefix, type, layer, own-dep-repos must all be present.

C2. own-dep-repos paths resolve to existing directories For each "<dep-name>: <relative-path>" entry, resolve <repo-root>/<relative-path> and check the directory exists.

C3. @repo.prefix has valid format The prefix value must be uppercase, 4-12 chars, alphanumeric only (no hyphens / underscores / spaces / lowercase). It must NOT collide with Ac* / Mg* C# class-name prefixes (must be ≥ 4 chars, see REPO_PREFIXES.md).

C4. ## Session Setup section present with reactive + user-gated skill classification Header ## Session Setup must appear. The section body must reference:

2 reactive skills (mandatory pre-load at session start): docs-discovery/SKILL.md, docs-check/SKILL.md.
3 user-gated skills (lazy-loaded on demand, listed for trigger-recognition): protocol-audit/SKILL.md, adr-author/SKILL.md, docs-archive/SKILL.md.

For inherit files, the section must additionally reference loading the canonical copilot-instructions.md (from the host repo — e.g., AyCode.Core).

Expected first-response [LOADED_DOCS] counts: 3 for primary (this copilot-instructions.md + 2 reactive SKILL.md), 4 for inherit (this file + canonical copilot-instructions.md + 2 reactive SKILL.md). Lazy-loaded skills add to the count only when first invoked. Updated per LLMP-DEC-43 (5-skill 2-reactive/3-user-gated matrix) and LLMP-DEC-64 (text-drift fix from initial 3-skill wording).

3B — Primary-only invariants (applied to files classified as primary in REPOS.md)

P1. Rule numbering is contiguous 1..N Extract all ^\d+\. \*\* lines. Numbers must form 1, 2, 3, ..., N with no gaps and no duplicates.

P2. Rule count is ≥ 5 The AI AGENT CORE PROTOCOL has five core rules. Sections after Rule #5 (Conventions etc.) may add more; the first 5 are mandatory.

P3. Rule #1 uses count+delta format Substring N files (+K this turn present in Rule #1. Old substring comma-separated list of .md files currently in your context must be ABSENT.

P4. Rule #2 contains CROSS-REPO HARD-GATE

P5. Rule #2 contains PER-QUESTION DOC-FIRST

P6. Rule #3 is the NO-RE-READ rule Header matches STRICT NO-RE-READ POLICY (ANTI-LOOP).

P7. Rule #3 contains the "in context" definition Substring lossy compressions present.

P8. Rule #4 contains auto-detection triggers Substring Auto-detection triggers present AND substring LOADED_DOCS: NONE present.

P9. Rule #5 scope is broad Substring any file (code, documentation, configuration, memory, or otherwise) present. Negative: substring delete code/files without must be ABSENT (old wording).

P10. strictly maintain rule 3 reference exists Substring strictly maintain rule 3 present. Old references (rule 15, rule 18, rule 19, rule 20, rule 21) must be absent.

3C — Inherit-only invariants (applied to files classified as inherit in REPOS.md)

I1. References the canonical protocol host Substring follows the AI Agent Core Protocol defined in <HOST> present, where <HOST> is the repo designated as the canonical host in REPOS.md (the file content's literal phrasing must match the host's name — this workspace's files currently say "AyCode.Core"). If REPOS.md designates a different host, both the inherit files and this invariant's expected substring are updated in lockstep.

I2. Does NOT duplicate numbered Rules #1-5 Must NOT contain the header 🛑 AI AGENT CORE PROTOCOL (CRITICAL ENFORCEMENT) (that belongs to primary files only). If the file has ^\d+\. \*\*MANDATORY OUTPUT PREFIX or similar, flag as FAIL — the inherit file has leaked primary content.

I3. Has a link to the Decision Log Substring LLM_PROTOCOL_DECISIONS.md present (via the Protocol History section — see X2 below).

3D — Cross-cutting invariants (applied to all files EXCEPT the canonical protocol host)

The canonical protocol host is the repo designated in references/REPOS.md as housing the shared skills, Decision Log, and registries (typically the first row labeled the "host" in REPOS.md). That host does not need to reference itself. These X invariants apply to every other file registered in REPOS.md.

X1. ## Shared Agent Skills section present with all five skills Header ## Shared Agent Skills must appear. All five bullets must be listed: docs-discovery (reactive), docs-check (reactive), protocol-audit (user-gated), adr-author (user-gated), docs-archive (user-gated). Updated per LLMP-DEC-43 + LLMP-DEC-64.

X2. ## Protocol History section present Header ## Protocol History must appear AND it must reference the Decision Log at the canonical host's location (e.g., <HOST_REPO>/.github/LLM_PROTOCOL_DECISIONS.md; the concrete path is resolvable from REPOS.md).

X3. Docs-sync rule points to docs-check skill (primary files only) In each primary file's docs-sync rule (the numbered rule whose title begins "Keep all .md documentation in sync"), the substring `docs-check` (backtick-wrapped skill name) must be present, AND a reference to the docs-check skill's SKILL.md path (e.g., .github/skills/docs-check/SKILL.md or a correct relative variant) must be present.

Invariant applicability matrix

Invariant set	Canonical host	Other primary	Inherit
Common (C1-C4)	✓	✓	✓
Primary-only (P1-P10)	✓	✓	N/A (skip)
Inherit-only (I1-I3)	N/A (skip)	N/A (skip)	✓
Cross-cutting (X1-X2)	N/A (skip — the host does not cross-reference itself)	✓	✓
Cross-cutting (X3)	✓	✓	N/A (skip — inherit files don't have the numbered docs-sync rule)

The primary/inherit classification and the "canonical host" designation both come from references/REPOS.md. This skill does not hardcode any specific repo or project name.

Use N/A in the report cell, not PASS, for skipped invariants — so it's obvious the check wasn't applicable.

Step 4 — Produce the report

Emit a markdown report with three sections:

4A — Summary table

One row per file, grouped by type. Columns: the invariant IDs from Step 3 (C1, C2, C3, P1..P10, I1..I3, X1, X2). Cell values: PASS / FAIL / N/A / MISSING / UNREADABLE / EMPTY.

Use short column headers (C1, P1, P2, I1, X1, etc.) — 19 columns is dense but fits in a readable table when values are 2-4 chars.

4B — Failure details

For every FAIL, list:

File name + type (primary / inherit)
Invariant ID (e.g., P3, I1, X2)
Evidence — the offending line, missing substring, or unresolved path
Suggested patch — a concrete old_string / new_string pair (or "create this section" scaffold) the user can review

4C — Known-issues reconciliation

Cross-reference any FAIL with the "Known issues" section in REPOS.md. If a failure is already tracked as a known issue, mark it FAIL (known) so the user can distinguish fresh regressions from pre-existing TODOs.

Step 5 — DO NOT apply patches

End the report with:

All checks complete. N failures detected (M known, N-M new). To apply any of the suggested patches, reply with "apply patches P3, I1" (or similar IDs). No files have been modified.

Wait for explicit user consent before using any edit / write tool. Per Rule #5: phrases like "we are just thinking" / "what do you think" do NOT constitute approval.

Tool usage

This skill is tool-neutral. Map these capabilities to the host agent's tools (per the active repo's CLAUDE.md):

Reading files: Read (Claude Code), get_file (Copilot), or equivalent
Globbing / directory existence: Glob, file_search, ls, Test-Path
Applying patches (only after consent): Edit, replace_string_in_file

Edge cases

Repo path missing from disk: Skip that file, record MISSING in every invariant cell, continue with the others.
File read fails: Record UNREADABLE, continue.
File is 0 bytes: Record EMPTY; every content-sensitive invariant returns FAIL. Still run C1-C3 (they'll fail too, which is correct signal).
Multiple @repo blocks in one file: Audit the first one; flag the duplicate as its own finding.
Rule order differs (e.g., Rules #3 and #4 swapped in a primary file): invariants P6 and P8 fail independently — do not try to auto-reorder.
Unfinished mid-edit: If a file has obviously truncated content (cut off mid-sentence), record CORRUPT and stop that file's audit.
Ambiguous file type (has both AI AGENT CORE PROTOCOL header AND the inherit-blockquote substring from I1): flag as FAIL on I2 and P1 — file has structural identity crisis, user must resolve.
New file not in REPOS.md: Do NOT audit it automatically. Report it separately as "Unregistered .github/copilot-instructions.md found at <path> — add to REPOS.md to include in future audits."

12 KiB Raw Blame History Unescape Escape