KrzysztofPajak · Oct 4, 2026 · Aug 16, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/.ai/agents/admin-ui-specialist.md 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/.ai/checklists/README.md b/.ai/checklists/README.md
@@ -0,0 +1,19 @@
+# Checklists
+
+Cross-cutting gates. Skills carry their own domain checklists (a widget plugin's `Validation Checklist` belongs in the widget skill); these cover what no single skill owns.
+
+| Checklist | Run it |
+|---|---|
+| `definition-of-done.md` | Before calling any change complete |
+| `code-review.md` | When reviewing someone else's diff, or your own before opening a PR |
+| `security.md` | When the change touches auth, input, scoped data, secrets, or file handling |
+| `performance.md` | When the change adds a query, a loop over entities, or a page render path |
+| `data-change.md` | When the change touches entities, migrations, settings, or persisted identities |
+| `plugin-release.md` | Before shipping a plugin or theme |
+
+## How to use
+
+1. Run `definition-of-done.md` on every change. Add the situational ones the change triggers.
+2. A checklist item is a question to answer, not a box to tick by reflex. "Yes, because …" is the passing answer.
+3. Report items that do not apply as N/A with a reason. Silence reads as an unchecked box.
+4. An item you cannot verify is a risk to state in the PR, not an item to skip.
diff --git a/.ai/checklists/code-review.md b/.ai/checklists/code-review.md
@@ -0,0 +1,107 @@
+# Checklist: Code Review
+
+For reviewing a diff. Report only high-confidence findings, each with file, line, the rule violated, the failure it causes, and a minimal fix.
+
+Use with `.ai/prompts/review-change.md`, which handles skill selection.
+
+---
+
+## Read the diff twice
+
+- [ ] First pass: does the change do what its description claims?
+- [ ] Second pass: what did it change that the description does not mention?
+
+## Layering
+
+- [ ] No business logic in a controller.
+- [ ] No view model in a business service.
+- [ ] No MongoDB driver type outside `Grand.Data`.
+- [ ] No HTTP or `IWorkContext` dependency in `Grand.Domain`.
+- [ ] No core → plugin reference.
+- [ ] Services registered in `IStartupApplication`, not `Program.cs`.
+
+## Scoping — the highest-yield section
+
+- [ ] Every new query filters by store.
+- [ ] Vendor-reachable code filters by `VendorId` and re-checks ownership on write.
+- [ ] `LimitedToStores` / `LimitedToGroups` honoured where the entity supports them.
+- [ ] Every new cache key contains store id — and language id if the data is localized.
+- [ ] Settings loaded and saved with the same store scope.
+- [ ] No `IWorkContext` in a scheduled task, migration, or plugin install.
+
+## Duplication and reuse
+
+- [ ] The logic does not already exist in a service, extension, or helper.
+- [ ] A near-copy of an existing method was not introduced instead of a parameter.
+- [ ] A third repetition of the same block was extracted rather than added.
+- [ ] Copy-pasted code had **every** identifier updated — stale names from the source are a classic defect.
+
+## Validation
+
+- [ ] Inputs crossing a trust boundary are validated.
+- [ ] Validators cover the new fields, not just the old ones.
+- [ ] Guard clauses use `ArgumentNullException.ThrowIfNull`.
+- [ ] Invalid model state does not partially save.
+
+## Exception handling
+
+- [ ] No empty `catch`, no `catch (Exception)` that continues silently.
+- [ ] Expected business failures return results, not exceptions.
+- [ ] Notification handlers cannot throw into the publisher.
+- [ ] Migrations return `false` instead of throwing.
+- [ ] Disposables are disposed.
+
+## Logging
+
+- [ ] Diagnosable failures are logged with store/entity/operation context.
+- [ ] No secrets or personal data in log output.
+- [ ] Log levels are proportionate.
+- [ ] No logging in a hot loop.
+
+## Async
+
+- [ ] No `.Result`, `.Wait()`, `GetAwaiter().GetResult()`.
+- [ ] No `async void`.
+- [ ] No `Task.Run` wrapping synchronous work.
+- [ ] `CancellationToken` forwarded where the surrounding signatures carry one.
+
+## Data lifecycle
+
+- [ ] Every write invalidates its cache prefix.
+- [ ] Every write publishes its entity event.
+- [ ] Cross-family caches that embed the entity are invalidated too.
+- [ ] Migration `Identity` GUID is new.
+- [ ] Migration is idempotent and destroys nothing operator-owned.
+- [ ] No persisted identity renamed (plugin system name, permission name, template name, task name).
+
+## Localization
+
+- [ ] No hardcoded user-facing string.
+- [ ] Resource keys follow the naming convention and are added **and** removed symmetrically in plugin install/uninstall.
+- [ ] Localized entity properties read through the translation extension, not the raw property.
+
+## Frontend
+
+- [ ] Storefront data attributes preserved on touched views.
+- [ ] Widget zones preserved.
+- [ ] No `Html.Raw` on user content.
+- [ ] Bundles rebuilt if source changed.
+
+## Tests
+
+- [ ] New behavior has tests, in the mirror project.
+- [ ] Bug fixes have a regression test.
+- [ ] No assertion weakened to make the suite pass.
+- [ ] Tests mock at interface boundaries and hit no real database or network.
+
+## Backward compatibility
+
+- [ ] An existing installation upgrading in place still works.
+- [ ] New settings default to previous behavior.
+- [ ] No public interface, view model, or route changed without the PR saying so under "Breaking changes".
+
+## Before submitting the review
+
+- [ ] Every finding verified by opening the file — no speculative claims.
+- [ ] Findings ranked by severity, not by file order.
+- [ ] Style and preference comments omitted unless a mandatory rule is broken.