@imolko/ultra-agent 0.1.0-beta

package/skills/ultra-generator/references/domain-event.md

@@ -0,0 +1,174 @@
+# Working with a Domain Event
+
+## Files Generated
+
+| File | Purpose |
+|------|---------|
+| `event.ts` | Main class with `@RegisterEvent` decorator + `DomainEventFactory` |
+| `definition.ts` | `EventDefinitionPayload` — static event template |
+| `shape-history.ts` | Shape evolution definition (initial + evolution[]) |
+| `shape-v1.ts` | Shape v1.0.0 conditions (Zod schema for event data) |
+| `shape-v1-sample.ts` | Sample data for v1.0.0 |
+| `payload.ts` | Payload type (re-exported from ultra-ddd) |
+| `index.ts` | Barrel exports |
+| `README.md` | Frontmatter metadata + narrative documentation |
+| `event.spec.ts` | Test file |
+
+## What to Customize
+
+### `definition.ts` — Event Definition
+
+The `EventDefinitionPayload` defines all static properties of the event.
+The `securityToken` must be replaced before production deployment.
+
+- [ ] Replace `securityToken` with a real secret before production
+- [ ] Verify `emitterApp` matches your application
+- [ ] Verify `eventOwner` matches your organization
+
+### `shape-v1.ts` — Data Schema
+
+The Zod schema validates the `data` field of event occurrences.
+Each property maps to a domain concept.
+
+**Auto-generated imports**: The generator attempts to resolve imports for
+value-object, entity, and aggregate-root types from sibling directories.
+Types that cannot be resolved at generation time are emitted with TODO placeholders.
+
+- [ ] Replace TODO placeholder imports with real imports for referenced domain types
+  ```typescript
+  // TODO: Import StockMovementId from its domain directory
+  // Example: import { StockMovementId } from '../stock-movement-id/value-object';
+  const StockMovementId = { rules: () => z.any() }; // placeholder — replace with real import
+  ```
+- [ ] Add `.refine()` or `.superRefine()` for custom data validation rules
+- [ ] Verify all domain types referenced in the schema exist and are properly imported
+
+### `shape-history.ts` — Shape Evolution
+
+The `ShapeEvolution` tracks all data schema versions. The initial version is v1.0.0.
+
+**When adding a new data version:**
+1. Create `shape-v2.ts` with the new conditions
+2. Create `shape-v2-sample.ts` with sample data
+3. Add an entry to `evolution[]`:
+   ```typescript
+   evolution: [
+     {
+       shape: { version: '2.0.0' as const, conditions: SHAPE_V2_0_0, sampleData: SAMPLE_DATA_V2_0_0 },
+       migrate: (data) => { /* transform v1 data to v2 */ },
+     },
+   ],
+   ```
+4. Update the `LastShapeVersion` type to the newest version:
+   ```typescript
+   export type LastShapeVersion = '2.0.0';
+   ```
+
+**Important**: Never remove old shape versions — they are needed to hydrate historical events.
+
+- [ ] Add new shape version files when evolving the data schema
+- [ ] Implement the `migrate` function for each evolution step
+- [ ] Update `LastShapeVersion` type
+
+### `event.spec.ts` — Tests
+
+Two tests are generated: one for valid input (green start) and one for invalid input.
+
+- [ ] The valid-input test should pass (green)
+- [ ] Write additional failing tests for domain-specific invalid data (red → green)
+- [ ] Add test for `hydrate()` — restoring from a serialized CloudEvent:
+  ```typescript
+  it('hidratar desde cloud event firmado', () => {
+    const event = StockMovementCreated.produce(validPayload).getValue();
+    const signed = event.getCloudEventSigned().getValue();
+    const hydrated = StockMovementCreated.hydrate(signed).getValue();
+    expect(hydrated.getPayload()).toEqual(event.getPayload());
+  });
+  ```
+- [ ] Add test for `getCloudEventSigned()` — CloudEvent serialization produces valid signed output
+
+### `README.md` — Documentation
+
+Rich documentation rendered by ultra-reporter.
+
+- [ ] Fill Purpose / Propósito section — what does this event represent?
+- [ ] Document Rules / Reglas — what invariants does the event data enforce?
+- [ ] Add Usage Examples / Ejemplos de uso
+- [ ] Update Mermaid diagram in Relationships / Relaciones with real artifact connections
+
+## What Not to Touch
+
+| File | Reason |
+|------|--------|
+| `index.ts` | Barrel exports — regenerated on scaffold updates |
+| `payload.ts` | Re-export from ultra-ddd — managed automatically |
+
+## Shape Evolution
+
+Domain events use ShapeEvolution to version the `data` field schema.
+Each version has:
+
+- **conditions**: Zod schema defining the data shape for that version
+- **sampleData**: Example data used by ultra-reporter and tests
+
+The `LastShapeVersion` type in `shape-history.ts` tracks the current version
+for type-narrowing when accessing occurrence data:
+
+```typescript
+const data = event.getOcurrenceData<StockMovementCreatedV1>();
+```
+
+## Testing
+
+### TDD Cycle
+
+Domain event validation follows the red-green-refactor loop:
+
+1. **Red**: Write a failing test for invalid data
+2. **Green**: Add the validation rule to `shape-v1.ts`
+3. **Refactor**: Clean up while keeping tests green
+
+### Example
+
+```typescript
+// Test: movementId must not be empty
+it('rechazar movementId vacio', () => {
+  const payload: Payload = {
+    context: {
+      instance: 'test-instance',
+      tenantId: '00000000-0000-0000-0000-000000000001',
+      schemaRegistryUrl: 'https://schema.example.dev',
+      emitterDomain: 'example',
+    },
+    ocurrence: {
+      id: '00000000-0000-0000-0000-000000000002',
+      ocurredAt: '2026-01-01T00:00:00.000Z',
+      publishedAt: '2026-01-01T00:00:00.000Z',
+      aggregateId: 'stock-movement-001',
+      dataSchemaVersion: '1.0.0',
+      data: { movementId: '', type: 'INBOUND', timestamp: '2026-01-01T00:00:00.000Z' },
+    },
+  };
+  const result = StockMovementCreated.produce(payload);
+  expect(result.isValid()).toBe(false);
+});
+```
+
+### `hydrate()` and `getCloudEventSigned()`
+
+Test round-trip serialization to ensure events can be persisted and restored:
+
+```typescript
+it('serializar y deserializar cloud event', () => {
+  const event = StockMovementCreated.produce(validPayload).getValue();
+  const signed = event.getCloudEventSigned().getValue();
+  const hydrated = StockMovementCreated.hydrate(signed).getValue();
+  expect(hydrated.getPayload()).toEqual(event.getPayload());
+});
+```
+
+## Integration with ultra-reporter
+
+The `@RegisterEvent` decorator registers the event with the domain directory.
+ultra-reporter discovers registered events and generates documentation including
+the data schema and sample data from the shape history.

package/skills/ultra-generator/references/entity.md

@@ -0,0 +1,133 @@
+# Working with an Entity
+
+## Files Generated
+
+| File | Purpose |
+|------|---------|
+| `entity.ts` | Main class with `@RegisterEntity` decorator |
+| `definition.ts` | Validation, serialization, and identity logic |
+| `props.ts` | Internal state interface |
+| `conditions.ts` | Zod validation rules |
+| `primitive.ts` | Public read shape (exposed to application layer) |
+| `payload.ts` | Serialization format for reconstruction |
+| `index.ts` | Barrel exports |
+| `errors/index.ts` | Domain error types |
+| `README.md` | Frontmatter metadata + narrative documentation |
+| `entity.spec.ts` | Test file |
+
+## What to Customize
+
+### `props.ts` — Internal State
+
+The `Props` interface defines the internal representation of this entity.
+Entities have an identity (`id: Uuid`) that is 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. Every entity must be
+created in a valid state — these rules enforce that.
+
+**Checklist:**
+- [ ] Review each validation rule
+- [ ] Add custom refinements for domain-specific constraints
+- [ ] Ensure the `id` condition is present (auto-added for entities)
+
+### `primitive.ts` — Public API Shape
+
+Defines what the application layer can read from this entity.
+This is the "read model" — it should not expose internal details.
+
+**Checklist:**
+- [ ] Verify the public shape includes all necessary fields
+- [ ] Ensure internal-only fields are excluded
+
+### `definition.ts` — Identity & Serialization Logic
+
+Contains `getPrimitive()` and `getPayload()`. Entities have identity management
+via `Uuid` — the base class handles this.
+
+**Checklist:**
+- [ ] Review serialization — does it properly map Props to Primitive?
+- [ ] Review deserialization — does Payload reconstruct correctly?
+- [ ] Add custom methods for domain operations
+
+### `errors/` — Domain Errors
+
+Domain-specific errors that this entity can produce.
+
+**Checklist:**
+- [ ] Define custom error classes for each failure mode
+- [ ] Register errors in `errors/index.ts`
+
+### `entity.spec.ts` — Tests
+
+The template includes a valid-creation test that verifies the entity is created
+correctly and its primitive output matches expectations. It also includes
+placeholder tests for error cases.
+
+**Checklist:**
+- [ ] The valid-creation test should already pass (green)
+- [ ] Add a failing test for an error case (red)
+- [ ] Implement the validation to make it pass (green)
+- [ ] Refactor if needed
+- [ ] Add tests for identity-related edge cases
+
+### `README.md` — Narrative Documentation
+
+Rich documentation rendered by ultra-reporter on the Docusaurus site.
+
+**Checklist:**
+- [ ] Fill the `Purpose` section — what is this entity 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 |
+| `errors/index.ts` | Error re-exports — managed automatically |
+
+## Validation & Errors
+
+Entities use Zod for validation via `conditions.ts`. The `id` condition is auto-added
+as a `Uuid` type. Custom domain errors can be added via Zod refinements.
+
+## Testing
+
+### TDD Cycle
+
+Entities follow the red-green-refactor TDD loop:
+
+1. **Red**: Write a failing test for an invalid input or identity 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: entity creation with valid input
+it('crear UserEntity valida', async () => {
+  const payload: Payload = { name: 'John', email: 'john@example.com' };
+  const result = UserEntity.create(payload);
+  expect(result).toBeValid();
+  const entity = result.getValue();
+  expect(entity).toBeInstanceOf(UserEntity);
+});
+
+// Test: invalid email rejected
+it('rechazar email inválido', async () => {
+  const payload: Payload = { name: 'John', email: 'not-an-email' };
+  const result = UserEntity.create(payload);
+  expect(result).toBeError();
+});
+```

package/skills/ultra-generator/references/service.md

@@ -0,0 +1,92 @@
+# Working with a Service
+
+## Files Generated
+
+| File | Purpose |
+|------|---------|
+| `service.ts` | Main class with `@RegisterService` decorator |
+| `definition.ts` | Service execution logic |
+| `service-input.ts` | Input type for the service |
+| `service-output.ts` | Output type for the service |
+| `index.ts` | Barrel exports |
+| `README.md` | Frontmatter metadata + narrative documentation |
+| `service.spec.ts` | Test file |
+
+## What to Customize
+
+### `service-input.ts` — Input Type
+
+Defines the input that this service accepts. This is the contract
+that callers must fulfill.
+
+**Checklist:**
+- [ ] Define the shape of input data
+- [ ] Add JSDoc descriptions for each field
+- [ ] Consider validation — should the input be validated before reaching the service?
+
+### `service-output.ts` — Output Type
+
+Defines the output that this service produces.
+
+**Checklist:**
+- [ ] Define the shape of output data
+- [ ] Add JSDoc descriptions for each field
+
+### `definition.ts` — Execution Logic
+
+Contains the `execute()` method — the core business logic of the service.
+
+**Checklist:**
+- [ ] Implement the `execute()` method with domain logic
+- [ ] Add helper methods as needed
+- [ ] Consider error handling — what errors can this service produce?
+- [ ] Add JSDoc to document the execution contract
+
+### `service.spec.ts` — Tests
+
+The template includes a placeholder test.
+
+**Checklist:**
+- [ ] Write a test for the happy path
+- [ ] Write tests for error scenarios
+- [ ] Write tests for edge cases
+- [ ] Follow the red-green-refactor TDD loop
+
+### `README.md` — Narrative Documentation
+
+Rich documentation rendered by ultra-reporter on the Docusaurus site.
+
+**Checklist:**
+- [ ] Fill the `Purpose` section — what is this service for?
+- [ ] Document `Domain Rules` — what business logic does it implement?
+- [ ] Add `Usage Examples` — how is this service invoked?
+- [ ] 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 |
+
+## Testing
+
+### TDD Cycle
+
+Services follow the red-green-refactor TDD loop:
+
+1. **Red**: Write a failing test for a service execution
+2. **Green**: Implement the minimal logic to make it pass
+3. **Refactor**: Clean up while keeping tests green
+
+### Example
+
+```ts
+// Test: service execution with valid input
+it('ejecutar servicio exitosamente', () => {
+  const input: ServiceInput = { ... };
+  const result = BillingService.of().execute(input);
+  expect(result).toEqual(expectedOutput);
+});
+```

package/skills/ultra-generator/references/value-object.md

@@ -0,0 +1,135 @@
+# Working with a Value Object
+
+## Files Generated
+
+| File | Purpose |
+|------|---------|
+| `value-object.ts` | Main class with `@RegisterValueObject` decorator |
+| `definition.ts` | Validation, serialization, and construction logic |
+| `props.ts` | Internal state interface |
+| `conditions.ts` | Zod validation rules |
+| `primitive.ts` | Public read shape (exposed to application layer) |
+| `payload.ts` | Serialization format for reconstruction |
+| `index.ts` | Barrel exports |
+| `errors/index.ts` | Domain error types |
+| `README.md` | Frontmatter metadata + narrative documentation |
+| `value-object.spec.ts` | Test file |
+
+## What to Customize
+
+### `props.ts` — Internal State
+
+The `Props` interface defines the internal representation of this value object.
+Each property maps to a domain concept and is validated by `conditions.ts`.
+
+**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. Every value object must be
+created in a valid state — these rules enforce that.
+
+**Checklist:**
+- [ ] Review each validation rule
+- [ ] Add custom refinements for domain-specific constraints
+- [ ] Ensure error messages are meaningful
+
+### `primitive.ts` — Public API Shape
+
+Defines what the application layer can read from this value object.
+This is the "read model" — it should not expose internal details.
+
+**Checklist:**
+- [ ] Verify the public shape includes all necessary fields
+- [ ] Ensure internal-only fields are excluded
+
+### `definition.ts` — Serialization Logic
+
+Contains `getPrimitive()` (for application layer) and `getPayload()` (for persistence/reconstruction).
+The base class provides default implementations; override if you need custom serialization.
+
+**Checklist:**
+- [ ] Review serialization — does it properly map Props to Primitive?
+- [ ] Review deserialization — does Payload reconstruct correctly?
+- [ ] Add custom methods for domain operations
+
+### `errors/` — Domain Errors
+
+Domain-specific errors that this value object can produce.
+
+**Checklist:**
+- [ ] Define custom error classes for each failure mode
+- [ ] Register errors in `errors/index.ts`
+
+### `value-object.spec.ts` — Tests
+
+The template includes a valid-input test and a placeholder for error cases.
+
+**Checklist:**
+- [ ] The valid-input test should already pass (green)
+- [ ] Add a failing test for an error case (red)
+- [ ] Implement the validation to make it pass (green)
+- [ ] Refactor if needed
+- [ ] Add tests for all error scenarios identified in `errors/`
+
+### `README.md` — Narrative Documentation
+
+Rich documentation rendered by ultra-reporter on the Docusaurus site.
+
+**Checklist:**
+- [ ] Fill the `Purpose` section — what is this value object 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 |
+| `errors/index.ts` | Error re-exports — managed automatically |
+
+## Validation & Errors
+
+Value objects use Zod for validation via `conditions.ts`. Each condition is a Zod schema
+that validates construction inputs. Errors are automatically classified by ultra-ddd
+based on the Zod error type.
+
+To add custom domain errors:
+1. Create an error class in `errors/`
+2. Use it in a Zod `.refine()` or `.superRefine()` in `conditions.ts`
+3. Export it from `errors/index.ts`
+
+## Testing
+
+### TDD Cycle
+
+Value objects follow the red-green-refactor TDD loop:
+
+1. **Red**: Write a failing test for an invalid input
+2. **Green**: Add the validation rule to make it pass
+3. **Refactor**: Clean up while keeping tests green
+
+### Example
+
+```ts
+// Test: value must be non-empty
+it('rechazar valor vacío', () => {
+  const payload: Payload = { value: '' };
+  const result = UserEmail.of(payload);
+  expect(result).toBeError();
+});
+```
+
+```ts
+// Implementation in conditions.ts
+export const conditions = z.object({
+  value: z.string().min(1, 'Value must not be empty'),
+});
+```