@opengroundplan/core 0.1.1

package/adapters/cursor/templates/rule.mdc.tmpl

@@ -0,0 +1,9 @@
+---
+description: {{ itemDescription }}
+globs: {{ itemGlobsCsv }}
+alwaysApply: false
+---
+
+# {{ itemName }}
+
+{{ itemBody }}

package/adapters/gemini-cli/adapter.yaml

@@ -0,0 +1,51 @@
+id: gemini-cli
+name: Gemini CLI
+# Not native: AGENTS.md is only read if you add it to context.fileName. We wrap via @import instead.
+readsAgentsMd: false
+# Headless activates on -p or a non-TTY stdin.
+invoke:
+  binary: gemini
+  args: ["-p", "{prompt}", "--output-format", "json"]
+  promptVia: arg
+  autoApprove: ["--approval-mode", "yolo"]  # --yolo also works; this form is the documented one
+  modelFlag: ["--model", "{model}"]
+  detect: ["--version"]
+  install: "npm i -g @google/gemini-cli"
+  verifiedOn: "2026-07-19"
+  verified: "https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/headless.md"
+  # Google is ending service for free and AI Pro/Ultra tiers on 2026-06-18. API-key and
+  # Code Assist Standard/Enterprise users are unaffected, and @google/gemini-cli still
+  # publishes, so the adapter stays — removing it would break working setups (ADR 0007 §9).
+  deprecated:
+    since: "2026-06-18"
+    note: >-
+      Serving ends for Google AI Pro/Ultra and free tiers. API-key and Code Assist
+      Standard/Enterprise users are unaffected and the CLI continues to be supported.
+    successor: antigravity-cli
+    source: "https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/"
+
+capabilities:
+  - instructions
+  - nested-instructions
+  - slash-commands
+
+# Sources:
+#   https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md
+#     Hierarchy: ~/.gemini/GEMINI.md -> workspace GEMINI.md + ancestors -> just-in-time subdirs.
+#     `@file.md` import syntax is supported; context.fileName in settings.json can rename the file.
+#   https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md
+#     .gemini/commands/**/*.toml -> /namespaced:command; required key `prompt`, optional `description`.
+outputs:
+  # One-line @import. Chosen over context.fileName so the pointer is visible in the repo.
+  - path: GEMINI.md
+    kind: instructions
+    mode: wrapper
+
+  # TOML bodies use {{args}}, which collides with the content-token syntax — copy with raw: true.
+  - path: .gemini/commands/__commandId__.toml
+    template: command.toml
+    kind: command
+    mode: delta
+    when: hasCommands
+
+docs: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md

package/adapters/gemini-cli/templates/GEMINI.md.tmpl

@@ -0,0 +1,9 @@
+@{{ agentsMdPath }}
+
+# Gemini CLI
+
+The import above is the whole project instruction set. Nothing below restates it.
+
+- Custom commands live in `.gemini/commands/`; run `/commands reload` after editing one.
+- `/memory show` prints exactly what context was assembled — use it when behaviour surprises you.
+- Cross-tool handoff state lives in `.agent/`; routing is in `.agent/DELEGATION.md`.

package/adapters/gemini-cli/templates/command.toml.tmpl

@@ -0,0 +1,4 @@
+description = "{{ itemDescription }}"
+prompt = """
+{{ itemBody }}
+"""

package/adapters/github-copilot/adapter.yaml

@@ -0,0 +1,44 @@
+id: github-copilot
+name: GitHub Copilot
+# VS Code auto-detects root AGENTS.md (chat.useAgentsMdFile); the GitHub coding agent reads it too.
+readsAgentsMd: true
+# The standalone `copilot` agent, not the older `gh copilot` suggest/explain extension.
+# -s strips decoration for piping; there is no JSON output mode.
+invoke:
+  binary: copilot
+  args: ["-p", "{prompt}", "-s", "--no-ask-user"]
+  promptVia: arg
+  autoApprove: ["--allow-all-tools"]
+  modelFlag: ["--model", "{model}"]
+  detect: ["--version"]
+  install: "npm i -g @github/copilot"
+  verifiedOn: "2026-07-19"
+  verified: "https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference"
+capabilities:
+  - instructions
+  - nested-instructions
+  - glob-scoped-rules
+  - slash-commands
+
+# Sources:
+#   https://code.visualstudio.com/docs/copilot/customization/custom-instructions
+#     AGENTS.md at workspace root is native; nested files need chat.useNestedAgentsMdFiles.
+#   https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions
+#     .github/instructions/*.instructions.md carry glob frontmatter (applyTo).
+#   https://code.visualstudio.com/docs/copilot/customization/prompt-files
+#     .github/prompts/*.prompt.md become slash commands; frontmatter: description, agent, model, tools.
+outputs:
+  # Deliberately NO .github/copilot-instructions.md — it would duplicate AGENTS.md.
+  - path: .github/instructions/__ruleId__.instructions.md
+    template: instructions.md
+    kind: rule
+    mode: delta
+    when: hasGlobRules
+
+  - path: .github/prompts/__commandId__.prompt.md
+    template: prompt.prompt.md
+    kind: command
+    mode: delta
+    when: hasCommands
+
+docs: https://code.visualstudio.com/docs/copilot/customization/custom-instructions

package/adapters/github-copilot/templates/instructions.md.tmpl

@@ -0,0 +1,8 @@
+---
+applyTo: {{ itemGlobsCsv }}
+description: {{ itemDescription }}
+---
+
+# {{ itemName }}
+
+{{ itemBody }}

package/adapters/github-copilot/templates/prompt.prompt.md.tmpl

@@ -0,0 +1,6 @@
+---
+description: {{ itemDescription }}
+agent: agent
+---
+
+{{ itemBody }}

package/adapters/opencode/adapter.yaml

@@ -0,0 +1,18 @@
+id: opencode
+name: opencode
+# AGENTS.md is opencode's first-choice instruction file, ahead of CLAUDE.md.
+readsAgentsMd: true
+capabilities:
+  - instructions
+  - nested-instructions
+
+# Source: https://opencode.ai/docs/rules/
+#   Precedence: ./AGENTS.md -> ./CLAUDE.md -> ~/.config/opencode/AGENTS.md -> ~/.claude/CLAUDE.md
+#   opencode.json `instructions` accepts extra files, globs, and URLs.
+outputs:
+  # Points opencode at the shared handoff docs; adds no instruction content of its own.
+  - path: opencode.json
+    kind: settings
+    mode: settings
+
+docs: https://opencode.ai/docs/rules/

package/adapters/opencode/templates/opencode.json.tmpl

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".agent/DELEGATION.md"]
+}

package/adapters/roo-code/adapter.yaml

@@ -0,0 +1,21 @@
+id: roo-code
+name: Roo Code
+# AGENTS.md at workspace root is auto-loaded by default.
+readsAgentsMd: true
+capabilities:
+  - instructions
+  - glob-scoped-rules
+
+# Source: https://roocodeinc.github.io/Roo-Code/features/custom-instructions
+#   Workspace: .roo/rules/ (directory, preferred) or .roorules (single-file fallback).
+#   Mode-scoped: .roo/rules-{modeSlug}/ e.g. .roo/rules-code/.
+#   Directories are read recursively, files load alphabetically; directory form wins over the file form.
+outputs:
+  # Directory form only — emitting .roorules too would create two competing sources.
+  - path: .roo/rules/__ruleId__.md
+    template: rule.md
+    kind: rule
+    mode: delta
+    when: hasGlobRules
+
+docs: https://roocodeinc.github.io/Roo-Code/features/custom-instructions

package/adapters/roo-code/templates/rule.md.tmpl

@@ -0,0 +1,5 @@
+# {{ itemName }}
+
+Applies to: `{{ itemGlobsCsv }}`
+
+{{ itemBody }}

package/adapters/windsurf/adapter.yaml

@@ -0,0 +1,34 @@
+id: windsurf
+name: Windsurf (Cascade)
+# Conservative false: AGENTS.md discovery is documented for Devin Desktop, not for Windsurf Cascade.
+# A thin always_on rule pointing at AGENTS.md is correct either way and costs one file.
+readsAgentsMd: false
+capabilities:
+  - instructions
+  - glob-scoped-rules
+  - slash-commands
+
+# Sources (docs.windsurf.com now redirects to docs.devin.ai — Windsurf is Cognition/Devin):
+#   https://docs.devin.ai/desktop/cascade/memories
+#     Workspace rules: .devin/rules/*.md or .windsurf/rules/*.md (legacy), 12k chars per file.
+#     Frontmatter `trigger`: always_on | model_decision | glob | manual; `globs` for glob mode.
+#   https://docs.devin.ai/desktop/cascade/workflows
+#     .windsurf/workflows/*.md, invoked as /<workflow-name>, 12k char limit, manual only.
+outputs:
+  - path: .windsurf/rules/agents-md.md
+    kind: instructions
+    mode: wrapper
+
+  - path: .windsurf/rules/__ruleId__.md
+    template: rule.md
+    kind: rule
+    mode: delta
+    when: hasGlobRules
+
+  - path: .windsurf/workflows/__commandId__.md
+    template: workflow.md
+    kind: command
+    mode: delta
+    when: hasCommands
+
+docs: https://docs.devin.ai/desktop/cascade/memories

package/adapters/windsurf/templates/agents-md.md.tmpl

@@ -0,0 +1,12 @@
+---
+trigger: always_on
+---
+
+# Project instructions
+
+Read `{{ agentsMdPath }}` at the repository root before making any change. It is the single
+source of truth for this project's commands, conventions, boundaries, and protected paths.
+
+If you have not read it in this conversation, read it now.
+
+Cross-tool handoff state lives in `.agent/`. Routing is in `.agent/DELEGATION.md`.

package/adapters/windsurf/templates/rule.md.tmpl

@@ -0,0 +1,9 @@
+---
+trigger: glob
+globs: {{ itemGlobsCsv }}
+description: {{ itemDescription }}
+---
+
+# {{ itemName }}
+
+{{ itemBody }}

package/adapters/windsurf/templates/workflow.md.tmpl

@@ -0,0 +1,7 @@
+---
+description: {{ itemDescription }}
+---
+
+# {{ itemName }}
+
+{{ itemBody }}

package/adapters/zed/adapter.yaml

@@ -0,0 +1,14 @@
+id: zed
+name: Zed
+# AGENTS.md is in Zed's native rules-file precedence list. Nothing to wrap.
+readsAgentsMd: true
+capabilities:
+  - instructions
+
+# Source: https://github.com/zed-industries/zed/blob/main/docs/src/ai/rules.md
+#   Precedence: .rules, .cursorrules, .windsurfrules, .clinerules,
+#               .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md, GEMINI.md
+#   First match wins — so Groundplan must NOT emit a .rules file, or it would shadow AGENTS.md.
+outputs: []
+
+docs: https://zed.dev/docs/ai/rules

package/catalog/README.md

@@ -0,0 +1,62 @@
+# Catalog
+
+Decision knowledge as data. No code lives here — the engine in `packages/core` reads these files.
+
+```
+catalog/
+├── architectures/<id>.yaml   one file per architecture style
+├── characteristics.yaml      the 12 scoring axes + which styles are strong/weak on each
+├── decision.yaml             question tree, hard gates, and repo strategy
+└── README.md
+```
+
+## Adding an architecture
+
+1. **Create `architectures/<id>.yaml`.** The filename stem must equal the `id`, and `id` must be
+   kebab-case. It validates against `ArchitectureEntry` in `packages/core/src/schema.ts` — that file
+   is the contract, not this README.
+
+2. **Fill every required field.** `id`, `name`, `family`, `oneLine`, `bestFor` (≥1), `avoidWhen`
+   (≥1), `complexity`, `teamSize {min,max}`, `scores`, `stackFit`, `keyTradeoff`, `sources` (≥1).
+   `overlay` is optional — set it only when a blueprint under `templates/architectures/` actually
+   materializes the folder layout.
+
+3. **`scores` keys must be exactly the 12 `Characteristic` enum members**, each an integer 1–5.
+   `stackFit` keys must be exactly the 8 `Stack` enum members, each one of
+   `excellent | good | workable | awkward | n/a`. Both records are checked key-by-key; a typo fails
+   the load, it does not silently default.
+
+4. **Scoring rules.**
+   - Higher is always better, including `cost` — which is inverted from Richards' `$` row
+     (`$` = 5 … `$$$$$` = 1) so one ranking formula works across all 12 axes.
+   - `cost` means infrastructure and operational spend only. Engineering and modelling effort
+     belongs in `simplicity` and `complexity`.
+   - If the style is a column in Richards' [Architecture Styles Worksheet
+     V2.0](https://www.developertoarchitect.com/downloads/architecture-styles-worksheet.pdf), use its
+     numbers verbatim and say so in a comment above the `scores` block.
+   - If it is not, derive numbers *calibrated against* that matrix and put
+     `# derived, not from Richards` on the `scores` block, with one line on how you calibrated.
+     Never present derived numbers as sourced.
+   - Application-family styles do not change deployment topology, so their runtime rows
+     (`scalability`, `elasticity`, `fault-tolerance`) stay at monolith values and `cost` stays 5.
+     Deviating from that convention makes entries incomparable.
+
+5. **Sources must be real and must resolve.** Prefer the primary source — the author's own post, the
+   spec, the vendor's own docs. If you cannot source a claim, drop the claim; do not soften it into
+   a bullet. Never promote a number a research doc flagged as unverified.
+
+6. **Update `characteristics.yaml`.** Add the new id to the `strong` list of every characteristic it
+   scores ≥4 on, and the `weak` list of every characteristic it scores ≤2 on. These lists are
+   redundant with the entries by design — they are what makes "show me everything strong on
+   responsiveness" a lookup rather than a scan — so they drift unless updated in the same commit.
+
+7. **Wire it into `decision.yaml` only if it needs a new question or gate.** Ranking is
+   `sum(weight * score)` over the answered choices, so a new entry is reachable the moment it has
+   scores. Add to `gates` only for a genuine hard elimination, and to `defaults` only when a
+   published source recommends it for a named situation.
+
+## Comment style
+
+YAML comments carry provenance. Keep them one line where possible and explain *why* a number or
+exclusion is what it is — never restate the field. Comments marking derived scores, inverted scales,
+and deliberate omissions are the ones worth writing.

package/catalog/architectures/agentic-tool-loop.yaml

@@ -0,0 +1,62 @@
+id: agentic-tool-loop
+name: Agentic Tool Loop
+family: ai
+oneLine: >-
+  A single LLM dynamically directing its own process and tool usage in a loop, maintaining control
+  over how it accomplishes the task — mechanically, a loop that repeats while the stop reason is a
+  tool-use request.
+
+bestFor:
+  - Open-ended problems where it is difficult or impossible to predict the required number of steps
+  - Actions with side effects — sending mail, writing a file, updating a record
+  - Fresh or external data outside training data or specific to your system
+  - Calling into existing systems — databases, internal APIs, filesystems
+  - Structured, guaranteed-shape outputs where a schema beats parsing prose
+
+avoidWhen:
+  - The model can answer from training alone — summarization, translation, general-knowledge questions need no tool round trip
+  - The interaction is one-shot Q&A with no side effects
+  - Tool-calling latency would dominate a trivial response
+  - Simpler workflow patterns have not been tried and evaluated first
+  - You have no sandbox and no guardrails; autonomous loops need extensive testing in sandboxed environments
+
+complexity: medium
+teamSize: { min: 1, max: 30 }   # engine input — no primary source publishes a team size for this pattern
+
+# derived, not from Richards — AI application patterns are not in the worksheet.
+# Calibrated against Richards' scale. testability is low because the loop is non-deterministic
+# between runs even with identical prompts.
+scores:
+  maintainability: 3
+  testability: 2
+  deployability: 4
+  simplicity: 3
+  scalability: 3
+  elasticity: 4
+  responsiveness: 2   # unbounded step count; agentic systems trade latency and cost for task performance
+  fault-tolerance: 2  # errors compound across a long loop; minor failures can be catastrophic
+  evolvability: 4
+  abstraction: 3
+  interoperability: 4 # tool definitions are the integration surface
+  cost: 2             # ~4x the tokens of a chat interaction, per Anthropic's published figure
+
+stackFit:
+  typescript: excellent
+  python: excellent
+  dotnet: good
+  node: excellent
+  go: good
+  rust: workable      # no first-party SDK; HTTP API only
+  java: good
+  polyglot: good
+
+keyTradeoff: >-
+  Handing step-selection to the model buys adaptability on unpredictable tasks at the cost of
+  predictable step count, cost, and latency.
+
+overlay: agentic-tool-loop
+
+sources:
+  - https://www.anthropic.com/engineering/building-effective-agents
+  - https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works
+  - https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview

package/catalog/architectures/bff.yaml

@@ -0,0 +1,58 @@
+id: bff
+name: Backend-for-Frontend
+family: system
+oneLine: >-
+  A server-side component owned by the same team that builds a specific UI, serving exactly that
+  UI's needs rather than acting as a general-purpose API.
+
+bestFor:
+  - Multiple materially different clients (mobile, web, TV, partner) contending on one shared backend's release queue
+  - Heavy server-side aggregation collapsing chatty round-trips into one call, which matters most on mobile radio
+  - Holding OAuth tokens server-side for browser apps — the dominant reason new BFFs get built
+  - SSR where the render tier needs a tailored data shape
+
+avoidWhen:
+  - Web-only app with little aggregation — Newman himself says BFFs are unnecessary here
+  - You would build one BFF per team rather than per user experience; that is a distributed monolith with extra hops
+  - A typed client-server contract (tRPC in a TS monorepo, or a federated GraphQL gateway) already solves your shaping problem
+  - You have no tracing spanning BFF to services — otherwise you have added an invisible latency hop
+
+complexity: medium
+teamSize: { min: 5, max: 200 }
+
+# derived, not from Richards — no BFF column exists in the worksheet.
+# Calibrated against Richards' scale. fault-tolerance is low: the BFF sits in the request path and
+# is one more thing that can take a client offline.
+scores:
+  maintainability: 4
+  testability: 3
+  deployability: 4
+  simplicity: 3
+  scalability: 3
+  elasticity: 3
+  responsiveness: 4
+  fault-tolerance: 2
+  evolvability: 4
+  abstraction: 3
+  interoperability: 4
+  cost: 4
+
+stackFit:
+  typescript: excellent   # same language and team as the frontend, the classic fit
+  python: good            # FastAPI, most common fronting ML/inference services
+  dotnet: excellent       # YARP + ASP.NET Core OIDC + cookie auth; Duende BFF productizes the security variant
+  node: excellent
+  go: good
+  rust: workable
+  java: good
+  polyglot: good
+
+keyTradeoff: >-
+  Every BFF is a duplication surface, and the real risk is not duplicated DTOs but business rules
+  leaking into BFFs and drifting between web and mobile until the two clients enforce different policies.
+
+overlay: bff
+
+sources:
+  - https://samnewman.io/patterns/architectural/bff/
+  - https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps

package/catalog/architectures/clean.yaml

@@ -0,0 +1,61 @@
+id: clean
+name: Clean Architecture
+family: application
+oneLine: >-
+  Concentric circles — Entities, Use Cases, Interface Adapters, Frameworks and Drivers — governed by
+  the Dependency Rule: source code dependencies can only point inwards, and nothing in an inner circle
+  knows anything about an outer one.
+
+bestFor:
+  - Non-trivial monolithic applications, which Microsoft names as its most appropriate target
+  - Systems where the application core must be unit-testable in isolation, with no infrastructure present
+  - Anticipated infrastructure swaps — own-database to cloud persistence, or persistence to a web API — behind core-defined interfaces
+  - Codebases already applying dependency inversion plus DDD, which tend to arrive at this shape anyway
+
+avoidWhen:
+  - The app is genuinely small — Microsoft's own ladder starts at a single project where folders achieve separation of concerns
+  - You expect a novel concept; its author frames it as a synthesis of Hexagonal, Onion, DCI and BCE, not an invention
+  - You need Domain Services as a first-class layer, which Clean's circles omit
+  - Simple CRUD paths dominate, since they never repay the indirection
+
+complexity: high
+teamSize: { min: 3, max: 100 }   # engine input — no primary source publishes a team size for this style
+
+# derived, not from Richards — application-level styles are not columns in the worksheet.
+# Calibrated to Richards' scale using this convention: an application style does not change
+# deployment topology, so the runtime rows (scalability, elasticity, fault-tolerance) stay at
+# monolith values and cost stays at $ (=5); the style differentiates on the design rows only.
+scores:
+  maintainability: 4
+  testability: 5   # the headline claim — core has no infrastructure dependency to stub
+  deployability: 2
+  simplicity: 2
+  scalability: 1
+  elasticity: 1
+  responsiveness: 3
+  fault-tolerance: 1
+  evolvability: 4
+  abstraction: 5
+  interoperability: 3
+  cost: 5
+
+stackFit:
+  typescript: excellent
+  python: good        # Protocols work, but the interface layer is convention-only
+  dotnet: excellent   # the only stack with first-party sourced guidance and a reference template
+  node: good
+  go: workable        # small implicit interfaces fit; the concentric-project ceremony fights Go idiom
+  rust: good          # traits map cleanly onto ports
+  java: excellent
+  polyglot: awkward
+
+keyTradeoff: >-
+  Inward-only dependencies buy testability and swappable infrastructure at the price of indirection
+  and abstraction that simple CRUD paths never repay.
+
+overlay: clean
+
+sources:
+  - https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
+  - https://learn.microsoft.com/en-us/dotnet/architecture/modern-web-apps-azure/common-web-application-architectures
+  - https://herbertograca.com/2017/09/28/clean-architecture-standing-on-the-shoulders-of-giants/

package/catalog/architectures/cqrs.yaml

@@ -0,0 +1,58 @@
+id: cqrs
+name: CQRS (Command Query Responsibility Segregation)
+family: system
+oneLine: >-
+  Use a different model to update information than the model you use to read it — that is the
+  entire pattern.
+
+bestFor:
+  - Read-heavy workloads with genuinely asymmetric scaling, measured rather than assumed
+  - Task-based UIs over complex domains (BookHotelRoom, not SetReservationStatus)
+  - Collaborative domains where granular commands reduce merge conflicts
+  - Splitting write-domain and read-model/UI work across teams
+
+avoidWhen:
+  - A simple domain or a CRUD UI suffices — Azure states this outright
+  - Applied system-wide rather than to one bounded context; Fowler is explicit it belongs to a BoundedContext, not the system
+  - The team cannot name the specific asymmetry it solves
+  - You believe it requires event sourcing or separate databases — it requires neither, and the single-store version is nearly free
+
+complexity: medium
+teamSize: { min: 2, max: 200 }
+
+# derived, not from Richards — CQRS is not a column in the worksheet.
+# Calibrated against Richards' scale, rated for the common bounded-context-scoped form.
+# Separate-store CQRS shifts cost toward 2 and simplicity toward 2; single-store shifts both up.
+scores:
+  maintainability: 4
+  testability: 4
+  deployability: 2
+  simplicity: 3
+  scalability: 4
+  elasticity: 3
+  responsiveness: 4
+  fault-tolerance: 2
+  evolvability: 4
+  abstraction: 3
+  interoperability: 2
+  cost: 3
+
+stackFit:
+  typescript: good        # @nestjs/cqrs is mature and very easy to cargo-cult
+  python: workable        # thin ecosystem; most teams hand-roll, which is fine — the pattern is small
+  dotnet: excellent       # Wolverine, Mediator (source-generated), Brighter, or ~100 lines of dispatch
+  node: good
+  go: workable
+  rust: workable
+  java: good
+  polyglot: workable
+
+keyTradeoff: >-
+  Splitting the models costs nothing; splitting the stores buys eventual consistency for your entire
+  UX and you must then design for users acting on stale data.
+
+overlay: cqrs
+
+sources:
+  - https://martinfowler.com/bliki/CQRS.html
+  - https://learn.microsoft.com/en-us/azure/architecture/patterns/cqrs

package/catalog/architectures/ddd-tactical.yaml

@@ -0,0 +1,68 @@
+id: ddd-tactical
+name: DDD Tactical Patterns
+family: application
+oneLine: >-
+  The pattern set used to define domain models precisely within a bounded context — entities, value
+  objects, aggregates, domain and application services, domain events — applied after strategic DDD
+  has divided the system.
+
+bestFor:
+  - Complex, rule-heavy subsystems; Microsoft scopes DDD to advanced services tackling complex subsystems
+  - Domains derived from domain-expert knowledge with ever-changing business rules
+  - Finding service and module boundaries — design a service no smaller than an aggregate and no larger than a bounded context
+  - Distributed consistency, where database transactions cannot span boundaries and the domain must enforce its own invariants
+
+avoidWhen:
+  - The subsystem is data-driven or CRUD — Microsoft presents DDD as one option *versus* CRUD, not as the default
+  - You have no access to domain experts; the technique is learned from conversations and modelling sessions with them
+  - Logic would end up in service classes outside the entities, producing an anemic domain model that undermines the whole benefit
+  - The modelling cost cannot be repaid by the subsystem's actual rule complexity
+
+complexity: very-high
+teamSize: { min: 3, max: 150 }   # engine input — no primary source publishes a team size for this style
+
+# derived, not from Richards — application-level styles are not columns in the worksheet.
+# Same calibration convention as clean.yaml: runtime rows stay at monolith values, cost stays $ (=5).
+# The real expense here is modelling effort, not infrastructure — that signal lives in
+# simplicity (1) and complexity (very-high), not in the cost row.
+scores:
+  maintainability: 4
+  testability: 4
+  deployability: 2
+  simplicity: 1
+  scalability: 1
+  elasticity: 1
+  responsiveness: 3
+  fault-tolerance: 1
+  evolvability: 5
+  abstraction: 5
+  interoperability: 2
+  cost: 5
+
+stackFit:
+  typescript: good      # branded types express value objects, but they erase at runtime
+  python: workable      # frozen dataclasses cover value objects; invariants stay convention-only
+  dotnet: excellent     # records and readonly structs model identity and immutability directly
+  node: good
+  go: awkward           # no immutability, no sum types, so invariants are convention-only
+  rust: excellent       # algebraic types and ownership make value objects and invariants near-free
+  java: excellent       # records and sealed types
+  polyglot: awkward
+
+keyTradeoff: >-
+  Rich, invariant-enforcing domain models make complex business rules explicit and testable, at a
+  modelling cost that CRUD subsystems and expert-less teams cannot repay.
+
+# Guidance, not a layout — see `guidance` below. The engine enforces that every architecture
+# declares one or the other, so this is data rather than a comment nothing reads.
+guidance: >-
+  DDD's tactical patterns — entities, value objects, aggregates, repositories, domain events —
+  fill the core of whichever structural pattern you already chose. They tell you what goes
+  inside the domain folder that clean, hexagonal or modular-monolith created; they do not
+  dictate a folder layout of their own. An overlay here would invent a structure DDD does not
+  prescribe. Selecting this records the modelling decision in AGENTS.md and leaves the layout
+  to the architecture you pair it with.
+
+sources:
+  - https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-domain-driven-design
+  - https://learn.microsoft.com/en-us/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/