Domain Analysis

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
• User-question prompts mean to ask the user directly in Codex.
• Ignore Claude-specific mode-switch instructions when they appear.
• Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
• For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
• If a required step/tool cannot run in this environment, stop and ask the user before adapting.

Codex Project-Reference Loading (No Hooks)

Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.

Always read:

• docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
• docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
• docs/project-reference/lessons.md (always-on guardrails and anti-patterns)

Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.

Situation-based docs:

• Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): project-structure-reference.md
• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec authoring, docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
• Behavior/public-contract changes or spec-test-code sync: workflow-spec-test-code-cycle-reference.md plus the spec docs above
• Derived spec indexes/ERDs/reimplementation guides: spec-system-reference.md and source Feature Specs under docs/specs/
• Integration test implementation/review: integration-test-reference.md
• E2E test implementation/review: e2e-test-reference.md
• Code review/audit work: code-review-rules.md plus domain docs above based on changed files

Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Analyze business domain (bounded contexts, aggregates, entities, VOs, domain events, cross-context relationships) and generate a domain model report + ERD — producing a user-validated DDD domain model with correct bounded contexts, aggregate boundaries, and event flows so downstream implementation builds on the right invariants and avoids costly boundary rework after consumers depend on them.

Summary:

• Purpose: turn business artifacts into a user-validated DDD domain model (bounded contexts, aggregates, entities, VOs, domain events, ERD) so downstream code builds on correct invariants — never re-cut boundaries after consumers depend on them.
• Ten ordered steps (do all, none skippable): 0 locate active plan + domain-entities-reference.md → 1 load business context (nouns→entities, verbs→events) → 2 identify bounded contexts → 3 model entities & aggregates → 4 map relationships → 5 domain events → 6 generate Mermaid ERD → 7 user-validation interview → 8 entity-change assessment vs reference doc → 9 update plan.md ## Domain Model.
• Drive the model from business artifacts, not guesses: load plan/PBI/business-eval inputs and domain-entities-reference.md, then extract nouns→entities, verbs→events, roles, and processes before classifying anything.
• Every concept passes the Entity-vs-VO matrix and aggregate boundary rules (≤5 entities, one transaction, reference-by-ID only, root is the sole mutation entry) — flag primitive obsession and anemic models as you go.
• User validation is non-skippable: present bounded contexts and the Mermaid ERD, then run the 5-8 question ask the user directly interview to confirm boundaries, aggregate roots, and event flows before marking the model confirmed.
• Close the loop on persistence: reconcile findings against domain-entities-reference.md (new/modified/deprecated), update the ## Domain Model section of plan.md, and keep cross-context communication event-driven with {AggregateNoun}{PastTenseVerb} naming and no cross-service FKs.

Workflow:

0. Locate Active Plan & Domain Reference — Glob plans/*/plan.md, read plan + prior research + domain-entities-reference.md; set {plan-dir}
1. Load Business Context — Read idea, business evaluation, refined PBI artifacts; extract nouns→entities, verbs→events, roles, processes
2. Identify Bounded Contexts — Group related concepts, define context boundaries (validate grouping with user)
3. Model Entities & Aggregates — Define aggregates, entities, value objects per context
4. Map Relationships — Entity relationships, cross-context integration points (context map)
5. Domain Events — Identify events crossing context boundaries, {AggregateNoun}{PastTenseVerb}
6. Generate ERD — Mermaid ER diagram with all entities and relationships
7. User Validation — Present model, ask 5-8 questions, confirm decisions → status: confirmed
8. Domain Entity Change Assessment — Compare against domain-entities-reference.md, update/create if needed
9. Update Main Plan — Append/update ## Domain Model section of {plan-dir}/plan.md

Key Rules:

• MANDATORY IMPORTANT MUST ATTENTION validate every bounded context boundary with user
• MANDATORY IMPORTANT MUST ATTENTION include Mermaid ERD diagram in report
• MANDATORY IMPORTANT MUST ATTENTION run user validation interview at end (NEVER skip)
• Every entity belongs to exactly one bounded context
• Cross-context communication via domain events only — NEVER direct references

Be skeptical. Every claim needs traced proof, confidence percentages >80% to act.

DDD Reference: Strategic Design

Bounded Context Rules

Ubiquitous Language Rules:

• Every noun in codebase matches domain expert vocabulary exactly (not "User" when the domain says "Customer")
• Class/method/variable names reflect ubiquitous language — zero translation layers inside bounded context
• Developers say "we call it X but domain means Y" → model is wrong, fix it

Context Map Pattern Decision Table

ACL — when to use: Upstream is external/legacy/third-party (Salesforce, SAP, Workday). Upstream types NEVER cross ACL into domain model.

Shared Kernel — when NOT to use: Teams cannot coordinate on every change → use Customer-Supplier + Published Language instead.

DDD Reference: Entity vs Value Object

Decision Matrix

Fast heuristics:

• Replace with equal-valued copy → breaks nothing? → Value Object
• Must be tracked across time or fetched by ID? → Entity
• Always retrieved as part of another object? → likely Value Object
• Two instances with same data are interchangeable? → Value Object

Canonical Value Objects

Primitive Obsession → Value Object Mapping

Rule: Primitive with validation rules, formatting, or always passed grouped with other primitives → missing Value Object.

Value Object Construction Pattern

A VO is self-validating: invariants enforced at construction via a factory (no public constructor that can produce an invalid instance), immutable, and equality-by-value. The base class and factory names below are one illustrative instantiation — translate to your language's equivalents.

Example (illustrative — adapt to your language):

// Self-validating VO — never an invalid instance in memory
public sealed class Email : ValueObject<Email>
{
    private Email(string value) { Value = value; }
    public string Value { get; }

    public static Email Of(string raw)
    {
        var normalized = raw?.Trim().ToLowerInvariant();
        if (string.IsNullOrWhiteSpace(normalized) || !IsValidFormat(normalized))
            throw new DomainException($"Invalid email: {raw}");
        return new Email(normalized);
    }
}

Rules:

• No public constructor without validation — factory method (Of() / Create()) enforces invariants
• VOs can reference other VOs; VOs NEVER reference entities (lifecycle coupling)
• Mutation means replacement: email = Email.Of(newValue), NEVER email.Value = newValue

VO Persistence Strategies

Rule: VOs NEVER have own table with primary key — that makes them entities by infrastructure.

DDD Reference: Entity Design

Identity Strategies

Rules:

• Prefer ULID for new entities — sortable, no coordination overhead
• NEVER use email/username as PK — users change them
• Cross-service references use same ID type as the owning service

Rich vs Anemic Domain Model

Tell Don't Ask Principle:

• BAD: if (order.Status == Confirmed) { order.Status = OnHold; } (external ask + mutate)
• GOOD: order.Hold(reason) (entity enforces its own invariants)

Entity Invariant Enforcement

A rich entity guards its own state: a private constructor reserved for ORM/persistence hydration, named factory methods for valid creation, and intent-named mutation methods that reject invalid transitions and emit domain events. The base class, guard helper, and ID generator below are one illustrative instantiation — substitute your language's equivalents.

Example (illustrative — adapt to your language):

public class Order : AuditedAggregateRoot<Order, string>
{
    private Order() { }  // ORM hydration only

    public static Order Create(string name, Email email, WarehouseId warehouseId)
    {
        Guard.NotNullOrWhitespace(name, nameof(name));
        Guard.NotNull(email, nameof(email));
        return new Order
        {
            Id = Ulid.NewUlid().ToString(),
            Name = name,
            Email = email,
            WarehouseId = warehouseId,
            Status = OrderStatus.Confirmed
        };
    }

    public void Cancel(string reason, DateOnly cancellationDate)
    {
        if (Status == OrderStatus.Cancelled)
            throw new DomainException("Order already cancelled");
        if (cancellationDate < DateOnly.FromDateTime(DateTime.UtcNow))
            throw new DomainException("Cancellation date cannot be in the past");

        Status = OrderStatus.Cancelled;
        CancellationReason = reason;
        CancellationDate = cancellationDate;
        AddDomainEvent(new OrderCancelledDomainEvent(Id, cancellationDate));
    }
}

Entity Lifecycle State Machines

Document ALL transitions explicitly. Unmodeled transitions throw DomainException.

Draft → Submitted (Submit())
Submitted → Approved (Approve(approverId))
Submitted → Rejected (Reject(reason))
Approved → Active (Activate())
Active → Suspended (Suspend(reason))
Suspended → Active (Reinstate())
Active → Archived (Archive())

Domain Validation Layers

Decision rule:

• Rule requires loading another aggregate? → Application service
• Rule needs only data within aggregate? → Entity method
• Rule concerns single value's format? → Value Object constructor

Factory Methods on Entities

Use when: construction requires domain logic, multiple paths, raises domain events, or object graph initialization.

Naming:

• Order.Create(...) — primary creation
• Order.Place(...) — semantically loaded creation (domain language)
• Private constructor — ORM hydration only, NEVER called directly

Temporal (Bi-Temporal) Entities

Two time axes: valid time (fact true in real world) + transaction time (recorded in system).

ProductPrice {
    validFrom: DateOnly     // valid time: price effective from
    validTo: DateOnly       // valid time: price effective until
    recordedAt: DateTime    // transaction time: when entered into system
}

Use when: regulatory compliance, retroactive corrections, "as-of" queries.

DDD Reference: Aggregate Design

Aggregate Boundary Rules

1. Invariant scope — boundary = objects needed to enforce invariants atomically
2. Transaction boundary — exactly one database transaction per aggregate operation
3. Consistency scope — must be consistent atomically? same aggregate. Eventual consistency acceptable? separate aggregates
4. Small aggregates preferred — fewer members = fewer transaction conflicts = better scalability

Aggregate Size Heuristics

Aggregate Root Responsibilities

1. Maintain all invariants across all members
2. All mutation paths go through root (child entities NEVER directly accessible from outside)
3. Emit domain events for significant state changes
4. Control creation of child entities (factory methods on root)
5. Assign IDs to child entities

Rule: Outside code NEVER holds direct reference to non-root entity within aggregate.

Cross-Aggregate References

Aggregate Invariant Enforcement

All mutation flows through the aggregate root, which checks every invariant before applying a change and recomputes derived state so no member can be left inconsistent. The throw-on-violation idiom below is one illustrative instantiation — your language may surface invariant breaches differently (exceptions, result types).

Example (illustrative — adapt to your language):

public void AddLineItem(ProductId productId, int quantity, Money unitPrice)
{
    if (Status != OrderStatus.Draft)
        throw new DomainException("Cannot modify confirmed order");
    if (LineItems.Count >= 50)
        throw new DomainException("Order cannot exceed 50 line items");

    var item = OrderLineItem.Create(productId, quantity, unitPrice);
    _lineItems.Add(item);
    RecalculateTotal();  // invariant: Total == sum(lineItems)
}

Aggregate Design Patterns

When to Break Aggregate Rules (Pragmatic DDD)

Rule: Breaking aggregate rules acceptable ONLY when explicitly documented as technical debt with mitigation plan.

DDD Reference: ERD Design

Cardinality Types

M:N rule: Relationship has attributes (date joined, role) → make join table explicit named entity.

1:1 decision: Same concept with optional attributes → same table. Different concepts with independent lifecycles → separate tables with FK.

Normalization Targets

Rule: 3NF for OLTP write models; denormalize only in read models/projections with documented justification.

Identifying vs Non-Identifying Relationships

Mapping to DDD: Identifying relationship → child entity inside parent aggregate. Non-identifying FK → likely separate aggregates.

ERD for Microservices

• Each bounded context has its OWN ERD — NEVER cross-service entity arrows
• Cross-service references shown as ExternalEntityId (string/ULID) — ID only, no relationship line
• Shared data shown as replicated/synced data note, NEVER shared table
• Event-sourced aggregates: ERD shows current state projection, not event stream

ERD Anti-Patterns

ERD to Aggregate Mapping

DDD Reference: Domain Events

Event Naming Conventions

Format: {AggregateNoun}{PastTenseVerb} — what happened, not what to do.

Event Payload Design Rules

Domain Events vs Integration Events

Rule: Domain event raised → in-process handlers fire → if cross-service needed, handler publishes integration event to message bus.

Event Versioning Strategies

Backward compatibility rules:

• Adding optional field → backward compatible
• Removing or renaming field → breaking
• Changing field type → breaking

DDD Reference: Repository Pattern

Interface Design Principles

1. One repository per aggregate root — NEVER one for child entities
2. Domain language in methods — GetConfirmedOrdersInWarehouse() not FindAll(e => e.Status == Active)
3. Return domain objects — repositories return entities, not DTOs
4. No infrastructure concerns — no leaked query/ORM types or connection strings in the interface.
5. Async-first — methods return the configured runtime's async primitive.

Repository vs DAO

Query Objects — When to Use Specification

Use when: rule used in multiple places, warrants naming + testing, needs composition.

A specification names a query predicate as a reusable, composable, testable unit owned by the domain. The expression-tree form below is one illustrative instantiation — your language may model it as a predicate function, query builder, or specification object.

Example (illustrative — adapt to your language):

// Static expression on entity — composable, testable
public static Expression<Func<Order, bool>> ByWarehouseExpression(string warehouseId)
    => o => o.WarehouseId == warehouseId && o.Status == OrderStatus.Confirmed;

When NOT to use Specification: Simple single-use predicate → inline lambda. Rule only used once → repository method directly.

DDD Reference: Anti-Patterns Quick Reference

Skill Workflow

Step 0: Locate Active Plan & Domain Reference (MANDATORY)

1. Glob plans/*/plan.md sorted by modification time — find active plan directory
2. Read plan.md — project scope, goals, prior decisions
3. Read all {plan-dir}/research/*.md — avoid duplicating prior work
4. Read docs/project-reference/domain-entities-reference.md (if exists) — project's single source of truth for domain entities
5. Set {plan-dir} variable — all outputs write to this directory

If no plan directory, create using naming convention from session context.

MUST ATTENTION update {plan-dir}/plan.md with domain model summary section after completing analysis.

Step 1: Load Business Context

Read artifacts from prior workflow steps (search plans/ + team-artifacts/):

• Active plan ({plan-dir}/plan.md) — scope, goals, constraints
• Business evaluation report — value proposition, customer segments
• Refined PBI — acceptance criteria, user stories, features
• Discovery interview notes — problem statement, user roles

Extract and list:

• Nouns — Candidate entities (user, order, product, etc.)
• Verbs — Candidate domain events (created, approved, assigned, etc.)
• Roles — User types with different permissions/views
• Processes — Business workflows (application flow, review cycle, etc.)

Step 2: Identify Bounded Contexts

Group related entities using DDD principles. Apply context boundary signals from reference table above.

### Bounded Context: {Name}

**Purpose:** {What this context owns — one sentence}
**Classification:** Core domain / Supporting / Generic
**Key Responsibility:** {primary business capability}
**Team ownership:** {suggested team or role}
**Ubiquitous language:** {key terms and their meaning in this context}

Context boundary tests:

• Same term used by two teams with different meanings? → separate contexts
• Two entities with same name but different invariants? → separate contexts
• Can this context be worked on without understanding the other? → good separation

MANDATORY IMPORTANT MUST ATTENTION present identified contexts to user by asking the user directly:

• "I identified {N} bounded contexts: {list}. Does this grouping make sense?"
• Options: Agree (Recommended) | Merge {X} and {Y} | Split {Z} | Add missing context

Step 3: Model Entities & Aggregates

Per bounded context: classify each concept using Entity vs VO matrix above, then apply aggregate boundary rules.

### {Context Name}

**Aggregate Root:** {EntityName}
**Identity:** {ULID / UUID / Natural key — justify}
**Lifecycle states:** {Draft → Active → Archived, etc.}

- **Child Entities:** {list — share aggregate boundary, identifying FK}
- **Value Objects:** {list — immutable, no identity, embedded}
- **Invariants:** {business rules this aggregate enforces atomically}
- **Factory method:** {Order.Create(...) / Order.Place(...)}

**Other Aggregates in this Context:**

- {Entity} — {purpose, identity strategy, lifecycle}

Entity Detail Template

…(truncated)