Skip to content

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 six moments of a project in order, start, model the domain, build a slice, before a commit, before a pull request, release and deploy, each with its skills and commands; the next slice loops back to build a slice; connecting two contexts and persistence come inside a slice; a refusal or a kit upgrade can come at any moment

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.

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:

The files written by generate aggregate, repository, command, route and e2e for the PlaceOrder slice: the routes and the controller in presentation, the permissions, the command and the handler in application, the aggregate and the repository port in domain, the Drizzle repository, the mapper and the schema in infrastructure, the builder, the fake, the contract suite and the specs under test, and the end-to-end spec outside the context

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 ordering
src/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.

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
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
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
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
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
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
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
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
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
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 Order
error: "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:

Terminal window
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.ts
src/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-only
context/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).

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>"]