SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsddd-openspec-bridge

ddd-openspec-bridge

Coding & development

View repository

Updated 10-16 01:39

About this skill

DDD OpenSpec Bridge

English version: English

When to Use

  • Tactical modeling (Stage III) is complete, the model has passed validation (Stage IV), and it is ready to enter the development phase.
  • The domain model needs to be converted into a structured engineering specification that can be executed by an AI Agent or developers.
  • A "single source of truth" (Source of Truth) needs to be established between the business model and the code implementation.

Input Requirements

  • Required：
    • Problem space definition (from ddd-scope）
    • Subdomain classification and core domain declaration (from ddd-subdomains）
    • Context catalog and ADRs (from ddd-contexts）
    • Context mapping and integration patterns (from ddd-context-map）
    • Aggregate catalog and invariants (from ddd-aggregates）
    • Domain interaction definitions: domain events, domain services, repository interfaces, factories (from ddd-domain-interactions）
  • Optional：
    • Discovery phase event flows and boundary clues (from ddd-discover）
    • Model validation report (from ddd-model-review）
  • Execution Standards: The mapping logic must follow the standard definitions in ddd-openspec-mapping.md .

Process

  1. Initialize the OpenSpec change set: Under openspec/changes/<change-id>/ , create a directory and generate the .openspec.yamlfor this change. Note: this is different from the global openspec/config.yaml —the latter is maintained once by the ddd-contexts stage and is used to declare the domain-bounded context mapping and architectural constraints.
  2. Generate the Proposal (proposal.md）：
    • Map the problem statement of ddd-scope to Why.
    • Write the Capabilities involved in this change into What Changes; organize priorities according to the classification in ddd-subdomains :Core subdomainmust be fully Scenario-ized,Generic subdomainmay reference existing specifications or external components.
    • In Impact, list the affected Capabilities and the aggregate change list; in Goals, define success criteria (SLO / acceptance metrics).
  3. Establish the Bounded-Context directory: According to the context catalog in ddd-contexts , under specs/<bounded-context>/<capability>/spec.md , establish a specification file for each capability.Using a flat specs/domain-model/ directory is prohibited—it would break the strategic alignment between bounded contexts and the domain catalog.
  4. Write Requirements and Scenarios(strictly following the mapping direction of ddd-openspec-mapping.md §2.1 ):
    • Requirement ← ddd-domain-interactions commands and domain services in ; one Requirement corresponds toone independently verifiable business capability, the number of Scenarios ≤ 5 and does not cross aggregate roots.
    • Scenario ← ddd-aggregates aggregate behaviors and invariants in , described as Given/When/Then; P0-level invariants must have corresponding Scenarios.
    • Domain eventsare written as side effects in the Then/And clauses of the Scenario (e.g., "And publish the OrderPlaced event").
    • Business rules first: Scenarios only describe business rules and invariants, and must not leak technical details such as databases, HTTP, ORM, or caching.
  5. Ubiquitous language validation: Against the glossary in ddd-contexts , ensure that proposal.md and all terms in spec.md fall within the glossary; terms not included must first be written back to the glossary or replaced with synonyms.
  6. Design the technical solution (design.md）: Integrate ddd-context-map integration patterns with ddd-domain-interactions collaboration mechanisms; describe layered architecture mapping, cross-context translation (ACL), event publishing/consuming paradigms (Outbox pattern, idempotency keys, only one aggregate modified per transaction—see ddd-openspec-mapping.md Appendix A）。
  7. Break down development tasks (tasks.md）: break down tasks in Spec dependency order (Domain Model → Repository → Application Service → API/Integration), with each task linked to the corresponding Requirement or Scenario as acceptance criteria.

Output

Artifact Structural Requirements
proposal.md Includes Why, What Changes, Impact (Capabilities / aggregate changes), Goals.
design.md Includes architecture design, data model mapping, core data flows, interface protocol definitions.
specs/ directory Subfolders organized by capability, containing spec.md(Requirement + Scenario format).
tasks.md Includes task title, task description, linked Spec path, acceptance criteria.

Validation Checklist

  • The OpenSpec directory structure conforms to the specification (config, specs, changes);specs/ organized into directories by bounded context, with no flat domain-model/。
  • Requirement granularity meets the standard: each Requirement corresponds to one independently verifiable business capability, with ≤ 5 Scenarios and no crossing of aggregate roots.
  • Scenarios maintain business-rule priority: no technical details such as databases, HTTP, ORM, or caching appear; all ddd-aggregates P0 invariants have been converted into Scenarios.
  • Terminology consistency：proposal.md and all spec.md terminology can be found in the ddd-contexts glossary;proposal.md Capabilities are consistent with ddd-contexts .
  • Event-driven paradigm implemented: cross-aggregate scenarios in design.md explicitly follow the Outbox pattern, idempotency keys, and the "only one aggregate modified per transaction" constraint.
  • Iteration pace controllable (small steps, fast pace): the scale of this change set can complete the convergence of specification and code within a single Apply phase, without sliding into a mini-waterfall.
  • tasks.md tasks are executable, and each task has an explicit Requirement / Scenario reference as acceptance criteria.
  • Chinese and English typography conforms to project standards (spaces between Chinese and English, backticks around proper nouns).

Backtracking Triggers

  • When writing Scenarios, domain logic is found to be ambiguous or conflicting → backtrack to ddd-aggregates or ddd-domain-interactions。
  • A certain integration pattern cannot be clearly expressed under the OpenSpec structure → backtrack to ddd-context-map。
  • Technical details (database / HTTP / ORM, etc.) cannot be removed from Scenarios → violates the business-rule priority principle; first rewrite within this Skill, and if the semantics still cannot be purified, backtrack to ddd-aggregates to redefine aggregate behavior.
  • A single Requirement carries more than 5 Scenarios or spans multiple aggregate roots → violates the granularity convention, backtrack to ddd-domain-interactions to split commands and domain services.
  • Terminology is not included in the ddd-contexts glossary → backtrack to ddd-contexts to add or unify terminology.

Examples

@ddd-openspec-bridge
根据已完成的"会议室预订系统"建模产出，生成 OpenSpec 变更集规范：
- 聚合：Booking, RoomSchedule
- 关键流程：预订申请、冲突检测、签到、取消
- 上下文：Booking Context, Room Catalog Context
请输出 proposal.md, design.md 以及 specs/booking-context/booking/spec.md 的核心 Requirement 与 Scenario 片段。

For a complete demonstration of Requirement / Scenario writing, see ddd-openspec-mapping.md §5(an end-to-end minimal viable example using "user registration" as the example).