name: domain-driven-design-standards description: "Generates and refines code-free Domain-Driven Design (DDD) bounded context blueprints per Vlad Khononov's 'Learning Domain-Driven Design'. Trigger on 'model a domain', 'define a bounded context', 'write a DDD blueprint', or 'classify subdomains'. Do not use for writing application code, database schemas, SQL, or framework commands." tags: [domain-driven-design, ddd, bounded-contexts, architecture, ubiquitous-language] argument-hint: '[domain or bounded context name]'

Domain-Driven Design Standards

Advanced expert skill for producing pure, code-free DDD blueprints grounded in Vlad Khononov's Learning Domain-Driven Design (O'Reilly, 2021) and cross-checked against Evans, Vernon, Kleppmann, and Martin (see reading list).

Safety & Strict Constraints

1. No code. Never emit programming language source, pseudocode-as-implementation, database schemas, raw SQL/NoSQL queries, ORM mappings, framework/installation commands (e.g., PHP, Laravel, Artisan, Composer, npm), or diagram markup (e.g., Mermaid). Prose, tables, and lists are the only permitted artifacts — state machines are documented as transition tables, not diagrams.
2. Model, not mechanism. Describe what the domain does and why (rules, invariants, language, lifecycle) — never how it is persisted, queried, or rendered.
3. Ubiquitous Language only. Every noun/verb used in a blueprint must appear in the glossary (see ubiquitous-language.md). Reject/flag internal technical jargon (e.g., "DTO", "repository", "controller") leaking into domain documents.
4. Traceable classification. Every bounded context must be explicitly tagged Core / Supporting / Generic with a justification (see strategic-design.md).
5. File naming. Directories and files use kebab-case or snake_case consistently within a project (pick one and stay consistent); see blueprint-structure.md for exact rules and the main.json schema.
6. Preserve blueprints & non-destructive operations. Scaffolding operations must never overwrite existing directories. When refining existing blueprints, preserve existing files or verify git status before making edits.

When to Use

• A user asks to "model a domain", "define a bounded context", "write a DDD blueprint", "classify subdomains", or "build a ubiquitous language glossary".
• A user wants to decompose a monolith or sprawling business area into bounded contexts before any code is written.
• A user wants domain invariants, state machines, or domain events documented independently of an implementation stack.

When Not to Use

• The request is for application code, database schemas, SQL/NoSQL queries, ORM mappings, or framework commands — this skill produces code-free documentation only.
• The request is implementation design (API specs, persistence, infrastructure, deployment) — out of scope per Strict Constraints 1–2.
• The subject is purely technical infrastructure with no business vocabulary to model.

Procedure

Work through these phases in sequential order. Do not skip classification before decomposition — subdomain classification determines modeling depth.

Phase 1 — Strategic Alignment (tools: read_file)

1. Call read_file on strategic-design.md.
2. Take the user's business description (input), identify candidate subdomains, and classify each as Core (competitive differentiator), Supporting (necessary business capability, non-differentiating), or Generic (standard problem, off-the-shelf).
3. Establish bounded context boundaries using linguistic boundaries (where a term's meaning shifts) validated against team ownership.
4. Completion condition: All candidate subdomains are classified with rationale and bounded context boundaries are explicitly mapped.

Phase 2 — Ubiquitous Language (tools: read_file)

1. Call read_file on ubiquitous-language.md.
2. For each bounded context, interview the domain expert framing (request clarification from user if terminology is ambiguous) and extract core vocabulary.
3. Build the glossary table: term, context, precise definition, and explicit false-friend exclusions.
4. Completion condition: Glossary is documented for each bounded context with zero technical implementation jargon (such as DTO, repository, or controller).

Phase 3 — Tactical Modeling & The Law (tools: read_file)

1. Call read_file on tactical-modeling.md.
2. For each bounded context, enumerate entities, value objects, and aggregate roots.
3. Formulate domain invariants ("the law") as declarative rules enforced by aggregates; document lifecycles as markdown state transition tables.
4. Completion condition: Every invariant is mapped to a specific aggregate; state machines are structured in tables without diagram syntax.

Phase 4 — Structured Blueprint Assembly (tools: run_command, write_file)

1. Call read_file on blueprint-structure.md for document order, naming rules, and main.json schema.
2. Execute run_command with node scripts/scaffold-blueprint.js <context-name> "<Title Case Name>" <sort> [--case=kebab|snake] [--out=./path] to generate directory and stub files.
3. Use write_file to write documents 01 through 08 in sequential order without merging documents.
4. Completion condition: Target directory contains main.json and all 8 populated blueprint files matching the naming convention.

Phase 5 — Review Pass (tools: run_command, read_file)

1. Execute run_command with node scripts/validate-blueprint.js <path-to-bounded-context-dir> to verify document structure, naming consistency, and absence of jargon or code.
2. If validation exits with code 1, resolve every reported issue and re-run until it prints PASSED.
3. Call read_file on generated files and verify against the checklist in blueprint-structure.md.
4. Completion condition: Validator exits 0 with PASSED and all pre-delivery checklist items are satisfied.

Scripts

Run both from the skill root. They require only Node.js (no dependencies) and never write domain content — they manage structure and enforce the constraints above.

Troubleshooting

• Missing or underspecified domain input: If the request lacks domain scope, bounded context name, or business rules, prompt the user with clarifying questions to define domain boundaries before scaffolding.
• Node.js runtime unavailable: If node cannot run scaffold or validate scripts, use the manual fallback: copy templates from assets/templates/ (01-*.md through 08-*.md and main.json.template), manually populate tables, and verify against the checklist in blueprint-structure.md.
• Scaffolder fails with Directory already exists (exit 1): Scaffolding is non-destructive and never overwrites. Pick a new <context-name>, specify --out, or verify existing content before modifying.
• Validator fails (exit 1, Blueprint validation FAILED: + issue list): Each issue names the file and problem (missing document, invalid main.json, mixed naming, code fence, or leaked technical jargon). Fix the named file and re-run node scripts/validate-blueprint.js <dir> until it prints PASSED. The validator ignores > blockquote guidance lines.
• A document does not apply to this domain (e.g., no lifecycle-driven aggregate for Document 6): Retain the file — the validator requires all eight — and write "None applicable" with a one-line justification; never delete, merge, or renumber.

Assets

assets/templates/ holds a ready-to-fill template for each of the 8 documents plus main.json.template, each pre-populated with the required table skeletons and inline > guidance notes from the references. Templates 01–08 mirror the mandatory document sequence one-to-one; main.json.template takes two substitutions — <Title Case Bounded Context Name> and the sort integer (increments of 10). scaffold-blueprint.js uses these templates automatically; they can also be copied by hand when not scaffolding via script.

Concrete Examples

Example 1 — Strategic Classification & Glossary Entry

Input request: "Model the billing subdomain for our SaaS platform." Action: Classify subdomain and produce ubiquitous language glossary per Phases 1–2. Output blueprint excerpt:

• Subdomain: Billing & Invoicing — Supporting (necessary business capability, moderate complexity, standard commercial logic, not core competitive differentiator).
• Ubiquitous Language Glossary:

  Term	Context	Definition	False Friends / Exclusions
  Invoice	Billing Context	Finalized commercial claim for payment issued after billing cycle close.	Not an "Order" (Sales) or a "Payment Receipt" (Payment Gateway).
  Billing Cycle	Billing Context	Recurring monthly or annual time window governing subscription charges.	Distinct from "Subscription Period" in Account Management.

Example 2 — Tactical Aggregate & Invariant Rule ("The Law")

Input request: "Define invoice aggregate invariants and lifecycle." Action: Model tactical aggregate invariants and state machine table per Phase 3. Output blueprint excerpt:

• Aggregate Root: Invoice
• Invariants ("The Law"):
  1. An invoice cannot be issued with zero line items.
  2. Total amount must equal the exact sum of line item amounts plus calculated taxes.
  3. Once marked Paid, an invoice cannot transition to Void or have line items modified.
• State Transition Table:

  Current State	Event / Trigger	Next State	Guard / Invariant
  Draft	IssueInvoice	Issued	Line items > 0, total amount > 0
  Issued	RecordPayment	Paid	Received payment amount equals total balance
  Issued	VoidInvoice	Void	Invoice is not in Paid state

Reference Index