Skip to content

Open-source eCommerce platform for C# and ASP.NET Core 10 with MongoDB. Build multi-store shops and multi-vendor marketplaces with B2B/B2C, REST API, plugins, Vue 3 and Docker.

Add GitHub Copilot instructions adapter for the .ai folder (#815)

Copilot9fe130e50ee8
diff --git a/.ai/agents/admin-ui-specialist.md b/.ai/agents/admin-ui-specialist.md
new file mode 100644
index 000000000..18ce411e7
--- /dev/null
+++ b/.ai/agents/admin-ui-specialist.md
@@ -0,0 +1,15 @@
+---
+name: Admin UI Specialist
+description: Make admin-facing changes affecting Main Admin, Store Owner, Vendor, shared admin models, permissions, navigation, validation, or scoped data access.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md, .ai/skills/admin-area-changes.md, and
+.ai/skills/template-creation.md, which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/admin-area-changes.md` for Main Admin, Store Owner,
+Vendor, shared admin model, permission, navigation, validation, and scoped data access rules, and
+`.ai/skills/template-creation.md` for Razor views, partials, and admin tag helper conventions. Run
+`.ai/checklists/definition-of-done.md` before reporting the change complete.
diff --git a/.ai/agents/architecture-reviewer.md b/.ai/agents/architecture-reviewer.md
new file mode 100644
index 000000000..1900dd3a6
--- /dev/null
+++ b/.ai/agents/architecture-reviewer.md
@@ -0,0 +1,15 @@
+---
+name: Architecture Reviewer
+description: Review design, layering, dependency direction, module boundaries, public contracts, and maintainability.
+tools: ["codebase", "search", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md, .ai/skills/architecture-review.md, and
+.ai/knowledge/architecture.md, which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/architecture-review.md` for design, layering,
+dependency, module boundary, and public contract review rules, and `.ai/knowledge/architecture.md`
+for layering rules, DI lifetimes, mediator commands/queries, and domain events. Run
+`.ai/checklists/code-review.md` before reporting the review complete.
diff --git a/.ai/agents/bug-fixer.md b/.ai/agents/bug-fixer.md
new file mode 100644
index 000000000..7745cac04
--- /dev/null
+++ b/.ai/agents/bug-fixer.md
@@ -0,0 +1,16 @@
+---
+name: Bug Fixer
+description: Diagnose and fix a broken behavior when the root cause is not yet known — reproduce, find the cause, choose a fix, assess risk, test, verify.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/workflows/fix-bug.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/workflows/fix-bug.md` step by step; it names the
+skills and knowledge to load once the cause is located, and hands off to the matching prompt
+for the fix itself. Run `.ai/checklists/definition-of-done.md`, and
+`.ai/checklists/security.md` or `.ai/checklists/performance.md` when the bug touches those
+areas, before reporting the fix complete.
diff --git a/.ai/agents/dependency-upgrader.md b/.ai/agents/dependency-upgrader.md
new file mode 100644
index 000000000..74e3878d9
--- /dev/null
+++ b/.ai/agents/dependency-upgrader.md
@@ -0,0 +1,15 @@
+---
+name: Dependency Upgrader
+description: Move a NuGet package, framework, or shared version, using central package management conventions.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/workflows/upgrade-dependency.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/workflows/upgrade-dependency.md` step by step, using
+`.ai/standards/dependencies.md` for central package management, shared MSBuild props, project
+references, output paths, and SDK selection rules. Run `.ai/checklists/definition-of-done.md`
+before reporting the upgrade complete.
diff --git a/.ai/agents/dotnet-expert.md b/.ai/agents/dotnet-expert.md
new file mode 100644
index 000000000..c958d4c0e
--- /dev/null
+++ b/.ai/agents/dotnet-expert.md
@@ -0,0 +1,16 @@
+---
+name: .NET Expert
+description: Write or review idiomatic C#/.NET code — async/await, records, guard clauses, result objects, pattern matching, nullable types, and configuration binding.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md, .ai/skills/dotnet-review.md, and
+.ai/knowledge/dotnet.md / .ai/knowledge/async.md, which remain the single source of truth.
+Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/dotnet-review.md` for C#, .NET, ASP.NET Core, and
+.NET test review rules, `.ai/knowledge/dotnet.md` for idioms, and `.ai/knowledge/async.md` for
+async/await, `CancellationToken`, and `Task` vs `ValueTask` conventions. Run
+`.ai/checklists/definition-of-done.md` before reporting the change complete.
diff --git a/.ai/agents/migration-writer.md b/.ai/agents/migration-writer.md
new file mode 100644
index 000000000..4cf83d381
--- /dev/null
+++ b/.ai/agents/migration-writer.md
@@ -0,0 +1,15 @@
+---
+name: Migration Writer
+description: Add an upgrade migration that seeds or changes data for existing installations — settings, localization resources, permissions, admin sitemap entries, scheduled tasks, or document shape.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/prompts/add-migration.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/prompts/add-migration.md` step by step, using
+`.ai/skills/database-review.md` for migration, schema, and data integrity rules, and
+`.ai/templates/migration.md` as the scaffold. Run `.ai/checklists/data-change.md` and
+`.ai/checklists/definition-of-done.md` before reporting the migration complete.
diff --git a/.ai/agents/mongodb-expert.md b/.ai/agents/mongodb-expert.md
new file mode 100644
index 000000000..52d1f7ab9
--- /dev/null
+++ b/.ai/agents/mongodb-expert.md
@@ -0,0 +1,16 @@
+---
+name: MongoDB Expert
+description: Write or review MongoDB collections, filters, projections, indexes, repository queries, aggregations, updates, and data migrations.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md, .ai/skills/mongodb-review.md, and
+.ai/knowledge/mongodb.md, which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/mongodb-review.md` for collections, filters,
+projections, indexes, aggregations, updates, and data migration review rules, and
+`.ai/knowledge/mongodb.md` for `IRepository<T>` usage, query patterns, and partial update
+conventions. Run `.ai/checklists/data-change.md` and `.ai/checklists/definition-of-done.md`
+before reporting the change complete.
diff --git a/.ai/agents/notification-specialist.md b/.ai/agents/notification-specialist.md
new file mode 100644
index 000000000..6d3bb52d8
--- /dev/null
+++ b/.ai/agents/notification-specialist.md
@@ -0,0 +1,16 @@
+---
+name: Notification Specialist
+description: Work with message templates, DotLiquid tokens and drops, IMessageProviderService, queued email lifecycle, LiquidObjectBuilder, and domain event notification handlers.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/skills/message-notification.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/message-notification.md` for message templates,
+DotLiquid tokens and drops, `IMessageProviderService`, queued email lifecycle,
+`LiquidObjectBuilder`, the `MessageTokensAddedEvent` plugin extension point, and domain event
+notification handler rules. Run `.ai/checklists/definition-of-done.md` before reporting the
+change complete.
diff --git a/.ai/agents/performance-investigator.md b/.ai/agents/performance-investigator.md
new file mode 100644
index 000000000..e5397910e
--- /dev/null
+++ b/.ai/agents/performance-investigator.md
@@ -0,0 +1,16 @@
+---
+name: Performance Investigator
+description: Diagnose slow behavior when the bottleneck is unknown — define, measure, explain, fix, re-measure.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/workflows/investigate-performance.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/workflows/investigate-performance.md` step by step, using
+`.ai/knowledge/performance.md` for `ICacheBase`, cache key constants, pagination, and partial
+field write rules, and `.ai/knowledge/caching.md` for key composition and cross-family
+invalidation. Run `.ai/checklists/performance.md` and `.ai/checklists/definition-of-done.md`
+before reporting the fix complete.
diff --git a/.ai/agents/permission-navigation-specialist.md b/.ai/agents/permission-navigation-specialist.md
new file mode 100644
index 000000000..50410de22
--- /dev/null
+++ b/.ai/agents/permission-navigation-specialist.md
@@ -0,0 +1,16 @@
+---
+name: Permission & Navigation Specialist
+description: Add or change permissions, PermissionSystemName, PermissionActionName, StandardPermission, PermissionProvider, controller authorization attributes, AdminSiteMap entries, or permission/navigation migrations.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/skills/permission-navigation.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/permission-navigation.md` for permissions,
+`PermissionSystemName`, `PermissionActionName`, `StandardPermission`, `PermissionProvider`,
+controller authorization attributes, `AdminSiteMap` entries, and permission or navigation
+migration rules. Run `.ai/checklists/data-change.md` and `.ai/checklists/definition-of-done.md`
+before reporting the change complete.
diff --git a/.ai/agents/plugin-creator.md b/.ai/agents/plugin-creator.md
new file mode 100644
index 000000000..8724cea82
--- /dev/null
+++ b/.ai/agents/plugin-creator.md
@@ -0,0 +1,17 @@
+---
+name: Plugin Creator
+description: Scaffold a new installable GrandNode plugin (payment, shipping, tax, widget, external authentication, discount rule, exchange rate, or theme) end to end.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/prompts/create-plugin.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/prompts/create-plugin.md` step by step, using
+`.ai/skills/plugin-module.md` (and the plugin-kind skill it points to, e.g.
+`.ai/skills/plugin-payment.md`, `.ai/skills/plugin-shipping.md`, `.ai/skills/plugin-widget.md`,
+`.ai/skills/plugin-discount-rules.md`) and `.ai/templates/plugin/base-plugin.md` as the scaffold.
+Run `.ai/checklists/plugin-release.md` and `.ai/checklists/definition-of-done.md` before reporting
+the plugin complete.
diff --git a/.ai/agents/reviewer.md b/.ai/agents/reviewer.md
new file mode 100644
index 000000000..47e127975
--- /dev/null
+++ b/.ai/agents/reviewer.md
@@ -0,0 +1,16 @@
+---
+name: Reviewer
+description: Review a pull request or diff against all applicable repository skills and checklists before it is accepted.
+tools: ["codebase", "search", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/prompts/review-change.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/prompts/review-change.md` step by step: identify which
+skills from `.ai/skills/` apply to the change, load relevant `.ai/knowledge/` context, and run
+`.ai/checklists/code-review.md` plus any other checklist the change touches (`.ai/checklists/security.md`,
+`.ai/checklists/performance.md`, `.ai/checklists/data-change.md`, `.ai/checklists/plugin-release.md`)
+before reporting the review complete.
diff --git a/.ai/agents/scheduled-task-writer.md b/.ai/agents/scheduled-task-writer.md
new file mode 100644
index 000000000..b198551e7
--- /dev/null
+++ b/.ai/agents/scheduled-task-writer.md
@@ -0,0 +1,15 @@
+---
+name: Scheduled Task Writer
+description: Add scheduled task classes using IScheduleTask, AddKeyedScoped registration, the ScheduleTask seed, multi-instance distributed locking, error handling, and task migrations.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/skills/scheduled-task.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/scheduled-task.md` for `IScheduleTask`,
+`AddKeyedScoped` registration, the `ScheduleTask` seed, multi-instance distributed locking, error
+handling, and task migration rules. Run `.ai/checklists/data-change.md` and
+`.ai/checklists/definition-of-done.md` before reporting the task complete.
diff --git a/.ai/agents/security-reviewer.md b/.ai/agents/security-reviewer.md
new file mode 100644
index 000000000..953925842
--- /dev/null
+++ b/.ai/agents/security-reviewer.md
@@ -0,0 +1,16 @@
+---
+name: Security Reviewer
+description: Audit authentication, authorization, input handling, secrets, cryptography, sensitive data, and trust-boundary code.
+tools: ["codebase", "search", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md, .ai/skills/security-review.md, and
+.ai/knowledge/security.md, which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then read `.ai/skills/security-review.md` for authentication,
+authorization, input handling, secrets, cryptography, and trust-boundary review rules, and
+`.ai/knowledge/security.md` for authorization checks, FluentValidation patterns, guard clauses,
+HTML encoding, and safe MongoDB queries. Run `.ai/checklists/security.md` before reporting the
+review complete.
diff --git a/.ai/agents/test-writer.md b/.ai/agents/test-writer.md
new file mode 100644
index 000000000..16b3bc43b
--- /dev/null
+++ b/.ai/agents/test-writer.md
@@ -0,0 +1,15 @@
+---
+name: Test Writer
+description: Add or extend unit tests for a change, using the MSTest + Moq conventions already in src/Tests/.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/prompts/write-tests.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/prompts/write-tests.md` step by step, using
+`.ai/knowledge/tests.md` for the MSTest + Moq patterns, test structure, validator testing, and
+controller test setup. Run `.ai/checklists/definition-of-done.md` before reporting the tests
+complete.
diff --git a/.ai/agents/theme-builder.md b/.ai/agents/theme-builder.md
new file mode 100644
index 000000000..7d86f1b0a
--- /dev/null
+++ b/.ai/agents/theme-builder.md
@@ -0,0 +1,16 @@
+---
+name: Theme Builder
+description: Create a new storefront theme plugin, or override a subset of views in an existing theme, without forking the whole view tree.
+tools: ["codebase", "search", "edit", "terminal"]
+---
+
+<!--
+Adapter only. Full instructions live in AGENTS.md and .ai/prompts/create-theme.md,
+which remain the single source of truth. Do not duplicate rules here.
+-->
+
+Read `AGENTS.md` first. Then follow `.ai/prompts/create-theme.md` step by step, using
+`.ai/skills/theme-creation.md` for `IThemeView`, view-location fallback, and asset layout, and
+`.ai/skills/frontend-bundle-workflow.md` for when to run the Vite build and how to commit bundle
+output alongside source. Run `.ai/checklists/plugin-release.md` and
+`.ai/checklists/definition-of-done.md` before reporting the theme complete.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..c64a46d68
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,10 @@
+<!--
+Adapter only. All agent instructions live in AGENTS.md, which is the single source of truth
+across tools. GitHub Copilot loads .github/copilot-instructions.md automatically but does not
+follow Markdown imports, so read AGENTS.md in full before making or reviewing any change.
+Do not add rules here - add them to AGENTS.md.
+-->
+
+Read `AGENTS.md` at the repository root before doing any work here. It indexes the `.ai/` folder
+(principles, constraints, prompts, workflows, skills, knowledge, glossary, standards, checklists,
+examples, templates) and is the single source of truth for how to operate in this repository.
diff --git a/AGENTS.md b/AGENTS.md
index 9451ee8d2..5726de847 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -19,6 +19,7 @@ Use this file before making or reviewing repository changes.
| `.ai/checklists/` | cross-cutting gates | verify a change before calling it done |
| `.ai/examples/` | worked walkthroughs of shipped code | see the rules applied before writing new code |
| `.ai/templates/` | copy-ready skeletons | scaffold a plugin, theme, or migration |
+| `.ai/agents/` | agent definition wrappers | index reusable agent entry points to follow manually (mirror into `.github/agents/` for GitHub Copilot to discover them) |
**Start from a prompt or a workflow.** It names the skills, knowledge, standards, and templates to load. Use a prompt when the goal is known; use a workflow when the cause, bottleneck, or path is not.
@@ -115,6 +116,30 @@ Skills carry their own domain checklists; these cover what no single skill owns.
Templates are the shape; skills are the contract. Read the skill first, then diff the scaffold against the closest shipped plugin in `src/Plugins/`.
+## Agent Routing
+Each file in `.ai/agents/` is a thin wrapper around one prompt or workflow — same frontmatter
+shape as a GitHub custom agent (`name`, `description`, `tools`), kept in `.ai/` rather than
+`.github/agents/` so it stays indexed alongside the rest of the single source of truth. GitHub
+Copilot only discovers repository-scoped custom agents from `.github/agents/`, so these files are
+not directly usable by Copilot unless mirrored/moved there. Use them as a reference to follow when
+you want to hand off a whole recurring task instead of following a prompt manually.
+- Use `.ai/agents/plugin-creator.md` to scaffold a new installable plugin end to end.
+- Use `.ai/agents/bug-fixer.md` to diagnose and fix a broken behavior when the cause is unknown.
+- Use `.ai/agents/test-writer.md` to add or extend unit tests for a change.
+- Use `.ai/agents/reviewer.md` to review a pull request or diff against all applicable skills and checklists.
+- Use `.ai/agents/dotnet-expert.md` to write or review idiomatic C#/.NET code, async/await, and .NET test patterns.
+- Use `.ai/agents/mongodb-expert.md` to write or review MongoDB queries, indexes, aggregations, and data migrations.
+- Use `.ai/agents/security-reviewer.md` to audit authentication, authorization, input handling, secrets, and trust boundaries.
+- Use `.ai/agents/architecture-reviewer.md` to review layering, module boundaries, and public contracts.
+- Use `.ai/agents/theme-builder.md` to create a storefront theme or add view overrides to one.
+- Use `.ai/agents/migration-writer.md` to add an upgrade migration for existing installations.
+- Use `.ai/agents/admin-ui-specialist.md` for admin-facing changes across Main Admin, Store Owner, and Vendor.
+- Use `.ai/agents/performance-investigator.md` to diagnose slow queries or render paths.
+- Use `.ai/agents/permission-navigation-specialist.md` to add or change permissions and admin navigation entries.
+- Use `.ai/agents/notification-specialist.md` for message templates, DotLiquid tokens, and notification handlers.
+- Use `.ai/agents/scheduled-task-writer.md` to add a new scheduled task.
+- Use `.ai/agents/dependency-upgrader.md` to move a NuGet package, framework, or shared version.
+
## Operating Rules
1. Read the user's goal before inspecting files.
2. Load the matching prompt from `.ai/prompts/` or workflow from `.ai/workflows/`, plus the skills and standards it names.