158 lines
8.7 KiB
Markdown
158 lines
8.7 KiB
Markdown
---
|
||
name: protocol-audit
|
||
description: Audit the 8 AyCode/Mango `.github/copilot-instructions.md` files for protocol consistency. Two file types are recognized — **primary** (5 files with full numbered AI AGENT CORE PROTOCOL: AyCode.Core, AyCode.Blazor, Libraries, FruitBank, FruitBankHybridApp) and **inherit** (3 files that reference AyCode.Core's protocol: Mango.Nop.Core, Nop.Plugin.Misc.AIPlugin, Mango.FruitBank). 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 8 paths listed in `references/REPOS.md`.
|
||
metadata:
|
||
author: Fullepi
|
||
version: "2.0"
|
||
---
|
||
|
||
# Protocol Audit
|
||
|
||
Verify that all 8 known `.github/copilot-instructions.md` files share a consistent AI AGENT CORE PROTOCOL ecosystem. **Primary** files contain the full numbered protocol; **inherit** files reference AyCode.Core's 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 — Load the repo list
|
||
|
||
Read `references/REPOS.md` (relative to this SKILL.md). Extract:
|
||
- **Primary files table** (rows 1-5) with absolute paths
|
||
- **Inherit files table** (rows 6-8) with absolute paths
|
||
- **Expected own-dep-repos** tables (one per file type)
|
||
- **Known issues** section (pre-flagged expected failures)
|
||
|
||
## 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 4 required fields**
|
||
Inside the `@repo { ... }` block, the keys `name`, `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. `own-dep-repos` matches REPOS.md expectations**
|
||
The dep set must equal the expected set in REPOS.md's relevant "Expected own-dep-repos" table.
|
||
|
||
### 3B — Primary-only invariants (applied to rows 1-5 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 rows 6-8 in REPOS.md)
|
||
|
||
**I1. References AyCode.Core's protocol**
|
||
Substring `follows the AI Agent Core Protocol defined in AyCode.Core` present.
|
||
|
||
**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 4 non-Core primary + 3 inherit = 7 files)
|
||
|
||
These invariants apply to files OTHER than AyCode.Core itself — AyCode.Core does not need to reference itself.
|
||
|
||
**X1. `## Shared Agent Skills` section present**
|
||
Header `## Shared Agent Skills` must appear. Both `docs-discovery` and `protocol-audit` bullets must be listed under it.
|
||
|
||
**X2. `## Protocol History` section present**
|
||
Header `## Protocol History` must appear AND it must reference `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md`.
|
||
|
||
### Invariant applicability matrix
|
||
|
||
| Invariant set | AyCode.Core | 4× non-Core primary | 3× inherit |
|
||
|---------------|-------------|---------------------|------------|
|
||
| Common (C1-C3) | ✓ | ✓ | ✓ |
|
||
| Primary-only (P1-P10) | ✓ | ✓ | N/A (skip) |
|
||
| Inherit-only (I1-I3) | N/A (skip) | N/A (skip) | ✓ |
|
||
| Cross-cutting (X1-X2) | N/A (skip) | ✓ | ✓ |
|
||
|
||
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 `follows the AI Agent Core Protocol defined in AyCode.Core` blockquote): 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."`
|