Which command, when
Summary. The commands of the CLI and the skills of the plugin, by the moment of a project's life when they are called: what each does, what it leaves behind, and what usually comes next. The order of the moments is the order of the methodology, which is the supported path; this page says how to walk it. The last part is the reference of every command and flag, generated from the help of the CLI.
Commands are written for npm. On pnpm, npx ddd-ts-kit reads pnpm exec ddd-ts-kit and
npm run reads pnpm run. A skill is typed in Claude Code with the plugin installed:
/ddd-ts-kit:<skill>; the agent also uses most of them on its own when the situation matches.
The sections below follow these moments. Most of the time is spent in the loop from Build a slice to Before a pull request, one slice per turn of the loop.
A first feature, from zero
Section titled “A first feature, from zero”The realistic sequence for an order-taking service, each line in the order it is typed:
| # | Command | Leaves |
|---|---|---|
| 1 | /ddd-ts-kit:start We take orders from shops and bill them monthly |
docs/architecture/plan.md, then discovery.md, contexts.md, the glossary and the context map, one step per turn, each closed on your yes |
| 2 | /ddd-ts-kit:bootstrap (or npx ddd-ts-kit init, npm install, npm run verify) |
the project, green before any business code |
| 3 | npx ddd-ts-kit generate context ordering --classification core --term "Order=A shop's request to buy products" --term "Place=To submit an order" |
src/contexts/ordering/ and its CONTEXT.md with the glossary |
| 4 | /ddd-ts-kit:plan-slices |
docs/architecture/slices.md: PlaceOrder first |
| 5 | /ddd-ts-kit:use-case PlaceOrder, which runs generate aggregate ordering Order, generate repository ordering Order, generate command ordering PlaceOrder --permission order.place --aggregate Order --creates, generate route ordering PlaceOrder --method POST --path /orders, generate e2e ordering PlaceOrder |
the files, their specs and fakes, and the TODO(domain) places to fill |
| 6 | npx ddd-ts-kit todo ordering |
what is left to write in the slice, as file:line |
| 7 | npm run db:generate place-order, npm run docs:generate |
the migration of the new table, the OpenAPI contract with POST /orders |
| 8 | /ddd-ts-kit:quality-gate, that is npm run verify |
a green gate |
| 9 | /ddd-ts-kit:commit-discipline |
one commit for the slice, generated files with it |
| 10 | npx ddd-ts-kit status |
the next slice of the plan |
Line 5 is where the generators do the typing. With Drizzle chosen at init, the five commands
it runs write these files, each in its layer:
None of these files holds business code yet. Most of them hold TODO(domain) markers where a
decision is left to you; three come wired and hold none (the route group orders.routes.ts, the
permissions ordering.permissions.ts and the adapter drizzle-order.repository.ts). The
generated specs hold it.todo entries. Line 6 lists them, one
line each, in the order of the files:
$ npx ddd-ts-kit todo orderingsrc/contexts/ordering/CONTEXT.md:5 TODO(domain) say in two sentences which business capability this context owns and for whom; the first sentence is reused in the context map.src/contexts/ordering/application/commands/place-order/place-order.command.ts:7 TODO(domain) declare the input of "place order" as a constructor with the actor first, then readonly primitives and ids, ...src/contexts/ordering/application/commands/place-order/place-order.handler.ts:16 TODO(domain) decide what "place order" does to a Order: ...src/contexts/ordering/domain/aggregates/order.aggregate.ts:19 TODO(domain) record the fact Order is born with at `now`, the instant the handler takes from its Clock: `ddd-ts-kit generate domain-event ordering Order <Fact>` writes the event, then ......src/contexts/ordering/test/unit/order.aggregate.spec.ts:30 it.todo records the fact of its birth...The slice is finished when todo ordering no longer lists anything of it.
The route reads the command it calls: fill the constructor of PlaceOrderCommand before
generate route, and the route writes its body schema, the call
new PlaceOrderCommand(request.actor, request.body.customerId, ...) and a spec that sends a valid
body from those fields, a string, a number or a boolean each (a path parameter is read from the
path). A field of another type, the readonly string[] of the products for one, stays a
TODO(domain) of the schema and of the call.
Start a project
Section titled “Start a project”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:start |
conducts steps 1 to 7 of the method, one per turn, and resumes from the plan | first, before any code; again to resume | docs/architecture/plan.md and the artefact of each step |
the step its Next: line names |
/ddd-ts-kit:bootstrap |
chooses the stack by criteria, runs init, creates the contexts |
step 5, once the context map is drafted | the project and one CONTEXT.md per context |
/ddd-ts-kit:plan-slices |
npx ddd-ts-kit init [flags] |
writes the config, the platform, the pipeline, the agent rules; run again, it keeps the recorded stack: an invalid flag value is refused, a flag that differs from the record is noted and kept (init --force changes it) |
the bootstrap; --dry-run first to read what it writes |
a project that passes npm run verify |
npm install, npm run verify |
npx ddd-ts-kit init --preset identity, generate context <name> --preset identity |
writes a generic context whole instead of an empty one: accounts from the identity provider, organisations, members and roles, invitations, delegations (why and which) | when contexts.md holds a generic identity context |
the context, its specs, its adapters and its glossary, green at once | read its ## Design, then the slices of the core |
npx ddd-ts-kit status |
the next step of the plan, the slices by status and owner, what is left per context | at the start of every session | a short text, --json for data; a merge left in progress is its first line |
the step or slice it names, or merge-trunk --continue or --abort |
Model the domain
Section titled “Model the domain”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:discover-domain |
a written event storming: actors, commands, events, policies, read models | step 1 | docs/architecture/discovery.md |
/ddd-ts-kit:bounded-contexts |
/ddd-ts-kit:bounded-contexts |
finds and classifies the contexts, with the reason of each boundary | step 2 | docs/architecture/contexts.md |
/ddd-ts-kit:glossary |
/ddd-ts-kit:glossary |
the ubiquitous language of a context | step 3, and before any new name | docs/architecture/glossary.md, then ## Ubiquitous language of each CONTEXT.md |
/ddd-ts-kit:context-map |
/ddd-ts-kit:context-map |
upstream, downstream, pattern and contract of each pair | step 4, and when two contexts start depending on each other | docs/architecture/context-map.md, then the upstreams of the config |
the bootstrap, or the slice that needs it |
npx ddd-ts-kit generate context <name> --classification <c> --reason "..." --term "<Term>=<meaning>|<not to be confused with>" ... --upstream ... |
declares a context with its language, the sentence of why it is of its classification, and its relationships; on a context that exists, declares each --upstream it does not declare yet, refusing one that closes a cycle |
after the bootstrap, one per row of contexts.md, upstreams first |
the context directory, its CONTEXT.md, the config entry |
npx ddd-ts-kit docs |
npx ddd-ts-kit list, describe <context> |
what exists, per context or for one | before planning or changing a context | a map of the contexts, or one as facts (--json) |
/ddd-ts-kit:plan-slices |
npx ddd-ts-kit generate module <context> <module> --purpose "..." [--term ...] |
declares a module of the model: the config entry, its row of ## Modules in CONTEXT.md, its terms, and in the explicit style its module file <module>/<module>.module.ts, composed by <context>.module.ts; re-runnable, it adds what is missing |
when one context holds clusters of concepts of one language that a reader opens separately; never to hide a second language | the module, declared and documented | move-to-module, then generate ... --module |
npx ddd-ts-kit move-to-module <context> <module> <path>... [--dry-run] [--allow-cycle] |
moves files and folders of the layers of a context, and its specs, fakes and builders, into a declared module (<module>/<layer>/, <module>/test/), with every import of them in the project; writes nothing when the move would close a cycle between modules that is not there now, and names the cycle and the file to move along, unless --allow-cycle |
one cluster per commit, until module/complete warns no more |
the moved files and the rewritten imports | npm run verify |
Build a slice
Section titled “Build a slice”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:story <code> [<statement>] |
one user story from its questions to a green pull request, in its own worktree: questions first, then specification, rows, design review, acceptance, build, review, report (story workflow) | once the project is bootstrapped, one terminal per story | the pull request of the story and its report | review the report, validate each provisional decision |
npx ddd-ts-kit story-scope <code> |
the worktree of a story on story/<code>, its .ddd-ts-kit/story.json and its install; the other open stories and their contexts |
the first step of the story skill | .worktrees/<code> |
npx ddd-ts-kit story <code> |
npx ddd-ts-kit stories |
the stories open in the worktrees of the repository and where two of them meet: the contexts both name, the files both change, what merging one into the other leaves to settle by hand, how far each is behind its trunk | before cutting the rows of a story and before each row, after git fetch |
a short text, --json for data; exits 0 |
keep off what another story changes, or record which one lands first |
npx ddd-ts-kit worktree <name> |
the worktree of any piece of work that is neither a story nor a worker: .worktrees/<name> on work/<name> cut from origin/main, installed |
before writing the code of a context from the main checkout of the trunk, which the guard refuses in a project init created |
the worktree, its branch and its install | work there, commit, open its pull request |
npx ddd-ts-kit story [<code>] [--gate build|close] |
the phases of a story and the next step; build opens its code, close its pull request |
at any time in the worktree of a story | a short text, --json for data; exits 1 while the gate is not met |
do the next step |
npx ddd-ts-kit digest --base <ref> |
what the branch changes, for its reviewer: per context the use cases, permissions and the roles that hold them, routes and their error codes, events and ports added, changed or removed since the merge base; the new spec titles; the files to review in reading order, the generated ones apart | at the close of a story, into ## Report; at the top of its pull request |
about thirty lines of Markdown, --json for data; exits 2 outside git or on an unknown ref |
the reviewer reads it before the diff |
/ddd-ts-kit:plan-slices |
the work as vertical slices, ordered, with their generator commands | step 6, after the bootstrap | docs/architecture/slices.md |
/ddd-ts-kit:use-case |
npx ddd-ts-kit cited --rows <id> --base origin/main |
the names the design of a row cites as code that the trunk does not have: removed by its history (with the commit and what replaced them), refused by the canonical tree, or close to a name it gained since the line was written; planned names stay silent | before building a row alone, before committing a design review | one line per name, --json for data; exits 0 |
build on what the trunk has, and correct the document on the trunk |
npx ddd-ts-kit generate acceptance <story>, then npx ddd-ts-kit acceptance <story> --lock |
the acceptance spec of a story, one it.todo per criterion of docs/architecture/stories/<story>.md, to write as scenarios wrapped in pending(...); the lock records them, after which a scenario changes only with its criterion, and a criterion or a scenario whose criteria stayed only with a verdict of the acceptance-judge agent |
before the first row of code of a story | test/acceptance/<story>.acceptance.spec.ts and its .lock.json |
npx ddd-ts-kit acceptance <story> --gate written, then the rows |
npx ddd-ts-kit acceptance [<story>] [--gate written|passing] |
the scenarios of each story against its rows and criteria: left to write, pending, drifted from the lock, inconsistent, and the amendments to validate | before the code of a story (written), before closing it (passing) |
a short text, --json for data; exits 1 while the gate is not met |
write, lock, build, or report the amendments |
/ddd-ts-kit:use-case <UseCase> |
one slice end to end, test first | for each row of the slices | domain, handler, route and specs, filled | npm run verify |
npx ddd-ts-kit generate <kind> ... |
one file of a role with its spec, fake and registration (list below); --module <module> writes into a module of the model, and is required in a context that declares modules |
whenever a file of a role is needed, never by hand | the file and the TODO(domain) places, --json for the list |
fill the places, then todo |
npx ddd-ts-kit todo [<context>] |
each TODO(domain), TODO(platform), it.todo and TODO(review) left, in the code, the pages, the files of prisma/schema/ (under the context of the file or of the model), the migrations and the configuration at the root |
before closing a slice, a story or a milestone | file:line entries, with their first words only under --brief |
write them, then npm test; settle each TODO(review) or dismiss it with generate adr before the story or milestone is closed |
npx ddd-ts-kit story-check <code> [--strict] |
whether a story or a milestone (M1 for the rows M1.*) can close: every row done, no marker of its own left, a marker being its own when its text, the commit that wrote it or the worker holding it names one of its rows, or when it belongs to no row in a context no other open story works in |
before a story or a milestone is declared closed; status names one whose rows are done while markers keep it open |
one line when it can close; else each blocker with why it is the story's, its file:line and its fix, then the unattributed markers it lists without blocking; exits 0, 1, or 2 on an unknown code |
handle each blocker or dismiss it with generate adr, then delete the marker; name the row in an unattributed one (TODO(review): #M1.03 ...) |
npx ddd-ts-kit measures [--since <date>] [--story <code>] |
what the loop of each story cost and left, from git and docs/architecture/: design, build and lead time, the requirements changed after the build started, the provisional decisions, the compromises, the review markers settled and the findings repeated across stories, the verification, the stories built at the same time, the origin, the incidents repeated; then the medians of the period; --by-author only when the team agreed on it |
once a month, by whoever tunes the setup; before a retrospective | one line per story and the medians, --json for a dashboard; exits 0 |
a repeated remark becomes a line of AGENTS.md or a rule of the config; a long design time, a question asked earlier |
/ddd-ts-kit:parallel-work |
splits the slices between workers, one context each | when several agents or people build at once | a briefing per worker, npx ddd-ts-kit worker-scope <context> worktrees, with the documents of each row's design and the names they cite the trunk does not have |
each worker's use-case |
npx ddd-ts-kit status --workers |
each worker's worktree, branch, context, rows and commits ahead, its state (rows committed, row under way, last verify-slice), the files it changed, and the files two workers change | before briefing a second worker in a context, before each merge | a short text, --json for data |
other rows for the new worker, the merge order, or --resume for a stopped one |
npx ddd-ts-kit worker-scope <context> --resume |
where a stopped worker stands (rows by their Slice: trailer, files of the row under way, markers, last verify-slice, report, agent), read without changing anything |
on a stop notification of a context-builder (turn limit, error, a person) |
the SendMessage text for its agent, or the briefing of a new one | send it as it is |
Connect two contexts
Section titled “Connect two contexts”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:integration-event |
a versioned event in the producer's published language, its consumer downstream | a context must react to another | the declaration, the outbox publication, an idempotent handler | npm run docs:generate |
npx ddd-ts-kit generate integration-event <context> <Aggregate> <Fact> |
declares the event | in the upstream slice | published-language/*.integration-event.ts and its payload |
generate integration-handler downstream |
npx ddd-ts-kit generate integration-handler <context> <upstream> <eventType>[@v<n>] |
the consumer, named after the event, or as the design calls it with --name <Name> (the consumer name follows) |
in the downstream slice | the handler, its spec, its registration | npm run docs:generate |
npx ddd-ts-kit generate acl or gateway |
an anti-corruption layer, or a synchronous need behind a port | a downstream that must not take the upstream's model | the port and its adapter | the context map note |
Persistence
Section titled “Persistence”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:persistence |
repository port, ORM adapter, mapper, fake, contract suite | a new aggregate, table or read model | the adapter and its specs | npm run db:generate <what-it-does> |
npx ddd-ts-kit generate repository <context> <Aggregate> |
the port, the in-memory fake and the ORM adapter | with the first slice of an aggregate | the files and the table of the schema to fill | npm run db:generate <what-it-does> |
npm run db:generate <what-it-does> |
a migration from the schema, named <timestamp>_<what-it-does> |
after a change of the schema | migrations/ (prisma/migrations/ on Prisma) |
npm run db:migrate, npm run check:arch |
npm run infra:up, npm run db:migrate, npm run dev |
the database in Docker, migrated, the application with reload | to see it run | a running API, its documentation on /docs |
npm run test:e2e |
Before a commit
Section titled “Before a commit”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
npx ddd-ts-kit verify-slice <context> --since <ref> |
in one run: npm run regenerate, the architecture rules on the files changed since the ref (new ones included), the tests of the context, the merges since the ref (as verify-merge checks them, reported without failing the slice in this version), the changed files near the 350-line limit |
before the commit of a slice, again until it passes | each step with its cause, then the paths of the slice to stage (with the pages of docs/behaviour/ and the schema of the ORM the generator changed for its context alone), every other changed path, left out and never staged with it, and the names the slice removes that the design of a row not done still cites (never a failure) |
the commit of the slice, of the paths it lists to stage only; those names go to the conductor as notes |
npx ddd-ts-kit check --changed-since <ref> |
the architecture rules on what changed, and on the findings a changed file causes in another (a handler no changed module file registers) | while iterating | violations with their fix, then, with --explain, the reason of each rule reported, once |
npx ddd-ts-kit explain <rule-id> when one is unclear |
npm run regenerate (npx ddd-ts-kit depcruise-config --write, then npm run docs:generate, which runs npx ddd-ts-kit docs) |
regenerate every derived file: .dependency-cruiser.cjs, the context map, the CONTEXT.md lists, the barrels and the contracts |
after a change of a route, a schema, an event or the config | the generated files, committed with the code | /ddd-ts-kit:commit-discipline |
/ddd-ts-kit:commit-discipline, npx ddd-ts-kit check --commit-size --staged |
one slice per commit, its size against the config | before git commit (the hook runs the check) |
a message <type>(<context>): ... |
the next slice |
Before a pull request
Section titled “Before a pull request”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
/ddd-ts-kit:quality-gate, npm run verify |
every gate of the pipeline, fixed at the root cause | before opening the pull or merge request | a green gate | the request |
npx ddd-ts-kit merge-trunk |
brings the trunk into the branch as one merge commit computed from the branch's own diff (from where it landed after a squash): derived files, the package.json of each client (at the higher of both versions), generated regions and registries, slices.md rows, drizzle meta, the lockfile and the stored-events lock settled, migrations replayed (renamed with --to-land), decision records renumbered, regenerate (and db:client on Prisma when the merge changed a schema), then verify-merge on the result |
a worker: to bring the trunk in, never git merge alone; the conductor: --to-land --cwd <worktree> just before the squash merge |
one merge commit with Merge-Base:, Trunk: and Landed: trailers; or a merge in progress with each hunk left, what each side did there, exit 1 |
resolve each hunk, git add, merge-trunk --continue (--accept-lost for a removal decided on purpose, --abort to undo, which restores the derived files it regenerated; --continue says when the trunk moved since the merge started), then npm run verify |
npx ddd-ts-kit verify-merge |
what the merges of the branch lost, read from git alone: a line one side added, a row done, a test, a spec file, a migration, a conflict marker | merge-trunk runs it before its commit; after a merge made otherwise, or of a squash with --theirs <head>; the pre-push hook (--warn) and verify-slice run it too, as a warning in this version: a later minor version blocks |
the findings of each merge, with file:line and the side that held them; nothing without a merge; exit 1 on an error, 0 with --warn |
restore each one from its side, or record a removal decided on purpose with a Lost-Accepted: <file:line> trailer (merge-trunk writes <file>@<side>#<hash> for a line its settle of a Drizzle index takes out, and names the lines it writes there in Kit-Written:; on TypeORM it writes no name) |
npx ddd-ts-kit affected --base origin/main |
the contexts a change reaches through the context map | in the pipeline; locally to see what it will run | filters for the tests and the linter | the pipeline |
agent architecture-reviewer |
a read-only review of the diff against the rules | before merging a slice | findings with file and line | fixes, then merge |
Release and deploy
Section titled “Release and deploy”| Command | Does | When | Produces | Then |
|---|---|---|---|---|
npm run build, npm start |
compiles, rewrites the aliases of dist/, runs it with plain Node |
to ship | dist/ |
the image |
docker build --pull . |
the image of the Dockerfile that init wrote, on the newest node base image rather than the one the machine already holds (the pipeline builds it without pushing) |
to ship | an image | npm run db:migrate against the target database, then the deployment |
npx ddd-ts-kit sdk (or init --sdk) |
generates the typed client of each document of the contract under clients/<document>, wires its scripts, and keeps it current (docs:generate runs it, docs:check compares it) |
when another team, a front end or a test calls the API | one workspace package per document, built by npm run sdk:build |
npm publish --workspace clients/<document> by hand, see the client SDK |
npx ddd-ts-kit generate worker, generate service <context> |
a process for the jobs, or one context run alone | when the jobs or one context must scale apart | src/apps/<name>/main.ts |
/ddd-ts-kit:extract-service |
Migrate after a kit upgrade
Section titled “Migrate after a kit upgrade”| Command | Does | When | Produces | Then |
|---|---|---|---|---|
read CHANGELOG.md, also shipped as node_modules/ddd-ts-kit/CHANGELOG.md |
what changed and what to do | before upgrading, or when the session start says the plugin describes another version | the steps of the version | update the @ddd-ts-kit/* and ddd-ts-kit versions together |
commit, then npx ddd-ts-kit init --force |
rewrites the files init owns, keeps the config, records its version as initVersion and wires the contexts again. What the generators and the team wrote in those files stays: what each ddd-ts-kit:* region holds (a value of a gateway, the settings of a job, a policy, a hand-written fake), the grants of roles.ts and the role vocabulary, the database schemas and preview features of the Prisma datasource, the services of docker-compose.yml; the tables, the audited events and the read model stores a region does not hold are listed again from the tree (a read model store joins the list of read-model-tables.ts, with or without --force; one whose constructor is not the generated one is named in a note and among those the start warns of). At the same version git diff is empty. What it cannot keep is named in a note, file by file, with the command that writes it again: a region this version no longer holds, a marker left without its partner, a roles object it cannot read to its end, which it leaves out whole, the repositories left on the ORM a flag changed. Keeps README.md, AGENTS.md, CLAUDE.md, src/main.ts, the pipeline, the Drizzle journal migrations/meta/_journal.json and the tables the tests on a server keep their rows of (test/support/test-database-kept.ts) as the team's, merges .gitignore and .dockerignore; refuses, exit 2, while a file it would replace differs from the last commit |
after the upgrade, on a clean working tree | the platform files of the new version, the files it kept, and notes | git diff, then npm run verify |
npx ddd-ts-kit controllers, error-factories --plan then --apply, value-objects |
moves function routes to controllers, error classes to factories, value objects from a Result to factories that throw |
when the project adopts those forms | the rewritten files and the config key | npx ddd-ts-kit docs, npm run verify |
npx ddd-ts-kit platform-folders [--place <file>=<folder>]... [--dry-run] |
moves the files of src/platform/ a project generated flat to their folders (composition/, observability/, jobs/, auth/authentication/, auth/authorization/, the folder of the model, audit/search-audit-entries/), with every import of them and the scripts of package.json |
when doctor reports folder src/platform: flat; the generators and init --force keep the flat layout until then |
the moved files, the rewritten imports, the files of the team it left flat | npm run format, npm run verify |
npm run regenerate |
regenerate what derives from the config | after any change of the config | .dependency-cruiser.cjs, the generated documents |
npm run verify |
When something is refused
Section titled “When something is refused”| Command or skill | Does | When | Produces | Then |
|---|---|---|---|---|
npx ddd-ts-kit explain <rule-id> |
the reason of a rule and one example each way | a violation is not clear | the explanation | fix the cause |
npx ddd-ts-kit check-file <path>, rules |
one file checked; every rule id | after an edit; to look a rule up | violations; the list | fix the cause |
generate ... --term "<Term>=<meaning>" |
adds the missing word to the glossary as it generates | the generator refuses a name outside the glossary | the term in CONTEXT.md |
/ddd-ts-kit:glossary if the meaning is unsure |
/ddd-ts-kit:deviation, npx ddd-ts-kit generate adr "<title>" --deviation <what> --reason "<why>" |
puts the exception to the owner and records it | only when the owner agrees to go around a rule | a decision record and the config entry | npm run verify |
Every refusal says what to do next. The generator refuses a name the glossary of the context does not hold, and writes nothing:
$ npx ddd-ts-kit generate command ordering CancelOrder --permission order.cancel --aggregate Ordererror: "CancelOrder" uses "cancel", which the glossary of src/contexts/ordering/CONTEXT.md does not define. fix: Either use an existing term (Order, Place), or add the term in the same command: --term "Cancel=<what it means for the business>". The glossary is written before the code (rule language/glossary-term).so the same command, with the meaning of the word, goes through:
npx ddd-ts-kit generate command ordering CancelOrder --permission order.cancel --aggregate Order \ --term "Cancel=To withdraw an order before it is shipped"The generator also refuses, before it writes, what the checker would report afterwards. A query named
List... is refused: a read that takes criteria is a Search<Things>
(generate query <context> SearchInvoices --search --permission <aggregate>.<action>). A fact that starts with its
aggregate is refused by generate domain-event: generate domain-event ordering Order "Order Confirmed" would write
OrderOrderConfirmed, so give Confirmed (--allow-name lets a name through that is right as typed). --birth and
--event-sourced apply when the aggregate is created: on one that exists, the aggregate is kept, the event is not
written, and a note: says so.
The checker reports a violation with its rule id and a fix sentence. Here, a file of the
notification context of the example application imports an aggregate of scheduling:
$ npx ddd-ts-kit check-file src/contexts/notification/application/commands/probe.tssrc/contexts/notification/application/commands/probe.ts:1 error context/published-language-only "notification" imports the internals of "scheduling" (src/contexts/scheduling/calendars/domain/aggregates/appointment.aggregate.ts). fix: Import from src/contexts/scheduling/published-language only; if the type is missing there, publish it with `ddd-ts-kit generate integration-event scheduling <Aggregate> <Fact>` or react to an integration event.
1 error, 0 warnings, 0 suppressions in 1 file.and explain gives the reason of the rule, with one example each way:
$ npx ddd-ts-kit explain context/published-language-onlycontext/published-language-only
A file imports from another context only through that context's published-language/.
Why: A bounded context owns its model and must be free to change it. The published language is the only part designed for others; importing anything else couples two models and turns every refactoring into a cross-team negotiation.
Bad: // contexts/shipping/application/... import { Invoice } from '@/contexts/billing/domain/aggregates/invoice.aggregate';
Good: // contexts/shipping/application/... import type { InvoiceIssuedV1 } from '@/contexts/billing/published-language';
Suppress one line (with a reason): // ddd-ts-kit-disable-next-line context/published-language-only -- <reason>The last line is the suppression the checker accepts; using it is a deviation, which takes the owner's agreement and a decision record (the last row of the table above).
Reference
Section titled “Reference”Every command and flag, as npx ddd-ts-kit --help prints them. A test of the CLI fails when a
command or a flag is added without this part being regenerated. npx ddd-ts-kit <command> --help
prints the part of one command (its usage lines, its note and the notes of its flags), and
npx ddd-ts-kit generate <kind> --help one kind.
Exit codes: 0 success; 1 violations, a gate not met, stale documentation; 2 wrong usage or a
refusal (the message says what to do); 3 a command that writes files (init, generate,
docs, sdk, a move) could not write some of them where it ran, such as the paths the sandbox of
an agent protects. With 3 the report lists them under unwritable (and in skipped), a dry run
included; every other file is written and none is deleted. Run the same command where they can be
written, outside the sandbox: init gives the command in a note. 3 is also the code of generate
and of init --force when they leave the schema index (src/platform/database/schema.ts) as it
stood: what they would write there would lose a value a file exports by name and the index exports
under that name or another, or give that name to another table (a name exported as a type only, and
a default export re-exported, are not compared), which is judged only when everything the index
re-exports is read with certainty, or (init --force) the part of the index outside the regions
holds a line the kit does not read with certainty and the rewrite would drop it. The report lists
the index under left (and in skipped, never in updated), one note says why and what to do, and
it is a person who does it. While a file the index re-exports, or the index itself, is not read with
certainty, a name lost or a name moved never leaves the index: the command exits 0 and writes what
it wrote before, one note says which names may be shared and who keeps them, and each name no line
the kit reads exports after the command, and each name that may name another table, is said with
that doubt while the index still names what is not read after the command, and plainly when it does
not; the kit compares the names the index exports, not the tables behind them. 4 is an internal
error of the kit, never a mistake of the caller: one line with the version of the kit and where to
report it (under --json, an error with "internal": true); report it at
https://github.com/ddd-ts-kit/ddd-ts-kit/issues with the command it gives.
Under --json, a refusal is {"error": {"message": "...", "fix": "..."}}. The refusal of
move-to-module that would close a cycle between modules adds to it what a script reads without
parsing the sentences: cycles, each with its modules in order and its steps (from, to,
added for a step the move adds, and imports, each with file, line and imported, the paths
as they are before the move), and along, the files or folders to name in the same command,
relative to the context. With --allow-cycle the same cycles are in the report of the move.
Usage ddd-ts-kit init [--http express|fastify|hono|nest|none] [--validation zod|class-validator|typebox|standard-schema|none] [--di tsyringe|inversify|awilix|nest|manual] [--tests vitest|jest] [--orm drizzle|knex|prisma|typeorm|custom|none] [--database postgres|mysql|sqlite|none] [--events in-memory|outbox] [--docs-ui swagger|scalar|redoc|none] [--ci github|gitlab|both|none] [--ci-extras <extra>,...|none] [--authn jwt|keycloak|passport|none] [--authz rbac|abac|rebac|custom] [--broker none|rabbitmq|kafka|nats|redis|custom] [--cache none|redis] [--http-cache none|varnish] [--rpc none|orpc|trpc] [--storage local|s3|none] [--search none|opensearch] [--audit on|off] [--event-sourcing on|off] [--privacy on|off] [--errors none|sentry] [--logger stdout|pino|winston] [--style declared|explicit] [--assembly barrel|discovery] [--dependencies signature|listed] [--refusals named|factories|classes] [--routes controllers|functions|nest] [--representations negotiated|json] [--forms on|off] [--value-objects throwing|result] [--literals named|free] [--values classes|free] [--tenancy none|shared-table] [--queue database|redis|memory] [--schemas shared|per-route] [--package-manager npm|pnpm] [--allow-no-outbox "<reason>"] [--import-alias '$<name>/'] [--import-extension none|js] [--sdk] [--agent-profile regulated|none] [--context <name>:<core|supporting|generic>]... [--preset identity]... [--dry-run] [--force] ddd-ts-kit generate <kind> ... [--allow-name] [--local-only] [--dry-run] [--force] (alias: g) ddd-ts-kit generate [<kind>] --help [--json] ddd-ts-kit list [--context <name>] ddd-ts-kit describe <context> ddd-ts-kit status [--workers | --ready] ddd-ts-kit doctor [--strict] ddd-ts-kit todo [<context>] [--brief] ddd-ts-kit plan-waves [<context>] [--ready] ddd-ts-kit story-check <code> [--strict] ddd-ts-kit acceptance [<story>] [--gate written|passing] [--lock] ddd-ts-kit worker-scope <context> [--base <ref>] [--rows <id,...>] [--worktree <path>] [--branch <name>] [--no-install] [--dry-run] ddd-ts-kit worker-scope <context> --resume [--worktree <path> | --branch <name>] [--fresh] ddd-ts-kit worker-scope <context> --here [--rows <id,...>] [--base <ref>] [--dry-run] ddd-ts-kit story-scope <story> [--from <file>] [--kind story|fix] [--base <ref>] [--worktree <path>] [--branch <name>] [--no-install] [--dry-run] ddd-ts-kit story [<story>] [--gate build|close] ddd-ts-kit stories ddd-ts-kit digest --base <ref> [--json] ddd-ts-kit measures [--since <date>] [--story <code>] [--by-author] [--format text|json] ddd-ts-kit mutation [--report <file>] [--survivors] [--changed <ref>] [--json] ddd-ts-kit worktree <name> [--base <ref>] [--branch <name>] [--no-install] [--dry-run] ddd-ts-kit verify-slice <context> --since <git-ref> ddd-ts-kit cited [<context>] [--rows <id,...>] [--base <ref>] [--removed-since <ref>] ddd-ts-kit verify-merge [<commit>] [--since <git-ref>] [--theirs <git-ref>] [--base <commit>] [--warn] ddd-ts-kit merge-trunk [--trunk <git-ref>] [--since <commit>] [--to-land] [--dry-run] ddd-ts-kit merge-trunk --continue [--accept-lost] | --abort ddd-ts-kit docs [--check] [--dry-run] [--stored-events] [--behaviour] ddd-ts-kit sdk [--check] [--dry-run] ddd-ts-kit depcruise-config [--check|--write] ddd-ts-kit tsc <arguments of tsc> ddd-ts-kit build-aliases [--project <tsconfig>] ddd-ts-kit drizzle-generate --name <what-it-does> [--custom] ddd-ts-kit drizzle-generate --replay [--base <git-ref>] ddd-ts-kit knex-generate --name <what-it-does> [--custom] ddd-ts-kit prisma-client [--schema <path>] ddd-ts-kit prisma-generate --name <what-it-does> ddd-ts-kit typeorm-generate <folder>/<what-it-does> ddd-ts-kit error-factories --plan | --apply [--to named|factories] [--dry-run] ddd-ts-kit controllers [<context>] [--dry-run] ddd-ts-kit value-objects [--dry-run] ddd-ts-kit platform-folders [--place <file>=<folder>]... [--dry-run] ddd-ts-kit move-to-module <context> <module> <path>... [--dry-run] [--allow-cycle] ddd-ts-kit context-layout [<context>...] [--dry-run] ddd-ts-kit affected [--base <git-ref>] [--head <git-ref>] [--format text|json|github|env] ddd-ts-kit affected --base <git-ref> --run <script> ddd-ts-kit check [paths...] [--rule <id>]... [--format text|json|github|gitlab] [--changed-since <git-ref>] [--explain] [--self] ddd-ts-kit check --baseline write|prune ddd-ts-kit check --clean-only <dir>... [--rule <id>]... [--format text|json|github] ddd-ts-kit check --commit-size [--staged] [--strict] ddd-ts-kit check-file <path> [--content-from <file>] [--rule <id>]... ddd-ts-kit lint [paths...] [--format <eslint formatter>] [--fix] [--no-cache] [--ignore-pattern <pattern>]... ddd-ts-kit rules ddd-ts-kit explain <rule-id>
Every command accepts --json (machine-readable output, on one line) and --cwd <dir> (project root).ddd-ts-kit <command> --help prints the usage and the notes of that command alone, generate <kind> --help one kind;--json gives either as data.
affected what a pull request has to run: the contexts a change set reaches through the context map (a changed context and the contexts downstream of it), as filters for the test runner and the linter; everything when a shared path changed or without --base; --run <script> runs that script of the project on them (DDD_TS_KIT_AFFECTED set, --passWithNoTests on a partial run) and nothing when nothing that runs changed: the pre-push hook tests the contexts its branch reaches tsc the typecheck and build of a project: the native TypeScript compiler (@typescript/native) wherever it is installed, in the project or hoisted to the root of a workspace build-aliases after the compiler: rewrites the import aliases left in the emitted .js and .d.ts files into relative paths, so that plain node runs the output (tsconfig.build.json by default) drizzle-generate the db:generate of a Drizzle project: drizzle-kit generate --name, which without a terminal fails and names the fix when drizzle-kit would ask whether a column or table is renamed, where drizzle-kit alone writes nothing and exits 0; then formats the snapshot and the journal it wrote with the Biome or Prettier of the format script, and warns when the SQL changes a primary key in an order that fails on PostgreSQL (exit code unchanged); says first, exit code unchanged, when the migration will drop the tables of a declared context because the schema index no longer names them; --replay, after merging the trunk into a branch when both added migrations: when the history forks from --base <ref> (origin/main by default), deletes the migrations of the branch the base does not have, with their snapshots and journal entries, then generates each again on top, in order, under its name (working- dropped outside a worker's worktree, a custom one keeping its SQL); when it does not fork, only renames them; refused while the journal holds conflict markers, when two of them change the schema, or when drizzle-kit now writes a generated one otherwise (edited by hand), the folder then put back as it was knex-generate the db:generate of a Knex project, which has no schema diff: compares the compiled createTables with the migrations replayed, both on PostgreSQL in process (no server), and writes the tables, columns and indexes the migrations lack, as SQL held in the migration, which then replays on a fresh database whatever createTables becomes; what it cannot write (a column or an object changed under its name, something dropped) and a statement that changes rows or removes something are listed in the migration as a TODO(domain); nothing differs, nothing is written; --custom writes the empty migration of knex, to fill by hand; a word after the name is refused prisma-client the db:client of a Prisma project: prisma generate, then the schema of the tests (prisma migrate diff --from-empty into generated/schema.sql), from the schema at --schema (prisma/schema by default); nothing is written when both are current, generated from the same schema files, prisma.config.ts and Prisma, and still there; two runs in one project (two test runs started together, a type check beside them) take turns on .ddd-ts-kit/prisma-client, and the second finds the client current error-factories moves the refusals of a project to one class per refusal (--to named, the default), from one class per error or from the factories of one error class per concept: --plan writes error-factories.plan.json, where each refusal is given a class (the PascalCase of its code, which it keeps) and a factory (for<Concept>), both editable; --apply follows it (codes.ts per context, one class file per refusal, specs, every usage, the concept classes left empty, "stack.refusals" in the config) and lists what it cannot rewrite (a bare <Concept>Error.is(error), CodeOf<typeof <Concept>Error>); --to factories moves one class per error to static factories on one error class per concept instead value-objects moves the value objects of a project from a Result to factories that return the value or throw: every create returning Result<T, E> returns T, err(..) is thrown, unwrap(..) of them goes, specs assert expectRefusal(() => ..), "stack.valueObjects" becomes throwing platform-folders takes the files of the platform a project generated flat to their folders: composition/, observability/ (tracing.ts first), jobs/, auth/authentication/ (who is calling), auth/authorization/ (what they may do, whatever the model), the folder of the model (auth/roles/, attributes/, relationships/, custom/) and audit/search-audit-entries/; every import of them under the source root, test/ and scripts/ follows, and the scripts of package.json; a file the kit did not write at the root of the platform or of auth/ stays where it is, named, unless --place <file>=<folder> (both from the platform, a file outside it refused) gives it its folder; the generators and init --force keep either layout until then move-to-module takes files of a context into a module of its model, declared first with generate module, each to <module>/<layer>/, a spec, a fake or a builder to <module>/test/: each <path> is a file or a folder of a role or of the tests, relative to the context (domain/aggregates/waitlist.aggregate.ts, application/commands/join-waitlist, shared/test/fakes/clock.fake.ts), from the level of the context, from shared/ or from another module; the specs named after a moved file follow it, every import of them under the source root, test/ and scripts/ follows, a migration that names the compiled file too, and the generated declarations are rewritten; what belongs to no module stays: the code list and the permission set at the root of the context, and in shared/ the schema of its database, its route groups, guards and shared shapes, its worlds. A move that would close a cycle between modules that is not there now writes nothing, with or without --dry-run: it names the cycle, the imports that make it (file and line) and the file to move along; --allow-cycle moves all the same, and module/no-cycle then reports the cycle. A project that turns module/no-cycle off is not judged context-layout takes the files of the contexts, or of the ones named, to their place of today. The code list and the permission set that 0.86 or 0.87 wrote in a role folder: domain/errors/codes.ts to <context>.codes.ts and application/authorization/<context>.permissions.ts to <context>.permissions.ts, at the root of the context. In a context divided into modules, what it still holds at its own level: the specs of test/<unit|integration>/<module>/ to <module>/test/; the adapters, routes, specs, fakes and builders to the module of the file they are named after (a builder after an aggregate, a fake after a port or a repository), else of what they import; and what belongs to no module to shared/: the schema and tables of the context, its route groups, guards and shared shapes, its worlds, and the specs, fakes and builders no module is told for. A file of a layer that names no module, or two, or one while the code of another module imports it, is listed and stays; nothing is overwritten; run again, nothing moves. Every import of them under the source root, test/ and scripts/ follows, a migration that names the compiled file too; what derives from the tree is written again (.dependency-cruiser.cjs, the declarations, the entries of knip), a config of a test runner to align is named, and knip is told of the code lists where they are controllers moves the function routes of a project, or of one context, to controller classes: each <name>.route.ts becomes <resource>/<name>/<name>.controller.ts behind the route group of its resource, its schema files and its spec follow; a context is turned whole or not at all doctor what an upgrade left to do: the scripts, the packages of the kit (at the ranges of this version) and the agent permissions this version writes that the project lacks or writes otherwise, and the git hooks (the lefthook: line of lefthook.yml, the pre-commit hook of lefthook in this clone); init adds what is missing, hooks:install the hook; then what this checkout lacks to run the project, read without network: the running Node against engines.node and .nvmrc, node_modules installed since the lockfile last changed, each package of the kit installed at the version of this CLI, the submodules initialised; last, the overrides init writes under a dependency that pins a package below a security fix, missing or no longer needed once it asks for the fix itself; and each install script the stack needs (the engines of Prisma, the Kafka client) that allowScripts of package.json or allowBuilds of pnpm-workspace.yaml does not allow for the version installed: missing, pinned to another version, or denied; each with its fix; --strict exits 1 while something is missing or the checkout cannot run the project, never for a hook this clone has not installed, a Node .nvmrc does not name, a lockfile changed since the install, an override no longer needed or a denied install script lint the ESLint of the project (lint and ci:lint run it): fails on an error, and on a warning as on an error; --format and --fix as ESLint describe one context as facts: use cases, routes, events, ports, policies, gateways, dependencies status the next step of docs/architecture/plan.md, the slices of docs/architecture/slices.md by status and by owner, each row not done ready on the trunk (its dependencies done), ready on a branch (the others briefed to a worker with commits ahead of its base) or waiting (with the ids it waits for), a row that landed with a worker's branch but is not marked done, and the TODO(domain), TODO(platform), it.todo and TODO(review) left in each context, and each story or milestone whose rows are all done while markers of its own keep it open (see story-check, whose git blame it runs on those markers only); --workers shows instead each worktree holding .ddd-ts-kit/worker.json (branch, context, rows, base, commits ahead and files changed counted from where its branch landed on the base when it was squash-merged there (else from the merge base), commits behind, the commit it landed as, what merge-trunk would leave conflicted now, dependencies not installed, its report), a state line (rows committed, the row under way, files uncommitted, markers, last verify-slice, and the worker-scope --resume command of a stopped one), then the contexts and the files more than one worker holds; --ready lists instead the rows not started whose dependencies are done, the others counted in one line sdk the typed client of each document of the contract, a workspace package under clients/<document> without runtime dependency: typed errors keyed by the error codes, credentials per security scheme; records "sdk" in the config the first time, wires the scripts (docs:generate regenerates it, docs:check compares it, ci:build builds it); --check writes nothing and exits 1 while a client differs from its contract todo those markers as file:line, in the project or in one context, read in every kind of file they are written into: the code, the pages, the files of prisma/schema/ (a marker of prisma/schema/<context>.prisma is of that context, another of the context whose database schema holds its model), the migrations, the configuration at the root; --brief prints each as file:line and its first words (up to its first : or ;), the file holding the rest; --json keeps every text mutation the mutation score of the domain and application layers of each context, read from the json report the last stryker run wrote (reports/mutation/mutation.json, or --report <file>), each held to its "mutation" floor of the config (80 and 75 by default): detected over detected and undetected, the errors left out, as Stryker counts, the ignored mutants (the texts of refusals, the code that runs once when the module loads) shown beside, since the score says nothing about them; exits 1 while a layer is under its floor, 2 without a report. --survivors lists the mutants no test noticed (file:line, mutator, what the code became), each a decision: a test named after the rule, or left alive and said so; --changed <ref>, or DDD_TS_KIT_MUTATION_SINCE in the environment as the job of a pull request sets it, lists those of the files changed since the git ref alone and exits 0 whatever the scores, a reading for a change in progress. Runs no test: npm run test:mutation runs Stryker, then this; the pipeline runs it every night and, with the variable set to the merge base of the change, on a pull request plan-waves the rows of slices.md not done, of the project or of one context, in waves (wave 1: every dependency done; wave n: the others in earlier waves), each wave cut into batches of one owner, one or two rows on one aggregate, with the worker-scope command that briefs each, the batches of a wave likely to touch the same files (same aggregate in Start with, or unknown when it names none), each row a row waits for with its status (and its context and story when it is of another story or outside the context shown), the rows of other stories the planned rows wait for, not done, in a section of their own, the merge order and what runs before each merge (merge-trunk --to-land); a cycle, a dependency on an unknown id or a row without owner is reported alone, and exits 1. Then replays the generator commands of every open row in a copy of the project, in the order of the waves, those of other contexts too, and reports for the rows planned, without waves, exiting 1, each name whose words the glossary of its context does not define with the --term of its row and of the rows it waits for, each command the generator refuses for another reason (refused-command), its refusal and fix under the row, with the rows that generate what it builds on, and each command that builds on a file a row it does not wait for generates (missing-dependency); a row in progress, whose commands may have run and whose worker may have added a term, counts for none, its refusals listed apart; --ready keeps the first wave, whose dependencies are done, and counts the later waves in one line story-check whether a story or a milestone can close, <code> being the start of the ids of its rows (M1 for M1.01, M1.02: the id without its last .<number>): every row of it done in slices.md (the others listed with their status), and no marker of its own left (TODO(domain), TODO(platform), it.todo, TODO(review)). A marker is attributed to rows: those its text names (#M1.03 or M1.03, word-bounded), else those of the commit that wrote its line (git blame, once per file; its Slice: trailer, else the row ids its message names), else, not committed, those of .ddd-ts-kit/worker.json in a worker's worktree. It is the story's own when it belongs to one of its rows, wherever it is; a marker of a context of its rows that belongs to no row is its own when no other open story has a row in that context, and is listed without blocking otherwise (settle it or name its row in it); a marker of other stories' rows does not block. --strict: every marker of its contexts blocks. Each blocker comes with why it is its own, its file:line and its fix: handle it, or dismiss it by a decision record (generate adr), then delete the marker. A done row also holds to its design: every name the ## #<id> section of docs/architecture/reviews/<code>.md cites (a path, a PascalCase name, a Class.member, as cited reads them) exists in the tree, or is listed under ### Compromises of ## Report in the story file; a name that is neither blocks, with its file:line in the review. A commit of the story on the current branch (its Slice: trailer, else its message naming a row or the story) that changes a migration or a container file (the paths the change-reference hook of the regulated profile watches) without a Change: <id> trailer is listed, with its files, and blocks under agents.profile regulated or with --strict. Reads only: exits 0 when it can close, 1 listing what keeps it open, 2 on a code no row carries or without slices.md acceptance the acceptance scenarios of each story (test/acceptance/<story>.acceptance.spec.ts) against its rows in slices.md and the criteria of docs/architecture/stories/<story>.md: the rows and criteria each scenario names (#US5.02 AC1 in its title), the scenarios left to write (it.todo), those wrapped in pending(...) of @ddd-ts-kit/testing/e2e until their code is built, and what is inconsistent (no row, an unknown row or criterion, a scenario skipped, a pending one whose rows are done, a locked one changed while its criteria were not); --gate written: every slice row and criterion has a written scenario, none is left to write, the acceptance is locked (before the code of the story); --gate passing: none is pending either (before the story closes); exits 1 while a gate is not met, or, without one, on an inconsistency. Never runs a test. --lock writes test/acceptance/<story>.acceptance.lock.json, the fingerprint of each criterion and of each scenario (pending(...), layout and comments aside), refused while a scenario is left to write, or while a criterion changed, or a locked scenario changed while its criteria did not, without a verdict "amend" of the acceptance-judge agent on that very version (test/acceptance/verdicts/*.md, lines Story:, Subject:, Fingerprint:, Verdict:, Reason:); a refusal wins; the verdicts become amendments of the lock, listed for the owner to validate. A fix is a story file with a ## Regression section listing the spec files that prove it (- test/unit/<name>.spec.ts): held to the tests of those files instead of rows and scenarios, locked and judged the same way, the statement of the fix being the criterion worker-scope a git worktree on the branch build/<context> (by default .worktrees/<context>, see worktree), cut from --base <ref> (by default the current branch, refused from a worker's worktree), its .ddd-ts-kit/worker.json, and the briefing of the worker of that context; --rows <id,...> briefs those rows of slices.md only, with their rules, the documents of their design and the names that design cites the base does not have (see cited), and by default the first batch plan-waves cuts for the context (one or two rows on one aggregate), a note naming the next; a worktree it creates gets the clean install of the package manager (npm ci), its time in the notes, unless --no-install; an existing worktree or branch that does not contain the base is refused, with the merge-trunk that brings it in --here worker-scope in the worktree of a story (.ddd-ts-kit/story.json): writes the scope of the next agent in place, its base the base of the story, and prints its briefing; no worktree, branch or install of its own; the agents of a story run one after the other story-scope the worktree of one story, .worktrees/<story> on story/<story> cut from --base (by default origin/main from the trunk, else the current branch, refused from the worktree of a story), its .ddd-ts-kit/story.json ({ story, base, baseCommit, branch, kind, from }) and its clean install; an existing one is kept and the story resumes there; refused when the story is open in another worktree; names the other open stories and the contexts their rows change; --kind story (the default) or fix (a story built behind locked regression specs, listed under ## Regression of its file); --from <file> records where the story comes from, an intent of docs/architecture/intents/ (refused unless its header says Status: accepted) or an incident record of docs/architecture/incidents/, and the Next: line says that the story skill seeds the statement from it while the story file does not exist worktree the worktree of any other piece of work, .worktrees/<name> on work/<name> cut from --base (by default origin/main from the trunk, else the current branch), and its clean install unless --no-install; an existing one is kept; .worktrees/ lies in the main checkout, whichever worktree it runs from, ignored by git and by the tools of the project; while the .gitignore of a project started before does not hold it (init adds it), a worktree opens next to the project, ../<project>-<name>; in a project whose config says "worktrees": "required" (what init writes), the guard of the plugin refuses the code of a context in the main checkout of the trunk, and in a worktree of .worktrees/ without its own node_modules story where a story stands, phase by phase: its specification and criteria (docs/architecture/stories/<story>.md), its rows in slices.md, a design review section per row not done (docs/architecture/reviews/<story>.md, ## #<id>), its acceptance written and locked, its rows done, its acceptance passing, its trunk merged in, its ## Origin (From: and Built with:), its ## Report with ### Digest (what digest prints) then ### Verification naming npm run verify; and the next step; in the worktree of a story, the story is its own; --gate build exits 1 until the first four are met (the code may start: the guard of the plugin opens the contexts), --gate close until all are stories the stories open in the worktrees of the repository and where two of them meet: the contexts the rows of both name, the files both worktrees change (committed or not), what merging the branch of one into the other leaves to a person and what merge-trunk settles (git merge-tree, nothing written); how far each is behind its base; from the worktree of a story, the stories it meets; the guard of the plugin says it at session start and on a write to a file another story changes digest what the branch changes, for its reviewer, in about thirty lines of Markdown read before the diff: per context, the use cases, permissions (with the roles that hold them), routes (with their error codes), events published and consumed, ports and adapters added, changed or removed since the merge base of <ref> and HEAD (both described as describe reads them, each written under the temporary directory through an index of its own, export-ignore of .gitattributes aside, the working tree untouched); the spec titles the branch adds, those the kit generated counted; the files to review in reading order (context, domain, application, presentation, infrastructure, tests, elsewhere), and apart, as regenerated, the generated files REVIEW.md names; what is not committed is said, not digested; exits 2 outside a git repository or on an unknown ref --resume worker-scope reads where the stopped worker of the context stands (its rows by their Slice: trailer, the files of the row under way, the markers, its last verify-slice, its report, its agent as the guard recorded it) and prints the message that resumes its agent (SendMessage) or the briefing of a new one; creates and rewrites nothing; --fresh asks for a new agent whatever the last one did; several worktrees of the context need --worktree verify-slice closes a slice before its commit, in one run: the regenerate script, check on the files changed since --since (new ones included), the test script for the context; then the changed files past 300 of the 350 lines, the paths of the slice to stage (its context, its Prisma models, an end-to-end spec, a working migration, the pages of docs/behaviour/ but those of other contexts, prisma/schema/schema.prisma when its one change is the context joining the schemas of the datasource, the schema index of the platform and the list of the read model tables when every line changed there is of the context, the derived files git tracks) and every other changed path, left out and never to stage with it; the merges since --since, as verify-merge checks them, reported without failing the slice in this version (a later minor version fails it; a migration out of order is said apart, the push being refused on it already); exits 1 while a step fails; then the names the slice removes that the design of a row not done still cites (never a failure); in the worktree of a worker, the commit command with the trailer Slice: <row>, and .ddd-ts-kit/verification.json for the conductor cited the names the design of rows not done cites as code (paths, classes, Class.member) that the code does not have: those the history of --base removed (with the commit and the successor), the places the canonical tree refuses, and a name never there whose close name of the same part arrived after the line was written; planned names stay silent. The design of a row: its cells and rule lines in slices.md, a section of a document of docs/architecture whose heading names it, a document that names it or that its rule line links to. Default: every row not done, of the context when given, at the current branch. --removed-since <ref>: the names a change removes, from the merge base to the working tree, that such a design cites. Reads only, exits 0 verify-merge what the merges of a branch lost, read from git only: every merge commit since --since (by default the base of .ddd-ts-kit/worker.json, then origin/HEAD, then origin/main) and the merge in progress (its result: the index and the working tree), or one <commit>; a squash commit takes --theirs <head of the branch it took in>. Errors: a line one side added or both kept missing from the result (whitespace, a line laid out again, a move to another file and imports merged into one statement aside), a file neither side deleted gone from the result, a row of slices.md done on one side and no longer done or gone, a test title or a spec file of one side gone, a migration of one side whose description (name without number and working-) the result lacks, a conflict marker; warnings: a line one side removed brought back, a line one side wrote where the other changed the same lines or deleted the file (the merge chose), a line the merge replaced by lines of its own. Derived files, files a tool says it wrote, migrations, lockfiles and slices.md are left out of the lines. The base is --base, else the Merge-Base: trailer of the merge, else git merge-base; entries of a Lost-Accepted: <file:line>,... trailer, or <file>@<side>#<hash> as merge-trunk writes what its Drizzle settle takes out, are listed and never fail, nor what a later commit restored; the lines a Kit-Written: trailer names are never the merge's own; silent and exit 0 without a merge, exit 1 on an error; --warn prints the same and exits 0, as the pre-push hook of init runs it in this version (a later minor version blocks the push). Then, without a <commit>, the migrations of the working tree against that trunk: one the branch adds that sorts before the last migration of the trunk (a working- one aside), or, under drizzle-kit, was generated before it or is out of the journal. An error with the command that brings the order right, which --warn never softens: exit 1 merge-trunk brings the trunk (--trunk; by default the base of .ddd-ts-kit/worker.json in the worktree of a worker, then origin/HEAD, then origin/main; nothing is fetched) into the branch as one merge commit computed from the branch's own diff: from the newest commit of the branch the trunk holds (--since; else the commit whose patch, derived files, migrations, slices.md, plan.md and lockfiles left out, is one commit of the trunk, on this branch or a branch it shares commits with; else the base recorded for the worker when its lines are on the trunk; else git merge-base). Settles derived files and drizzle-kit meta (trunk side), the package.json of a client (trunk side, at the higher of both versions; left to you when one is not a semantic version), generated regions of CONTEXT.md and the context map (trunk side), conflicts inside generated registries (lines of both sides, read back: where they would leave a declaration open or do not give the declarations of the two sides merged one by one, the region merged declaration by declaration, one the two sides do not agree on left to you as one hunk; a region not read with certainty is merged by lines as before, one the kit merges neither way is left as git wrote it), slices.md row by row (the furthest status), the stored-events lock by key, the lockfile (trunk side, installed again when the branch changed package.json); the rest is left in a merge in progress git understands, with what each side did (exit 1). Then, or on --continue: the drizzle migrations of both sides replayed, on --to-land the working migrations renamed (knex, Prisma, TypeORM; stop when both sides change one table), decision records renumbered, regenerate, verify-merge on the uncommitted result (an error stops; --accept-lost records a Lost-Accepted: trailer), and the commit of the merge's paths only, with the trailers Merge-Base:, Trunk: and Landed:; any other changed path blocks it. On a branch that already holds the trunk, --to-land still lands the migrations (replayed or renamed after the last of the trunk) and leaves them to commit. --dry-run previews, --abort undoes; refused (exit 2) on a dirty tree, another operation in progress, no committer known to git, an unknown trunk, a --since at the head of the branch, or a git older than 2.40 with a base git would not compute --commit-size the files and lines about to be committed against "commit" in the config (20 files and 600 lines by default, generated files not counted); --staged reads the index only; advisory, --strict exits 1 when over --explain check follows the violations with the reason of each rule they report, once per rule, as explain gives it without its examples ("explanations" in JSON); with github and gitlab, each annotation carries the reason of its rule, a pull request showing an annotation on its own --behaviour docs writes the pages of what the tests state (docs/behaviour/) alone, every other generated document left as it is: what the pre-commit hook runs when a spec, a source under src/ or the config is staged; with --check, those pages alone are compared --stored-events docs records the shape of each version of the stored events in stored-events.lock.json, never rewriting a recorded one but one recorded by 0.82.0 or earlier, recorded again as the kit reads it now: run it once the shape of a version is the one to store; docs --check fails while a declared version is not recorded, or recorded by 0.82.0 or earlier, or recorded as the hash of nothing; the codecs of each module of a context are read too, and a codec whose data type is not found or declares no member is refused, nothing recorded --dry-run docs names each generated file it would create, update or delete, and writes none; --check compares instead, and exits 1 on a change --force init and generate replace the files that exist with what the kit writes, only while git holds them: a file to replace that differs from the last commit (uncommitted, staged, or untracked and not ignored) refuses the command, exit 2, the files named, nothing written; outside a git repository, every file whose content would change does; commit or stash first, then git diff shows what the kit rewrote; init --force keeps README.md, AGENTS.md, CLAUDE.md, the entry point and the pipeline definitions once written (listed as kept) and merges .gitignore and .dockerignore, the lines of the team kept; the files it rewrites keep what their ddd-ts-kit:* regions, the roles, the Prisma datasource and the services of the compose file hold, and a note names, file by file, what it could not keep: a region this version does not hold, a marker without its partner, a roles object it cannot read to its end, the repositories left on the ORM a flag changed --force generate replaces the files that exist with what the kit writes, only while git holds them: a file to replace that differs from the last commit refuses the command, exit 2, the files named, nothing written; outside a git repository, every file whose content would change does; commit or stash first, then git diff shows what the kit rewrote --sdk init records "sdk" in the config and generates the clients with the project --term generate adds the row "<Term>=<meaning>" to the glossary of the CONTEXT.md before it judges a name; "<Term>=<meaning>|<not to be confused with>" fills the third cell too, a pipe being the one character a cell of the table cannot hold; taken by the kinds whose usage below shows it, refused by the others, as is any flag the usage of a kind does not show --reason generate context writes it under ## Classification, the sentence of why the context is of its classification; generate adr --deviation records it as the reason of the deviation --local-only generate refuses, and writes nothing, when the kind would write outside its context; "generate --help --json" says which kinds do --module generate writes the files of the layers into that module of the model of the context (declared first with generate module), <module>/domain/ to <module>/presentation/, and their specs, fakes and builders into <module>/test/, finds the files it reads in the module that holds them and writes the imports to where they are; taken by the kinds whose usage below shows [--module <module>], and required by them in a context that declares modules (a file of a use case already in a module goes with it, and another module is refused); every other kind refuses it, what it writes belonging to no module: the code list and the permission set at the root of the context, and in its shared/ folder the database schema, the route groups, guards and shared shapes, the worlds; a context that still holds test/ at its own level is refused until context-layout moved it
Kinds context <name> --classification <core|supporting|generic> [--reason "<why it is of that classification>"] [--purpose "<two sentences>"] [--term "<Term>=<meaning>[|<not to be confused with>]"]... [--upstream <ctx>[:relationship]]... [--preset identity] module <context> <module> [--purpose "<what it holds>"] [--classification <core|supporting|generic>] [--term "<Term>=<meaning>"]... aggregate <context> <Name> [--birth "<Fact>"] [--event-sourced] [--term "<Term>=<meaning>"]... [--module <module>] builder <context> <Aggregate> [--module <module>] test-world <context> [Name] entity <context> <Name> [--term "<Term>=<meaning>"]... [--module <module>] value-object <context|shared-kernel> <Name> [--term "<Term>=<meaning>"]... [--module <module>] (alias: vo) property <context> <ValueObject> [--module <module>] vocabulary <context> <Name> --value <value> [--value <value>]... [--module <module>] state-machine <context> <Aggregate> [--value <state>]... [--transition "<intention>:<from>[,<from>]...[><to>]"]... [--term "<Term>=<meaning>"]... [--module <module>] domain-event <context> <Aggregate> <Fact> [--term "<Term>=<meaning>"]... [--module <module>] error <context|shared-kernel> <Refusal> <factory> [--code CODE] [--term "<Term>=<meaning>"]... [--module <module>] (alias: refusal) domain-error <context|shared-kernel> <Name> [--code CODE] [--term "<Term>=<meaning>"]... [--module <module>] domain-service <context> <Name> [--term "<Term>=<meaning>"]... [--module <module>] repository <context> <Aggregate> [--tenant-scoped] [--personal <column>,<column>... [--subject <column>] [--erasure pseudonymise|row] [--retention <column>:<n><d|m|y>]] [--module <module>] command <context> <UseCaseName> (--permission <aggregate>.<action> [--grant <role>] | --public) [--aggregate <Name> [--creates]] [--term "<Term>=<meaning>"]... [--module <module>] query <context> <UseCaseName> (--permission <aggregate>.<action> [--grant <role>] | --public) [--search] [--term "<Term>=<meaning>"]... [--module <module>] port <context> <Name> [--module <module>] route <context> <UseCaseName> --method <GET|POST|PUT|PATCH|DELETE> --path <path> [--command|--query] [--group <Name>] [--mapper] [--serializer] [--cache public|private|no-store] [--module <module>] controller <context> <UseCaseName> --method <GET|POST|PUT|PATCH|DELETE> --path <path> [--command|--query] [--group <Name>] [--mapper] [--serializer] [--cache public|private|no-store] [--module <module>] file-upload <context> <UseCaseName> --path <path> (--permission <aggregate>.<action> [--grant <role>] | --public) [--method <POST|PUT>] [--group <Name>] [--text <utf-8|single-byte>] [--term "<Term>=<meaning>"]... [--module <module>] route-group <context> <Name> [--prefix <path>] [--group <ParentName>] [--public | --role <role>] (alias: group) guard <context> <Name> representation <context> <UseCase> <xml|csv|media/type>[,...] [--module <module>] form <context> <UseCase> [--module <module>] schema <context|shared-kernel> <Name> integration-event <context> <Aggregate> <Fact> [--version <n>] [--term "<Term>=<meaning>"]... [--module <module>] integration-handler <context> <upstreamContext> <eventType>[@v<n>] [--version <n>] [--name <Name>] [--term "<Term>=<meaning>"]... [--module <module>] (alias: consumer) personal-fields <context> <table> --personal <column>,<column>... --subject <column> [--erasure pseudonymise|row] [--retention <column>:<n><d|m|y>] [--tenant-scoped] [--module <module>] erasure-handler <context> [--module <module>] event-handler <context> <Aggregate> <Fact> [--phase before-commit|after-commit] [--name <Name>] [--term "<Term>=<meaning>"]... [--module <module>] projection <context> <Name> <eventType>[@v<n>] [--term "<Term>=<meaning>"]... [--module <module>] (alias: projector) read-model <context> <Name> [--field <name>:<string|number|boolean|instant|decimal>[:nullable]]... [--tenant-scoped] [--term "<Term>=<meaning>"]... [--module <module>] job <context> <Name> (--every <duration> | --cron "<expression>" [--time-zone <zone>]) --command <UseCaseName> [--global] [--term "<Term>=<meaning>"]... [--module <module>] background-job <context> <Name> --command <UseCaseName> [--term "<Term>=<meaning>"]... [--module <module>] process <context> <Name> [--term "<Term>=<meaning>"]... [--module <module>] (alias: process-manager) acl <context> <upstreamOrSystemName> [--module <module>] e2e <context> <UseCaseName> [--event <eventType> | --job <JobName>] acceptance <story> ["<title>"] policy <context> <Name> --permission <aggregate>.<action> [--term "<Term>=<meaning>"]... [--module <module>] gateway <context> <upstreamContext> <Name> [--module <module>] adapter <context> <Port> [--kind external|gateway|simulated] [--decorators] [--module <module>] service <context> worker adr "<title>" [--number <n>] [--deviation <what>] [--reason "<why>"]See also
Section titled “See also”- Methodology: the path, step by step, with what each step leaves and when it is done
- CLI README: every command in detail
- Configuration