Iterating Ddd

Iterating DDD Workflow

Overview

Iterative DDD — adds new features to an existing DDD-structured codebase. Snapshots current code baseline first (via [snapshotting-code-context](../snapshotting-code-context/SKILL.md)), then routes through minimum necessary phases.

Routes: B (Extend existing BC) — requirement fits within existing boundaries, some phases skipped. C (Cross-domain) — requirement crosses/creates BC boundaries, all phases execute.

Foundational Principle: Iteration requires a code-derived baseline — not archived documents, not memory, not assumptions. The snapshot is mandatory. Route selection is a human decision — the agent must not default to Route B to avoid work. There is no shortcut threshold below which the snapshot or route evaluation may be skipped. Violating the letter of the rules is violating the spirit of the rules.

When to Use

• When adding new features to an existing DDD-structured codebase.
• When docs/ddd/ is empty (artifacts archived) and new requirements arrive.
• When the codebase already has Bounded Contexts, ports, adapters, and domain events in code.

Do NOT use when: starting a greenfield project from requirements (use [full-ddd](../full-ddd/SKILL.md)), fully restructuring an existing non-DDD project to DDD (use [restructuring-ddd](../restructuring-ddd/SKILL.md)), importing an existing technical document into DDD format (use [importing-technical-solution](../importing-technical-solution/SKILL.md)), adding features to an existing non-DDD codebase (use [piloting-ddd](../piloting-ddd/SKILL.md)), or modifying logic within a single established Bounded Context where the context map is unchanged (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md) directly — but verify docs/ddd/phase-4-technical-solution.md exists first).

Quick Reference

| Step | Action | Output | Gate | |:---|:---|:---|:---| | 0 | Pre-flight checks | Verified empty docs/ddd/, DDD structure confirmed, new requirement accepted | — | | 1 | Code snapshot | Baseline phase-*.md artifacts from code | Human confirms snapshot | | 2 | Route evaluation | Route plan document (B or C) | STOP: Human confirms route | | 3 | Delta Phase 1 → extracting-domain-events | New events table (delta) | B: Human / C: Autonomous | | 4 | Incremental Phase 2 — update Context Map (Route C only) | Updated context map with new/modified BCs | Autonomous (STOP/ASSUME) | | 5 | Delta Phase 3 — new contracts | New cross-context contracts | Autonomous (STOP/ASSUME) | | 6 | Phase 4 — new context tech decisions (Route C only) | 7-dimension decisions for new contexts | Autonomous (STOP/ASSUME) | | 7 | Phase 5 — Schema Merge → defining-schemas | Updated schema files + schema-manifest.md | Autonomous (STOP/ASSUME) | | 8 | Phase 6 — Behavior Contracts Merge → spec-driven-development | Updated behavior contracts + phase-6-behavior-contracts.md + phase-6/ | Autonomous (STOP/ASSUME) | | 9 | Project Init Gate | Assumptions confirmed + compilable project scaffold | Human must confirm | | 10 | Phase 7 → coding + TDD (affected contexts) | Domain code + tests for affected contexts | Human | | 11 | Archive | archive-artifacts.sh moves to archive/v{N}/ | — |

Route B (Extend existing BC):

Step 0 → 1 → 2 → 3 → [5 if new contracts needed] → [7 if schemas changed] → [8 if contracts OR event types changed] → 9 → 10 → 11

Route C (Cross-domain new functionality):

Step 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11

Subagent Dispatch I/O

All artifact paths below are relative to docs/ddd/. decisions-log.md and assumptions-draft.md are passed as context to every subagent and omitted from the table for brevity. Steps marked (C only) execute on Route C only; (conditional) steps have route-specific conditions documented in the Implementation section.

| Dispatch Step | Subagent Skill | Input Artifacts | Output Artifacts | |:---|:---|:---|:---| | Step 1 | snapshotting-code-context | Project codebase (Glob/Read scan) | phase-1-domain-events.md, phase-2-context-map.md, phase-3-contracts.md, phase-4-technical-solution.md (all baseline) | | Step 3 | extracting-domain-events | phase-1-domain-events.md (baseline), new requirement text | Updated phase-1-domain-events.md with [ITERATION: v{N+1}] section | | Step 4 (C only) | mapping-bounded-contexts | phase-2-context-map.md (baseline), phase-1-domain-events.md (with delta) | Updated phase-2-context-map.md, updated constraint files | | Step 5 (conditional) | designing-contracts-first | phase-1-domain-events.md (with delta), phase-2-context-map.md (updated or baseline) | Updated phase-3-contracts.md with [ITERATION: v{N+1}] section | | Step 6 (C only, new BC) | architecting-technical-solution | phase-2-context-map.md, phase-3-contracts.md, phase-4-technical-solution.md (existing) | Updated phase-4-technical-solution.md with [ITERATION: v{N+1}] section | | Step 7 (conditional) | defining-schemas | phase-1-domain-events.md, phase-2-context-map.md, phase-3-contracts.md, phase-4-technical-solution.md, existing schema files (via schema-manifest.md) | Updated schema files + schema-manifest.md | | Step 8 (conditional) | spec-driven-development | phase-1-domain-events.md, phase-2-context-map.md, phase-3-contracts.md, phase-4-technical-solution.md, schema files (via schema-manifest.md) | Updated phase-6-behavior-contracts.md + phase-6/*.md | | Step 10 (per context) | coding-isolated-domains + test-driven-development | phase-6-behavior-contracts.md, phase-6/{context}.md, schema files (via schema-manifest.md) | Domain code + tests, test-map.md, test-coverage.md |

Ambiguity Handling

Follow the [Ambiguity Handling Protocol](../ddd-protocol/ambiguity-handling-reference.md) throughout.

Iteration STOP Triggers

| Ambiguity | Why STOP | |:---|:---| | Route B vs Route C cannot be determined from the requirement | Route selection drives which phases execute — wrong route means missing or redundant work | | New requirement touches a BC boundary that is ambiguous in the snapshot | BC boundary changes cascade to contracts and tech decisions — must confirm before proceeding | | Unclear whether new events belong to an existing BC or require a new one | Wrong assignment creates coupling or misses necessary contracts | | Snapshot artifacts were rejected by human but no corrections provided | Cannot proceed with unconfirmed baseline |

Iteration ASSUME & RECORD

| Ambiguity | Default assumption | |:---|:---| | New events fit naturally in an existing BC based on domain language | ASSUME they belong to the nearest BC by language affinity; record for review | | Existing relationship pattern (e.g., ACL) still applies after adding new events | ASSUME relationship unchanged; record for verification at Project Init Gate | | New requirement doesn't mention a technology choice | ASSUME existing technology stack applies; record assumption | | UL terms in new requirement match existing dictionary entries | ASSUME same meaning; record for disambiguation |

Session Recovery

Before starting any step work, check for an existing DDD workflow:

1. Check if docs/ddd/ddd-progress.md exists.
2. If it exists with workflow_mode: iterate: Read ddd-progress.md and ALL persisted artifact files:

• docs/ddd/route-plan.md (Route B/C evaluation result)
• docs/ddd/phase-1-domain-events.md (snapshot baseline + delta events)
• docs/ddd/phase-2-context-map.md (baseline, updated if Route C)
• docs/ddd/phase-3-contracts.md (baseline + new contracts)
• docs/ddd/phase-4-technical-solution.md (baseline + new context decisions if Route C)
• docs/ddd/schema-manifest.md (if Phase 5 reached)
• docs/ddd/phase-6-behavior-contracts.md + docs/ddd/phase-6/*.md (if Phase 6 reached)
• docs/ddd/test-map.md, docs/ddd/test-coverage.md (if Phase 7 reached)
• docs/ddd/assumptions-draft.md (accumulated ASSUME entries, if not yet cleared)
• docs/ddd/decisions-log.md

Resume from the first incomplete step. Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.

1. If it does not exist: Start at Step 0.

Persisted artifacts contain human-approved decisions and are authoritative. Do not discard or re-do completed steps unless the user explicitly requests a rollback.

Implementation (Interactive Orchestration)

CRITICAL RULE: You are the orchestrator. The code snapshot (Step 1) and route evaluation (Step 2) are mandatory — never skip them. Route selection is a human decision — never default to Route B to minimize work. The Project Init Gate (Step 9) is a mandatory hard stop — never bypass it.

CRITICAL RULE: Sub-Skill Loading. Before executing any step that delegates to a sub-skill (linked via [skill-name](path)), you MUST read the sub-skill's SKILL.md file into your context using the Read tool. The markdown link is a file path — the sub-skill's rules, rationalization table, and red flags are binding constraints for that step. Operating without reading the sub-skill file means operating without anti-hallucination constraints for that step.

Step 0: Pre-flight Checks

1. Check docs/ddd/ state:

• If phase-*.md files exist → STOP: "Current artifacts exist. Are these up to date, or should I rebuild from code?"
• If docs/ddd/ is empty or absent → proceed.

1. Verify DDD structure: Glob scan for domain directories (internal/biz/, internal/domain/, src/*/domain/, or similar). If no DDD structure found → STOP: "This project doesn't appear to have DDD structure. Consider [piloting-ddd](../piloting-ddd/SKILL.md) for brownfield DDD introduction (existing non-DDD codebase), or [full-ddd](../full-ddd/SKILL.md) for greenfield from PRD."
2. Accept new requirement: Ask the user to provide the new requirement (PRD, feature spec, or description).
3. Initialize progress tracker: Create docs/ddd/ddd-progress.md from the iteration template (templates/ddd-progress-iterate.md).
4. Enforce platform hooks: Follow the [Hooks Enforcement Protocol](../ddd-protocol/persistence-defense-reference.md#hooks-enforcement-protocol) — detect platform, set up or merge hooks from templates, update the Hooks field in ddd-progress.md. HARD STOP if setup fails.

Step 1: Code Snapshot → snapshotting-code-context

Execute [snapshotting-code-context](../snapshotting-code-context/SKILL.md) to rebuild baseline artifacts from the current code.

Gate: Human must confirm the snapshot artifacts before proceeding. Verify that docs/ddd/phase-*.md files contain no unconfirmed [INFERRED] markers. If any [INFERRED] markers remain after human review, they must be resolved (Confirm / Revise / Remove) before proceeding to Step 2.

After confirmation, update ddd-progress.md: snapshot status = complete.

Step 2: Route Evaluation

Compare the new requirement against the baseline artifacts to determine the iteration route.

Evaluate using the 4-question table and detailed criteria in [route-evaluation-reference.md](./route-evaluation-reference.md). Mixed signals → recommend Route C. Only pure 4-for-4 Route B → recommend Route B. Human makes the final decision.

Produce a route plan using the template (templates/route-plan.md).

STOP — present the route plan to the human:

Checkpoint: "Here is the route evaluation with my reasoning for each question. Mixed signals default to Route C. Do you agree with this route, or do you want to override?"

The human may override. If the human chooses a different route, update the plan and proceed with their choice.

Persist the route plan to docs/ddd/route-plan.md. Update ddd-progress.md.

For Steps 3-8 (Autonomous Mode), follow the [Per-Phase Subagent Dispatch Protocol](../ddd-protocol/subagent-dispatch-reference.md) for STOP handling and subagent invocation. Common post-dispatch rule: After each subagent returns, verify the expected output artifact exists, update ddd-progress.md, and follow the dispatch protocol for STOP handling.

Route B step-skip decision table (Route C always executes all steps):

| Step | Condition to EXECUTE in Route B | Condition to SKIP | |:---|:---|:---| | 3 (Phase 1) | Always | Never | | 4 (Phase 2) | Never in Route B | Always skip | | 5 (Phase 3) | New cross-context communication identified | All communication within existing contracts | | 6 (Phase 4) | Never in Route B | Always skip | | 7 (Phase 5) | Any new contracts (Step 5 ran) OR any new event types (Step 3) | Zero new contracts AND zero new event types | | 8 (Phase 6) | Any new contracts OR any new event types | Zero new contracts AND zero new event types |

Step 3: Delta Phase 1 → extracting-domain-events (subagent)

Condition: Always runs.

Present baseline events alongside new events. Gate: Route B = human approval (last checkpoint before Project Init Gate). Route C = autonomous. If human identifies events for a new BC → upgrade to Route C.

Dispatch [extracting-domain-events](../extracting-domain-events/SKILL.md) with baseline + new requirement. Verify: phase-1-domain-events.md contains [ITERATION: v{N+1}] section.

Step 4: Incremental Phase 2 — Update Context Map (subagent)

Condition: Route C only. Route B skips this step.

Dispatch [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) with baseline + delta events. Iteration-specific: (1) find events that don't fit existing BCs, (2) propose new BC boundaries, (3) update existing BCs' event lists + UL, (4) check new cross-context deps.

Verify: phase-2-context-map.md updated + constraint files + CLAUDE.md DDD section.

Step 5: Delta Phase 3 — New Contracts (subagent)

Condition:

• Route B: Execute only if the new requirement introduces new cross-context communication not covered by existing contracts. Skip if all communication stays within existing contract boundaries.
• Route C: Always execute.

Dispatch [designing-contracts-first](../designing-contracts-first/SKILL.md) with delta events + context map (updated or baseline for Route B). Verify: phase-3-contracts.md contains [ITERATION: v{N+1}].

Step 6: Phase 4 — New Context Tech Decisions (subagent)

Condition: Route C only, and only when a new Bounded Context was created in Step 4. Route B and Route C without new BCs skip this step.

Dispatch [architecting-technical-solution](../architecting-technical-solution/SKILL.md) for new BC only. Reference existing decisions for consistency. Verify: phase-4-technical-solution.md contains [ITERATION: v{N+1}].

Step 7: Phase 5 — Schema Merge → defining-schemas (subagent)

Condition: Run if any contracts or tech decisions changed in Steps 3-6, OR if new event types were added in Step 3 (new events need event schemas). Route B skips only if zero new contracts AND zero new event types.

Dispatch [defining-schemas](../defining-schemas/SKILL.md) (auto-detects Merge/Generate). Verify: schema files + schema-manifest.md updated. Continue to Step 8.

Step 8: Phase 6 — Behavior Contracts Merge → spec-driven-development (subagent)

Condition: Run if any contracts changed in Steps 3-6 (new events, updated context map, new contracts, or new tech decisions). Route B skips this step ONLY if no new contracts were added AND zero new event types occurred in Step 3. (New event types create new event schemas in Step 7 that require corresponding behavior contract updates.)

Dispatch [spec-driven-development](../spec-driven-development/SKILL.md) (auto-detects Merge/Generate) with all Phase 1-5 artifacts. Verify: phase-6-behavior-contracts.md + phase-6/ updated. Proceed to Project Init Gate.

Step 9: Project Init Gate

MANDATORY hard stop before any coding begins.

1. Present to the developer:

• Baseline summary (from snapshot — what ex

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.