Mango.Nop.Libraries/Mango.Nop.Core/.github/copilot-instructions.md

Mango.Nop.Core — Domain Rules

Workspace Dependencies

@repo { name = "Mango.Nop.Core" type = "framework" layer = 2 own-dep-repos = ["AyCode.Core: ../../../../../../Aycode/Source/AyCode.Core"] }

Domain framework for NopCommerce plugins. Built on Layer 0 (AyCode.Core), consumed by Layer 3 (specific plugin apps, plural and unknown).

AI Agent Protocol: This repo follows the AI Agent Core Protocol defined in AyCode.Core. Same rules apply: [LOADED_DOCS] prefix, docs-before-code, no-re-read policy, context recovery on compaction, explicit consent for modifications. Full protocol: AyCode.Core's .github/copilot-instructions.md (see @repo path above).

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 via the own-dep-repos AyCode.Core entry above.
2. The two reactive workspace skills (see ## Shared Agent Skills section below for paths; the three user-gated skills are lazy-loaded on demand):
   • docs-discovery/SKILL.md — reactive (triggers on domain questions)
   • docs-check/SKILL.md — reactive (triggers at end of code-modifying responses)

Lazy-loaded (read on invocation, not at session start; the ## Shared Agent Skills bullets below describe their triggers):

• protocol-audit/SKILL.md — user-invoked / LLM-suggest-back on meta-protocol file modifications
• adr-author/SKILL.md — user-invoked / LLM-suggest-back on ADR-worthy conversation
• docs-archive/SKILL.md — user-invoked / LLM-suggest-back on bloated active artifact files

The first response's [LOADED_DOCS: ...] prefix must reflect 4 files (this file + AyCode.Core's copilot-instructions.md + 2 reactive SKILL.md files). Lazy-loaded skills add to the count when invoked.

Why mandatory: workspace skills live as plain SKILL.md files in .github/skills/ — LLMs do NOT auto-discover them via any built-in skill-registry. 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.

Framework-First Design Principle

🛑 This repo is framework (Layer 2 — Domain framework), not a consumer application. Provides base types for NopCommerce plugin development. Consumers = specific plugin projects (plural, unknown).

Before writing code, ask:

1. Generic (reusable across any NopCommerce plugin)? → belongs HERE
2. Plugin-specific (business logic, specific entities, plugin names)? → NOT HERE
3. Same pattern in 2+ plugins? → promote to framework

Hard rules:

• ❌ No plugin names or business-specific terms in code, identifiers, namespaces, or docs
• ❌ No framework → plugin references
• ✅ Abstract/virtual base classes — plugins derive/override
• ✅ Generic DTOs / extensions / interfaces for cross-plugin reuse
• ✅ Mirror NopCommerce entities without a hard runtime dependency on Nop

Nop-plugin-framework-specific emphasis:

• NopDependencies/ mirrors NopCommerce entity classes (same namespace as originals) — stays generic, no plugin-specific logic
• DTOs use type parameters for consumer entity types (e.g. MgOrderDto<TOrderItemDto, TProductDto>) — never hardcode concrete plugin types
• Zero runtime NopCommerce dependency — plugin apps bring their own Nop runtime
• Any plugin-specific logic (domain rules, business-specific entities) stays in the plugin, not here

Framework design = "write the base first, derive the specific later".

Full doctrine: AyCode.Core's .github/copilot-instructions.md#framework-first-design-principle and docs/ARCHITECTURE.md#framework-vs-consumer-boundary.

Shared Agent Skills

Skills defined in other repos. Two reactive skills are pre-loaded at session start; three user-gated skills are lazy-loaded on demand — see ## Session Setup above for the load matrix:

• 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) Invoke proactively before any domain-related coding task (see "Documentation-first coding" below). Honours the active repo's no-re-read rule.

• protocol-audit — Cross-repo consistency audit for .github/copilot-instructions.md across all repos. 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-<slug>.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).

• docs-archive — Rotate closed entries (Status: Fixed/Resolved/Won't fix/Superseded by X) from active _ISSUES.md, _TODO.md, and LLM_PROTOCOL_DECISIONS.md into year-bucketed archive companions (*_<year>.md). Year of the Status update determines destination file. Active files retain only Open/Partially Fixed entries plus a pointer to the archives. Archive files are NOT auto-loaded — agents read them on-demand when historical context becomes relevant. Location: AyCode.Core/.github/skills/docs-archive/SKILL.md Invoke on explicit user request ("archive ISSUES", "rotate logs") or proactively flag when an active artifact file has many closed prior entries (user must confirm — never auto-invoke).

Protocol History

Cumulative log of LLM-protocol decisions (rule changes, new skills, structural shifts):

• AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md

Read this file when you need to understand why a rule is the way it is, or before proposing a protocol change — it may save a debate about something already resolved.

Documentation-first coding

Before running any source-code Grep / get_file / code_search in response to a domain-related request, invoke the docs-discovery skill (path above). Scans docs/ folders in THIS repo AND in referenced repos (via own-dep-repos) via Glob, loads paired .md sets as a unit. Rule-number-agnostic — refers to rule NAMES (no-re-read, folder-navigation, explicit-consent) which are stable across repos.

Related Documentation

Document	Topic
docs/ARCHITECTURE.md	Layer position, Nop-framework-specific architecture notes
docs/CONVENTIONS.md	Framework-first placement + Nop-specific naming
docs/DTOS.md	DTO system — two mapping strategies, all DTO types
docs/NOP_DEPENDENCIES.md	Mirror pattern for NopCommerce entities
README.md	Folder structure, entity hierarchy, key types index

Related Solutions

Types referenced here but not defined may live in AyCode.Core or AyCode.Blazor (see @repo path above for AyCode.Core; AyCode.Blazor is at sibling path).