80 lines
8.9 KiB
Markdown
80 lines
8.9 KiB
Markdown
# LLM Protocol Decisions
|
||
|
||
Append-only log of decisions about the AI AGENT CORE PROTOCOL and related LLM tooling (skills, instruction files, shared conventions) across the 8 known `.github/copilot-instructions.md` files.
|
||
|
||
## Purpose
|
||
|
||
Quick lookup for **why** a rule is the way it is, to avoid:
|
||
- Re-debating decisions that were already discussed and resolved
|
||
- Silently "optimizing away" a rule whose edge-case purpose is no longer obvious
|
||
- Losing context between sessions / across team members
|
||
|
||
## Scope
|
||
|
||
**Tracked here:**
|
||
- `.github/copilot-instructions.md` rule additions / removals / rewordings
|
||
- `CLAUDE.md` changes
|
||
- New, modified, or removed agent skills (`docs-discovery`, `protocol-audit`, etc.)
|
||
- Protocol-level structural shifts (doc layout, file location conventions)
|
||
|
||
**NOT tracked here:**
|
||
- Code refactors or feature work — use commit messages / PR descriptions
|
||
- Code-architecture decisions — see `docs/ARCHITECTURE.md` at the relevant layer
|
||
- Trivial fixes (typos, path corrections without rule-semantic change)
|
||
|
||
## Writing rules
|
||
|
||
1. **Append-only.** If a decision is reversed or superseded, add a NEW entry that points to the old one. Do not rewrite history — the evolution itself is informative.
|
||
2. **One row per decision.** Keep the rationale concise; the purpose is scan-ability, not prose.
|
||
3. **`Affected` column** uses the scope codes defined below — always be explicit about which files were touched.
|
||
4. **Explicit consent required for additions** (per Rule #5 of the active `copilot-instructions.md`). The LLM proposes the entry; the user reviews and approves before the write.
|
||
5. **Reference this log** before proposing a protocol change — if the change was already discussed, the existing entry may save a debate.
|
||
|
||
## Scope codes (for the `Affected` column)
|
||
|
||
| Code | Meaning |
|
||
|------------------------|-----------------------------------------------------------------------------------------------------------|
|
||
| `5× primary` | All 5 primary `copilot-instructions.md` (AyCode.Core, AyCode.Blazor, Libraries, FruitBank, FruitBankHybridApp) |
|
||
| `4× non-Core primary` | The 4 primary files except AyCode.Core |
|
||
| `3× inherit` | The 3 inherit files (Mango.Nop.Core, Nop.Plugin.Misc.AIPlugin, Mango.FruitBank) |
|
||
| `all 8` | All 8 files: 5 primary + 3 inherit |
|
||
| `<repo>/...` | A single specific file path |
|
||
| `<skill-name>/...` | Skill directory under `.github/skills/` |
|
||
|
||
The "primary" vs "inherit" distinction is defined in `protocol-audit/references/REPOS.md`.
|
||
|
||
## 2026
|
||
|
||
| Date | Decision | Rationale | Affected |
|
||
|------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
|
||
| 2026-04-20 | Added CROSS-REPO HARD-GATE to Rule #2 | Docs-before-code was applied only to the own repo, not external deps | `5× primary` |
|
||
| 2026-04-20 | Added PER-QUESTION DOC-FIRST to Rule #2 | LLM skipped checking for relevant `.md` before jumping to code search | `5× primary` |
|
||
| 2026-04-21 | Expanded Rule #5 scope: "code/files" → "any file..." | Memory / config / docs edits also need consent; old wording too narrow | `5× primary` |
|
||
| 2026-04-22 | Added Auto-detection triggers to Rule #4 | "realize" was subjective; post-compaction reset to `[LOADED_DOCS: NONE]` didn't fire reliably | `5× primary` |
|
||
| 2026-04-22 | Added "in context" definition to Rule #3 | Summary content was mistaken for actually-loaded docs (lossy compression) | `5× primary` |
|
||
| 2026-04-22 | Unified AyCode.Blazor Rule #3 with the other 4 repos | Was custom "CRITICAL TOOL EXECUTION FIREWALL" variant; normalized | `AyCode.Blazor/copilot-instructions.md` |
|
||
| 2026-04-22 | "strictly maintain rule X" → "rule 3" | Per-repo numbers varied (15/18/19/20/21); unified reference | `5× primary` |
|
||
| 2026-04-22 | Created `protocol-audit` skill at repo-level | Cross-repo consistency check; `.github/skills/` chosen over personal paths (DRY) | `protocol-audit/SKILL.md` + `protocol-audit/references/REPOS.md` |
|
||
| 2026-04-22 | Added `## Shared Agent Skills` section (protocol-audit) | Discoverability of AyCode.Core-hosted skills from dependent repos | `4× non-Core primary` |
|
||
| 2026-04-23 | Created `docs-discovery` skill (parallel session) | Paired-doc (`main` + `_ISSUES` + `_TODO`) auto-loading before code search | `docs-discovery/SKILL.md` + `AyCode.Core/copilot-instructions.md` |
|
||
| 2026-04-23 | Extended `## Shared Agent Skills` with `docs-discovery` (parallel session) | Both skills now listed in each dependent repo | `4× non-Core primary` + `Mango.Nop.Core/copilot-instructions.md` |
|
||
| 2026-04-24 | LOADED_DOCS prefix: full list → count+delta format | Long lists became visual noise at scale; delta preserves self-commitment | `5× primary` + `docs-discovery/SKILL.md` |
|
||
| 2026-04-24 | Created this Decision Log | Institutional memory for protocol evolution; avoid re-debating resolved choices | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` |
|
||
| 2026-04-24 | Added `## Protocol History` section | Cross-repo discoverability of the Decision Log | `4× non-Core primary` + `Mango.Nop.Core/copilot-instructions.md` |
|
||
| 2026-04-24 | Filled empty Nop.Plugin.Misc.AIPlugin instruction file | Previously 0 bytes; now minimal inherit-pattern referencing AyCode.Core + both skills + log | `Nop.Plugin.Misc.AIPlugin/copilot-instructions.md` |
|
||
| 2026-04-24 | Filled empty Mango\FruitBank instruction file | Previously 0 bytes; now minimal inherit-pattern with ⚠️ "purpose TBD" notice | `Mango/FruitBank/copilot-instructions.md` |
|
||
| 2026-04-24 | Expanded REPOS.md: 5 repos → 8 (primary + inherit) | Audit scope was incomplete; sub-project & plugin files were missed | `protocol-audit/references/REPOS.md` |
|
||
| 2026-04-24 | Fixed Mango.Nop.Core `@repo` path (7 `..` → 6 `..`) | Previous path resolved to `H:\Aycode\...` (non-existent). Corrected relative depth from repo root | `Mango.Nop.Core/copilot-instructions.md` |
|
||
| 2026-04-24 | Resolved Mango.FruitBank purpose (nopCommerce host) | Confirmed: directory is a nopCommerce deployment for FruitBank company, hosting Nop.Plugin.Misc.AIPlugin. Layer 4 (host), not TBD. Updated content accordingly. | `Mango/FruitBank/copilot-instructions.md` |
|
||
| 2026-04-24 | `protocol-audit` v1.0 → v2.0: primary/inherit invariant split | SKILL.md now applies Common + Primary invariants to rows 1-5, Common + Inherit + Cross-cutting to rows 6-8. New invariants: P3 (Rule #1 count+delta format), X1 (Shared Agent Skills), X2 (Protocol History). | `protocol-audit/SKILL.md` + `protocol-audit/references/REPOS.md` (issues cleared) |
|
||
|
||
## Known follow-ups
|
||
|
||
*(No open follow-ups. All items from previous audits resolved — see dated entries above for fix history.)*
|
||
|
||
## Notes
|
||
|
||
- Dates before 2026-04-24 are retroactive reconstructions from session history; intra-day ordering is approximate.
|
||
- For precise attribution of individual file changes, consult the git history of the affected files.
|
||
- This log is a **summary** artifact — it records the decision and its rationale, not the full diff.
|