# The AI Agent Kit

For developers

The GrandNode repository ships an AI Agent Kit: an `AGENTS.md` file at the root and a `.ai/` folder with the knowledge, rules and procedures that a coding agent — Claude Code, GitHub Copilot, Cursor, Codex or any other tool that reads repository instructions — needs to change GrandNode the way its maintainers would. It is plain Markdown, model-agnostic, and just as useful to a human developer new to the codebase. An overview for decision makers is on the [AI Agent Kit](https://grandnode.com/ai-agent-kit) page.

### The entry point: AGENTS.md

`AGENTS.md` is the file agents read first (`CLAUDE.md` simply includes it). It does not contain the rules itself; it routes the agent to the right material for the task: which prompt to start from, which skills apply to which domain, which checklists to run before calling a change done, and a short list of operating rules — read the goal first, inspect existing patterns before proposing changes, keep changes in scope, never overwrite unrelated work, report what was and was not verified.

### What is in .ai/

| Folder | Contains | Use it to |
|---|---|---|
| `principles.md` | Why the code is shaped the way it is | Resolve a judgment call between two valid approaches |
| `constraints.md` | Hard prohibitions (no AutoMapper, no Newtonsoft.Json, no blocking on tasks, no plugin references from core, no package versions in project files) | Know what is never acceptable |
| `prompts/` | Task entry points: implement a feature, create a plugin or theme, add a migration, write tests, review a change, explore the repository | Start work when you know what to build |
| `workflows/` | Multi-phase procedures with gates: fix a bug, investigate performance, refactor safely, upgrade a dependency, respond to review | Start work when the cause or path is not known yet |
| `skills/` | Domain procedures with mandatory rules: plugins by type, themes, admin panels, permissions and navigation, settings and localization, messages, scheduled tasks, MongoDB, security | Do or review work in one domain |
| `knowledge/` | How the system works: architecture, request lifecycle, scoping, caching, domain events, MongoDB, async, tests | Understand before changing |
| `glossary/` | The domain vocabulary, including the renamed terms | Name things the way GrandNode does |
| `standards/` | Naming, C# style, Razor and frontend, dependencies, git and pull requests | Format, structure and ship a change |
| `checklists/` | Definition of done, code review, security, performance, data change, plugin release | Verify a change before calling it done |
| `examples/` | Walkthroughs of shipped code: a cached store-scoped service, a payment plugin file by file, a theme override | See the rules applied |
| `templates/` | Skeletons for a plugin, an admin configuration screen, a theme and a migration | Scaffold new code |
| `agents/` | Agent definitions (plugin creator, bug fixer, reviewer, migration writer and more) | Hand a whole recurring task to an agent |

### Why the glossary matters

GrandNode renamed much of the vocabulary it inherited: *Brand* not Manufacturer, *Page* not Topic, *Customer group* not Customer role, *Merchandise return* not Return request, *Loyalty points* not Reward points, *User field* not Generic attribute. A model trained on older e-commerce code reaches for the old word, produces types that read as foreign and searches that find nothing. `.ai/glossary/renamed-terms.md` is short and prevents that.

### Using it

1. Clone the repository; the kit is part of it, nothing to install.
2. Open the repository in your agent. Tools that read `AGENTS.md` or `CLAUDE.md` pick it up automatically; for others, point the agent at `AGENTS.md` in your first message.
3. Describe the goal and name the entry point, for example:
   ```
   Follow .ai/prompts/create-plugin.md and create a shipping plugin
   Shipping.PostNord that calculates rates by weight and country.
   ```
4. Review the result against `.ai/checklists/definition-of-done.md` and `.ai/prompts/review-change.md` — the same checklists the agent was asked to run.

For GitHub Copilot, `.github/copilot-instructions.md` is a thin adapter that sends Copilot to `AGENTS.md`. The agent definitions in `.ai/agents/` follow the GitHub custom agent format; mirror them into `.github/agents/` if you want Copilot to discover them as custom agents.

### For your own project

If you build a store or plugins on GrandNode, keep the kit in your fork and extend it: add your own knowledge files (your integrations, your naming), your own skills for recurring tasks, and your constraints. Agents then follow both the platform's rules and yours.

### Related

- [AI Agent Kit](https://grandnode.com/ai-agent-kit) on grandnode.com
- [The .ai folder on GitHub](https://github.com/grandnode/grandnode2/tree/develop/.ai)
- [Contributing](https://grandnode.com/developers-contributing)

- [Web page](https://grandnode.com/developers-ai-agent-kit)