ddd-ts-kit 0.17.0 → 0.18.0

package/dist/sdk/instruct-agents.js

@@ -1,19 +1,23 @@
 import { AGENT_INSTRUCTION } from './agent-instruction.js';
-const INSTRUCTIONS = 'CLAUDE.md';
-const PRESENTATION_RULE = '.claude/rules/presentation.md';
+/** The guide of every agent; a project written before it kept its instructions in CLAUDE.md. */
+const GUIDES = ['AGENTS.md', 'CLAUDE.md'];
+const PRESENTATION_RULES = ['.claude/rules/presentation.md', '.github/instructions/presentation.instructions.md'];
 /**
  * What `init --sdk` writes for the agents of a project, in one that asks for clients later: the
- * instruction of CLAUDE.md, appended once, and a note for the paths of the presentation rule,
+ * instruction of its guide, appended once, and a note for the paths of the presentation rules,
  * which the team may have rewritten.
  */
 export function instructAgents(ws) {
-    const instructions = ws.read(INSTRUCTIONS);
+    const guide = GUIDES.find((file) => ws.exists(file));
+    const instructions = guide === undefined ? undefined : ws.read(guide);
     const instruction = ws.spoken(AGENT_INSTRUCTION);
-    if (instructions !== undefined && !instructions.includes(instruction)) {
-        ws.update(INSTRUCTIONS, `${instructions}${instructions.endsWith('\n') ? '' : '\n'}\n${instruction}\n`);
+    if (guide !== undefined && instructions !== undefined && !instructions.includes(instruction)) {
+        ws.update(guide, `${instructions}${instructions.endsWith('\n') ? '' : '\n'}\n${instruction}\n`);
     }
-    if (!(ws.read(PRESENTATION_RULE) ?? '"clients/**"').includes('"clients/**"')) {
-        ws.note(`${PRESENTATION_RULE}: add "clients/**" to its paths, so that an agent editing a client reads it.`);
+    for (const rule of PRESENTATION_RULES) {
+        if (!(ws.read(rule) ?? 'clients/**').includes('clients/**')) {
+            ws.note(`${rule}: add "clients/**" to its paths, so that an agent editing a client reads it.`);
+        }
     }
 }
 //# sourceMappingURL=instruct-agents.js.map

package/dist/sdk/instruct-agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"instruct-agents.js","sourceRoot":"","sources":["../../src/sdk/instruct-agents.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,MAAM,YAAY,GAAG,WAAW,CAAC;AACjC,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAa;IAC1C,MAAM,YAAY,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAEjD,IAAI,YAAY,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QACtE,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC;IACzG,CAAC;IAED,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,cAAc,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC7E,EAAE,CAAC,IAAI,CAAC,GAAG,iBAAiB,8EAA8E,CAAC,CAAC;IAC9G,CAAC;AACH,CAAC"}
+{"version":3,"file":"instruct-agents.js","sourceRoot":"","sources":["../../src/sdk/instruct-agents.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,gGAAgG;AAChG,MAAM,MAAM,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAC1C,MAAM,kBAAkB,GAAG,CAAC,+BAA+B,EAAE,mDAAmD,CAAC,CAAC;AAElH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAa;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrD,MAAM,YAAY,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtE,MAAM,WAAW,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAEjD,IAAI,KAAK,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7F,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC;IAClG,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,kBAAkB,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAC5D,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,8EAA8E,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.18.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '0.17.0';
+export const VERSION = '0.18.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,7 +1,28 @@
 {
   "name": "ddd-ts-kit",
-  "version": "0.17.0",
-  "description": "Bootstrap, scaffold and verify DDD and Clean Architecture TypeScript projects.",
+  "version": "0.18.0",
+  "description": "Bootstrap, scaffold and verify Domain-Driven Design (DDD), Clean Architecture and hexagonal TypeScript backends on Node.js: project and code generators, architecture checks, OpenAPI and AsyncAPI documents, for developers and AI coding agents (Claude Code, Codex, GitHub Copilot).",
+  "keywords": [
+    "ddd",
+    "domain-driven-design",
+    "clean-architecture",
+    "hexagonal-architecture",
+    "typescript",
+    "cli",
+    "scaffolding",
+    "code-generator",
+    "project-generator",
+    "architecture-testing",
+    "cqrs",
+    "event-sourcing",
+    "modular-monolith",
+    "microservices",
+    "nodejs",
+    "claude-code",
+    "codex",
+    "github-copilot",
+    "ai-agents"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -29,6 +50,6 @@
     "clean:packages": "node dist/bin.js check --clean-only ../kernel/src ../validation/src ../http/src ../tracing/src ../di/src ../events/src ../testing/src ../s3/src ../drizzle/src ../knex/src ../prisma/src ../typeorm/src ../aspects/src ../rabbitmq/src ../auth/src ../audit/src ../redis/src ../scheduling/src ../pino/src ../winston/src ../sentry/src ../kafka/src ../nats/src ../eslint-plugin/src"
   },
   "devDependencies": {
-    "@ddd-ts-kit/kernel": "^0.17.0"
+    "@ddd-ts-kit/kernel": "^0.18.0"
   }
 }

package/templates/command/handler.declared.ts.tpl

@@ -1,8 +1,14 @@
 {{#if command.hasAggregate}}
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import type { Clock, IdGenerator } from '@ddd-ts-kit/kernel';
 import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';
 import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate{{alias.ext}}';
 import type { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository{{alias.ext}}';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.command{{alias.ext}}';
 
 @CommandHandler({{name.pascal}}Command)
@@ -11,9 +17,17 @@ export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Com
     private readonly {{aggregate.camel}}Repository: {{aggregate.pascal}}Repository,
     private readonly ids: IdGenerator,
     private readonly clock: Clock,
+{{#if access.policy}}
+    private readonly access: Access,
+{{/if}}
   ) {}
 
   async execute(command: {{name.pascal}}Command): Promise<string> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" acts on once it is loaded, in place of `command`.
+    await this.access.authorize(command.actor, {{access.reference}}, command);
+
+{{/if}}
 {{#if refusals.factories}}
     // TODO(domain): decide what "{{name.words}}" does to a {{aggregate.pascal}}: either it gives birth to one (keep `create`, pass the facts of `command` as value objects), or it changes an existing one (load it with `findById`, throw its not-found refusal, `{{aggregate.pascal}}Error.notFound(id)` (`ddd-ts-kit generate error {{context.kebab}} {{aggregate.pascal}} notFound`), call ONE intention method). The events it records leave with the save: nothing else to do here.
 {{/if}}
@@ -29,12 +43,27 @@ export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Com
 }
 {{/if}}
 {{#unless command.hasAggregate}}
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import { CommandHandler } from '@ddd-ts-kit/kernel/declarations';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.command{{alias.ext}}';
 
 @CommandHandler({{name.pascal}}Command)
 export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Command> {
+{{#if access.policy}}
+  constructor(private readonly access: Access) {}
+
+{{/if}}
   async execute(command: {{name.pascal}}Command): Promise<void> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" acts on once it is loaded, in place of `command`.
+    await this.access.authorize(command.actor, {{access.reference}}, command);
+
+{{/if}}
     // TODO(domain): receive the repository of the aggregate "{{name.words}}" acts on in the constructor, typed by its port (rerun with --aggregate <Name> --force to get it declared), load or create the aggregate from `command`, call its intention method and save it (its events leave with the save); the unit of work is opened by the command bus.
   }
 }

package/templates/command/handler.spec.buses.ts.tpl

@@ -1,6 +1,11 @@
 import { describe, expect, it } from '{{tests.module}}';
 {{#if access.protected}}
+{{#if access.policy}}
+import { AuthorizationMap, PolicyAccess, RoleBasedAuthorizer, authorizationMiddleware, requires } from '@ddd-ts-kit/auth';
+{{/if}}
+{{#unless access.policy}}
 import { AuthorizationMap, RoleBasedAuthorizer, authorizationMiddleware, requires } from '@ddd-ts-kit/auth';
+{{/unless}}
 import { anActor } from '@ddd-ts-kit/auth/testing';
 {{/if}}
 import { createTestBuses } from '@ddd-ts-kit/testing';
@@ -14,12 +19,22 @@ import { Fake{{aggregate.pascal}}Repository } from '{{alias.context}}/test/fakes
 {{/if}}
 {{#if access.protected}}
 
+{{#if access.policy}}
+const authorizer = new RoleBasedAuthorizer({ roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] } });
+
+const holders = authorizationMiddleware({
+  authorizer,
+  map: AuthorizationMap.of(requires({{name.pascal}}Command, {{context.camel}}Permissions['{{access.permission}}'])),
+});
+{{/if}}
+{{#unless access.policy}}
 const holders = authorizationMiddleware({
   authorizer: new RoleBasedAuthorizer({
     roles: { holder: [{{context.camel}}Permissions['{{access.permission}}']] },
   }),
   map: AuthorizationMap.of(requires({{name.pascal}}Command, {{context.camel}}Permissions['{{access.permission}}'])),
 });
+{{/unless}}
 
 const holder = anActor().withRole('holder').build();
 {{/if}}
@@ -71,16 +86,24 @@ function arrange() {
   // As the application hands it to the handler: the save announces the events of the {{aggregate.words}} to `domainEvents`.
   const {{aggregate.camel}}Repository = dispatching(new Fake{{aggregate.pascal}}Repository());
 
-  const handler = new {{name.pascal}}Handler({{aggregate.camel}}Repository, ids, clock);
+  const handler = new {{name.pascal}}Handler({{aggregate.camel}}Repository, ids, clock{{#if access.policy}}, new PolicyAccess({ authorizer, clock }){{/if}});
 
   commandBus{{spec.guard}}.register({{name.pascal}}Command, handler);
 
   return { commandBus, {{aggregate.camel}}Repository, domainEvents };
   {{/if}}
   {{#unless command.hasAggregate}}
+{{#if access.policy}}
+  const { commandBus, clock } = createTestBuses();
+  const handler = new {{name.pascal}}Handler(new PolicyAccess({ authorizer, clock }));
+
+  commandBus{{spec.guard}}.register({{name.pascal}}Command, handler);
+{{/if}}
+{{#unless access.policy}}
   const { commandBus } = createTestBuses();
 
   commandBus{{spec.guard}}.register({{name.pascal}}Command, new {{name.pascal}}Handler());
+{{/unless}}
 
   return { commandBus };
   {{/unless}}

package/templates/command/handler.ts.tpl

@@ -1,7 +1,13 @@
 {{#if command.hasAggregate}}
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import type { Clock, CommandHandler, IdGenerator } from '@ddd-ts-kit/kernel';
 import { {{aggregate.pascal}} } from '{{alias.context}}/domain/aggregates/{{aggregate.kebab}}.aggregate{{alias.ext}}';
 import type { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository{{alias.ext}}';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import type { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.command{{alias.ext}}';
 
 export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Command> {
@@ -9,9 +15,17 @@ export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Com
     private readonly {{aggregate.camel}}Repository: {{aggregate.pascal}}Repository,
     private readonly ids: IdGenerator,
     private readonly clock: Clock,
+{{#if access.policy}}
+    private readonly access: Access,
+{{/if}}
   ) {}
 
   async execute(command: {{name.pascal}}Command): Promise<string> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" acts on once it is loaded, in place of `command`.
+    await this.access.authorize(command.actor, {{access.reference}}, command);
+
+{{/if}}
 {{#if refusals.factories}}
     // TODO(domain): decide what "{{name.words}}" does to a {{aggregate.pascal}}: either it gives birth to one (keep `create`, pass the facts of `command` as value objects), or it changes an existing one (load it with `findById`, throw its not-found refusal, `{{aggregate.pascal}}Error.notFound(id)` (`ddd-ts-kit generate error {{context.kebab}} {{aggregate.pascal}} notFound`), call ONE intention method). The events it records leave with the save: nothing else to do here.
 {{/if}}
@@ -27,11 +41,26 @@ export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Com
 }
 {{/if}}
 {{#unless command.hasAggregate}}
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import type { CommandHandler } from '@ddd-ts-kit/kernel';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import type { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.command{{alias.ext}}';
 
 export class {{name.pascal}}Handler implements CommandHandler<{{name.pascal}}Command> {
+{{#if access.policy}}
+  constructor(private readonly access: Access) {}
+
+{{/if}}
   async execute(command: {{name.pascal}}Command): Promise<void> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" acts on once it is loaded, in place of `command`.
+    await this.access.authorize(command.actor, {{access.reference}}, command);
+
+{{/if}}
     // TODO(domain): receive the repository of the aggregate "{{name.words}}" acts on in the constructor (rerun with --aggregate <Name> --force to get it wired), load or create the aggregate from `command`, call its intention method and save it (its events leave with the save); the unit of work is opened by the command bus.
   }
 }

package/templates/command/wiring.manual.tpl

@@ -5,10 +5,10 @@ import { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{
 import { {{name.pascal}}Handler } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.handler{{alias.ext}}';
 @@registrations
 {{#if command.hasAggregate}}
-platform.commands.register({{name.pascal}}Command, new {{name.pascal}}Handler({{aggregate.camel}}Repository, platform.ids, platform.clock), { context: '{{context.kebab}}' });
+platform.commands.register({{name.pascal}}Command, new {{name.pascal}}Handler({{aggregate.camel}}Repository, platform.ids, platform.clock{{#if access.policy}}, platform.access{{/if}}), { context: '{{context.kebab}}' });
 {{/if}}
 {{#unless command.hasAggregate}}
-platform.commands.register({{name.pascal}}Command, new {{name.pascal}}Handler(), { context: '{{context.kebab}}' });
+platform.commands.register({{name.pascal}}Command, new {{name.pascal}}Handler({{#if access.policy}}platform.access{{/if}}), { context: '{{context.kebab}}' });
 {{/unless}}
 @@authorization
 {{access.manualDeclaration}}

package/templates/command/wiring.tsyringe.tpl

@@ -1,4 +1,7 @@
 @@imports
+{{#if access.policy}}
+import { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 {{#if command.hasAggregate}}
 import { Clock, IdGenerator } from '@ddd-ts-kit/kernel';
 import { {{aggregate.pascal}}Repository } from '{{alias.context}}/domain/repositories/{{aggregate.kebab}}.repository{{alias.ext}}';
@@ -8,8 +11,8 @@ import { {{name.pascal}}Command } from '{{alias.context}}/application/commands/{
 import { {{name.pascal}}Handler } from '{{alias.context}}/application/commands/{{name.kebab}}/{{name.kebab}}.handler{{alias.ext}}';
 @@registrations
 {{#if command.hasAggregate}}
-builder.command({{name.pascal}}Command){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{aggregate.pascal}}Repository, IdGenerator, Clock]);
+builder.command({{name.pascal}}Command){{access.declaration}}.handledBy({{name.pascal}}Handler, [{{aggregate.pascal}}Repository, IdGenerator, Clock{{#if access.policy}}, Access{{/if}}]);
 {{/if}}
 {{#unless command.hasAggregate}}
-builder.command({{name.pascal}}Command){{access.declaration}}.handledBy({{name.pascal}}Handler);
+builder.command({{name.pascal}}Command){{access.declaration}}.handledBy({{name.pascal}}Handler{{#if access.policy}}, [Access]{{/if}});
 {{/unless}}

package/templates/event-handler/event-handler.declared.ts.tpl

@@ -1,7 +1,7 @@
 import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
 import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event{{alias.ext}}';
 
-@DomainEventHandler({{event.pascal}}, { name: {{event.reference}}{{#if handler.afterCommit}}, phase: 'after-commit'{{/if}} })
+@DomainEventHandler({{event.pascal}}{{#if handler.afterCommit}}, { phase: 'after-commit' }{{/if}})
 export class {{event.pascal}}EventHandler implements DomainEventHandler<{{event.pascal}}> {
   async handle(event: {{event.pascal}}): Promise<void> {
 {{#unless handler.afterCommit}}

package/templates/init/AGENTS.md.tpl

@@ -0,0 +1,46 @@
+# {{project.name}}
+
+A ddd-ts-kit project: one bounded context per directory of `{{config.contextsDir}}/`, each described by its `CONTEXT.md`. The plan and what is next: `docs/architecture/plan.md`, when the project follows the method.
+
+## Commands
+
+- `npm run verify`: types, lint, format, tests with the coverage thresholds of `ddd-ts-kit.config.json` (per context and layer), architecture rules, import graph, dead code, documentation drift. Once, before a commit that closes a slice. A layer under its threshold gets the missing test, never an exclusion.
+- `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
+- `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
+- `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
+- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract, the forms and the event catalog.
+
+## Read less
+
+1. `describe <context> --json` and the `CONTEXT.md` of the context before the tree: do not browse `{{config.sourceRoot}}/` to learn what exists.
+2. Open only what the `next` list of a generator (`file:line`) or a violation names.
+3. `check --changed-since <ref>` and the tests of the context while iterating; `npm run verify` once at the end.
+
+## Rules by layer
+
+One file per layer in `.claude/rules/`: `domain.md` (`domain/`, the shared kernel), `application.md`, `published-language.md`, `infrastructure.md`, `presentation.md` (and the OpenAPI contract), `platform.md` (`{{config.platformDir}}/`, `main.ts`, `apps/`{{#if style.explicit}}, module files{{/if}}), `tests.md` (specs, fakes, builders, `test/`). The same text is in `.github/instructions/<layer>.instructions.md`. Claude Code and GitHub Copilot load it with the files it applies to; an agent that does not (Codex) reads the file of a layer before it edits a file of that layer.
+
+## Generated files
+
+Create every file of a role with `npx ddd-ts-kit generate <kind> ... --json`, then fill the `TODO(domain)` places it lists; never write one by hand, never restructure what a generator wrote.
+{{#if assembly.barrel}}
+Never edit `<context>.declarations.ts`: `generate`, `docs` and `npm run dev` rewrite it, from the role files and from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
+{{/if}}
+{{#if assembly.discovery}}
+Never edit `<context>.dependencies.ts`: `generate`, `docs` and `npm run dev` rewrite it from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
+{{/if}}
+Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it, the forms of `openapi/forms/`), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `{{config.platformDir}}/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
+{{#if sdk.on}}
+{{sdk.instruction}}
+{{/if}}
+Imports: a file of the project is imported by its alias from the project root, never by a relative path, the same directory included: `{{alias.source}}/...` for `{{config.sourceRoot}}/`, `{{alias.test}}/...` for `test/`, `{{alias.scripts}}/...` for `scripts/`, {{#if alias.extensionless}}never ending in `.js` or `.ts`, and naming a file, never a directory{{/if}}{{#unless alias.extensionless}}always ending in `.js`{{/unless}} (`imports/alias-only`, `imports/extension`; `npm run lint:fix` rewrites a relative import and a wrong ending). The alias is declared once, under `paths` in `tsconfig.json`, from `importAlias` of `ddd-ts-kit.config.json`, and the ending follows `importExtension`: never add a second entry or mapping, never change `module` or `moduleResolution` in `tsconfig.json`, and never compile without `npm run build`, which rewrites the aliases of `dist/` into relative paths ending in `.js` for Node (`imports/alias-declared`).
+Everywhere: one exported class, interface or function per file, named after it in kebab-case; at most 350 lines a file, 30 lines and 3 parameters a function; `private` members, never `#name`; a blank line before a `return` and around `if`, `for`, `try` (`npm run lint:fix`); braces around the body of every `if`, `else`, `for`, `while` and `do`, on its own lines: a branch is visible at a glance, and a statement added to it later cannot silently fall outside it. `npm run format` (Biome, line width 120) lays out every file: do not spend tokens on line breaks.
+
+## TypeScript
+
+The compiler is the native TypeScript 7, installed as `@typescript/native`; `typescript` 6 is there for the tools that need its API (ESLint, dependency-cruiser). Use `npm run typecheck` and `npm run build`, never `npx tsc`, which would run version 6.
+
+## Workflow
+
+Follow the recommended steps in order, the supported path (`README.md`, "Recommended steps"): discover the domain, bounded contexts, glossaries, context map, bootstrap, plan the slices, build slice by slice, quality gate, document. `npx ddd-ts-kit status` says where the project stands. When asked to skip a step, say which one and what it costs, and record it in `docs/architecture/plan.md`.
+With the ddd-ts-kit plugin: `/ddd-ts-kit:start` for a new project or to resume one, `/ddd-ts-kit:glossary` before a new name, `/ddd-ts-kit:use-case` for a feature, `/ddd-ts-kit:document` for the contracts, `/ddd-ts-kit:quality-gate` before a pull or merge request. The plugin installs in Claude Code, Codex and the Copilot CLI from the marketplace `gbourgeat/ddd-ts-kit`; Codex calls a skill by its name, `$start`, `$use-case`.

package/templates/init/CLAUDE.md.tpl

@@ -1,46 +1,3 @@
-# {{project.name}}
+@AGENTS.md
 
-A ddd-ts-kit project: one bounded context per directory of `{{config.contextsDir}}/`, each described by its `CONTEXT.md`. The plan and what is next: `docs/architecture/plan.md`, when the project follows the method.
-
-## Commands
-
-- `npm run verify`: types, lint, format, tests with the coverage thresholds of `ddd-ts-kit.config.json` (per context and layer), architecture rules, import graph, dead code, documentation drift. Once, before a commit that closes a slice. A layer under its threshold gets the missing test, never an exclusion.
-- `npx ddd-ts-kit check --changed-since <ref>`: the architecture rules on what changed; `npx ddd-ts-kit explain <rule-id>` gives the reason and an example.
-- `npx ddd-ts-kit list --json`: the map of the contexts. `npx ddd-ts-kit describe <context> --json`: one context as data (use cases, routes, events, ports, dependencies).
-- `npx ddd-ts-kit status`: the next step of the plan, the slices by status, the markers left per context. `npx ddd-ts-kit todo [<context>]`: each remaining `TODO(domain)` and `it.todo` as `file:line`.
-- `npx ddd-ts-kit docs`: regenerates the context map and the generated sections of each `CONTEXT.md`; `npm run docs:generate` the OpenAPI contract, the forms and the event catalog.
-
-## Read less
-
-1. `describe <context> --json` and the `CONTEXT.md` of the context before the tree: do not browse `{{config.sourceRoot}}/` to learn what exists.
-2. Open only what the `next` list of a generator (`file:line`) or a violation names.
-3. `check --changed-since <ref>` and the tests of the context while iterating; `npm run verify` once at the end.
-
-## Rules by layer
-
-Loaded with the files they apply to, from `.claude/rules/`: `domain.md` (`domain/`, the shared kernel), `application.md`, `published-language.md`, `infrastructure.md`, `presentation.md` (and the OpenAPI contract), `platform.md` (`{{config.platformDir}}/`, `main.ts`, `apps/`{{#if style.explicit}}, module files{{/if}}), `tests.md` (specs, fakes, builders, `test/`).
-
-## Generated files
-
-Create every file of a role with `npx ddd-ts-kit generate <kind> ... --json`, then fill the `TODO(domain)` places it lists; never write one by hand, never restructure what a generator wrote.
-{{#if assembly.barrel}}
-Never edit `<context>.declarations.ts`: `generate`, `docs` and `npm run dev` rewrite it, from the role files and from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
-{{/if}}
-{{#if assembly.discovery}}
-Never edit `<context>.dependencies.ts`: `generate`, `docs` and `npm run dev` rewrite it from the constructor signatures (it registers what each constructor is injected). After changing a constructor by hand, `npx ddd-ts-kit docs`.
-{{/if}}
-Never edit the contracts under `openapi/` (`openapi/openapi.yaml`, one file per document when `openapi.documents` splits it, the forms of `openapi/forms/`), `docs/integration/asyncapi.yaml`, `docs/integration/event-catalog.md`, `{{config.platformDir}}/http/openapi-documents.ts`, `.dependency-cruiser.cjs` or the generated sections of a `CONTEXT.md`: change the code or the config, then `npm run docs:generate`, `npx ddd-ts-kit docs` and `npx ddd-ts-kit depcruise-config --write`. `stored-events.lock.json` is written by `npx ddd-ts-kit docs --stored-events` once the shape of a version is final (`docs --check` fails while one is unrecorded), never by hand: a stored shape changes only by a new version with its upcaster (`event-sourcing/upcaster-required`).
-{{#if sdk.on}}
-{{sdk.instruction}}
-{{/if}}
-Imports: a file of the project is imported by its alias from the project root, never by a relative path, the same directory included: `{{alias.source}}/...` for `{{config.sourceRoot}}/`, `{{alias.test}}/...` for `test/`, `{{alias.scripts}}/...` for `scripts/`, {{#if alias.extensionless}}never ending in `.js` or `.ts`, and naming a file, never a directory{{/if}}{{#unless alias.extensionless}}always ending in `.js`{{/unless}} (`imports/alias-only`, `imports/extension`; `npm run lint:fix` rewrites a relative import and a wrong ending). The alias is declared once, under `paths` in `tsconfig.json`, from `importAlias` of `ddd-ts-kit.config.json`, and the ending follows `importExtension`: never add a second entry or mapping, never change `module` or `moduleResolution` in `tsconfig.json`, and never compile without `npm run build`, which rewrites the aliases of `dist/` into relative paths ending in `.js` for Node (`imports/alias-declared`).
-Everywhere: one exported class, interface or function per file, named after it in kebab-case; at most 350 lines a file, 30 lines and 3 parameters a function; `private` members, never `#name`; a blank line before a `return` and around `if`, `for`, `try` (`npm run lint:fix`); braces around the body of every `if`, `else`, `for`, `while` and `do`, on its own lines: a branch is visible at a glance, and a statement added to it later cannot silently fall outside it. `npm run format` (Biome, line width 120) lays out every file: do not spend tokens on line breaks.
-
-## TypeScript
-
-The compiler is the native TypeScript 7, installed as `@typescript/native`; `typescript` 6 is there for the tools that need its API (ESLint, dependency-cruiser). Use `npm run typecheck` and `npm run build`, never `npx tsc`, which would run version 6.
-
-## Workflow
-
-Follow the recommended steps in order, the supported path (`README.md`, "Recommended steps"): discover the domain, bounded contexts, glossaries, context map, bootstrap, plan the slices, build slice by slice, quality gate, document. `npx ddd-ts-kit status` says where the project stands. When asked to skip a step, say which one and what it costs, and record it in `docs/architecture/plan.md`.
-With the ddd-ts-kit plugin: `/ddd-ts-kit:start` for a new project or to resume one, `/ddd-ts-kit:glossary` before a new name, `/ddd-ts-kit:use-case` for a feature, `/ddd-ts-kit:document` for the contracts, `/ddd-ts-kit:quality-gate` before a pull or merge request.
+The rules by layer of `.claude/rules/` load with the files they apply to.

package/templates/init/README.md.tpl

@@ -1,7 +1,7 @@
 # {{project.name}}
 
 Domain-Driven Design and Clean Architecture on [ddd-ts-kit](https://www.npmjs.com/package/ddd-ts-kit).
-The rules are in `CLAUDE.md` and `.claude/rules/`; `npx ddd-ts-kit explain <rule-id>` explains each one.
+The rules are in `AGENTS.md`, which every coding agent reads, and by layer in `.claude/rules/` and `.github/instructions/`; `npx ddd-ts-kit explain <rule-id>` explains each one.
 
 ## Run it
 

package/templates/init/rules/application.md.tpl

@@ -11,7 +11,7 @@ paths:
 - Nothing here reads the event store: an event-sourced aggregate is loaded and saved through its repository port like any other (`event-sourcing/store-behind-repository`). A projection writes its read model and never a stream (`event-sourcing/projection-never-appends`); one fed by the store is declared `@Projection(name, { feed: 'event-store' })`.
 {{#if style.declared}}
 - Every command and query carries `@Requires(permission)` or `@Public()` (`authz/declared`), and the actor is in the message (`authz/actor-explicit`). Permissions live in `authorization/<context>.permissions.ts`, rules that need loaded state in `authorization/*.policy.ts`.
-- The decorator is the registration (`declarations/role-declared`): `@CommandHandler(Message)`, `@QueryHandler(Message)`, `@DomainEventHandler(Event, { name })`, `@IntegrationEventHandler(definition, { consumer })`, `@Scheduled('<context>.<job>', schedule)`, `@Background(options)` (the name is the static `jobName`), `@Projection('<context>.<name>')`, `@Policy(permission, { name })`. Names are string literals.
+- The decorator is the registration (`declarations/role-declared`): `@CommandHandler(Message)`, `@QueryHandler(Message)`, `@DomainEventHandler(Event)` (the name is the static `eventName` of the event class), `@IntegrationEventHandler(definition, { consumer })`, `@Scheduled('<context>.<job>', schedule)`, `@Background(options)` (the name is the static `jobName`), `@Projection('<context>.<name>')`, `@Policy(permission, { name })`. Names are string literals.
 - The constructor is the one statement of what a class depends on (`declarations/constructor-injection`): each parameter is typed by one port class, with no `?`, default value, rest or destructuring, and no list repeats it in the decorator. To add a dependency, add the parameter: `npx ddd-ts-kit docs` reads the signature into the generated file of the context (`npm run dev` does it on every change), never edit that file.
 {{/if}}
 {{#if style.explicit}}

package/templates/integration-event/publisher.declared.ts.tpl

@@ -3,7 +3,7 @@ import { DomainEventHandler } from '@ddd-ts-kit/kernel/declarations';
 import { {{event.pascal}} } from '{{alias.context}}/domain/events/{{event.kebab}}.event{{alias.ext}}';
 import { {{event.camel}}V{{event.version}} } from '{{alias.context}}/published-language/{{event.kebab}}.v{{event.version}}.integration-event{{alias.ext}}';
 
-@DomainEventHandler({{event.pascal}}, { name: {{event.reference}} })
+@DomainEventHandler({{event.pascal}})
 export class {{publisher.pascal}}Publisher implements DomainEventHandler<{{event.pascal}}> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/pipeline/github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,26 @@
+name: Copilot setup steps
+
+# The environment the Copilot cloud agent starts in: Node and the dependencies of the lockfile,
+# so that the checks and the generators of the kit answer at once. Copilot reads this file from
+# the default branch, and only a job of this name; the runs below check it when it changes.
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/setup

package/templates/pipeline/package-scripts.json

@@ -23,7 +23,7 @@
     "@biomejs/biome": "2.5.15",
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
-    "@ddd-ts-kit/eslint-plugin": "^0.17.0",
+    "@ddd-ts-kit/eslint-plugin": "^0.18.0",
     "@eslint/js": "^10.0.1",
     "@typescript/native": "npm:typescript@~7.0.2",
     "@vitest/coverage-v8": "5.0.3",

package/templates/presets/identity/context/application/integration/publishers/account-deactivated.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { AccountDeactivated } from '{{alias.context}}/domain/events/account-deac
 import { accountDeactivatedV1 } from '{{alias.context}}/published-language/account-deactivated.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(AccountDeactivated, { name: AccountDeactivated.eventName })
+@DomainEventHandler(AccountDeactivated)
 export class AccountDeactivatedPublisher implements DomainEventHandler<AccountDeactivated> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/delegation-granted.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { DelegationGranted } from '{{alias.context}}/domain/events/delegation-gr
 import { delegationGrantedV1 } from '{{alias.context}}/published-language/delegation-granted.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(DelegationGranted, { name: DelegationGranted.eventName })
+@DomainEventHandler(DelegationGranted)
 export class DelegationGrantedPublisher implements DomainEventHandler<DelegationGranted> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/delegation-revoked.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { DelegationRevoked } from '{{alias.context}}/domain/events/delegation-re
 import { delegationRevokedV1 } from '{{alias.context}}/published-language/delegation-revoked.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(DelegationRevoked, { name: DelegationRevoked.eventName })
+@DomainEventHandler(DelegationRevoked)
 export class DelegationRevokedPublisher implements DomainEventHandler<DelegationRevoked> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-joined.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberJoined } from '{{alias.context}}/domain/events/member-joined.even
 import { memberJoinedV1 } from '{{alias.context}}/published-language/member-joined.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberJoined, { name: MemberJoined.eventName })
+@DomainEventHandler(MemberJoined)
 export class MemberJoinedPublisher implements DomainEventHandler<MemberJoined> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-removed.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberRemoved } from '{{alias.context}}/domain/events/member-removed.ev
 import { memberRemovedV1 } from '{{alias.context}}/published-language/member-removed.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberRemoved, { name: MemberRemoved.eventName })
+@DomainEventHandler(MemberRemoved)
 export class MemberRemovedPublisher implements DomainEventHandler<MemberRemoved> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/member-role-changed.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { MemberRoleChanged } from '{{alias.context}}/domain/events/member-role-c
 import { memberRoleChangedV1 } from '{{alias.context}}/published-language/member-role-changed.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(MemberRoleChanged, { name: MemberRoleChanged.eventName })
+@DomainEventHandler(MemberRoleChanged)
 export class MemberRoleChangedPublisher implements DomainEventHandler<MemberRoleChanged> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/presets/identity/context/application/integration/publishers/organisation-opened.publisher.ts.tpl

@@ -4,7 +4,7 @@ import { OrganisationOpened } from '{{alias.context}}/domain/events/organisation
 import { organisationOpenedV1 } from '{{alias.context}}/published-language/organisation-opened.v1.integration-event{{alias.ext}}';
 
 /** Tells the other contexts, through the outbox, in the transaction of the fact. */
-@DomainEventHandler(OrganisationOpened, { name: OrganisationOpened.eventName })
+@DomainEventHandler(OrganisationOpened)
 export class OrganisationOpenedPublisher implements DomainEventHandler<OrganisationOpened> {
   constructor(
     private readonly publisher: IntegrationEventPublisher,

package/templates/query/handler.declared.ts.tpl

@@ -1,13 +1,32 @@
+{{#if access.policy}}
+import type { Access } from '@ddd-ts-kit/auth';
+{{/if}}
 import { QueryHandler } from '@ddd-ts-kit/kernel/declarations';
+{{#if access.policy}}
+{{access.useCasePermissionsImport}}
+{{/if}}
 import type { {{name.pascal}}Reader } from '{{alias.context}}/application/ports/{{name.kebab}}-reader.port{{alias.ext}}';
 import { {{name.pascal}}Query } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.query{{alias.ext}}';
 import type { {{name.pascal}}Result } from '{{alias.context}}/application/queries/{{name.kebab}}/{{name.kebab}}.result{{alias.ext}}';
 
 @QueryHandler({{name.pascal}}Query)
 export class {{name.pascal}}Handler implements QueryHandler<{{name.pascal}}Query> {
+{{#if access.policy}}
+  constructor(
+    private readonly reader: {{name.pascal}}Reader,
+    private readonly access: Access,
+  ) {}
+{{/if}}
+{{#unless access.policy}}
   constructor(private readonly reader: {{name.pascal}}Reader) {}
+{{/unless}}
 
   async execute(query: {{name.pascal}}Query): Promise<{{name.pascal}}Result> {
+{{#if access.policy}}
+    // TODO(domain): a policy refines {{access.reference}}: ask it about the element "{{name.words}}" reads once it is read, in place of `query`.
+    await this.access.authorize(query.actor, {{access.reference}}, query);
+
+{{/if}}
     // TODO(domain): narrow what is read to what the asker may see: ask `Access.scope(query.actor, permission, '<type>')` for the scope and hand it to the reader, never filter in memory after loading; a query never changes state.
     return this.reader.read(query);
   }