Using AI assistants (optional examples)

Not part of Core MUST. Modular Hexagonal Domain-Driven Design is AI-neutral. Skip this page entirely if your project does not use AI coding assistants.

This page shows example layouts for teams that do want assistants to follow the same Core rules as humans. Pick the pattern that matches your tool; keep this site as the source of truth.

Prefer a host one-shot when an agent should bootstrap a repo with the entire architecture in one fetch:

Index: /v1/adopt/apply · /llms.txt
Hosts (equal): laravel · symfony · yii · codeigniter · cakephp · spiral · slim · mezzio

Download: Optional assistant pack (SKILL.md, RULES.core.md, CHECKLIST.md).

This page is a layout reference. Each host one-shot’s Phase AI is the authoritative ordered procedure for Cursor / Claude / Gemini / Copilot / generic on that host.

Shared principles (any tool)

Core stays on this site — local AI files are a short reminder, not a fork of the standard.
Separate host rules — ORM / admin UI / host tooling notes live beside Core rules, never mixed into Domain MUST wording.
Greenfield names in prompts — Ordering, Warehouse, Directory, Identity (or your renamed domains).
Humans still own boundaries — run architecture boundary tests; do not trust the assistant alone.
No AI vendor required — Cursor, Copilot, Claude, Windsurf, Aider, or others are interchangeable here.

Example A — Cursor

Illustrative only. Paths reflect a common Cursor layout; adjust if your workspace differs. Replace <host> with your framework slug.

your-app/
├── README.md                          # links to this docs site
├── ROADMAP.md                         # product backlog only
├── .cursor/
│   ├── rules/
│   │   ├── modular-hexagonal-ddd.mdc  # from RULES.core.md (+ short pointer to docs URL)
│   │   └── <host>-host.mdc            # optional — adapter-only notes
│   └── skills/
│       └── modular-hexagonal-ddd/
│           └── SKILL.md               # from the optional pack
└── app/Modules/…                      # or src/Modules/ — host convention

Suggested modular-hexagonal-ddd.mdc head matter (conceptually):

# Modular Hexagonal DDD — Core pointer

Canonical docs: <URL of this site>/v1/core  (Core 1.0.0-draft)
Host adapter: <URL>/v1/adapters/<host>

Follow RULES from the optional pack. Do not invent alternate module layouts.
Design test: peer replaced by HTTP → Application/Domain still compile.

Paste the body of RULES.core.md under that pointer. Keep host ORM/UI tooling guidance in <host>-host.mdc.

Example B — Generic project instructions (vendor-agnostic)

Works for tools that read a root instructions file (AGENTS.md, .github/copilot-instructions.md, CLAUDE.md, etc.):

your-app/
├── README.md
├── AGENTS.md                 # or your tool’s equivalent filename
├── docs/
│   └── architecture-pointer.md
└── .ai/                      # optional folder name — pick one convention
    ├── RULES.core.md         # copied from the pack
    ├── SKILL.md
    └── CHECKLIST.md

Minimal AGENTS.md:

# Architecture

We follow Modular Hexagonal Domain-Driven Design.

- Canon: <URL of this site> (Core 1.0.0-draft)
- Host mapping: <URL>/v1/adapters/<host>
- Local reminder: .ai/RULES.core.md
- Review checklist: .ai/CHECKLIST.md

Do not treat this file as a second architecture standard.
When unsure, open the canon site pages (strictness ladder, ACL, events, contracts).

Example C — First session prompt (copy/paste)

Use after the pack (or pointer) is in the repo:

Follow Modular Hexagonal Domain-Driven Design from our canonical docs:
<URL>/v1/core and <URL>/v1/adapters/<host>.

Prefer one-shot: <URL>/apply/<host>.full.md
Rules reminder: .ai/RULES.core.md (or .cursor/skills/modular-hexagonal-ddd/SKILL.md).
Keep delivery work in ROADMAP.md. Do not invent alternate layouts.
Greenfield illustrative names only — rename Ordering/Warehouse to our domains when implementing.

Task: <describe the feature>

Example D — PR / review habit

Whether or not an assistant wrote the code:

Run host boundary tests (see the matching adapter Tooling page under Adapters).
Walk CHECKLIST.md from the pack.
Re-check the design test on any new cross-module touch.

What not to do

Smell	Prefer
Pasting the entire Core site into the repo as a second canon	Short pointer + optional pack
Requiring Cursor (or any vendor) in the project README as architecture MUST	Link this optional page only
Mixing product GAP IDs into AI rules	Keep `ROADMAP.md` for delivery
Letting the assistant skip ACL/Events “for speed”	Reject in review; fix toward Core
Treating one host’s folders as Core	Point at that host’s adapter only

Optional assistant pack
Greenfield bootstrap
Adopt overview
Portable requirements (AI is a non-goal / not required)