jdi-cli 0.1.1 → 0.1.2

package/core/skills/the-method/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: the-method
+description: The Method (Juval Löwy, "Righting Software"). Volatility-based decomposition with universal hierarchy (Clients, Managers, Engines, ResourceAccess, Resources, Utilities). Strict communication rules. Language-agnostic. Mutually exclusive with DDD, Clean Architecture, Hexagonal, Onion, Vertical Slice.
+type: skill
+applies_to: |
+  Loaded by doer and reviewer when PROJECT.md `Code Design` is `The Method`.
+  Inviolable design rules. Doer applies during creation. Reviewer enforces at gate 5.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "The Method"
+      - "Juval Lowy"
+      - "Righting Software"
+      - "volatility decomposition"
+      - "Universal Hierarchy"
+---
+
+# Skill: The Method (Juval Löwy)
+
+Rigid, inviolable design rules from Juval Löwy's *Righting Software*. Decompose by **volatility**, not functionality. Single architecture in the system — do not mix with any other code design.
+
+The Method is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: The Method`. Do not introduce DDD aggregates, Clean Architecture use cases, Hexagonal ports, Onion shells, or Vertical Slice handlers. Do not invent a hybrid.
+
+## Core principle (inviolable)
+
+**Decompose the system by axes of volatility, never by functionality.**
+
+A component is justified only when it encapsulates an independent reason to change. Two pieces of code that change for the same reason belong together. Two pieces that change for different reasons must be separated even if they currently look identical.
+
+If a component has no clear volatility it encapsulates, it must not exist.
+
+## The Universal Hierarchy (mandatory)
+
+Every system has exactly these 5 architectural categories plus 1 cross-cutting category. No other category may be invented.
+
+1. **Clients** — entry points. UI, CLI, public API endpoints, scheduled triggers, test harnesses. Volatility: presentation, protocol, channel.
+2. **Managers** — own a use case end-to-end. Sequence the work. Hold the workflow. Volatility: business workflow, use case orchestration.
+3. **Engines** — stateless business algorithms. Pure rules, calculations, validation logic. Volatility: business algorithm, formula, policy.
+4. **ResourceAccess** — only path to a Resource. Hides the technology of the data store. Volatility: data access technology.
+5. **Resources** — the actual data store / external system / queue / cache. Volatility: storage technology, vendor, schema.
+
+Cross-cutting (callable from any layer):
+
+6. **Utilities** — Security, Logging, Diagnostics, Hosting, Configuration, Localization, Pub/Sub bus, Identity. Stateless cross-cutting concerns. Volatility: infrastructure technology.
+
+Every code unit produced MUST belong to exactly one of these categories. If you cannot decide its category, the unit is wrong and must be redesigned.
+
+## Communication rules (inviolable)
+
+The hierarchy is strictly directed. Communication that violates these rules is a defect, regardless of how convenient it appears.
+
+1. **Clients call Managers only.** Clients do not call Engines, ResourceAccess, Resources, or other Clients.
+2. **Managers call Engines and ResourceAccess.** Managers may also call Utilities.
+3. **Managers do not call Managers directly.** Manager-to-Manager communication, when required, goes through a **Queue** (publish/subscribe via the Utility bus). Never synchronous Manager-to-Manager.
+4. **Engines do not call Engines.** Composition of engines happens in the Manager.
+5. **Engines do not call ResourceAccess.** The Manager pulls data via ResourceAccess and passes it into the Engine.
+6. **Engines and ResourceAccess do not call Clients.** No upward calls.
+7. **ResourceAccess is the only component allowed to touch a Resource.** Nothing else (no Manager, no Engine, no Client, no Utility) touches a Resource directly.
+8. **Resources do not call anything.** They are passive.
+9. **Utilities are callable by any layer, but do not contain business logic.** Utilities never call Managers, Engines, or ResourceAccess.
+10. **No skip-level calls upward.** Lower layers never call higher layers synchronously.
+11. **Calls fan out, never fan in across the same layer synchronously.** No sideways synchronous calls within Managers or within Engines.
+
+## Volatility rules (inviolable)
+
+1. A component exists only to **encapsulate one axis of volatility**. State it explicitly.
+2. The component's public surface must change only when its encapsulated volatility changes. If a change to an unrelated axis requires editing the component, the decomposition is wrong.
+3. The more volatile the area, the deeper inside the architecture it lives. The more stable, the closer to the edges.
+4. **Functional decomposition is forbidden.** Naming components after features ("OrderManager", "CustomerEngine") is allowed only when the feature itself is a volatility boundary. Naming components after operations ("CreateOrder", "ValidateCustomer") is forbidden.
+5. **Naming after volatility, not noun.** Prefer `PricingEngine` (algorithm volatility) over `OrderService` (feature). Prefer `OrderRepository` only if data-access technology is the encapsulated volatility.
+
+## Composability rules
+
+1. Every Manager must be composable. Adding a new Client (new UI, new API) must not require touching the Manager.
+2. Engines and ResourceAccess components must be reusable across Managers. If they cannot be reused, the volatility encapsulation is wrong.
+3. The system must support adding a new use case by adding 1 Manager (and possibly 1 Client method) without modifying any Engine, ResourceAccess, Resource, or Utility.
+
+## Forbidden patterns (inviolable)
+
+- **No domain-driven aggregates, anti-corruption layers, or bounded contexts** — that is DDD.
+- **No use cases as a separate layer** — Managers ARE the use cases. Do not create a "UseCase" layer on top of Managers.
+- **No ports & adapters / hexagonal terminology** — ResourceAccess plays the role of adapter for Resources. Do not introduce additional port/adapter layers.
+- **No vertical slices** — code is organized by category, never by feature folder.
+- **No Onion shells.** No "domain core" layer above Engines.
+- **No Repository pattern named after entities** ("UserRepository", "OrderRepository"). ResourceAccess is named after the **resource technology and its volatility**, not after a domain entity. Acceptable: `BillingDataAccess`, `CatalogStore`. Forbidden: `OrderRepository` if "Order" is not a volatility boundary.
+- **No anemic Engine** — an Engine without business logic is forbidden. An Engine with only getters/setters is a defect.
+- **No business logic in Clients.** Clients only translate input to a Manager call and present a Manager response.
+- **No business logic in ResourceAccess.** ResourceAccess maps technology to in-memory representations and nothing more.
+- **No business logic in Resources.** Stored procedures, triggers, or business-logic-bearing schemas are violations.
+- **No business logic in Utilities.** Utilities are infrastructure.
+- **No bypassing ResourceAccess** to touch a Resource (no ORM call in a Manager, no raw SQL in an Engine).
+- **No shared mutable state across components.** Engines are stateless. Managers hold transient workflow state only.
+
+## Mandatory acceptance per code unit
+
+Before any Manager / Engine / ResourceAccess / Client / Utility is committed, the author must be able to answer:
+
+1. Which one of the 6 categories does this belong to? (must be exactly one)
+2. What single axis of volatility does it encapsulate? (must be statable in 1 sentence)
+3. Which categories does it call? (must comply with the communication rules above)
+4. What change in the system would cause it to be edited? (must be the volatility it encapsulates, nothing else)
+5. Is it composable: can another Manager / Client be added without modifying this unit? (must be yes for non-Client units)
+
+A unit failing any answer must be redesigned before it ships.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- A Client calls Engine / ResourceAccess / Resource directly.
+- A Manager calls another Manager synchronously.
+- An Engine calls another Engine.
+- An Engine calls ResourceAccess.
+- Any code outside ResourceAccess touches a Resource.
+- A Utility contains business logic.
+- A Repository / Service / Manager is named after a noun-entity instead of a volatility axis (warn first, block on second occurrence in the same PR).
+- The PR adds a new top-level category not in the universal hierarchy.
+- The PR splits code by feature folders instead of by category.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- A component's encapsulated volatility is not declared (missing 1-line statement at top of file or class).
+- An Engine has no behavior (anemic).
+- A new Manager was added without a Client-level entry point.
+
+## Anti-patterns
+
+- "Service layer" with mixed Manager + Engine responsibilities
+- "Helper" / "Util" classes containing business logic
+- Domain entity classes with both data and behavior bound to persistence
+- "Facade" components that hide multiple Managers behind a single class
+- ResourceAccess methods that return business-decided values instead of raw data
+- Cross-Manager transactions implemented via direct calls
+- Synchronous chains crossing 3+ layers
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/core/skills/vertical-slice/SKILL.md

@@ -0,0 +1,127 @@
+---
+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.
+type: skill
+applies_to: |
+  Loaded by doer and reviewer when PROJECT.md `Code Design` is `Vertical Slice`.
+  Inviolable design rules. Doer applies during creation. Reviewer enforces at gate 5.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "Vertical Slice"
+      - "Jimmy Bogard"
+      - "feature folder"
+      - "slice architecture"
+---
+
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jdi-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "JDI (Just Do It) — lean workflow toolkit for Claude Code, GitHub Copilot, Antigravity, and OpenCode. 10 commands (7 loop + ralph + adopt + meta), 6 core agents + N per-project specialists with file-glob routing. Optional Playwright MCP + Caveman plugin install.",
   "bin": {
     "jdi": "bin/jdi.js"

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

@@ -0,0 +1,125 @@
+---
+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.
+triggers:
+  - "Clean Architecture"
+  - "Robert Martin clean"
+  - "Dependency Rule"
+  - "Use Cases layer"
+---
+
+# 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/antigravity/skills/ddd/SKILL.md

@@ -0,0 +1,131 @@
+---
+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.
+triggers:
+  - "DDD"
+  - "Domain-Driven Design"
+  - "bounded context"
+  - "aggregate root"
+  - "ubiquitous language"
+---
+
+# 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.