# Piloting Ddd

> Use when adding new features to an existing non-DDD codebase (legacy, monolith, "屎山") and wanting to introduce DDD discipline. Use when the project has no DDD structure (no ports, adapters, bounded contexts) but needs a clean new feature. Use when asked to "add DDD to legacy code", "build a clean feature in a messy codebase", "introduce DDD without rewriting everything", or "create a DDD island i…

- **Type:** Skill
- **Install:** `agentstack add skill-lockp111-agent-ddd-engineering-piloting-ddd`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lockp111](https://agentstack.voostack.com/s/lockp111)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lockp111](https://github.com/lockp111)
- **Source:** https://github.com/lockp111/agent-ddd-engineering/tree/main/skills/piloting-ddd

## Install

```sh
agentstack add skill-lockp111-agent-ddd-engineering-piloting-ddd
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Piloting DDD Workflow

## Overview

Brownfield DDD introduction — adds a clean DDD "island" alongside existing non-DDD legacy code. Maps legacy landscape first, then builds the island through the DDD pipeline.

Routes: **A (Full DDD Island)** — complete BC with full pipeline. **D (Disciplined Extension)** — clean code with ACL contracts without full BC ceremony.

**Foundational Principle:** Legacy code gets minimal touch (additive only, never modify existing logic). ACL adapters are the mandatory bridge — never skip them, never let legacy concepts leak into the domain. Route selection is a **human decision** — the agent must not recommend Route D to minimize work. There is no simplicity threshold below which the landscape scan, impact analysis, or ACL 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 non-DDD codebase (legacy, monolith, 屎山).
- When introducing DDD for the first time in a project that has no DDD structure.
- When the codebase uses MVC, layered, or no discernible architecture pattern.

**Do NOT use when:** the project already has DDD structure (use [iterating-ddd](../iterating-ddd/SKILL.md)), fully restructuring the entire codebase to DDD (use [restructuring-ddd](../restructuring-ddd/SKILL.md)), starting from scratch with no existing code (use [full-ddd](../full-ddd/SKILL.md)), or importing an existing technical document (use [importing-technical-solution](../importing-technical-solution/SKILL.md)).

## Quick Reference

| Step | Action | Output | Gate |
|:---|:---|:---|:---|
| 0 | Pre-flight checks (confirm non-DDD, has code, accept requirement) | Confirmed status | — |
| 1 | Legacy landscape mapping → `mapping-legacy-landscape` | `legacy-landscape.md` | Human confirms landscape |
| 2 | Impact analysis + interaction type classification | `impact-analysis.md` (with Interaction Types) | Autonomous; MODIFY ≥ 1 → STOP |
| 3 | Boundary proposal + Legacy Touch Register | `boundary-proposal.md` (ACL directions + legacy touch list) | **STOP: Human confirms boundary + legacy changes** |
| 4 | **Scope Gate** (Route A: full island / Route D: disciplined extension) | Scope decision | **STOP: Human chooses** |
| 5 | Phase 1 → `extracting-domain-events` (new requirement only) | Events table | A: Human / D: Autonomous |
| 6 | Minimal Phase 2 — define new BC + relationships to legacy | Context Map (minimal version) | Autonomous (STOP/ASSUME) |
| 7 | Phase 3 → `designing-contracts-first` (ACL contracts focus) | ACL port interfaces + Legacy Adapter Specs | Autonomous (STOP/ASSUME) |
| 8 | Phase 4 → `architecting-technical-solution` (DDD island only) | 7-dimension decisions (with legacy tech constraints) | Autonomous (STOP/ASSUME) |
| 9 | Phase 5 → defining-schemas (Generate mode) | Schema files + schema-manifest.md | Autonomous (STOP/ASSUME) |
| 10 | Phase 6 → spec-driven-development | Behavior contracts + phase-6-behavior-contracts.md + phase-6/ | Autonomous (STOP/ASSUME) |
| 11 | **Project Init Gate** | Assumptions confirmed + compilable project scaffold | **Human confirmation** |
| 12 | Phase 7 → `coding-isolated-domains` + `test-driven-development` + ACL adapters | Domain code + tests + ACL adapter code | Human |
| 13 | Archive | `archive-artifacts.sh` | — |

**Route A (Full DDD Island):**
```
Step 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13
```

**Route D (Disciplined Extension):**
```
Step 0 → 1 → 2 → 3 → 4 → 5(minimal) → [skip 6] → 7(ACL-only) → [skip 8] → 9 → 10 → 11 → 12(extension) → 13
```

## 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.

| Dispatch Step | Subagent Skill | Output Artifacts |
|:---|:---|:---|
| Step 1 | mapping-legacy-landscape | `legacy-landscape.md` |
| Step 5 | extracting-domain-events | `phase-1-domain-events.md` |
| Step 6 (A only) | mapping-bounded-contexts | `phase-2-context-map.md`, constraint files, CLAUDE.md DDD section |
| Step 7 | designing-contracts-first | `phase-3-contracts.md` |
| Step 8 (A only) | architecting-technical-solution | `phase-4-technical-solution.md` |
| Step 9 | defining-schemas | Schema files + `schema-manifest.md` |
| Step 10 | spec-driven-development | `phase-6-behavior-contracts.md` + `phase-6/*.md` |
| Step 12 (per context) | coding-isolated-domains + test-driven-development | Domain code + tests + ACL adapters, `test-map.md`, `test-coverage.md` |

Input artifacts per step: each subagent receives the accumulated outputs of prior steps plus context-specific artifacts. Route D input differences: see [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Route D Execution Specifics.

**Orchestrator-executed steps:** Step 2 (Impact Analysis: `legacy-landscape.md` + requirements -> `impact-analysis.md`) and Step 3 (Boundary Proposal: `impact-analysis.md` + `legacy-landscape.md` -> `boundary-proposal.md`).

## Ambiguity Handling

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

### Pilot STOP Triggers

| Ambiguity | Why STOP |
|:---|:---|
| Impact analysis reveals MODIFY interaction type — legacy behavior change has high blast radius | Changing existing legacy behavior is the opposite of Strangler Fig — must confirm before proceeding |
| Cannot determine DDD island boundary — unclear which behavior is "new" vs "existing" | Wrong boundary creates coupling or misplaces responsibility — the island must have a clear perimeter |
| ACL direction unclear — cannot tell if legacy needs to call island or vice versa | ACL direction determines integration mechanism and which side owns the adapter — wrong direction means wrong architecture |
| Legacy code has no natural seams — ACL attachment requires invasive changes | Invasive changes violate the additive-only principle — must discuss alternatives with the human |
| Requirement scope overlaps significantly with existing legacy functionality — may need larger refactor than pilot | Overlap means the pilot may not be the right approach — the human must decide between pilot, refactor, or phased migration |
| Shared domain concept has different semantics in legacy vs new requirement — translation rules ambiguous | Semantic mismatch in shared concepts creates subtle bugs — translation rules must be explicit and human-confirmed |

### Pilot ASSUME & RECORD

| Ambiguity | Default assumption |
|:---|:---|
| Legacy technology stack applies to DDD island deployment (same DB, same framework) | ASSUME same stack; record for Phase 4 review |
| Existing legacy API patterns (REST, JSON) apply to island's external interfaces | ASSUME same pattern; record assumption |
| Legacy integration points remain stable during pilot | ASSUME no concurrent legacy changes; record risk |
| Shared concepts use the legacy name as alias in the translation table | ASSUME legacy name is well-understood; record for UL review |

## 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: pilot`: Read `ddd-progress.md` and ALL persisted artifact files — `legacy-landscape.md` (Step 1), `impact-analysis.md` (Step 2), `boundary-proposal.md` (Step 3), `phase-1-domain-events.md`, `phase-2-context-map.md` (Route A), `phase-3-contracts.md`, `phase-4-technical-solution.md` (Route A), `schema-manifest.md`, `phase-6-behavior-contracts.md` + `phase-6/*.md`, `test-map.md` + `test-coverage.md`, `assumptions-draft.md`, `decisions-log.md`. All paths under `docs/ddd/`. Resume from first incomplete step. Run `sh skills/full-ddd/scripts/session-recovery.sh` for a quick status report.
3. **If it does not exist:** Start at Step 0.

If session was interrupted during Step 12 (ACL adapter implementation), check which adapters have been written by scanning `internal/{context}/adapter/` directories. Resume from the first unimplemented ACL adapter. Do not re-implement adapters that already exist and pass tests.

**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 legacy landscape mapping (Step 1) and impact analysis (Step 2) are **mandatory** — never skip them. Route selection is a **human decision** — never default to Route D to minimize work. The Project Init Gate (Step 11) 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 proceed with a fresh pilot?"
2. **Verify NON-DDD structure:** Glob scan for domain directories (`internal/biz/`, `internal/domain/`, `src/*/domain/`, or similar). If DDD structure IS found → STOP: "This project appears to have DDD structure. Consider [iterating-ddd](../iterating-ddd/SKILL.md) instead." If no DDD but has code → proceed.
3. **Accept new requirement** from the human.
4. **Initialize progress tracker:** Create `docs/ddd/ddd-progress.md` from the pilot template (`skills/piloting-ddd/templates/ddd-progress-pilot.md`).
5. **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: Legacy Landscape Mapping → `mapping-legacy-landscape`

Execute [mapping-legacy-landscape](../mapping-legacy-landscape/SKILL.md) to produce the legacy landscape map.

**Gate:** Human must confirm the landscape map before proceeding. Verify that `docs/ddd/legacy-landscape.md` contains no unconfirmed `[OBSERVED]` markers with LOW confidence. LOW-confidence observations require human confirmation before proceeding to Step 2.

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

### Step 2: Impact Analysis + Interaction Type Classification

Analyze how the new requirement interacts with the legacy code identified in the landscape map.

For each legacy component touched by the requirement: classify Interaction Type (READ/WRITE/HOOK/SHARED/MODIFY) per [pilot-integration-reference.md](./pilot-integration-reference.md) § Interaction Type Classification. Produce Interaction Direction Summary.

**If ANY MODIFY interaction → STOP.** Confirm behavior change and additive approach with human.

Persist to `docs/ddd/impact-analysis.md`. Update `ddd-progress.md`.

### Step 3: Boundary Proposal + Legacy Touch Register

Follow the 7-item Boundary Proposal Checklist in [pilot-integration-reference.md](./pilot-integration-reference.md) § Boundary Proposal Checklist: island boundary, ACL boundaries, Legacy Touch Register, Shared Concept Translation, Non-Touch Zone, Architecture Sketch, Scope Assessment.

**STOP — present the complete boundary proposal:**

**Checkpoint:** "Here is the proposed DDD island boundary, ACL design, and legacy touch points. Please review, especially the Legacy Touch Register (items requiring legacy code changes)."

Persist to `docs/ddd/boundary-proposal.md`. Update `ddd-progress.md`.

### Step 4: Scope Gate

Present the scope decision to the human. This follows the same pattern as [full-ddd](../full-ddd/SKILL.md)'s Exit Gate.

Present Route A vs Route D using criteria from [pilot-scope-reference.md](./pilot-scope-reference.md). Agent MUST NOT recommend Route D — present data neutrally, default to Route A. Route D skips Step 6 + Step 8.

**Inline minimum criteria (if reference not loaded):** see [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Scope Gate Inline Criteria.

**STOP — present scope decision:**

**Checkpoint:** "Based on the analysis: [data]. Route A creates a full DDD Bounded Context. Route D creates a disciplined extension with ACL contracts. Which approach would you like?"

Update `ddd-progress.md` with scope decision.

### Step 5: Phase 1 → `extracting-domain-events` (New Requirement Only) (subagent)

Dispatch [extracting-domain-events](../extracting-domain-events/SKILL.md) scoped to **new requirement only** + `boundary-proposal.md` + `legacy-landscape.md`. Route A: interactive. Route D: Orchestrator Mode. **Verify:** `phase-1-domain-events.md` exists.

**Autonomous Steps (6–10):** Follow the [Per-Phase Subagent Dispatch Protocol](../ddd-protocol/subagent-dispatch-reference.md) for STOP handling in all subagents below.

### Step 6: Minimal Phase 2 — Define New BC + Relationships to Legacy (subagent)

**Only execute for Route A.** Route D skips this step.

Dispatch [mapping-bounded-contexts](../mapping-bounded-contexts/SKILL.md) — define only the new DDD island BC (boundary, classification, UL) + its ACL relationships to legacy. **Verify:** `phase-2-context-map.md` + constraint files + CLAUDE.md DDD section exist.

### Step 7: Phase 3 → `designing-contracts-first` (subagent)

Dispatch [designing-contracts-first](../designing-contracts-first/SKILL.md) with brownfield ACL extensions from [pilot-integration-reference.md](./pilot-integration-reference.md). Route A: full Phase 1-2 + landscape + boundary. Route D: no `phase-2-context-map.md` (use `boundary-proposal.md`). Run 3-question Boundary Challenge. **Verify:** `phase-3-contracts.md` exists.

### Step 8: Phase 4 → `architecting-technical-solution` (subagent)

**Only execute for Route A.** Route D skips this step.

Dispatch [architecting-technical-solution](../architecting-technical-solution/SKILL.md) with brownfield considerations (Dim 1: separate schema, Dim 4: legacy as external dep via ACL, Dim 7: integration tests cover ACL). **Verify:** `phase-4-technical-solution.md` exists.

### Step 9: Phase 5 → `defining-schemas` (subagent)

Dispatch [defining-schemas](../defining-schemas/SKILL.md) — Generate mode. Route A: full Phase 1-4 input. Route D: see [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Route D Execution Specifics. **Verify:** `schema-manifest.md` exists.

### Step 10: Phase 6 → `spec-driven-development` (subagent)

Dispatch [spec-driven-development](../spec-driven-development/SKILL.md) — Generate mode. Route A: full input. Route D: see [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Route D Execution Specifics. **Verify:** `phase-6-behavior-contracts.md` + `phase-6/` exist. Proceed to Project Init Gate.

### Step 11: Project Init Gate

**MANDATORY hard stop before any coding begins.**

Present all accumulated artifacts and assumptions per [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Project Init Gate — Presentation Items. Developer reviews each `[ASSUMPTION]`: Keep | Revise. Re-run affected phases if schema files or behavior contracts change.

Then developer sets up the project scaffold per [brownfield-strategy-reference.md](./brownfield-strategy-reference.md) § Project Init Gate — Project Scaffold Setup.

**Checkpoint:** "The Project Init Gate is complete. Landscape + impact + boundary + design + schemas + behavior contracts + assumptions are confirmed, and the project scaffold is ready. Reply **'ready for Phase 7'** when done."

**Gate Rules:**
- Agent MUST NOT run code generators autonomously.
- Agent MUST wait for explicit "ready for Phase 7" confirmation

…

## Source & license

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

- **Author:** [lockp111](https://github.com/lockp111)
- **Source:** [lockp111/agent-ddd-engineering](https://github.com/lockp111/agent-ddd-engineering)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-lockp111-agent-ddd-engineering-piloting-ddd
- Seller: https://agentstack.voostack.com/s/lockp111
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.