Add implement-design-doc-java skill

src/agent_extensions/skills/implement_design_doc_java/README.md

@@ -0,0 +1,75 @@
+# implement-design-doc-java
+
+Skill that translates DesignDoc JSON contracts into Java domain model code, adapting to the target project's coding style.
+
+## Installation
+
+```bash
+claude install-skill src/agent_extensions/skills/implement_design_doc_java/implement_design_doc_java.skill
+```
+
+Or copy `SKILL.md` and `references/` into your project's `.claude/skills/` directory.
+
+## Usage
+
+Provide a DesignDoc JSON file (conforming to `contracts/design-doc-schema.json`) and point to your Java project:
+
+```
+Implement the DesignDoc JSON into my Java project.
+DesignDoc: path/to/design-doc.json
+Project: path/to/java-project/
+```
+
+The skill will:
+1. Read existing code to detect project conventions (Lombok, records, Either, sealed interfaces, facade pattern, etc.)
+2. Parse the DesignDoc JSON and resolve building block references
+3. Search for existing shared types (IDs, Money) and import them instead of creating duplicates
+4. Generate Java classes in dependency order: value objects → events → entities → aggregates → services → repositories → application services
+5. Match the project's package structure, error handling, encapsulation, and naming conventions
+
+## What it handles
+
+- **Building block types**: aggregate, entity, value_object, domain_event, domain_command, domain_query, domain_service, application_service, repository, factory, external_integration
+- **Style adaptation**: Lombok, plain Java, Java records, sealed interfaces, Vavr Either, Spring Configuration, facade pattern, command/handler pattern, service-per-use-case
+- **Reuse detection**: finds existing classes by name before creating new ones
+- **Encapsulation**: entities within aggregates get package-private visibility
+- **Cross-module**: places building blocks in correct packages based on bounded context / module hierarchy
+
+## DesignDoc JSON schema
+
+The input JSON follows the DesignDoc schema with these top-level fields:
+
+```json
+{
+  "actors": [],
+  "businessGoals": [],
+  "domainConcepts": [],
+  "rules": [],
+  "qualityAttributes": [],
+  "boundedContexts": [],
+  "buildingBlocks": [],
+  "useCases": [],
+  "scenarios": []
+}
+```
+
+Each `buildingBlock` has `id`, `name`, `type`, `description`, `properties`, and `behaviours`. Behaviours reference other building blocks by ID (`input`/`output`) and rules by ID.
+
+See `references/designdoc_mapping.md` for detailed mapping rules from JSON to Java.
+
+## Eval results
+
+Tested on 4 discriminating scenarios with neutral prompts (no hints):
+
+| Scenario | With Skill | Without Skill | Delta |
+|---|---|---|---|
+| Pricing (Plain Java + Vavr) | 9/9 | 7/9 | +22% |
+| Payroll (Mixed patterns) | 9/9 | 7/9 | +22% |
+| Receiving (Unusual conventions) | 8/8 | 6/8 | +25% |
+| Returns (Cross-module) | 9/9 | 9/9 | 0% |
+| **Total** | **35/35 (100%)** | **29/35 (83%)** | **+17pp** |
+
+Key skill advantages over baseline Claude:
+- Reuses existing shared types instead of creating duplicates
+- Detects package-private encapsulation for entities within aggregates
+- Follows service-per-use-case pattern when project uses it

src/agent_extensions/skills/implement_design_doc_java/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: implement-design-doc-java
+description: Generate or update Java domain model code from a design document JSON file. Use this skill whenever the user asks to implement, generate, or create Java classes from a design doc, design document, design specification, or any JSON file that describes domain building blocks (aggregates, entities, value objects, domain events, repositories, services). Also use when the user wants to turn a domain model specification into Java code, sync Java code with a design contract, or implement building blocks from a JSON description. Trigger on phrases like "implement the design doc", "generate Java from this JSON", "create domain classes from the spec", "implement the building blocks", "turn this design into code", even if the user doesn't say "DesignDoc" exactly — any JSON describing a domain model with bounded contexts, modules, or building blocks qualifies.
+---
+
+# Implement Design Doc (Java)
+
+You are implementing Java domain model code from a DesignDoc JSON contract. The contract is the single source of truth for what the code must contain. Your job is to produce Java code that faithfully represents every building block, property, behaviour, and relationship described in the contract, while matching the style and conventions of the target project.
+
+## Core Principles
+
+1. **DesignDoc JSON is authoritative.** Every building block, property, behaviour, and structural relationship in the JSON must be reflected in code. Never invent domain concepts not in the contract. If something is ambiguous, ask the user.
+
+2. **Adapt to the project's style.** Before writing any code, read existing sources to detect the project's conventions (see Style Detection below). The contract dictates *what* exists; the project dictates *how* it looks.
+
+3. **Reuse existing classes — never duplicate.** When a building block's `description` says "Already exists in the project" or a class with that name already exists in the codebase, import it from its current location. Do not create a new copy in a different package. Search the project for the class before creating it. This is critical for types like shared value objects (IDs, Money) that are used across modules.
+
+4. **Replicate the project's exact patterns.** When the project uses a specific pattern for domain events (e.g., `sealed interface Event permits ...` with inner records), aggregates (e.g., `pendingEvents` + `flushEvents()`), or use case coordination (e.g., facade + package-private services + @Configuration), replicate that exact pattern. Do not substitute a different pattern even if it's valid DDD — the goal is consistency with the existing codebase.
+
+5. **Implement domain model only.** Infrastructure implementations (persistence, messaging, HTTP) are out of scope unless the contract explicitly includes `external_integration` building blocks. Repository interfaces are in scope; their implementations are not.
+
+6. **Tests are out of scope.** Other skills or project conventions handle testing. Focus exclusively on production domain code.
+
+## Input
+
+A DesignDoc JSON conforming to the schema at `contracts/design-doc-schema.json`. The JSON contains:
+
+- `boundedContexts` with `modules` and `buildingBlocks` references
+- `buildingBlocks` — flat list, each with `type`, `properties`, `behaviours`
+- `rules` — business rules referenced by behaviours
+- `useCases` — application-level orchestrations referencing building blocks
+- `actors`, `businessGoals`, `domainConcepts`, `scenarios` — contextual information
+
+See [designdoc_mapping.md](references/designdoc_mapping.md) for the complete mapping rules from JSON to Java.
+
+## Workflow
+
+### 1. Detect project style
+
+Before writing any code, read the target project to understand its conventions:
+
+1. **Find the build system** — look for `pom.xml` or `build.gradle` to determine Java version and dependencies
+2. **Read CLAUDE.md** and any project-level instructions — they may override default patterns
+3. **Sample 3-5 existing domain classes** across different building block types (aggregates, value objects, services) and note:
+   - Package structure (how bounded contexts and modules map to packages)
+   - Naming conventions (class names, method names, field access)
+   - Annotation usage (Lombok, JPA, custom annotations, or none)
+   - Error handling pattern (exceptions, Result/Either monads, Optional)
+   - **Domain event pattern** — this is critical: does the project use a marker interface? sealed interfaces with inner records? separate event classes with @Value? a pendingEvents list flushed from aggregates? Copy the exact mechanism.
+   - Value object style (records, final classes, Lombok @Value)
+   - Encapsulation style (package-private vs public, accessor methods vs direct fields)
+   - Constructor patterns (static factories, builders, plain constructors)
+   - Repository interface style (method naming, return types)
+   - **Application service / use case coordination pattern** — does the project use: facades delegating to package-private services (with Spring @Configuration wiring)? command/handler pairs (Command<R> + CommandHandler<C,R>)? service-per-use-case classes? This determines how you structure the application layer.
+
+4. **Search for existing shared types** — before creating any value object, search the entire project for a class with that name. Especially for ID types and Money-like types which are commonly shared across modules. If found, import it — do not create a duplicate.
+
+Document detected conventions in a mental checklist before proceeding. When the project has no existing code in a category, fall back to standard Java DDD patterns.
+
+### 2. Resolve the DesignDoc
+
+Parse the JSON and build a mental model:
+
+1. **Map ownership** — for each `buildingBlock`, determine which `boundedContext` and `module` owns it (via `buildingBlocks` id references in contexts/modules)
+2. **Resolve references** — behaviours reference other building blocks by id (in `input`/`output` fields) and rules by id. Resolve these to actual names and types.
+3. **Identify dependencies** — which building blocks reference which others, to determine implementation order
+4. **Detect what already exists** — search the codebase for classes matching building block names. Existing classes need modification, missing ones need creation.
+
+### 3. Plan implementation batches
+
+Group by dependency order:
+
+1. **Value Objects** — no domain dependencies, implement first
+2. **Domain Events** — typically simple immutable records
+3. **Entities** — may depend on value objects
+4. **Aggregates** — depend on entities, value objects, events
+5. **Domain Services** — coordinate multiple domain objects
+6. **Repositories** — interfaces referencing aggregate roots
+7. **Application Services / Use Cases** — orchestrate everything above
+8. **Factories** — complex creation logic
+
+### 4. Implement or modify code
+
+For each building block, follow the mapping rules in [designdoc_mapping.md](references/designdoc_mapping.md).
+
+**For new classes:** Create in the correct package following the project's package structure conventions. Match the style detected in step 1.
+
+**For existing classes:** Compare the DesignDoc contract with what exists:
+- Missing properties → add fields
+- Missing behaviours → add methods
+- Changed types → update types
+- Missing building blocks within an aggregate → add inner/companion classes
+- Present edits as minimal diffs — don't rewrite files unnecessarily
+
+**Key rules for all code:**
+- Every `property` in the JSON becomes a field in the class
+- Every `behaviour` becomes a method. The behaviour's `description` informs the method's purpose. `input` and `output` references determine parameter and return types.
+- `rules` referenced by a behaviour represent business logic that the method must enforce
+- The `description` field on building blocks informs relationships and responsibilities — parse it for mentions of ownership, containment, and collaboration patterns
+
+### 5. Verify completeness
+
+After implementation, verify that:
+- Every building block in the JSON has a corresponding class
+- Every property is represented as a field
+- Every behaviour is represented as a method
+- Every rule referenced by a behaviour is enforced in the method's logic
+- Package structure reflects the bounded context / module hierarchy
+- Use cases are wired to the correct building blocks
+
+Present a summary to the user mapping each DesignDoc element to its code location.
+
+## Style Detection Cheat Sheet
+
+| What to detect | Where to look | How it affects output |
+|---|---|---|
+| Java version | `pom.xml` / `build.gradle` | Records (16+), sealed classes (17+), pattern matching |
+| Lombok | `lombok.config`, imports | Use @Value, @Builder, @RequiredArgsConstructor if project uses them |
+| Error handling | Aggregate methods, service returns | Match: exceptions, Result monad, Either, checked exceptions |
+| Event pattern | Existing domain events | Match: records, classes, marker interfaces, event bus |
+| Package layout | src/main/java structure | Match: flat vs layered (domain/application/infrastructure) |
+| Encapsulation | Access modifiers on existing classes | Match: package-private children, public API surface |
+| Immutability | Field declarations, setters | Match: final fields, records, defensive copies |
+| Constructor style | Existing constructors | Match: static factories, builders, plain |
+| Repository location | Existing repository interfaces | Match: separate file vs **nested interface inside aggregate** (e.g., `Order.Repository`) |
+| DI framework | Spring/Guice/CDI annotations | Match: @Component, @Service, configuration classes |
+
+## Scope
+
+**IN:** Domain model classes, value objects, aggregates, entities, domain events, domain services, application services, repository interfaces, factory classes — all derived from DesignDoc JSON.
+
+**OUT:** Tests, infrastructure implementations, UI, database migrations, build configuration, design changes. If the contract seems wrong, ask — don't fix it silently.

src/agent_extensions/skills/implement_design_doc_java/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "skill_name": "implement-design-doc-java",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Implement the DesignDoc JSON into my Java project. DesignDoc: evals/fixtures/designdoc-pricing.json, project: evals/fixtures/style-plain-java/",
+      "files": ["evals/fixtures/designdoc-pricing.json", "evals/fixtures/style-plain-java/"]
+    },
+    {
+      "id": 2,
+      "prompt": "Implement the DesignDoc JSON into my Java project. DesignDoc: evals/fixtures/designdoc-payroll.json, project: evals/fixtures/style-mixed-patterns/",
+      "files": ["evals/fixtures/designdoc-payroll.json", "evals/fixtures/style-mixed-patterns/"]
+    },
+    {
+      "id": 3,
+      "prompt": "Implement the DesignDoc JSON into my Java project. DesignDoc: evals/fixtures/designdoc-receiving.json, project: evals/fixtures/style-unusual-conventions/",
+      "files": ["evals/fixtures/designdoc-receiving.json", "evals/fixtures/style-unusual-conventions/"]
+    },
+    {
+      "id": 4,
+      "prompt": "Implement the DesignDoc JSON into my Java project. DesignDoc: evals/fixtures/designdoc-returns.json, project: evals/fixtures/style-cross-module/",
+      "files": ["evals/fixtures/designdoc-returns.json", "evals/fixtures/style-cross-module/"]
+    }
+  ]
+}