jdi-cli 0.1.1 → 0.1.2

package/runtimes/claude/skills/vertical-slice/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: vertical-slice
+description: Vertical Slice Architecture (Jimmy Bogard). Organize by feature, not by technical layer. Each feature owns its full request-to-response path with minimal sharing. Language-agnostic rigid rules. Mutually exclusive with The Method, DDD, Clean Architecture, Hexagonal, Onion.
+---
+
+# Skill: Vertical Slice Architecture
+
+Rigid, inviolable rules from Jimmy Bogard's Vertical Slice Architecture. The system is organized by **feature**, not by technical layer. Each slice owns the full path from external request to external response.
+
+Vertical Slice is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: Vertical Slice`. Do not impose Clean Architecture's 4-layer structure, Onion shells, Hexagonal core/ports/adapters, DDD aggregates as primary structure, or The Method's universal hierarchy on top.
+
+## Mandatory structure
+
+1. **Each feature is one slice.** A feature is a single user-facing capability (e.g., `RegisterCustomer`, `CancelOrder`, `RenewSubscription`).
+2. **A slice owns its full pipeline:** input contract, validator, handler, business logic, persistence access, output contract, and slice-specific tests.
+3. **Slices live in feature folders / packages.** The primary code organization is `features/{feature-name}/` (or equivalent in the language). Technical-layer folders (`controllers/`, `services/`, `repositories/`, `models/`) as the primary structure are forbidden.
+4. **Each feature folder is self-contained.** Inside a folder live only the artifacts that serve that feature.
+5. **No shared "Service" layer, no shared "Repository" layer, no shared "Manager" layer across slices.** Each slice has its own.
+
+## Slice isolation rules (inviolable)
+
+1. **Slices do not call each other directly.** If slice A needs work done by slice B, slice A either duplicates the minimum needed code OR they both publish/subscribe to a shared event bus. Direct invocation of slice B's handler from slice A is forbidden.
+2. **No shared mutable state across slices.** A slice never mutates state owned by another slice except through the shared persistence boundary, and never through another slice's handler.
+3. **DRY applies inside a slice, not across slices.** Two slices that look similar today are still allowed to diverge tomorrow. Forced sharing is the enemy.
+4. **Cross-slice abstractions are introduced only when 3+ slices need the exact same behavior with the exact same shape, and that behavior is stable.** Premature shared abstractions are violations.
+
+## Slice composition (mandatory contents)
+
+Each slice MUST contain:
+
+1. **Request / Command / Query contract** — a structure describing the input.
+2. **Handler** — receives the request, executes the logic, returns the response.
+3. **Validator** (if input requires validation) — slice-local validation rules.
+4. **Response contract** — the output shape returned to the caller.
+5. **Slice-local types** — any DTOs, view models, or projections the slice needs.
+6. **Slice-local tests** — integration tests that exercise the slice end-to-end.
+
+A slice MAY contain:
+
+- A slice-specific persistence access path (raw query, ORM query, projection, command-side persistence).
+- A slice-specific external system call.
+- Slice-local pre/post processing.
+
+A slice MUST NOT contain:
+
+- References to another slice's handler, request, or response types.
+- References to a shared "Service" abstracting multiple slices.
+- A "Manager" coordinating multiple slices.
+
+## Cross-cutting concerns (inviolable)
+
+1. Cross-cutting concerns (logging, authentication, authorization, transactions, validation pipeline, error handling) are applied as **pipeline behaviors / middleware** that wrap the handler, never as shared services injected into the handler.
+2. Authentication and authorization decisions may use shared types (claims, principals) but are enforced at the pipeline level, not inside the handler.
+3. Validation runs as a pipeline step before the handler executes. The handler assumes valid input.
+4. Logging, tracing, metrics: pipeline behaviors. The handler does not invoke logging libraries for cross-cutting purposes.
+
+## Persistence rules
+
+1. **No generic repository spanning slices.** A slice that needs persistence either uses the ORM/database client directly within the slice OR has its own slice-local repository.
+2. **Reads and writes may diverge structurally.** A slice that reads may use a different model than a slice that writes; this is encouraged.
+3. **No "Domain Model" required to be shared across slices.** Each slice models the data it needs in the shape it needs.
+4. **A shared schema (database) is acceptable; a shared in-code model abstraction is not.**
+
+## Forbidden patterns (inviolable)
+
+- **Technical-layer primary folders** (`controllers/`, `services/`, `repositories/`, `models/`) used as the system's primary organization.
+- **A handler calling another handler.**
+- **A "Service" class injected into multiple handlers** to provide their business logic.
+- **A "Manager" class coordinating multiple slices.**
+- **A shared "Repository" abstraction** consumed by 5+ slices.
+- **Cross-slice imports of internal slice types.** Slice A importing `B.HandleQuery` or `B.RequestDto` is forbidden.
+- **Slice A invoking slice B via an internal interface** instead of via the public boundary (HTTP, queue, event).
+- **DRY refactoring that merges 2 slices into 1 because they share 80% of the code.** Slices stay separate until 3+ identical use cases exist with stable shape.
+- **Forcing all slices through a shared base handler class** that contains business logic.
+- **A shared "Domain Model" referenced by all slices** as the primary modeling element.
+
+## Naming conventions
+
+- Feature folders: feature name in domain language (`RegisterCustomer/`, `CancelOrder/`, `ViewCustomerDashboard/`).
+- Request types: domain operation name (`RegisterCustomerCommand`, `CancelOrderCommand`, `ViewCustomerDashboardQuery`).
+- Handler types: paired with request (`RegisterCustomerHandler`).
+- Validator types: paired with request (`RegisterCustomerValidator`).
+- Response types: domain output name (`RegisterCustomerResponse`).
+- Internal slice types: prefixed by feature name when shared inside the slice (`RegisterCustomerEmailTemplate`).
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- The codebase is primarily organized by technical layer instead of by feature.
+- A handler invokes another slice's handler, request, or response type.
+- A new "Service" / "Manager" / "Coordinator" class is introduced that spans multiple slices and carries business logic.
+- A shared generic repository is introduced and consumed by multiple slices.
+- Cross-cutting concerns are injected into handlers as shared services instead of applied as pipeline behaviors.
+- Slice A imports types from slice B's internal folder.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- Two slices share an identical small helper that has been duplicated 3+ times (candidate for extraction, not required).
+- A slice contains logic that appears to belong to a different slice.
+- A slice handler is long enough to suggest splitting into pipeline behaviors.
+- A slice references a "Domain Service" or "Aggregate" terminology that may indicate a different design creeping in.
+
+## Anti-patterns
+
+- "Vertical slices" implemented inside an MVC controllers/services/repositories folder structure (the folders betray the layer-primary structure)
+- A "Domain" project that all slices reference, containing entities + services + repositories — that is layered or Onion in disguise
+- Cross-slice "Coordinator" classes that orchestrate two handlers
+- A shared "BaseHandler" that contains transaction management AND business logic
+- A slice handler that delegates 90% of its work to a shared service (the slice is hollow)
+- Premature "DRY" extraction that merges slices into a generic handler with strategy patterns
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/runtimes/copilot/agents/jdi-architect.agent.md

@@ -381,13 +381,29 @@ Write to `.jdi/agents/jdi-reviewer-{slug}.md`.
 
 After writing doer/reviewer, inject `<skills_to_load>` block after `</role>` via Edit.
 
+**Code-design skill (mandatory) — resolve from `PROJECT.md.Code Design` (LOCKED value) using this mapping:**
+
+| Code Design (PROJECT.md) | Skill to load |
+|---|---|
+| The Method | `the-method` |
+| DDD | `ddd` |
+| Clean Architecture | `clean-architecture` |
+| Hexagonal | `hexagonal` |
+| Onion | `onion` |
+| Vertical Slice | `vertical-slice` |
+
+The resolved code-design skill is loaded by **both doer and reviewer**. Exactly one code-design skill is loaded. Never load two code-design skills simultaneously — the project uses exactly one design. If the mapping cannot resolve, abort with an error and ask the user to fix `PROJECT.md.Code Design`.
+
 **Doer — always:**
 ```markdown
 <skills_to_load>
 - solid — before creating classes/modules/interfaces. Detects god class, large switches, deep inheritance, dep on concretes.
+- {CODE_DESIGN_SKILL} — INVIOLABLE structural rules for the project's locked code design. Apply on every file created.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the resolved entry from the mapping above (e.g. `the-method`, `ddd`, `clean-architecture`, `hexagonal`, `onion`, `vertical-slice`).
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — when task touches .tsx/.vue/.svelte/.razor/.cshtml/.html/.twig/.erb/.blade.php. WCAG 2.2 AA + UX.
@@ -400,9 +416,12 @@ If `has_frontend=true`, append:
 - kiss — gate 5: over-engineering — interface with 1 impl, factory for new(), pass-through, deep inheritance.
 - yagni — gate 5: speculative code — optional params never passed, TODO without ticket, generic with 1 type.
 - clean-code — bad names, long functions, magic numbers, silent catch, boolean params, redundant comments.
+- {CODE_DESIGN_SKILL} — gate 5: enforce INVIOLABLE structural rules for the project's locked code design. BLOCKED on violations defined by the skill.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the same resolved entry — both doer and reviewer load the SAME code-design skill.
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — gate 5 frontend: <input> without label, button without aria-label, localStorage with token, outline removed.

package/runtimes/copilot/agents/jdi-researcher.agent.md

@@ -56,10 +56,11 @@ Options:
 - Vertical Slice
 - Clean Architecture
 - Hexagonal (Ports & Adapters)
+- Onion Architecture
 - The Method (Juval Löwy)
 - "Don't know, suggest" (-> recommend based on type + stack)
 
-Locked for the life of the project (global rule).
+Locked for the life of the project (global rule). Mutually exclusive — the project uses exactly ONE code design. The choice is enforced by a JDI skill loaded into doer + reviewer (one of: `ddd`, `vertical-slice`, `clean-architecture`, `hexagonal`, `onion`, `the-method`).
 
 **Q4 — MVP scope**
 "Which minimum features for the MVP? (comma-separated)"

package/runtimes/opencode/agents/jdi-architect.md

@@ -378,13 +378,29 @@ Write to `.jdi/agents/jdi-reviewer-{slug}.md`.
 
 After writing doer/reviewer, inject `<skills_to_load>` block after `</role>` via Edit.
 
+**Code-design skill (mandatory) — resolve from `PROJECT.md.Code Design` (LOCKED value) using this mapping:**
+
+| Code Design (PROJECT.md) | Skill to load |
+|---|---|
+| The Method | `the-method` |
+| DDD | `ddd` |
+| Clean Architecture | `clean-architecture` |
+| Hexagonal | `hexagonal` |
+| Onion | `onion` |
+| Vertical Slice | `vertical-slice` |
+
+The resolved code-design skill is loaded by **both doer and reviewer**. Exactly one code-design skill is loaded. Never load two code-design skills simultaneously — the project uses exactly one design. If the mapping cannot resolve, abort with an error and ask the user to fix `PROJECT.md.Code Design`.
+
 **Doer — always:**
 ```markdown
 <skills_to_load>
 - solid — before creating classes/modules/interfaces. Detects god class, large switches, deep inheritance, dep on concretes.
+- {CODE_DESIGN_SKILL} — INVIOLABLE structural rules for the project's locked code design. Apply on every file created.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the resolved entry from the mapping above (e.g. `the-method`, `ddd`, `clean-architecture`, `hexagonal`, `onion`, `vertical-slice`).
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — when task touches .tsx/.vue/.svelte/.razor/.cshtml/.html/.twig/.erb/.blade.php. WCAG 2.2 AA + UX.
@@ -397,9 +413,12 @@ If `has_frontend=true`, append:
 - kiss — gate 5: over-engineering — interface with 1 impl, factory for new(), pass-through, deep inheritance.
 - yagni — gate 5: speculative code — optional params never passed, TODO without ticket, generic with 1 type.
 - clean-code — bad names, long functions, magic numbers, silent catch, boolean params, redundant comments.
+- {CODE_DESIGN_SKILL} — gate 5: enforce INVIOLABLE structural rules for the project's locked code design. BLOCKED on violations defined by the skill.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the same resolved entry — both doer and reviewer load the SAME code-design skill.
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — gate 5 frontend: <input> without label, button without aria-label, localStorage with token, outline removed.

package/runtimes/opencode/agents/jdi-researcher.md

@@ -60,10 +60,11 @@ Options:
 - Vertical Slice
 - Clean Architecture
 - Hexagonal (Ports & Adapters)
+- Onion Architecture
 - The Method (Juval Löwy)
 - "Don't know, suggest" (-> recommend based on type + stack)
 
-Locked for the life of the project (global rule).
+Locked for the life of the project (global rule). Mutually exclusive — the project uses exactly ONE code design. The choice is enforced by a JDI skill loaded into doer + reviewer (one of: `ddd`, `vertical-slice`, `clean-architecture`, `hexagonal`, `onion`, `the-method`).
 
 **Q4 — MVP scope**
 "Which minimum features for the MVP? (comma-separated)"

package/runtimes/opencode/skills/clean-architecture/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: clean-architecture
+description: Clean Architecture (Robert C. Martin). 4 concentric layers - Entities, Use Cases, Interface Adapters, Frameworks & Drivers. The Dependency Rule points strictly inward. Language-agnostic rigid rules. Mutually exclusive with The Method, DDD, Hexagonal, Onion, Vertical Slice.
+---
+
+# Skill: Clean Architecture
+
+Rigid, inviolable rules from Robert C. Martin's *Clean Architecture*. The system is organized as **concentric layers**, and source-code dependencies point only **inward**.
+
+Clean Architecture is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: Clean Architecture`. Do not mix with The Method, DDD aggregates as a primary structure, Hexagonal terminology as the primary structure, Onion shells, or Vertical Slice feature folders as the primary structure.
+
+## The 4 layers (mandatory)
+
+From innermost to outermost:
+
+1. **Entities (Enterprise Business Rules)** — the most general and high-level rules. Reusable across applications in the enterprise. Pure data + behavior. No knowledge of any other layer.
+2. **Use Cases (Application Business Rules)** — application-specific business rules. Orchestrate the dance of Entities to satisfy a use case. No knowledge of UI, DB, frameworks, devices, or external systems.
+3. **Interface Adapters** — convert data between the form most convenient for use cases/entities and the form most convenient for external agents. Controllers, Presenters, Gateways, ViewModels live here. No knowledge of frameworks beyond what is necessary to expose adapter contracts.
+4. **Frameworks & Drivers** — the outermost layer. Web framework, database, UI framework, file system, devices, external APIs. Glue code only — minimal logic.
+
+Every code unit belongs to exactly one of these 4 layers. A unit that does not fit must be redesigned.
+
+## The Dependency Rule (inviolable)
+
+**Source-code dependencies point only inward. Nothing in an inner circle may know anything at all about something in an outer circle.**
+
+1. Entities depend on nothing outside the Entities layer.
+2. Use Cases depend on Entities only. Use Cases do not import, reference, or know the names of anything in Interface Adapters or Frameworks & Drivers.
+3. Interface Adapters depend on Use Cases and Entities only. They do not depend on Frameworks & Drivers code directly — they depend on framework abstractions only where unavoidable, and never let framework types cross into the inner circles.
+4. Frameworks & Drivers depend on whatever is convenient (Adapters, libraries, vendor SDKs).
+5. Names defined in outer circles (e.g., entity names from a DB schema, DTOs from a controller, framework annotations) must not appear in inner-circle code.
+
+## Boundary Crossing rules (inviolable)
+
+1. **Cross boundaries via interfaces owned by the inner side.** Inputs into Use Cases are defined by interfaces in the Use Cases layer; implementations live in Interface Adapters.
+2. **Cross boundaries via Data Transfer Objects (DTOs) that are simple structures.** No framework objects, no ORM entities, no HTTP request objects cross a boundary.
+3. **Use Cases never receive framework-specific types** (HTTP request, ORM entity, file handle, socket). The Adapter translates these into the Use Case's input DTOs.
+4. **Use Cases return DTOs / output ports.** They never return entities directly to outer layers.
+5. **The Use Case interactor invokes an output port (interface) to deliver results.** The Presenter implements the output port. Use Cases never call presenters or controllers directly.
+
+## Layer purity rules (inviolable)
+
+### Entities
+
+1. Entities are pure. No imports from any other layer.
+2. Entities encapsulate enterprise-wide business rules; if a rule is application-specific, it does not belong here.
+3. Entities are not Database records, ORM models, JSON shapes, or API DTOs. If a class plays one of those roles, it is not an Entity.
+4. Entities have no annotations from persistence, serialization, or web frameworks.
+5. Entities are not anemic. Behavior lives with data.
+
+### Use Cases
+
+6. Each Use Case has a single, application-specific purpose stated by its name (verb-noun: e.g., `RegisterCustomer`, `RenewSubscription`).
+7. A Use Case owns its input port (input boundary) and output port (output boundary) as interfaces in the Use Cases layer.
+8. A Use Case does not import any framework, ORM, HTTP, file-system, or external-API type.
+9. A Use Case is testable without any infrastructure. If it cannot be tested without spinning up DB / HTTP / queue, the design is wrong.
+10. A Use Case orchestrates Entities. It does not duplicate enterprise rules that already live in Entities.
+
+### Interface Adapters
+
+11. Controllers translate external input (HTTP request, CLI args, message payload) into Use Case input DTOs and invoke the Use Case.
+12. Presenters convert Use Case output DTOs into a form suitable for delivery (ViewModel, response body).
+13. Gateways implement the persistence interfaces declared by the Use Cases.
+14. Adapters never contain business rules.
+15. Adapters depend inward on Use Cases / Entities, never outward on Frameworks.
+
+### Frameworks & Drivers
+
+16. Framework code is glue only. It wires Adapters to the framework runtime.
+17. Web framework controllers in the Frameworks layer call Adapters, not Use Cases directly.
+18. ORM-mapped models, framework annotations, configuration code, dependency injection wiring live here.
+
+## Composition rules
+
+1. **Composition Root is in the outermost layer.** The main / startup / DI container assembles all components.
+2. **Inner layers never construct outer layer types.** Dependencies are injected through interfaces defined by the inner layer.
+3. **Plug-in architecture.** A change in framework, DB, or UI must require changes only in the outer layers. Inner layers stay untouched.
+
+## Forbidden patterns (inviolable)
+
+- **Use Cases referencing framework types** (HTTP request, ORM entity, file handle, vendor SDK type).
+- **Entities referencing persistence frameworks** (ORM annotations, database column attributes that encode behavior).
+- **Anemic Entities.** Behavior must accompany data.
+- **Skipping a layer for convenience** (Controller calling a repository directly, Presenter calling the database).
+- **Returning framework / ORM types from a Use Case.**
+- **Use Case knowing the concrete Adapter** (e.g., calling a specific HTTP client class). Use Cases declare interfaces; Adapters implement.
+- **Shared "Util" / "Helper" classes spanning layers** with hidden business rules.
+- **Database-driven design** where the schema dictates Entity shape.
+- **Cross-layer reach-around** (Framework code calling Use Cases bypassing Adapters, Adapters calling Frameworks bypassing the Composition Root).
+- **Concentric layers reorganized as feature folders** that hide which layer a unit belongs to.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- An Entity or Use Case imports a framework, ORM, HTTP, or vendor SDK type.
+- A Use Case returns a framework / ORM / DTO defined in an outer layer.
+- A Controller invokes persistence directly instead of going through a Use Case.
+- An Adapter contains a business rule.
+- An inner-layer file imports an outer-layer file (direct dependency violation).
+- Boundary crossings carry framework-specific types instead of plain DTOs.
+- Use Cases or Entities are not testable without infrastructure.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- A Use Case is named after a CRUD verb without application semantics.
+- An Entity has only getters/setters (anemic).
+- An Adapter file leaks framework annotations into its public interface.
+- The Composition Root is split across layers instead of living in the outermost layer.
+
+## Anti-patterns
+
+- "Service" layer mixing Use Cases with Adapter responsibilities
+- DTOs leaking into Entities
+- ORM entities serving as both Entity and persistence model
+- Controller-with-business-logic
+- Use Case classes that depend on framework annotations
+- Hexagonal-style port terminology used to disguise a violation (the rule is the Dependency Rule, not the port naming)
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/runtimes/opencode/skills/ddd/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ddd
+description: Domain-Driven Design (Eric Evans). Strategic patterns (Bounded Context, Ubiquitous Language, Context Map) plus tactical patterns (Aggregates, Entities, Value Objects, Domain Services, Repositories, Domain Events). Language-agnostic rigid rules. Mutually exclusive with The Method, Clean Architecture, Hexagonal, Onion, Vertical Slice.
+---
+
+# Skill: Domain-Driven Design (DDD)
+
+Rigid, inviolable rules from Eric Evans's *Domain-Driven Design* and Vaughn Vernon's *Implementing DDD*. The domain is the center of the system. Persistence, UI, frameworks, and external integrations are peripheral details.
+
+DDD is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: DDD`. Do not introduce The Method's Managers/Engines/ResourceAccess, Clean Architecture's concentric layers as a structural primary, Hexagonal port terminology as the primary structure, Onion shells, or Vertical Slice handlers as the primary structure.
+
+## Strategic rules (inviolable)
+
+1. **Bounded Context (BC) is the unit of model isolation.** Every BC owns its own model, its own ubiquitous language, its own database schema, and its own deployment unit (where feasible). A model is meaningful only inside its BC.
+2. **Each BC must be named.** Anonymous BCs do not exist. The name appears in the codebase (folder, namespace, module, package).
+3. **Ubiquitous Language (UL) is contractual within a BC.** The same word means exactly one thing inside the BC. Synonyms are forbidden. Code, tests, docs, conversations, and database column names share the UL terminology.
+4. **No shared model across BCs.** When two BCs reference the same real-world concept, each has its own model class for it. Cross-BC reuse of classes is forbidden.
+5. **Cross-BC interaction follows a Context Map relationship.** Every integration between BCs is explicitly typed as exactly one of: Shared Kernel, Customer/Supplier, Conformist, Anticorruption Layer (ACL), Open Host Service (OHS), Published Language (PL), Partnership, Separate Ways. Undeclared integration is forbidden.
+6. **Anticorruption Layer (ACL) is required when integrating with a legacy or external model.** Foreign models do not leak into a BC.
+7. **Core Domain is identified explicitly.** Other BCs are classified as Supporting Subdomain or Generic Subdomain. The Core Domain receives the highest engineering investment and is never outsourced or replaced by a generic library.
+8. **Domain knowledge does not leak into Generic Subdomains.** Generic Subdomain code (Identity, Logging, Notification) must be reusable across projects without domain assumptions.
+
+## Tactical rules (inviolable)
+
+### Aggregate
+
+1. **An Aggregate has exactly one Root.** All external access goes through the Root. References to inner entities from outside the Aggregate are forbidden.
+2. **The Aggregate Root enforces all invariants of the Aggregate.** No partial state may be observed by other Aggregates or by Application Services.
+3. **One transaction modifies at most one Aggregate instance.** Multi-aggregate consistency is achieved by Domain Events, not by enclosing transactions.
+4. **Aggregates reference other Aggregates only by identifier (ID), never by direct object reference.** Cross-aggregate navigation through references is forbidden.
+5. **Aggregate boundaries are designed around invariants and transactional consistency, never around UI screens or convenience.**
+6. **Aggregates must be small.** If an Aggregate contains a collection that grows unbounded, the design is wrong and must be split.
+
+### Entity vs Value Object
+
+7. **An Entity has identity that persists across state changes.** Equality is by identity, never by attributes.
+8. **A Value Object is immutable and identity-less.** Equality is by attributes. Mutating a Value Object is forbidden — replace, do not modify.
+9. **Prefer Value Objects.** When a concept has no identity, model it as a Value Object. Default to Value Object; promote to Entity only when identity is required.
+10. **Value Objects must be self-validating.** Construction of a Value Object with invalid state must fail at construction time.
+
+### Domain Service
+
+11. **A Domain Service exists only when an operation does not belong to any Entity or Value Object.** If the operation can fit on an Entity/VO, it must live there.
+12. **Domain Services are stateless and named with a Ubiquitous Language verb-noun expressing a domain operation, not a technical action.**
+13. **Domain Services contain domain logic only.** Persistence, transactions, messaging, and orchestration of use cases live in Application Services.
+
+### Repository
+
+14. **One Repository per Aggregate Root.** No repository per Entity that is not a Root. No "generic" repository shared across Aggregates.
+15. **Repository interface lives with the domain model, not with persistence.** Persistence implementation lives outside the domain layer.
+16. **Repositories return whole Aggregates, never partial state.** A method returning a piece of an Aggregate (single inner entity, partial fields) is forbidden.
+17. **Queries that span multiple Aggregates or return projections do not use Repositories.** Use a dedicated Query/ReadModel pattern (CQRS-style). Reads and writes may diverge structurally.
+
+### Domain Event
+
+18. **Domain Events are immutable, past-tense facts.** Names are past tense (e.g., "OrderPlaced", "PaymentRefused"). Mutating a Domain Event is forbidden.
+19. **Domain Events are emitted by Aggregates.** Application Services do not invent domain events.
+20. **Domain Events carry only the data needed to react to the fact.** Do not embed entire Aggregate state.
+21. **Cross-Aggregate consistency uses Domain Events, not synchronous calls between Aggregates.**
+
+### Application Service
+
+22. **Application Services orchestrate use cases.** They load Aggregates via Repositories, invoke domain methods, persist changes, and emit Domain Events. They contain no business rules.
+23. **Application Services are thin.** A method longer than orchestration of 5-8 domain calls is a smell; extract domain logic back to the domain.
+24. **Application Services do not return domain entities directly to UI.** Return DTOs or projections.
+
+### Domain layer purity
+
+25. **The Domain Layer depends on nothing external.** No framework, ORM, HTTP, file system, or messaging library is referenced from domain code.
+26. **Persistence-ignorant domain.** Entities/Aggregates do not inherit from ORM base classes, do not have persistence annotations leaking semantic meaning, and do not know about transactions.
+27. **No anemic models.** Entities and Value Objects own their behavior. A class with only getters/setters and no business methods is forbidden in the domain layer.
+28. **No "Manager", "Helper", "Util", "Processor" classes in the domain layer.** These names betray missing domain concepts.
+
+## Modeling rules (inviolable)
+
+1. The model in code must match the model in conversation with domain experts. If they diverge, the code is wrong.
+2. Names come from the Ubiquitous Language. Technical names ("Data", "Info", "Object", "Item", "Entry") are forbidden in the domain layer.
+3. New domain concepts are added to the Ubiquitous Language before they are added to the code.
+4. Domain experts must recognize the names, intents, and invariants encoded in the domain layer.
+
+## Forbidden patterns (inviolable)
+
+- **Generic Repository** spanning multiple Aggregates (`Repository<T>`) is forbidden.
+- **Lazy-loaded navigation across Aggregates** is forbidden.
+- **Transactions spanning multiple Aggregates** are forbidden.
+- **Returning Entities from a query that crosses Aggregates** is forbidden — use a read model.
+- **CRUD-only Application Services** ("CreateUser", "UpdateUser") with no domain semantics are a smell; reframe as domain operations ("RegisterCustomer", "DeactivateAccount") when meaning exists.
+- **Anti-corruption layer absence** when consuming an external/legacy model is a violation.
+- **Sharing entities across Bounded Contexts** is forbidden.
+- **DTO leaking into the domain layer** is forbidden.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- Domain code references a framework / ORM / HTTP / messaging library.
+- An Aggregate is mutated from outside its Root.
+- A single transaction modifies more than one Aggregate instance.
+- A Repository serves multiple Aggregate Roots, or returns partial state.
+- Cross-Aggregate references are by object instead of by ID.
+- A Domain Service performs persistence, transactions, or messaging.
+- An Application Service contains business rules.
+- An Entity / VO has only getters/setters (anemic).
+- Two Bounded Contexts share the same model class.
+- An integration with an external system has no Anticorruption Layer.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- A class is named "Manager" / "Helper" / "Util" / "Processor" in the domain layer.
+- A Value Object is mutable.
+- An Aggregate exposes its internal collections directly.
+- A Domain Event is named in present/future tense.
+- The Ubiquitous Language used in code disagrees with the language in PROJECT.md or CONTEXT.md.
+
+## Anti-patterns
+
+- Anemic Domain Model
+- Generic Repository pattern
+- God Aggregate (entire schema under one Root)
+- Smart UI bypassing domain
+- Domain services that orchestrate use cases (those are Application Services)
+- "Service layer" without distinguishing Domain Service vs Application Service
+- Database-first design driving Aggregate shape
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/runtimes/opencode/skills/hexagonal/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: hexagonal
+description: Hexagonal Architecture / Ports and Adapters (Alistair Cockburn). Application core in the center, surrounded by Ports (interfaces owned by the core) and Adapters (implementations). Driving (primary) vs Driven (secondary) sides. Language-agnostic rigid rules. Mutually exclusive with The Method, DDD, Clean Architecture, Onion, Vertical Slice.
+---
+
+# Skill: Hexagonal Architecture (Ports and Adapters)
+
+Rigid, inviolable rules from Alistair Cockburn's Ports and Adapters. The application is a **core** isolated from the outside world by **ports** (interfaces) and **adapters** (implementations).
+
+Hexagonal is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: Hexagonal`. Do not use The Method, DDD as primary structure, Clean Architecture's 4-layer terminology as primary structure, Onion shells, or Vertical Slice feature folders as primary structure.
+
+## Mandatory structure
+
+The system consists of exactly three structural elements:
+
+1. **Application Core (the hexagon)** — domain model + application logic. Knows nothing about technology, protocols, or external systems. The core is the only place where business rules exist.
+2. **Ports** — interfaces **owned by the core** that declare what the core needs from the outside (driven ports) or what the outside can ask the core to do (driving ports). A port is an abstract contract; it has no implementation in the core.
+3. **Adapters** — implementations of ports living outside the core. Adapters translate between the technology-specific outside world (HTTP, DB, queue, file, UI) and the technology-free core.
+
+Every code unit belongs to exactly one of: Core, Port (still inside the core's package), or Adapter. A unit that does not fit must be redesigned.
+
+## Driving vs Driven (mandatory)
+
+1. **Driving (primary) side** — the side that initiates interaction with the core. UI, HTTP controllers, CLI handlers, scheduled job triggers, integration tests. Driving adapters invoke driving ports.
+2. **Driven (secondary) side** — the side the core delegates to. Persistence, message bus, external APIs, file system, email, cache. The core invokes driven ports, which are implemented by driven adapters.
+3. **Driving port** is an interface that exposes the core's capabilities to the outside. **Driven port** is an interface declared by the core that the outside must satisfy.
+4. **Direction of dependency: adapters depend on ports; ports live in the core; the core depends on nothing infrastructural.**
+
+## Inviolable rules
+
+### Core purity
+
+1. The core has zero imports from any framework, ORM, HTTP library, vendor SDK, file system API, or transport library.
+2. The core defines its own types for inputs and outputs to ports. Adapter types (HTTP request, ORM model, queue message) do not appear in core code.
+3. The core does not know the identity of any adapter. It interacts only with ports.
+4. The core does not perform I/O. All I/O happens through driven ports.
+5. The core is fully testable without any adapter. If a unit test of the core requires spinning up DB / HTTP / queue, the design is wrong.
+
+### Ports
+
+6. A port is an interface. It has no logic.
+7. Ports live in the core's package / module. They are not in an "infrastructure" or "adapters" package.
+8. The core defines a port; the adapter implements it. A port defined outside the core, or implemented in the core, is forbidden.
+9. Driving ports name capabilities of the core in domain language (e.g., `PlaceOrder`, `RenewSubscription`). Driven ports name dependencies in domain language (e.g., `OrderRepository`, `NotificationSender`).
+10. Port methods receive and return only types defined inside the core. They do not receive HTTP requests, ORM entities, or framework-specific types.
+
+### Adapters
+
+11. An adapter implements exactly one port (driving or driven). An adapter that mixes driving and driven roles is forbidden.
+12. A driving adapter translates an external trigger (HTTP request, CLI command, message, schedule) into a core-defined input and invokes a driving port.
+13. A driven adapter translates a core-defined call into a technology-specific action (SQL query, HTTP call, file write, queue publish) and translates the result back into core-defined output.
+14. Adapters contain only translation and I/O. Business rules in an adapter are forbidden — they must move into the core.
+15. Adapters never call other adapters directly. Coordination between adapters happens through the core via a driving adapter → core → driven adapter sequence.
+16. Adapters never call the core's internal classes directly. They go through ports.
+
+### Composition
+
+17. The Composition Root assembles adapters and injects them into the core at startup. The core does not construct its own adapters.
+18. Replacing an adapter (e.g., swapping PostgreSQL for MongoDB, REST for gRPC) must not require changes inside the core. If it does, the port is leaking.
+19. Multiple adapters may implement the same port. The core does not know how many.
+20. Test adapters (fakes, in-memory implementations) are first-class adapters and must use the same ports as production adapters. The core cannot have a "test-only" code path.
+
+## Forbidden patterns (inviolable)
+
+- **Framework types crossing into the core.** No HTTP request type, no ORM entity, no vendor SDK type referenced in core code.
+- **Business rules in adapters.** A driven adapter computing a price, a driving adapter validating a domain rule — both forbidden.
+- **Adapters calling adapters.** Adapter coordination outside the core is forbidden.
+- **Core code instantiating an adapter.** Construction happens in the Composition Root.
+- **Ports defined outside the core.** A port placed in an "infrastructure" module is a violation.
+- **Anemic core.** A core without behavior is a violation — adapters become a leak path for rules.
+- **A driving port returning a framework-specific type** (a port returning `HttpResponse` is wrong).
+- **Driven ports leaking persistence concepts** (a port named `SqlUserRepository` is wrong; it must be domain-named).
+- **Mixed-role adapter** (one adapter both responding to HTTP and writing to DB).
+- **Bypassing ports** by injecting an adapter directly where a port should appear.
+- **Concentric layer terminology** ("Entities layer", "Use Cases layer", "Application Services layer") imposed as the primary structure — Hexagonal organizes by core/ports/adapters, not by concentric layers.
+
+## Naming conventions
+
+- Driving ports: domain capability verbs (`PlaceOrder`, `RegisterCustomer`).
+- Driven ports: dependency names in domain language (`OrderRepository`, `EmailSender`, `PaymentGateway`).
+- Adapters: technology-qualified (`HttpPlaceOrderAdapter`, `PostgresOrderRepositoryAdapter`, `SmtpEmailSenderAdapter`).
+- The core never references a name containing a technology word.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- Core code imports a framework / ORM / HTTP / vendor SDK / file-system type.
+- A port is defined outside the core or implemented inside the core.
+- A port method's signature mentions a framework-specific type.
+- An adapter contains business logic.
+- An adapter calls another adapter directly.
+- The core instantiates an adapter.
+- A driven port name leaks a persistence technology.
+- A driving adapter returns the result of a port call without translating from a core type to an external type.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- An adapter file is doing more translation than necessary (smell: complex mapping suggesting hidden rules).
+- A port is implemented by a single adapter and is unlikely ever to vary (still allowed — keep the port).
+- A core class has no behavior (anemic).
+- Composition wiring is scattered instead of centralized in a Composition Root.
+
+## Anti-patterns
+
+- "Service" layer between core and adapters (no such thing in Hexagonal)
+- Repository implemented inside the core (must be a port)
+- Use Case classes shaped after Clean Architecture's Use Case layer (the structure is core/ports/adapters)
+- Ports tied to a transport (e.g., `RestOrderPort`) — ports are domain-shaped, adapters are transport-shaped
+- "Domain Services" terminology imported wholesale from DDD as the primary structure (acceptable internal to the core when meaningful, but does not replace the hexagonal primary structure)
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.