diff --git a/Nop.Plugin.Misc.AIPlugin/.github/copilot-instructions.md b/Nop.Plugin.Misc.AIPlugin/.github/copilot-instructions.md index 573e020..08eac58 100644 --- a/Nop.Plugin.Misc.AIPlugin/.github/copilot-instructions.md +++ b/Nop.Plugin.Misc.AIPlugin/.github/copilot-instructions.md @@ -5,6 +5,23 @@ This plugin follows the AI Agent Core Protocol defined in AyCode.Core. Same rule **Full protocol:** `../../../../../../Aycode/Source/AyCode.Core/.github/copilot-instructions.md` **Protocol history:** `../../../../../../Aycode/Source/AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` +## Session Setup + +**Mandatory reads at session start** — in addition to this `copilot-instructions.md`, the agent MUST also load: + +1. **Canonical AI Agent Core Protocol** — AyCode.Core's `copilot-instructions.md` (for the full numbered Rules #1-5 that this inherit file references but does NOT duplicate). Path: `../../../../../../Aycode/Source/AyCode.Core/.github/copilot-instructions.md`. +2. **The four workspace skills** (see `## Shared Agent Skills` section below for paths): + - `docs-discovery/SKILL.md` — **reactive** (triggers on domain questions) + - `docs-check/SKILL.md` — **reactive** (triggers at end of code-modifying responses) + - `protocol-audit/SKILL.md` — **on-demand** (triggers on explicit "audit protocol" command) + - `adr-author/SKILL.md` — **on-demand + LLM-suggested** (triggers on explicit planning/design requests, or LLM flag + user confirmation) + +The first response's `[LOADED_DOCS: ...]` prefix must reflect **6 files** (this file + AyCode.Core's `copilot-instructions.md` + 4 SKILL.md files). + +**Why mandatory**: workspace skills are NOT in Claude Code's native skill-registry / system-reminder — without pre-loading, implicit triggers (e.g., "domain question → invoke docs-discovery" at the moment of the question) may be missed. This file inherits rules from AyCode.Core, so the canonical protocol file must be loaded alongside. One-time cost per session; Rule #3 (no-re-read) prevents repeated reads; re-read only if Rule #4 (Context Recovery) fires. + +**Amortization — critical, do NOT re-evaluate per-turn**: the Session Setup cost is measured over the ENTIRE session, not per single turn. A typical session has many turns; the first domain question alone already recoups the investment (alternative — repeated source-code `Grep`/`Read` per turn — costs 10-20K tokens *per turn* with lower output quality). Do NOT flag pre-loaded content as "wasteful" for turns that don't invoke it — the design depends on cross-turn amortization + Rule #3 (no-re-read) + on-demand specificity of Rule #4 (Context Recovery). This amortization is the **central token-economics principle** of the entire protocol stack. + ## Workspace Dependencies @repo { @@ -22,7 +39,7 @@ This plugin follows the AI Agent Core Protocol defined in AyCode.Core. Same rule ## Shared Agent Skills -Skills defined in other repos that can be referenced from here: +Skills defined in other repos. **All four are pre-loaded at session start per the `## Session Setup` section above** (mandatory — ensures implicit triggers fire reliably): - **docs-discovery** — Load relevant `.md` documentation (main + `_ISSUES` + `_TODO` paired sets) BEFORE source-code search or modifications. Saves tokens vs. grep-based rediscovery. Location: `AyCode.Core/.github/skills/docs-discovery/SKILL.md` (see `own-dep-repos` above for the relative path to AyCode.Core) @@ -32,6 +49,14 @@ Skills defined in other repos that can be referenced from here: Location: `AyCode.Core/.github/skills/protocol-audit/SKILL.md` Activate from an AyCode.Core session, or read the SKILL.md directly and follow its steps. +- **docs-check** — Evaluate loaded `.md` files at the end of every code-modifying response: drift vs code, missing topic coverage, csproj-glob registration gaps for new `.md` files, and new issue/TODO candidates. Emits the `[DOCUMENTATION CHECK]` section. + Location: `AyCode.Core/.github/skills/docs-check/SKILL.md` + **Invoke at the end of every code-modifying response.** Read-only on loaded docs; all patches surface as proposals (Rule #5 approval required). + +- **adr-author** — Create Architecture Decision Records (ADRs) for architecturally significant design decisions. Structured interview (context → alternatives → trade-offs → decision → consequences) producing a durable `docs/adr/NNNN-.md` file (product decisions) or a new `LLMP-DEC-N` row in the protocol decision log (meta-protocol decisions). + Location: `AyCode.Core/.github/skills/adr-author/SKILL.md` + **Invoke on explicit user request** ("let's plan X", "decide Y vs Z", "design the W module") **or proactively flag** when the conversation looks ADR-worthy (user must confirm — never auto-invoke). + ## Protocol History Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts): diff --git a/Nop.Plugin.Misc.AIPlugin/Nop.Plugin.Misc.FruitBankPlugin.csproj b/Nop.Plugin.Misc.AIPlugin/Nop.Plugin.Misc.FruitBankPlugin.csproj index 447e967..c49f8de 100644 --- a/Nop.Plugin.Misc.AIPlugin/Nop.Plugin.Misc.FruitBankPlugin.csproj +++ b/Nop.Plugin.Misc.AIPlugin/Nop.Plugin.Misc.FruitBankPlugin.csproj @@ -668,12 +668,8 @@ - - - - - - + + @@ -686,4 +682,4 @@ - \ No newline at end of file + diff --git a/Nop.Plugin.Misc.AIPlugin/README.md b/Nop.Plugin.Misc.AIPlugin/README.md index 63c05b0..72393d0 100644 --- a/Nop.Plugin.Misc.AIPlugin/README.md +++ b/Nop.Plugin.Misc.AIPlugin/README.md @@ -24,7 +24,7 @@ Project file: `Nop.Plugin.Misc.FruitBankPlugin.csproj` | `docs/MEASUREMENT.md` | Three measurement workflows (inbound shipping, outbound order, stocktaking), MeasuringStatus lifecycle, pricing, checkout filter | | `docs/AI_SERVICES.md` | OpenAI, Cerebras, Replicate providers, FruitBankSettings, file storage, PDF conversion, audio transcription | | `docs/DATA_LAYER.md` | FruitBankDbContext, StockTakingDbContext, DbTable repositories, entity mapping, FruitBankEventConsumer | -| `docs/SIGNALR_ENDPOINTS.md` | SignalR endpoints, FruitBankDataController, InnVoice/Billingo integration, FruitBankAttributeService | +| `docs/SIGNALR/README.md` | SignalR endpoints, FruitBankDataController, InnVoice/Billingo integration, FruitBankAttributeService | ## Folder Structure diff --git a/Nop.Plugin.Misc.AIPlugin/docs/MEASUREMENT.md b/Nop.Plugin.Misc.AIPlugin/docs/MEASUREMENT.md index 8a27ce3..bf1b223 100644 --- a/Nop.Plugin.Misc.AIPlugin/docs/MEASUREMENT.md +++ b/Nop.Plugin.Misc.AIPlugin/docs/MEASUREMENT.md @@ -2,7 +2,7 @@ > Part of `Nop.Plugin.Misc.FruitBankPlugin`. See `README.md` for project overview. > For entity model see `docs/DOMAIN_MODEL.md`. -> For SignalR endpoints see `docs/SIGNALR_ENDPOINTS.md`. +> For SignalR endpoints see `docs/SIGNALR/README.md`. > For core measurement system rules and common domain traps, see: `../../../../../FruitBankHybridApp/FruitBank.Common/docs/GLOSSARY.md` Three parallel measurement workflows share the same weight formula and `MeasuringStatus` lifecycle. diff --git a/Nop.Plugin.Misc.AIPlugin/docs/README.md b/Nop.Plugin.Misc.AIPlugin/docs/README.md new file mode 100644 index 0000000..f0b3ffd --- /dev/null +++ b/Nop.Plugin.Misc.AIPlugin/docs/README.md @@ -0,0 +1,31 @@ +# Nop.Plugin.Misc.AIPlugin (FruitBank plugin) documentation + +Topic documentation for the FruitBank-specific NopCommerce plugin (Layer 3 — consumer). + +## Reference docs (flat) + +- [`AI_SERVICES.md`](AI_SERVICES.md) — AI-related service integrations +- [`DATA_LAYER.md`](DATA_LAYER.md) — Data access specifics for this plugin +- [`SCHEMA.md`](SCHEMA.md) — Database schema (Toon format — LLM-optimized) +- [`DOMAIN_MODEL.md`](DOMAIN_MODEL.md) — Business domain behavior +- [`MEASUREMENT.md`](MEASUREMENT.md) — Weight measurement logic (NetWeight formula, MeasuringStatus lifecycle) + +## Topic folders + +- [`SIGNALR/`](SIGNALR/README.md) — SignalR endpoints exposed by this plugin (project-specific variant) + +## Navigation + +Per the AI Agent Core Protocol (folder navigation rule), start from this README when browsing `docs/`. Single-file reference docs remain flat; project-specific variants of framework topics (like SIGNALR) live in named subfolders. + +## Critical reminders (inherited from domain) + +- **`MeasuringStatus.Finnished`** is an intentional typo — do NOT "fix" the spelling (database-level value). +- **Weight formula**: `NetWeight = GrossWeight - PalletWeight - (TrayQuantity * TareWeight)`. +- **MeasuringStatus lifecycle**: NotStarted(0) → Started(10) → Finnished(20) → Audited(30). + +## See also + +- **Parent framework** (Mango.Nop.Core): `../../../Libraries/Mango.Nop.Core/docs/README.md` +- **Client-side app**: `../../../../FruitBankHybridApp/docs/README.md` +- **Host (nopCommerce deployment)**: `../../../../../FruitBank/` (see `.github/copilot-instructions.md` for scope) diff --git a/Nop.Plugin.Misc.AIPlugin/docs/SIGNALR_ENDPOINTS.md b/Nop.Plugin.Misc.AIPlugin/docs/SIGNALR/README.md similarity index 100% rename from Nop.Plugin.Misc.AIPlugin/docs/SIGNALR_ENDPOINTS.md rename to Nop.Plugin.Misc.AIPlugin/docs/SIGNALR/README.md