112 lines
8.7 KiB
Markdown
112 lines
8.7 KiB
Markdown
# Mango.Nop.Core — Domain Rules
|
|
|
|
## Workspace Dependencies
|
|
|
|
@repo {
|
|
name = "Mango.Nop.Core"
|
|
prefix = "MGNOPCORE"
|
|
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).
|