@imolko/ultra-agent 0.1.0-beta

package/skills/tdd/references/deep-modules.md

@@ -0,0 +1,53 @@
+# Deep Modules
+
+Value-objects and aggregates are naturally **deep modules**: small public API, rich encapsulated behavior. The same lens applies to every code shape.
+
+## Deep = Value Object
+
+```
+┌───────────────────────┐
+│  ProductName          │
+│  .of(payload)         │  ← Small interface (1 factory + getters)
+│  .getPrimitive()      │
+│  .getPayload()        │
+├───────────────────────┤
+│  Validation rules     │
+│  Length constraints   │  ← Deep implementation (conditions, errors)
+│  Type checking        │
+│  Error aggregation    │
+│  Zod transformations  │
+└───────────────────────┘
+```
+
+## Shallow = Primitive Obsession
+
+```
+┌─────────────────────────────────┐
+│  createOrder(name,              │
+│    type, warehouse, productId,  │
+│    quantity, batch, state, ...) │  ← Large interface (many primitives)
+├─────────────────────────────────┤
+│  if (name.length === 0) throw   │  ← Thin implementation (inlined validation)
+│  if (quantity <= 0) throw       │
+│  // ...                         │
+└─────────────────────────────────┘
+```
+
+## When Designing Artifacts
+
+Ask:
+- Can I wrap this string/number in a value-object to encapsulate its rules?
+- Can I reduce the number of conditions by composing value-objects?
+- Can I hide the transformation logic inside the `Definition` class?
+- Can the `.getPrimitive()` and `.getPayload()` methods provide clear, minimal interfaces?
+
+## Example: Deepen a Shallow Module
+
+**Before (shallow)**: Order has `name: string`, `type: string`, `productId: string` — all inlined validation.
+
+**After (deep)**: Order composes `OrderName`, `OrderType`, `ProductId` — each with its own encapsulated rules. The aggregate's interface shrinks but behavior becomes richer.
+
+## The Same Lens Across the Codebase
+
+- **Use-cases are deep**: a small interface (input DTO → output DTO through the presenter) hiding rich orchestration. Keep the pipe steps internal; expose only `execute`.
+- **Representations and adapters are shallow by nature**: read models are data + projection; adapters are translation. Depth is earned where behavior lives, not forced onto every module.

package/skills/tdd/references/interface-design.md

@@ -0,0 +1,74 @@
+# Interface Design for Testability
+
+These interface patterns make testing natural; they apply to every code shape:
+
+## 1. Factory Method Pattern (`of()`)
+
+```typescript
+// The artifact's public API — already testable
+const result = ProductName.of(payload);
+if (result.isValid()) {
+  const name = result.getValue();
+  // use name
+}
+```
+
+The `Execution` monad (`of()` returns `Execution<Error, T>`) makes both success and failure paths testable without mocks.
+
+## 2. Return Results, Don't Produce Side Effects
+
+```typescript
+// GOOD: Returns a new Execution — testable
+ProductName.of('test') → Execution<ProductName>
+
+// GOOD: getPrimitive returns a plain value — testable
+productName.getPrimitive() → string
+```
+
+## 3. Values as Input, Values as Output
+
+Domain artifacts are purely functional at the public API level:
+
+- `of(payload)` — value in, Execution out
+- `getPrimitive()` — value out
+- `getPayload()` — value out
+- `toJSON()` — value out
+
+No internal state mutation exposed. This makes every test deterministic.
+
+## 4. Use-Case Interface (Ports as Seams)
+
+A feature exposes a small, value-in/value-out interface too: `execute(input)` pushes an `InputDto` through the pipe and hands the result to a `PresenterPort`. The `QueryPort` (and any other port) is the seam where a test double plugs in:
+
+```typescript
+// Input → execute → presenter result; query port is the seam
+const useCase = new UseCase(presenter, new InMemoryQueryDriver());
+const task = useCase.execute(input);
+await task();
+```
+
+The same rules as the factory: small surface, values in, values out, no hidden state.
+
+## 5. Dependency Injection for Services and Adapters
+
+When a service or adapter needs external dependencies, use constructor injection:
+
+```typescript
+class OrderService {
+  constructor(
+    private readonly policy: PricingPolicy,
+    private readonly orderRepo: OrderRepository,
+  ) {}
+}
+```
+
+This allows replacing `PricingPolicy` and `OrderRepository` with test doubles in tests.
+
+## 6. Small Surface Area per Artifact
+
+Each artifact keeps a minimal public API — value-objects and aggregates with a factory + getters, use-cases with `execute` + DTOs:
+- 1 factory (`of()`)
+- 2-3 getters (`getPrimitive()`, `getPayload()`)
+- Type exports (`Payload`, `Primitive`, `Errors`)
+
+Fewer methods = fewer tests needed = simpler test setup.

package/skills/tdd/references/mocking.md

@@ -0,0 +1,80 @@
+# When to Mock
+
+Mocks belong at system boundaries, never in domain or use-case logic. The same line applies to every code shape — domain artifacts, features, shared-infra, adapters.
+
+## Mock at System Boundaries Only
+
+- External services (payment gateways, email, SMS)
+- External context adapters (other bounded contexts)
+- Database / EventStore (prefer in-memory or test instances)
+- Time / randomness (`Date.now()`, `Math.random()`)
+- File system
+
+## Don't Mock
+
+- Value objects, entities, aggregates — use real instances
+- `Definition` classes — test through the public artifact
+- `conditions` — test through the value-object/aggregate's `of()`
+- `Props`, `Payload`, `Primitive` types — just use the types
+- Use-case orchestration / pipe steps — test through `execute(input)`
+- Read-model mapping logic — test through the public query
+- Internal collaborators within the domain
+
+## Domain Artifacts Are Naturally Testable
+
+DDD value-objects and aggregates already follow good testing patterns:
+
+```typescript
+// No mock needed — create real instances
+const productName = ProductName.of('Valid Name').getValue();
+const product = Product.of({ id: Uuid.generate(), version: 1 }).getValue();
+```
+
+Because domain objects use the `Execution` pattern (`of()` returns `Execution<Error, Value>`), error cases are testable without mocking:
+
+```typescript
+// Error path is testable without mocking
+const result = ProductName.of('');
+expect(result).toBeInvalid();
+```
+
+## Features / Use Cases
+
+Mock the port behind the use-case, never the use-case itself. Drive it with an in-memory query/adapter and capture the presenter's result:
+
+```typescript
+// In-memory driver implements QueryPort — no mock framework needed
+const queryDriver = new InMemoryQueryDriver();
+let captured: Execution<Errors, OutputDto[]> | null = null;
+const presenter: PresenterPort = { setResult: (r) => { captured = r; } };
+
+const useCase = new UseCase(presenter, queryDriver);
+const task = useCase.execute({});
+await task();
+```
+
+## Services / Adapters
+
+For a service or adapter that calls an external dependency, use constructor injection and replace the dependency with a test double:
+
+```typescript
+// Service accepts adapter as parameter (testable)
+class OrderService {
+  constructor(private readonly orderRepo: OrderRepository) {}
+  
+  async getTotal(orderId: OrderId): Promise<Quantity> {
+    const order = await this.orderRepo.getById(orderId);
+    return order.total;
+  }
+}
+
+// Test with test double
+it('calculates the order total', async () => {
+  const mockRepo = {
+    getById: async () => ({ total: Quantity.of(10).getValue() }),
+  };
+  const service = new OrderService(mockRepo);
+  const result = await service.getTotal(orderId);
+  expect(result.getValue()).toBe(10);
+});
+```

package/skills/tdd/references/refactoring.md

@@ -0,0 +1,49 @@
+# Refactor Candidates
+
+After a TDD cycle, look for these, by code shape:
+
+## Domain Artifacts
+
+- **Duplicate conditions** → Extract into shared Zod schemas or value-objects
+- **Long conditions** → Break complex `.refine()`, `.superRefine()` into named helpers
+- **Primitive obsession** → If `string` appears with multiple distinct rules, introduce a value-object
+- **Leaky errors** → Error messages should reference the domain field, not internal names
+- **Feature envy in aggregates** → If an aggregate has many methods operating on a specific value-object's data, move the logic to the value-object
+- **Unused error types** → Remove error classes that no conditions produce
+- **Props duplication** → If multiple artifacts share the same computed property, extract to a shared module
+- **Magic numbers** → Extract `MIN_LENGTH`, `MAX_LENGTH` constants
+- **Repeated Zod chains** → Consider composing from smaller validators
+- **Inline object shapes** → If multiple conditions share the same nested structure, create a named schema
+
+## Features / Use Cases
+
+- **Long pipe** → Extract steps into named functions (T-008)
+- **Fat use-case** → Move domain logic down to value-objects/aggregates; keep the use-case as orchestration (A-025)
+- **Duplicated DTO mapping** → Extract a shared mapper instead of repeating input-DTO → domain translations in every use-case
+- **Unused ports** → Remove ports no driver or adapter implements
+- **Methods without intention verbs** → Rename per A-029
+
+## Representations
+
+- **Duplicated projection logic** → Extract a shared projector instead of repeating the same shape across read models (A-002)
+- **Fat read model** → Decompose a projection that mixes several queries into focused read models
+
+## Adapters / Drivers
+
+- **Duplicated adapter logic** → If several features repeat the same external-call shape, extract a shared adapter
+- **Wiring duplication** → Move repeated construction into the app factories instead of inlining it in drivers
+
+## Test Files
+
+- **Duplicate test setup** → Extract payloads into `beforeEach` or helper functions
+- **Overly specific error assertions** → Use `toHaveErrorLike()` with partial matching instead of full object comparison
+- **Missing JSDoc** → Add `@name` and `@scenario` for test discoverability
+- **Pending tests** → Use `todo()` and `it.todo()` for known gaps
+
+## Safety Rules
+
+- [ ] Refactor only after GREEN (all tests passing)
+- [ ] Run tests after each refactor step
+- [ ] Don't change public API behavior during refactor
+- [ ] If a refactor breaks tests, revert and try a smaller step
+- [ ] New artifacts extracted during refactor get their own spec file

package/skills/tdd/references/tests.md

@@ -0,0 +1,184 @@
+# Good and Bad Tests
+
+The public-API-vs-internals line applies to every code shape — domain artifacts, features, shared-infra, adapters. Test the observable behavior through the public entry point, never the internals. The domain case is canonical; the same rule holds for the rest.
+
+## Domain Artifacts
+
+### Good Tests
+
+**Test through the artifact's public API.**
+
+```typescript
+// GOOD: Tests observable domain behavior
+import { ProductName } from './value-object';
+import { Payload } from './payload';
+
+it('crear ProductName válido', () => {
+  const payload: Payload = 'Nombre de Empresa Valida';
+  const result = ProductName.of(payload);
+  expect(result).toBeValid();
+  expect(result.getValue()).toBeInstanceOf(ProductName);
+});
+```
+
+```typescript
+// GOOD: Tests domain rule violation
+it('crear ProductName vacío', () => {
+  const payload: Payload = '';
+  const result = ProductName.of(payload);
+  expect(result).toBeInvalid();
+  expect(result).toBeInvalidWithError(TooSmallError);
+});
+```
+
+Characteristics:
+
+- Tests domain rules users care about
+- Uses the artifact's `of()` factory, `getValue()`, `getPrimitive()`
+- Survives conditions refactors
+- Verifies through the artifact's public API, not by importing conditions directly
+- Uses the semantic matchers (A-003)
+
+### Bad Tests
+
+**Implementation-detail tests**: Coupled to the `conditions` or `Definition` internals.
+
+```typescript
+// BAD: Tests conditions directly instead of through the value-object
+import { conditions } from './conditions';
+
+it('validates string type', () => {
+  const result = conditions.safeParse('hello');
+  expect(result.success).toBe(true);
+});
+```
+
+```typescript
+// BAD: Tests the Definition class directly
+import { Definition } from './definition';
+
+it('definition getPrimitive works', () => {
+  const def = new Definition({ name: 'test' });
+  expect(def.getPrimitive()).toBe('test');
+});
+```
+
+```typescript
+// BAD: Bypasses the of() factory
+it('creates with valid props', () => {
+  const vo = new ProductName({ name: 'Test' });
+  expect(vo.props.name).toBe('Test');
+});
+```
+
+Red flags:
+
+- Importing `conditions.ts` directly in tests
+- Testing `Definition` class directly
+- Using `new ClassName()` instead of `ClassName.of()`
+- Asserting on `props` internals
+- Test breaks when you refactor conditions but behavior doesn't change
+- Mocking `Definition` or `ValueObjectBase`
+
+### Correct Pattern: Test Through Public API
+
+```typescript
+// GOOD: Full test of a value-object's domain rules
+import '@imolko/ultra-result/test';
+import { InvalidTypeError, TooBigError, TooSmallError } from '@imolko/ultra-v8n';
+import { MAX_LENGTH } from './conditions';
+import { ProductName } from './value-object';
+import { Payload } from './payload';
+
+describe('product-name', () => {
+  it('crear ProductName válido', () => {
+    const payload: Payload = 'Nombre de Empresa Valida';
+    const result = ProductName.of(payload);
+    expect(result).toBeValid();
+  });
+
+  it('Instancia de ProductName', () => {
+    const payload: Payload = 'Nombre de Empresa Valida';
+    const result = ProductName.of(payload);
+    expect(result.getValue()).toBeInstanceOf(ProductName);
+  });
+
+  it('crear ProductName con la cantidad maxima de caracteres', () => {
+    const payload: Payload = 'Nombre de Empresa larga exacta'.padEnd(MAX_LENGTH, 'o');
+    const result = ProductName.of(payload);
+    expect(result).toBeValid();
+  });
+
+  it('crear ProductName numérico', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const payload: Payload = 3 as any;
+    const result = ProductName.of(payload);
+    expect(result).toBeInvalid();
+    expect(result).toBeInvalidWithError(InvalidTypeError);
+    expect(result.getErrors().length).toBe(1);
+    expect(result).toHaveErrorLike({
+      type: "http://journal/v8n/invalid_type",
+      title: "Invalid Type",
+    });
+  });
+
+  it('crear ProductName vacío', () => {
+    const payload: Payload = '';
+    const result = ProductName.of(payload);
+    expect(result).toBeInvalid();
+    expect(result).toBeInvalidWithError(TooSmallError);
+  });
+
+  it('Crear ProductName con mayor extensión de lo permitido', () => {
+    const payload: Payload = 'Nombre de Empresa muy larga'.padEnd(MAX_LENGTH + 1, 'o');
+    const result = ProductName.of(payload);
+    expect(result).toBeInvalid();
+    expect(result).toBeInvalidWithError(TooBigError);
+  });
+});
+```
+
+Note: `MAX_LENGTH` is imported from `conditions.ts` — this is acceptable because it's a constant used as test input, not testing conditions behavior. If the constant value changes, tests should adapt.
+
+## Features / Use Cases
+
+The public entry point is `useCase.execute(input)`; the seams are the ports. Test through the entry point with in-memory ports and assert on the presenter's result.
+
+### Good
+
+```typescript
+// GOOD: Tests the use-case through its public entry point
+it('ejecuta el caso de uso y entrega el resultado al presentador', async () => {
+  const queryDriver = new InMemoryQueryDriver(); // implements QueryPort
+  let captured: Execution<Errors, OutputDto[]> | null = null;
+  const presenter: PresenterPort = { setResult: (r) => { captured = r; } };
+
+  const useCase = new UseCase(presenter, queryDriver);
+  const task = useCase.execute({});
+  await task();
+
+  expect(captured).toBeValid();
+});
+```
+
+### Bad
+
+```typescript
+// BAD: Tests a pipe step directly instead of through execute()
+import { computeCutoffDate } from './use-case'; // internal helper
+
+it('calcula la fecha de corte', () => {
+  expect(computeCutoffDate(10)).toBe(...);
+});
+```
+
+Red flags (features):
+
+- Importing a pipe step or internal helper directly
+- Calling a private method instead of `execute(input)`
+- Asserting on the driver's internal state instead of the presenter's result
+- Test breaks when you refactor the pipe but behavior doesn't change
+
+## Representations / Adapters
+
+Same line: test the public query or port, not the internal mapping. A read model is tested through its public query and asserted on the returned shape; an adapter is tested through the port it implements, with the external side mocked.

package/skills/to-specs/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: to-specs
+description: Turn the current conversation into a spec and publish it as an issue — no interview, just synthesis.
+disable-model-invocation: true
+---
+
+# To-Specs
+
+This skill takes the current conversation context and codebase understanding, produces a spec in the repo's issue language (`issue_language`) using the project's issue template, and publishes it 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-034 (its place in the canonical set), A-042 (spec structure), A-038 (spec `Skill recomendado` references skills by name), A-037 (labels), A-039 (spec → child issues).
+
+Do NOT interview the user unnecessarily — synthesize what you already know from the conversation. Ask only when critical information is missing.
+
+## Process
+
+### 1. Explore the Codebase
+
+Understand the current state of the repo. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area the issue touches.
+
+Look at:
+- Existing artifacts in the relevant bounded context
+- ADRs that may constrain the implementation
+- Domain glossary terms that apply
+
+### 2. Sketch the seams
+
+Identify the major modules that need to be built or modified, and the seams at which they'll be tested. Propose deep modules that can be tested in isolation — the `seam` / `deep` / `shallow` vocabulary is owned by `/skill:codebase-design`.
+
+**Check with the user** that these seams match their expectations. Tests at those seams follow A-003 — every module gets tested, so there's nothing to select.
+
+### 3. Write the spec
+
+Use the template below — the canonical spec structure is owned by A-042; this is its operational copy. Write in `issue_language` (default Spanish).
+
+<spec-template>
+
+# 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 issue. This is important to give the person that will work on the issue a general context and information to be productive really quickly.
+
+# Alcance
+
+Define the precise scope — short paragraphs on what is needed to close the issue.
+
+# Criterio de cierre
+
+Indicate in tasks what is the criteria for finishing this issue. 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 issue (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 issue 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.
+
+# Decisiones de implementación
+
+A list of implementation decisions made. Include:
+
+- The modules that will be built or modified
+- The interfaces of those modules
+- Technical clarifications
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Record decisions in prose — it stays accurate longer than file paths or code snippets. A spike snippet that encodes a decision more precisely than prose (state machine, reducer, schema, type shape) may be inlined, noted as from a spike.
+
+# Decisiones de testing
+
+A description of the testing approach:
+
+- Which seams will be tested and why
+- What makes a good test for this issue — public API over internals (A-003)
+- Prior art for the tests (similar types of tests in the codebase)
+
+# Fuera de alcance
+
+A description of things that are explicitly out of scope for this spec.
+
+# Notas adicionales
+
+Any further notes about the issue.
+
+</spec-template>
+
+### 4. Publish to the issue tracker
+
+Publish the spec as an issue using `tracker_cli` (default `glab`). Before publishing:
+
+1. Show a preview of the issue to the user
+2. Ask for confirmation
+3. On confirmation, create the issue:
+
+```bash
+<tracker_cli> issue create \
+  --title "<TITULO_DEL_ISSUE>" \
+  --description "<CUERPO_DEL_ISSUE>" \
+  --label "state::ready"
+```
+
+**Important:** The description body must be properly escaped for the shell. Use a temporary file approach for long descriptions:
+
+```bash
+# Write the body to a temp file
+cat > /tmp/issue-body.md << 'ISSUE_EOF'
+<CUERPO_DEL_ISSUE>
+ISSUE_EOF
+
+# Create the issue from the file
+<tracker_cli> issue create \
+  --title "<TITULO_DEL_ISSUE>" \
+  --description "$(cat /tmp/issue-body.md)" \
+  --label "state::ready"
+```
+
+The issue title should be concise and descriptive in `issue_language`. Apply the `state::ready` label automatically (label taxonomy: A-037).
+
+### 5. Confirm
+
+After creating the issue, show the user:
+- The issue URL
+- The issue number
+- A summary of what was created
+
+## Rules
+
+The spec's formatting rules are owned by A-042 — read and apply them from there, not restated here.