@imolko/ultra-agent 0.1.0-beta

package/skills/to-tasks/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: to-tasks
+description: Break a spec into independently-grabbable tasks, each declaring its blocking edges, using tracer-bullet vertical slices.
+disable-model-invocation: true
+---
+
+# To Tasks
+
+Break a spec into independently-grabbable tasks using vertical slices (tracer bullets), then publish them to the issue tracker via `tracker_cli`.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+Reference: A-042 (task structure), A-038 (skill-first in `Skill recomendado`), A-037 (labels), A-039 (spec → child issues).
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes an issue reference (issue number, URL, or path) as an argument, fetch it from the issue tracker using `tracker_cli` and read its full body and comments:
+
+```bash
+<tracker_cli> issue view <issue-id>
+```
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state. Task titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you are touching.
+
+### 3. Draft vertical slices
+
+Break the spec into **tracer bullet** tasks. Each task is a thin vertical slice that cuts through ALL integration layers end-to-end.
+
+Slices may be **HITL** or **AFK** — the `exec::` dimension (A-037). HITL requires a human in the loop (an architectural decision or a design review); AFK can be implemented and merged without one. Prefer AFK over HITL where possible.
+
+Rules for vertical slices:
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, tests, etc.)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each task, show:
+
+- **Titulo**: short descriptive name in `issue_language`
+- **Modo**: `exec::AFK` o `exec::HITL`
+- **Bloqueado por**: which other tasks (if any) must complete first
+
+Iterate with the user until they approve the breakdown.
+
+### 5. Publish the tasks to the issue tracker
+
+For each approved slice, publish a new issue using `tracker_cli` (default `glab`). Write all tasks in `issue_language` (default Spanish).
+
+Publish tasks in dependency order (blockers first) so you can reference real issue identifiers in the "Bloqueado por" section.
+
+#### Task Template
+
+Each task body must follow this structure — the canonical task structure is owned by A-042; this is its operational copy:
+
+```
+# Skill recomendado
+
+Name the skill(s) to use, by exact name (`/skill:<name>`) as the first instruction (A-038), and the next step in the flow. Example: `Para comenzar, usa /skill:tdd (→ /skill:ship).`
+
+# Contexto
+
+Explain the situation and general context for the task. This is important to give the person that will work on the task a general context and information to be productive really quickly.
+
+# Alcance
+
+Define the precise scope — short paragraphs on what is needed to close the task.
+
+# Criterio de cierre
+
+Indicate in tasks what is the criteria for finishing this task. Each task must have a clear focus and allows the worker to have a clear view of the goals required.
+
+This section helps the person responsible for approving the task (a different person from the implementer) to check if all the work has been done.
+
+Use a task format for each point: one checkbox per criterion (checkbox-list format owned by A-042).
+
+# Pruebas recomendadas
+
+When the responsible for the task completes the work, another person must check if it is OK.
+
+In this section, provide a suggestion of minimum tests the reviewer must perform to verify the work. The reviewer can approve if all tests pass, or reject otherwise.
+
+Each test should include a detailed list of steps and verifications to perform.
+
+# Tarea padre
+
+A reference to the parent spec.
+
+# Bloqueado por
+
+- A reference to the blocking task (if any)
+
+If no blockers, write: "Ninguno - puede iniciarse de inmediato"
+```
+
+#### Creating the Issue
+
+Before publishing each task, show a preview and ask for confirmation. On confirmation:
+
+```bash
+# Write the body to a temp file to avoid shell escaping issues
+cat > /tmp/issue-body.md << 'ISSUE_EOF'
+<CUERPO_DEL_ISSUE>
+ISSUE_EOF
+
+# Create the issue
+<tracker_cli> issue create \
+  --title "<TITULO_DEL_ISSUE>" \
+  --description "$(cat /tmp/issue-body.md)" \
+  --label "state::ready,<EXEC_MODE>" \
+  --linked-issues <PARENT_IID>
+```
+
+(`<EXEC_MODE>` in the command above is `exec::AFK` or `exec::HITL`.)
+
+**Linked issues:** Use `--linked-issues <PARENT_IID>` to link each task to the parent spec. This enables `ship` to discover children via the tracker's API.
+
+The task title should be concise and descriptive in `issue_language`.
+
+### 6. Confirm
+
+After creating all tasks, show a summary table:
+
+```
+| # | Titulo | Modo | Bloqueado por |
+|---|--------|------|---------------|
+| #1 | ... | exec::AFK | Ninguno |
+| #2 | ... | exec::HITL | #1 |
+```
+
+Include each task's URL.
+
+Leave the parent spec open and untouched — you create only the child tasks.
+
+Offer the next step: `/skill:ship` over the parent spec — its IID is already resolved.
+
+## Rules
+
+The task's formatting rules are owned by A-042 — read and apply them from there, not restated here.

package/skills/triage/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: triage
+description: Move issues and external merge requests through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.
+disable-model-invocation: true
+---
+
+# Triage
+
+Move issues on the issue tracker through a small state machine of triage roles. External merge requests are the same machine applied to attached code.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+Reference: A-037 (label taxonomy and state machine), A-042 (issue-triado brief), A-038 (skill-first), A-031 (ubiquitous language).
+
+Every comment or issue posted during triage **must** start with:
+
+```
+> *This was generated by AI during triage.*
+```
+
+## Triage's part of the machine
+
+Triage fills the ingestion region of the label taxonomy: `type::` (bug/enhancement), `state::` up to `ready`, and `exec::` when the brief is written. The dimension values and the state transitions are owned by A-037 — read them there, not restated here.
+
+An MR: `state::ready` + `exec::AFK` means an agent takes the next step on the diff; `state::ready` + `exec::HITL` means ready for a human to merge.
+
+If state labels conflict, flag it and ask the maintainer before doing anything else. The maintainer can override any transition — flag unusual ones and ask before proceeding.
+
+## Invocation
+
+The maintainer invokes `/skill:triage` and describes what they want:
+
+- "Show me anything that needs my attention"
+- "Let's look at #42"
+- "Move #42 to state::ready"
+- "What's ready for agents to pick up?"
+
+## Show what needs attention
+
+Query the issue tracker and present three buckets, oldest first:
+
+1. **Unlabeled** (no `state::`) — never triaged.
+2. **`state::needs-info`** — waiting on the reporter.
+3. **`state::ready`** — specified, in the queue (`exec::` says who takes it).
+
+## Categorise and verify
+
+For each issue:
+
+1. Read the body and comments (`<tracker_cli> issue view <id>`).
+2. Assign the category (`type::bug`/`type::enhancement`) and initial state (`state::`).
+3. **Verify**: can the issue be actioned as written? If it's ambiguous, move to `state::needs-info` with the specific questions the reporter must answer.
+4. If a design decision is half-baked, grill it (`/skill:grill-me`) before writing the brief.
+
+## Write the agent-ready brief
+
+When an issue reaches `state::ready`, write the brief the implementing agent will consume without asking, and set the execution mode — `exec::AFK` if an agent can do it alone, `exec::HITL` if a human must stay in the loop. The brief's required content is owned by A-042 (issue triado) — read it there. Point the brief at the relevant skill as its first instruction (A-038): `type::bug` → `/skill:diagnose-bug` first, then `/skill:implement` + `/skill:tdd` for the fix; `type::enhancement` → `/skill:implement` + `/skill:tdd` (+ `/skill:ultra-generator` if scaffolding).
+
+## Apply labels
+
+Apply the labels via `tracker_cli` (default `glab`) — the mapping from triage roles to labels is fixed in A-037. Post the brief as a comment on the issue, prefixed with the disclaimer:
+
+```bash
+<tracker_cli> issue note <iid> -m "> *This was generated by AI during triage.*
+
+<brief>"
+```
+
+A comment on the issue is the brief's only home — the reporter's body stays untouched.
+
+## Rules
+
+The label taxonomy and state machine are owned by A-037; the triaged-issue brief content is owned by A-042 — read and apply them from there, not restated here.

package/skills/ultra-generator/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: ultra-generator
+description: Generate ultra-ddd compliant domain artifacts using ultra-generator
+---
+
+# Ultra-Generator
+
+## Purpose
+
+Ultra-Generator is a scaffolding tool for [ultra-ddd](https://gitlab.com/imolko/ultra-ddd) projects. It generates domain artifacts (value objects, entities, aggregates, services, domain events), features (commands and queries with minimal in-memory infrastructure), actions, errors, and infrastructure drivers with boilerplate code that is immediately compilable and testable.
+
+Ultra-Generator works in tandem with [ultra-reporter](https://gitlab.com/imolko/ultra-reporter), which scans generated files to produce Docusaurus-based documentation.
+
+## DDD Philosophy: Forget About Infrastructure First
+
+Ultra-Generator follows Clean Architecture principles. The recommended workflow is:
+
+1. **Define domain objects** using `add-domain`
+2. **Create features** using `add-feature` — this generates the use case with **minimal in-memory drivers** (no database, no GraphQL, no NestJS)
+3. **Validate business logic** — run tests against in-memory drivers, iterate with domain experts
+4. **Add actions** using `add-action` — extend ports with specific methods
+5. **Wire infrastructure** using `add-driver` — ONLY after business logic is validated, add MongoDB, GraphQL, or NestJS drivers
+
+This ensures the domain layer stays pure and infrastructure choices are deferred until the business rules are correct.
+
+## When to Use
+
+Use ultra-generator when the user needs to:
+- Create a new domain artifact (value object, entity, aggregate-root, service, domain event)
+- Create a new feature (command or query) with minimal in-memory infrastructure
+- Add actions to a feature
+- Define domain errors
+- Add infrastructure drivers (MongoDB, GraphQL + NestJS) to a feature
+
+## How to Invoke
+
+### Primary: CLI Mode
+
+```bash
+# Preview (dry-run)
+npx ultra-generator generate --json-file /tmp/input.json --dry-run
+
+# Execute
+npx ultra-generator generate --json-file /tmp/input.json
+```
+
+Input JSON format: `{ "generator": "<generator-name>", "data": { ... } }`
+
+### Advanced: JS/TS API
+
+```ts
+import { run } from '@imolko/ultra-generator';
+
+const result = await run(
+  { generator: 'add-domain', data: { ... } },
+  { dryRun: true }
+);
+```
+
+## Agent Workflow
+
+1. **Collect data** from the user (see Generator Input Guides below)
+2. **Construct JSON** with `{ generator, data }`
+3. **Dry-run** to preview generated files
+4. **Present summary** to the user (recommended)
+5. **Execute** generation
+6. **Read the `.instructions.md` stub** in the generated artifact directory
+7. **Follow the checklist** — the stub links to canonical instructions
+8. **Implement customizations** following the TDD red-green-refactor loop
+
+### Recommended Agent Workflow for Features
+
+```
+User requests a new business capability
+  → Step 1: add-domain (define domain objects needed)
+  → Step 2: add-feature (create command/query with in-memory drivers)
+  → Step 3: add-errors (define domain/feature errors)
+  → Step 4: add-action (add methods to ports — repository, presenter, etc.)
+  → Step 5: User validates business logic with domain experts
+  → Step 6: add-driver (wire MongoDB, GraphQL, NestJS after validation)
+```
+
+## Response Interpretation
+
+The `GeneratorResult` response contains:
+- `success: boolean` — whether generation succeeded
+- `generator: string` — which generator was used
+- `changes: FileChange[]` — list of created/modified files
+- `dryRun: boolean` — whether changes were written to disk
+- `instructions: { canonical: string, stubPath: string }` — references to instructions
+
+After generation, the agent should read the `.instructions.md` stub (path in `instructions.stubPath`) and follow the canonical instructions (path in `instructions.canonical`).
+
+## Batch Generation
+
+For creating multiple artifacts at once, collect data as an array of `GeneratorInput` objects. Order matters — resolve dependencies:
+
+- An artifact may reference other artifacts via `conditions[].type` and `props[].type`
+- Build a dependency graph from these references
+- Topologically sort: leaf artifacts first, dependent artifacts after
+- Generate artifacts in dependency order
+- **Important**: `add-driver` should always be the LAST step — add infrastructure only after business logic is defined and validated
+
+## Generator Input Guides
+
+### add-domain
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `domainType` | ✅ | `value-object` \| `entity` \| `aggregate-root` \| `service` \| `domain-event` | Type of domain artifact |
+| `domainName` | ✅ | string (kebab-case) | Name of the artifact |
+| `description` | ✅ | string | Human-readable description |
+| `conditions` | [] | `DomainProperty[]` | Validation conditions |
+| `props` | [] | `DomainProperty[]` | Computed properties |
+| `conditionsErrorsName` | [] | `string[]` | Custom error names for conditions |
+| `othersErrorsName` | [] | `string[]` | Other domain error names |
+| `testCases` | [] | `string[]` | Test case descriptions |
+| `contextName` | — | string | Domain context (default: `''`) |
+| `boundedContext` | — | string | Bounded context for documentation tagging (fallback: `contextName`) |
+| `language` | — | `'en'` \| `'es'` | Language for generated README (default: `'en'`) |
+| `tags` | — | string | Comma-separated tags |
+| `directory` | — | string | Custom output directory |
+
+#### Domain event fields
+
+These fields apply when `domainType` is `domain-event`:
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `eventTitle` | ✅ | string | Human-readable event title |
+| `aggregateName` | ✅ | string (kebab-case) | Owning aggregate name |
+| `scope` | — | `LOCAL` \| `GLOBAL` | Event scope (default: `LOCAL`) |
+| `emitterApp` | — | string | Emitting application name (default: from config `appName`, then context) |
+| `dataContentType` | — | string | Content type of event data (default: `application/json`) |
+| `eventOwner` | — | string | Organization/team identifier (default: `default`) |
+| `sampleData` | — | `object[]` | Sample data payloads (auto-generated from conditions if omitted) |
+
+#### DomainProperty
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `name` | ✅ | string (camelCase) | Property name |
+| `type` | ✅ | string | Property type (e.g., `string`, `number`, `Uuid`, domain object name) |
+| `category` | ✅ | `basic` \| `value-object` \| `entity` \| `aggregate-root` \| `service` | Type category |
+| `description` | — | string | Human-readable description |
+| `validation` | — | `ValidationConstraints` | Zod native constraints (see below) |
+
+#### ValidationConstraints
+
+Native Zod primitives for standard validations. Only applicable when `category` is `basic`.
+
+| Field | Type | Applies to | Generates |
+|-------|------|-----------|-----------|
+| `minLength` | `number` | `string` | `.min(n)` |
+| `maxLength` | `number` | `string` | `.max(n)` |
+| `pattern` | `string` | `string` | `.regex(new RegExp(pattern))` |
+| `min` | `number` | `number` | `.min(n)` |
+| `max` | `number` | `number` | `.max(n)` |
+| `customErrors` | `string[]` | any | `superRefine` at object level + triggers `add-errors` |
+
+**Constraints are validated at schema level**: string properties reject `min`/`max`, number properties reject `minLength`/`maxLength`/`pattern`, and `min` must be ≤ `max`.
+
+**Examples:**
+
+```json
+// String with native validations
+{ "name": "email", "type": "string", "category": "basic",
+  "validation": { "minLength": 5, "maxLength": 100, "pattern": "^[a-z]+@[a-z]+\\.com$" } }
+
+// Number with range
+{ "name": "age", "type": "number", "category": "basic",
+  "validation": { "min": 0, "max": 150 } }
+
+// Complex domain rule with custom error
+{ "name": "password", "type": "string", "category": "basic",
+  "validation": { "customErrors": ["weak-password"] } }
+```
+
+### add-errors
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `target` | ✅ | `features` \| `domain-rules` \| `domain-others` | Where to add errors |
+| `featureTargetName` | ✅ | string | Target artifact name |
+| `errorsName` | ✅ | `string[]` | Error names (kebab-case) |
+| `contextName` | — | string | Domain context |
+| `domainFeatureRoot` | — | string | Auto-derived from config if omitted |
+
+### add-feature
+
+Generates a feature (command or query) with **minimal in-memory infrastructure** — no database, no GraphQL, no NestJS. The use case is immediately compilable and testable.
+
+Generated structure:
+```
+feature/
+├── use-case/           # Pure business logic
+│   ├── use-case.ts     # Functional pipeline (seedTV → checkRequirements → executeSequentially → when)
+│   ├── presenter.port.ts
+│   ├── repository.port.ts
+│   └── errors/
+├── adapters/           # Port adapters
+│   ├── presenter/
+│   ├── repository/
+│   └── controller/
+└── drivers/            # In-memory implementations
+    ├── in-memory-presenter/
+    └── in-memory-repository/
+```
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `featureName` | ✅ | string (kebab-case) | Feature name |
+| `featureType` | ✅ | `command` \| `query` | Feature type |
+| `testCases` | [] | `string[]` | Test case descriptions |
+| `featuresRoot` | — | string | Auto-derived from config if omitted |
+
+### add-action
+
+Adds methods to service ports and adapters within an existing feature. The generator discovers available service ports by scanning `use-case/*.port.ts` files in the target feature. It updates the use case, adapters, controller, and spec — but does **NOT** touch any driver implementations.
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `serviceTargetName` | ✅ | string | Service name (e.g., `repository`, `presenter`) |
+| `featureTargetName` | ✅ | string | Target feature name in kebab-case |
+| `actionName` | ✅ | string (camelCase) | Action/method name |
+| `actionType` | ✅ | `command` \| `query` \| `validation` | Type of action |
+| `params` | [] | `ActionParams[]` | Method parameters |
+| `executionDataType` | — | string | Return type for queries (default: `void`) |
+| `errorsName` | [] | `string[]` | Error names for this action |
+| `featuresRoot` | — | string | Auto-derived from config if omitted |
+
+### add-driver
+
+Adds infrastructure-specific drivers to an existing feature. Should be invoked **AFTER** business logic is validated with in-memory drivers.
+
+Available driver types:
+- `mongodb` — Repository driver with Mongoose model injection port
+- `graphql` — Presenter driver + NestJS resolver/module (generated together)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `featureTargetName` | ✅ | string | Target feature name in kebab-case |
+| `driverType` | ✅ | `mongodb` \| `graphql` | Type of driver to add |
+| `templatePath` | — | string | Custom driver template directory path (for team-specific drivers) |
+| `featuresRoot` | — | string | Auto-derived from config if omitted |
+
+**Important**: Running `add-driver` on a feature with no port actions will fail. Use `add-action` first to define the ports, then `add-driver` to add the implementation.
+
+## Canonical Instructions
+
+After generating an artifact, read the canonical instructions for post-generation steps:
+
+| Artifact Type | Canonical Instructions |
+|---------------|----------------------|
+| Value Object | `@imolko/ultra-generator/skills/ultra-generator/references/value-object.md` |
+| Entity | `@imolko/ultra-generator/skills/ultra-generator/references/entity.md` |
+| Aggregate Root | `@imolko/ultra-generator/skills/ultra-generator/references/aggregate-root.md` |
+| Service | `@imolko/ultra-generator/skills/ultra-generator/references/service.md` |
+| Domain Event | `@imolko/ultra-generator/skills/ultra-generator/references/domain-event.md` |
+| Feature | (coming soon) |
+| Action | (coming soon) |
+| Errors | (coming soon) |
+| Driver | (coming soon) |

package/skills/ultra-generator/references/aggregate-root.md

@@ -0,0 +1,149 @@
+# Working with an Aggregate Root
+
+## Files Generated
+
+| File | Purpose |
+|------|---------|
+| `aggregate.ts` | Main class with `@RegisterAggregate` decorator |
+| `definition.ts` | Validation, serialization, identity, and snapshot logic |
+| `props.ts` | Internal state interface |
+| `conditions.ts` | Zod validation rules (build + rebuild schemas) |
+| `primitive.ts` | Public read shape (exposed to application layer) |
+| `snapshot.ts` | Persistence shape for event sourcing / database storage |
+| `payload.ts` | Serialization format for reconstruction |
+| `security-token.ts` | Security token for snapshot integrity |
+| `index.ts` | Barrel exports |
+| `errors/index.ts` | Domain error types |
+| `README.md` | Frontmatter metadata + narrative documentation |
+| `aggregate.spec.ts` | Test file |
+
+## What to Customize
+
+### `props.ts` — Internal State
+
+The `Props` interface defines the internal representation of this aggregate.
+Aggregates have identity (`id: Uuid`) and a `version` field managed automatically.
+
+**Checklist:**
+- [ ] Verify property types match your domain model
+- [ ] Update or add property descriptions in JSDoc
+- [ ] Ensure all domain concepts are represented
+
+### `conditions.ts` — Validation Rules
+
+Zod validation schema that guards construction and reconstruction.
+Aggregates have two schemas: `build` (for creation) and `rebuild` (for restoring from persistence).
+
+**Checklist:**
+- [ ] Review each validation rule in both `build` and `rebuild`
+- [ ] Add custom refinements for domain-specific constraints
+- [ ] Ensure the `id` and `version` conditions are present
+
+### `primitive.ts` — Public API Shape
+
+Defines what the application layer can read from this aggregate.
+
+**Checklist:**
+- [ ] Verify the public shape includes all necessary fields
+- [ ] Ensure internal-only fields are excluded
+
+### `snapshot.ts` — Persistence Shape
+
+Defines the shape for persisting the aggregate (event sourcing, database storage).
+This may differ from `Primitive` to include versioning metadata.
+
+**Checklist:**
+- [ ] Ensure the snapshot includes all fields needed for reconstruction
+- [ ] Verify the version field is included for optimistic concurrency
+
+### `definition.ts` — Identity, Snapshot & Serialization
+
+Contains `getPrimitive()`, `getSnapshot()`, and lifecycle methods.
+The base class handles identity and version management.
+
+**Checklist:**
+- [ ] Review `getSnapshot()` — does it capture all persistence-relevant fields?
+- [ ] Review `getPrimitive()` — does it properly expose the public shape?
+- [ ] Add custom methods for domain operations
+- [ ] Add methods that mutate state (with proper version tracking)
+
+### `errors/` — Domain Errors
+
+Domain-specific errors that this aggregate can produce.
+
+**Checklist:**
+- [ ] Define custom error classes for each failure mode
+- [ ] Register errors in `errors/index.ts`
+
+### `aggregate.spec.ts` — Tests
+
+The template includes tests for valid creation, snapshot save/restore, and
+placeholder tests for error cases and invalid snapshots.
+
+**Checklist:**
+- [ ] The valid-creation test should already pass (green)
+- [ ] The snapshot restore test should pass (green)
+- [ ] Add a test for invalid snapshot restoration (tampered data)
+- [ ] Add tests for domain operations and state mutations
+- [ ] Add tests for error scenarios
+
+### `README.md` — Narrative Documentation
+
+Rich documentation rendered by ultra-reporter on the Docusaurus site.
+
+**Checklist:**
+- [ ] Fill the `Purpose` section — what is this aggregate for?
+- [ ] Document `Domain Rules` — what invariants does it enforce?
+- [ ] Add `Usage Examples` — how is it created and used?
+- [ ] Document `Relationships` — to other domain artifacts
+
+## What Not to Touch
+
+These files are managed by scaffolding. Avoid direct edits:
+
+| File | Reason |
+|------|--------|
+| `index.ts` | Barrel exports — regenerated on scaffold updates |
+| `payload.ts` | Type derived from conditions — managed automatically |
+| `security-token.ts` | Security token — managed by generator |
+| `errors/index.ts` | Error re-exports — managed automatically |
+
+## Validation & Errors
+
+Aggregates use Zod for validation via `conditions.ts` with two schemas:
+- `build`: Validates creation inputs, transforms with `setVersionOne`
+- `rebuild`: Extends `build` with a required `version` field for restoring from persistence
+
+## Testing
+
+### TDD Cycle
+
+Aggregates follow the red-green-refactor TDD loop:
+
+1. **Red**: Write a failing test for an invalid input, state transition, or snapshot scenario
+2. **Green**: Add the validation rule or domain logic to make it pass
+3. **Refactor**: Clean up while keeping tests green
+
+### Example
+
+```ts
+// Test: aggregate creation with valid input
+it('crear Order válida', async () => {
+  const payload: Payload = { customerId: 'abc-123', amount: 100 };
+  const result = Order.create(payload);
+  expect(result).toBeValid();
+  const aggregate = result.getValue();
+  expect(aggregate).toBeInstanceOf(Order);
+});
+
+// Test: snapshot save and restore
+it('restaurar snapshot', async () => {
+  const payload: Payload = { customerId: 'abc-123', amount: 100 };
+  const createResult = Order.create(payload);
+  expect(createResult).toBeValid();
+  const memento = createResult.getValue().takeMemento();
+  const mementoSerialized = memento.getValue().getPrimitive();
+  const restored = Order.restore(mementoSerialized);
+  expect(restored).toBeValid();
+});
+```