@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-027-patron-wiring-entry-point.md

@@ -0,0 +1,67 @@
+# A-027: Patrón de wiring entry-point
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: A-001
+
+**Enriquecido desde**: Cortex ADR 004 — Clean Architecture feature structure with ports & drivers
+
+**tags**: arquitectura
+
+## Contexto
+
+Cada app necesita instanciar drivers concretos y arrancar su lógica. Si el wiring de dependencias se mezcla con la lógica de negocio en una única función, esa lógica no puede probarse con drivers en-memoria sin ejecutar la función de wiring, y cambiar un driver obliga a tocar código que también contiene lógica.
+
+## Decisión
+
+Cada app separa el wiring de dependencias de la lógica de negocio usando dos funciones:
+
+- **Función de wiring** (p. ej. `main()`, `bootstrap()`) — la **raíz de composición única** de la app: lee configuración, instancia los drivers concretos de `shared-infra/<tech>/` ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md), [A-026](./A-026-infraestructura-compartida.md)), ensambla los adaptadores y el caso de uso de la feature, y construye el controlador y el presentador. Este es el **único** lugar donde se instancian clases concretas (drivers, adaptadores, caso de uso, controlador y presentador). Llama a la función de lógica pasándole el controlador ya cableado.
+- **Función de lógica** (p. ej. `startServer(deps)`, `run(deps)`) — recibe las dependencias ya construidas y contiene la lógica pura (setup HTTP, poll loop, etc.). Esta función nunca importa drivers concretos.
+
+Este patrón asegura:
+
+- Las funciones de lógica son testeables con drivers en-memoria sin tocar la función de wiring
+- Cambiar un driver solo toca la función de wiring
+- Todas las apps siguen la misma estructura legible
+- El **controlador y el presentador** son la frontera de la app, dos mitades simétricas: el controlador recibe el input desde afuera y lo entrega al caso de uso; el presentador recibe la salida del caso de uso (un `OutputDto` o su stream) y la mapea a la wire — con `representations/<protocol>/` cuando es schema'd, con transformaciones cosméticas propias de la app en caso contrario ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md), [A-026](./A-026-infraestructura-compartida.md)). La feature no nombra ni el transporte, ni el presentador, ni la representación.
+
+**Variante sin contenedor de inyección**: cuando una app compone varios casos de uso a mano (p. ej. un CLI con un registry por feature), el seam de cada caso de uso declara los **puertos** que consume — en lugar del controlador ya cableado — y la función de lógica ensambla caso de uso y controlador a partir de ellos. El objetivo es el mismo (separar wiring de lógica); cambia qué cruza el seam: los puertos, para que el seam documente las dependencias reales del caso de uso.
+
+Ejemplo conceptual (`server.ext`):
+
+```text
+// función de wiring — única raíz de composición; instancia todo lo concreto
+function main() {
+  settings = SettingsSchema.parse(env)
+  pool = new PostgresPool(settings.dbUrl)              // shared-infra/postgres — conexión
+  repository = new RepositoryDriver(pool)              // driver de shared-infra/postgres — implementa el driver port
+  notifier = new NotifierDriver(settings.smtpConfig)   // driver autocontenido de shared-infra/notifier
+  useCase = new UseCase({ repository: new RepositoryAdapter(repository), notifier: new NotifierAdapter(notifier) })
+  controller = new Controller(useCase)                 // valida y traduce el input, invoca el caso de uso
+  presenter = new Presenter()                          // mapea la salida del caso de uso a la wire
+  return startServer({ settings, controller, presenter })
+}
+
+// función de lógica — setup HTTP puro, sin imports de drivers concretos
+function startServer(deps) {
+  server = createServer((req, res) => { /* usa deps.controller y deps.presenter */ })
+  server.listen(deps.settings.port)
+}
+```
+
+El mismo patrón aplica a workers (la función de wiring cablea, la función de lógica es el loop) y a cualquier otro modo de despliegue. La composición de features en la función de wiring es la que describe [A-024](./A-024-features-slices-verticales-portables.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Testabilidad**: la lógica se prueba con drivers en-memoria sin ejecutar la función de wiring.
+- **Cambios acotados**: cambiar un driver solo toca la función de wiring.
+- **Estructura uniforme**: todas las apps comparten la misma separación.
+
+### Negativas
+
+- **Convención obligatoria**: toda app debe respetar las dos funciones; mezclar wiring y lógica reintroduce el acoplamiento.

package/docs/adr/foundational/A-029-verbos-intencion-metodos-lado-negocio.md

@@ -0,0 +1,54 @@
+# A-029: Verbos de intención para métodos del lado del negocio
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: A-010
+
+**Enriquecido desde**: Cortex ADR 037
+
+**tags**: dominio
+
+## Contexto
+
+En el lado del negocio de la Clean Architecture
+([A-001](./A-001-clean-architecture-4-capas.md)), los métodos comunican la acción de negocio que
+ejecutan. Cuando un método usa un verbo de almacenamiento (`guardar_entidad`,
+`persistir_datos`) expresa una operación CRUD, no la intención de negocio: entierra la acción
+bajo el detalle de cómo se persiste. Un método con verbo de intención (`crear_entidad`,
+`registrar_pedido`) comunica qué ocurrió en el negocio.
+
+El vocabulario de esos verbos es el lenguaje ubicuo del sistema
+([A-031](./A-031-ubiquitous-language.md)). La regla alcanza a los métodos del lado del negocio
+— el dominio y los casos de uso, con sus puertos —; el lado tecnológico (driver ports y
+drivers) conserva su vocabulario técnico
+([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)).
+
+## Decisión
+
+Los métodos del lado del negocio se nombran con verbos de intención de dominio, no con
+verbos de almacenamiento. Por ejemplo:
+
+| Verbo de almacenamiento | Verbo de intención |
+|---|---|
+| `guardar_entidad(...)` | `crear_entidad(...)`, `actualizar_entidad(...)` |
+| `guardar_pedido(...)` | `registrar_pedido(...)` |
+| `persistir_documento(...)` | `publicar_documento(...)` |
+
+## Consecuencias
+
+### Positivas
+
+- **Nombres auto-documentados**: el nombre del método comunica la acción de negocio, no cómo se
+  persiste.
+- **Alineación con el lenguaje ubicuo**: los métodos usan el vocabulario del dominio, manteniendo
+  código y modelo alineados.
+- **Frontera agnóstica a la tecnología**: el nombre no menciona persistencia; el driver decide la
+  operación concreta (base de datos, GraphQL, bus de mensajes).
+
+### Negativas
+
+- **Disciplina de nomenclatura**: el equipo debe rechazar verbos de almacenamiento en las revisiones.
+- **Migración**: los métodos existentes con verbos de almacenamiento deben renombrarse, aunque pueden
+  migrarse feature por feature sin dependencias entre ellas.

package/docs/adr/foundational/A-030-global-development-tooling.md

@@ -0,0 +1,52 @@
+# A-030: Herramientas de desarrollo globales
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-14
+
+**originally**: imolko
+
+**tags**: tooling, agentes
+
+## Contexto
+
+Cada repositorio de Imolko depende de un conjunto pequeño de herramientas globales
+que el entorno de desarrollo usa en todas las apps y flujos de trabajo, sin importar
+el dominio ni el lenguaje: **kubectl**, **glab** (el CLI de GitLab) y **pi** (el
+agente de codificación).
+
+Sin una decisión canónica, el toolchain queda implícito: cada desarrollador instala
+las herramientas ad hoc (versiones distintas, o ninguna), el onboarding es manual, y
+los scripts o agentes asumen herramientas que pueden no estar presentes.
+
+## Decisión
+
+El toolchain global es **kubectl, glab y pi**. Cada herramienta tiene un único rol
+definido:
+
+| Tool | Rol |
+|------|-----|
+| kubectl | Interacción directa con los clústeres de Kubernetes: inspección, diagnóstico y operaciones ad hoc (`get`, `describe`, `logs`). |
+| glab | CLI canónico del servidor de GitLab: issues, merge requests, labels, pipelines y releases. Es la interfaz de scripting que usan los skills. |
+| pi | El agente de codificación ([pi.dev](https://pi.dev), paquete `@earendil-works/pi-coding-agent`) para desarrollo asistido y bucles autónomos. |
+
+El despliegue pertenece a Helm ([A-012](./A-012-helm-mecanismo-primario-despliegue.md)).
+
+### Provisioning
+
+Las tres herramientas se instalan en el **DevContainer**
+([A-020](./A-020-entorno-desarrollo-estandarizado-devcontainer.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Toolchain canónico**: las tres herramientas y sus roles quedan en un único
+  documento, en lugar de asumirse por convención no escrita.
+
+### Negativas
+
+- **Un ADR más que mantener**: si el toolchain cambia (se añade o reemplaza una
+  herramienta), este ADR debe actualizarse.
+- **Herramientas que evolucionan aparte**: glab y pi publican a su propio ritmo;
+  este ADR las referencia por rol, no por versión.

package/docs/adr/foundational/A-031-ubiquitous-language.md

@@ -0,0 +1,64 @@
+# A-031: Lenguaje ubicuo
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-14
+
+**originally**: imolko
+
+**tags**: dominio, agentes
+
+## Contexto
+
+Cada repositorio de sistema de Imolko modela su negocio con Domain-Driven Design: la
+capa `domain/` ([A-001](./A-001-clean-architecture-4-capas.md)) aloja el **lenguaje ubicuo** del sistema — el vocabulario
+de negocio compartido por los expertos del dominio, los desarrolladores y el agente de
+codificación.
+
+La obligación de usarlo necesita una decisión canónica que fije en qué superficies
+aplica y quién debe seguirlo.
+
+Mientras esa obligación queda implícita y dispersa, el código, la documentación, los
+tests y los artefactos de agente derivan hacia términos técnicos o inventados que no
+son las palabras del negocio, erosionando el alineamiento entre el modelo y las
+personas que lo usan.
+
+## Decisión
+
+El **lenguaje ubicuo** de un sistema es el vocabulario canónico para nombrar y
+describir los conceptos del dominio. Cada participante — desarrolladores y el agente
+de codificación — lo usa en estas superficies:
+
+1. **Código**: nombres de artefactos de dominio, métodos, puertos y casos de uso que
+   representan conceptos de negocio.
+2. **Documentación**: READMEs, ADRs y documentación generada.
+3. **Tests**: nombres y descripciones de los tests.
+4. **Artefactos de agente**: PRDs, issues, slices, títulos y descripciones.
+
+### Fuente de verdad
+
+El lenguaje ubicuo vive en la **capa de dominio** (`domain/`): cada concepto del
+dominio se documenta en su propio `README.md`, que define su propósito de negocio y
+sus reglas (ver
+[A-032](./A-032-domain-artifact-documentation-format.md)). Cuando hay que elegir o
+comprobar un término, la capa de dominio es la autoridad.
+
+## Consecuencias
+
+### Positivas
+
+- **Una autoridad**: la capa de dominio es el único lugar donde el vocabulario se
+  define y se comprueba.
+- **Nombrado consistente**: código, docs, tests y artefactos de agente hablan el mismo
+  lenguaje de negocio, manteniendo el modelo alineado con los expertos del dominio.
+- **Alineación del agente**: el agente de codificación tiene una regla canónica y
+  citable.
+
+### Negativas
+
+- **No aplicable mecánicamente**: si un nombre es el término de dominio correcto es un
+  juicio semántico; el gate de ADRs no puede validarlo (a diferencia de enlaces o
+  índices).
+- **Requiere conocimiento del dominio**: usar el lenguaje correctamente depende de
+  conocer la capa de dominio; el onboarding debe apuntar a los recién llegados hacia
+  ella.

package/docs/adr/foundational/A-032-domain-artifact-documentation-format.md

@@ -0,0 +1,128 @@
+# A-032: Formato de documentación de artefactos de dominio y features
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-14
+
+**originally**: imolko
+
+**tags**: dominio, tooling
+
+## Contexto
+
+Los artefactos de dominio — value objects, entidades, agregados, eventos de dominio,
+servicios y enums — son el vocabulario del lenguaje ubicuo del sistema (ver
+[A-031](./A-031-ubiquitous-language.md)). Cada artefacto y cada caso de uso (feature) necesitan documentación
+legible por humanos que los expertos del dominio puedan validar y que los
+desarrolladores y agentes puedan descubrir, en todo repositorio de sistema, sin
+importar el lenguaje de implementación.
+
+Sin un formato canónico, cada artefacto se documenta de forma distinta: los nombres
+de sección varían, el idioma se mezcla, y la documentación no puede ensamblarse en un
+todo coherente y navegable.
+
+## Decisión
+
+Cada artefacto de dominio o feature se documenta en su propio `README.md` con una
+estructura canónica, escrito en español (el idioma de los expertos del dominio).
+
+### Estructura
+
+- **El `README.md` empieza directamente con las secciones de contenido**: el nombre,
+  tipo y estado del artefacto los presenta el sistema de documentación.
+- **Secciones obligatorias en español**, por tipo de artefacto:
+
+  | Tipo | Secciones obligatorias |
+  |------|----------------------|
+  | value-object, entity, aggregate | `## Propósito`, `## Reglas`, `## Ejemplos de uso`, `## Relaciones` |
+  | domain-event | `## Propósito`, `## Data del evento (vX.Y.Z)`, `## Ejemplos de uso`, `## Relaciones` |
+  | service | `## Propósito`, `## ServiceInput`, `## ServiceOutput`, `## Reglas`, `## Errores`, `## Ejemplos de uso`, `## Relaciones` |
+  | enum | `## Propósito`, `## Valores`, `## Ejemplos de uso`, `## Relaciones` |
+
+  Los casos de uso (features) siguen su propia estructura según `command` o `query`:
+
+  - command: `## Propósito`, `## Precondiciones`, `## Poscondiciones`, `## Flujo`, `## Errores`, `## Relaciones`
+  - query: `## Propósito`, `## Parámetros`, `## Resultado`, `## Flujo`, `## Errores`, `## Relaciones`
+
+- **Columnas de las secciones tabulares**:
+
+  | Sección | Columnas |
+  |---------|----------|
+  | `## Reglas` | `Regla`, `Descripción` |
+  | `## Errores` | `Error`, `Condición` (features añaden `Recovery`) |
+  | `## ServiceInput`, `## ServiceOutput`, `## Data del evento` | `Campo`, `Tipo`, `Descripción` |
+  | `## Valores` | `Valor`, `Descripción` |
+  | `## Precondiciones` | `Precondición`, `Validación` |
+  | `## Poscondiciones` | `Poscondición`, `Efecto` |
+  | `## Parámetros` | `Parámetro`, `Tipo`, `Requerido`, `Descripción` |
+  | `## Resultado` | `Campo`, `Tipo`, `Descripción` |
+
+- `## Relaciones` incluye siempre un diagrama Mermaid `graph TD` con aristas
+  etiquetadas que explican cada relación (`identidad`, `propiedad`, `contiene`,
+  `selecciona`, `emite`, `consume`, etc.). Los nodos llevan el nombre y el tipo del
+  artefacto: `Nombre["Artefacto<br/>(tipo)"]`.
+
+  ```mermaid
+  graph TD
+      Artifact["Artefacto<br/>(tipo)"]
+      Owner["Owner<br/>(entity)"]
+      Referrer["Referrer<br/>(aggregate)"]
+      Service["Service<br/>(service)"]
+
+      Owner -->|"identidad"| Artifact
+      Referrer -->|"propiedad"| Artifact
+      Service -->|"consume"| Artifact
+  ```
+
+- `## Flujo` (command y query) es un diagrama Mermaid del pipeline del caso de uso.
+- `## Ejemplos de uso` incluye siempre bloques de código.
+
+### Frontmatter
+
+Cada `README.md` empieza con un bloque de frontmatter YAML delimitado por `---`.
+
+**Artefactos de dominio:**
+
+```yaml
+---
+description: |
+  <descripción enriquecida del artefacto>
+domain: <nombre-del-proyecto>
+boundedContext: <nombre-del-bounded-context>
+type: value-object | entity | aggregate | domain-event | service | enum
+tags:
+  - completed
+---
+```
+
+**Features (casos de uso):**
+
+```yaml
+---
+feature: <nombre-de-la-feature-en-kebab-case>
+type: command | query
+title: <título legible>
+description: <descripción corta>
+tags:
+  - completed | pending
+  - scope::*
+---
+```
+
+El `type` del feature (`command` o `query`) lo clasifica [A-002](./A-002-cqrs-semantico.md); el tag `scope::*` lo define [A-009](./A-009-use-case-taxonomy.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Un formato, cualquier lenguaje**: el estándar aplica a cualquier repositorio de
+  sistema, independiente del tooling que ensambla la documentación.
+- **Vocabulario descubrible**: cada `README.md` es el punto de entrada al propósito y
+  las reglas de su artefacto, alimentando el lenguaje ubicuo.
+
+### Negativas
+
+- **No aplicable mecánicamente**: el formato se verifica por revisión o se delega al
+  agente, no por el gate de ADRs.
+- **Diagramas manuales**: el diagrama Mermaid de `Relaciones` debe actualizarse
+  cuando nuevos artefactos se relacionan con el documentado.

package/docs/adr/foundational/A-033-estandar-mensajes-commit.md

@@ -0,0 +1,127 @@
+# A-033: Estándar de mensajes de commit
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-14
+
+**originally**: imolko
+
+**tags**: tooling, agentes
+
+## Contexto
+
+Los mensajes de commit son la materia prima de tres capacidades que el equipo
+quiere fiables: generar changelogs a partir del historial, trazar cada commit a
+su work item y a su merge request, y conservar un repositorio de conocimiento de
+la evolución del proyecto. Sin una convención canónica, los mensajes derivan
+hacia estilos dispares:
+
+- Estilo informal y desigual: `docs(adr):`, `chore(adr):`, `refactor:` y
+  `fix:` conviven con `feat(#670): Crear readme` (número de work item en el
+  alcance) y con descripciones en inglés y español sin criterio.
+- El versionado de las librerías (SemVer) se apoya en keywords ad hoc en el
+  mensaje (`UPGRADE_MAJOR_VERSION`, `UPGRADE_MINOR_VERSION`): una segunda
+  convención de commits implícita, distinta de la anterior y tampoco gobernada.
+
+Mientras no exista una decisión canónica, el changelog no puede derivarse de los
+commits, la trazabilidad depende de la memoria de cada autor y no existe
+validación del formato.
+
+## Decisión
+
+Adoptar **Conventional Commits 1.0.0** como el estándar de mensajes de commit de
+todo repositorio de Imolko, con vocabulario acotado y reglas de gobierno sobre
+las superficies que lo consumen.
+
+### 1. Formato
+
+```text
+<tipo>[alcance][!]: <descripción>
+
+[cuerpo opcional]
+
+[footers]
+```
+
+- El **tipo** responde "qué tipo de cambio es"; el **alcance**, "dónde ocurrió".
+  El cuerpo explica el *porqué* cuando no es obvio desde el título.
+- La descripción va en **español**, en infinitivo, en minúscula tras `:`, sin
+  punto final y de ≤72 caracteres. El tipo, el alcance y las keywords de footer
+  son tokens en **inglés**.
+- Los términos de dominio usan el término canónico de la capa de dominio, tal cual
+  ([A-031](./A-031-ubiquitous-language.md)).
+
+### 2. Vocabulario de tipos
+
+El contrato semántico fija qué tipos describen versión y cuáles no:
+
+- `feat` (funcionalidad nueva) y `fix` (corrección de bug) se usan de forma
+  estricta; son los únicos tipos que mueven versión.
+- Un **breaking change** se marca con `!` tras el tipo/alcance y/o con el footer
+  `BREAKING CHANGE:`.
+- El vocabulario queda cerrado al de Conventional Commits 1.0.0: el resto de
+  tipos del estándar queda disponible.
+
+La validación ejecutable del contrato vive en la configuración del linter de
+cada repositorio; este ADR fija el contrato semántico, no duplica la lista.
+
+### 3. Alcances
+
+El alcance es **opcional**, pero cuando aparece debe ser un **componente
+arquitectónico estable** (bounded context, app desplegable o módulo transversal)
+de la lista canónica del repositorio. La enumeración de cada repositorio
+vive en la configuración de su linter.
+
+### 4. Trazabilidad con work items
+
+Todo commit canónico lleva un **footer obligatorio** que enlaza al work item:
+`Refs: #N` (lo toca) o `Closes: #N` (lo resuelve). El token `#N` es lo que
+GitLab indexa para el enlace commit ↔ work item; `Closes` añade el cierre
+automático al fusionar. El número de work item vive solo en el footer.
+
+### 5. Squash como commit canónico
+
+El **commit canónico** es el **squash commit** del merge request de una feature: el título del
+MR es el subject y la descripción del MR es el cuerpo con los footers. El flujo
+de ramas y sus fusiones se gobierna en [A-041](./A-041-estrategia-de-ramas.md).
+
+Los commits intermedios de desarrollo (`wip`, `fix typo`) no tienen que cumplir
+la convención; solo el commit canónico la cumple.
+
+### 6. Enforcement
+
+El formato se valida con un **linter en CI**: un job linta el título del MR y
+su descripción — el commit canónico —, no cada commit de desarrollo; por eso la
+validación vive en CI y no en push rules.
+
+### 7. Changelog y versionado
+
+El commit convencional es la **única fuente de metadata** de la que se deriva el
+changelog. La derivación de versión depende del tipo de repositorio, según
+[A-017](./A-017-taxonomia-repositorios-librerias-sistemas.md)
+y [A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md):
+
+- **Librerías** (SemVer): `feat`→minor, `fix`→patch, breaking→major.
+- **Sistemas** (CalVer): la versión se deriva de la fecha; los tipos solo
+  agrupan el changelog y el marcador breaking señala una liberación de ruptura.
+- **Configuración**: queda fuera del versionado por tipos; si versiona (p. ej.
+  `version` de un chart), lo gobierna su propio mecanismo.
+
+En las librerías, los tipos **sustituyen** a las keywords ad hoc
+`UPGRADE_MAJOR_VERSION` / `UPGRADE_MINOR_VERSION`.
+
+## Consecuencias
+
+### Positivas
+
+- **Contrato único para autores y agentes**: el estándar gobierna por igual los
+  commits de los autores y los del agente de codificación.
+
+### Negativas
+
+- **Fricción en el MR**: el autor debe redactar título y footers según el
+  estándar.
+- **No mecánicamente perfecto**: el linter valida forma, no semántica (si un
+  cambio es `feat` o `refactor` sigue siendo juicio humano).
+- **Migración pendiente**: sustituir las keywords por tipos exige migrar el flujo
+  de release de las librerías; hasta entonces conviven dos convenciones.

package/docs/adr/foundational/A-034-canonical-skill-set.md

@@ -0,0 +1,64 @@
+# A-034: Conjunto canónico de skills del asistente de codificación
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-14
+
+**originally**: mattpocock-skills
+
+**Enriquecido desde**: mattpocock/skills — taxonomía canónica de skills (engineering + productivity), adaptada al registro ADR de Guarura
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El asistente de codificación (pi) descubre skills mediante el frontmatter de cada `SKILL.md` del paquete `@imolko/ultra-agent` ([A-052](./A-052-distribucion-metodologia-paquete-versionado.md)), que los materializa en la ubicación de descubrimiento de cada harness. El agente es más productivo cuando las convenciones de cada skill se adaptan a las prácticas del repositorio; sin una decisión canónica, cada skill mapearía esas convenciones a su manera, produciendo referencias rotas y convenciones inconsistentes entre skills.
+
+## Decisión
+
+Adoptar un **conjunto canónico de skills** que cubre el ciclo de desarrollo completo y trabaja en tándem con el registro ADR. El conjunto gobierna la metodología de desarrollo; cada repositorio añade skills propios para los problemas particulares de su proyecto, fuera del alcance de este ADR. La lista concreta vive en el paquete `@imolko/ultra-agent` — la fuente canónica, distribuida y versionada según [A-052](./A-052-distribucion-metodologia-paquete-versionado.md) — y no se duplica aquí (regla `hardcoded` de [ADR-0000](../ADR-0000-proceso-y-formato-de-adrs.md)).
+
+### Modelo del ciclo
+
+Los skills se dividen en dos clases según cómo se invocan:
+
+- **Puntos de entrada**: invocados por la persona, sin carga de contexto; inician una unidad de trabajo deliberada.
+- **Disciplinas**: invocados por el modelo, o alcanzados por otro skill a mitad de trabajo; llevan `description` en el prompt del sistema para que el agente las alcance por sí mismo o desde otro skill.
+
+Qué skills pertenecen a cada clase vive en el paquete `@imolko/ultra-agent` (la fuente canónica del conjunto, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)).
+
+### Contrato de adaptación
+
+Cada skill adoptado de una taxonomía externa reemplaza las convenciones ajenas por las del repositorio:
+
+| Convención ajena | Equivalente en el repositorio |
+|---------------------------|------------------------|
+| `CONTEXT.md` (glosario) | `domain/` READMEs ([A-031](./A-031-ubiquitous-language.md), [A-032](./A-032-domain-artifact-documentation-format.md)) |
+| `CODING_STANDARDS.md` | el registro `docs/adr/` |
+| `docs/agents/issue-tracker.md` + `ready-for-agent` | GitLab + la convención skill-first ([A-038](./A-038-issues-referencian-skills-nombre.md)) |
+| `AGENTS.md` / `CLAUDE.md` | no se referencian |
+
+El CLI del tracker se lee de `tracker_cli` en `docs/agents/repo-config.md` ([A-052](./A-052-distribucion-metodologia-paquete-versionado.md)).
+
+### Límite de escritura
+
+El registro global es de solo lectura: `ADR-0000` y los tiers A, T y P no se modifican nunca desde un skill. Lo escribible es el **tier de proyecto** (las decisiones específicas del dominio del proyecto) y los `README.md` de `domain/`. El skill que registra decisiones (modelado de dominio) escribe solo en ese ámbito, siguiendo A-031 y A-032 para el glosario y ADR-0000 para los ADR.
+
+### Documentación del conjunto
+
+- Un **router skill** (`workflow`) nombra los skills canónicos y el orden del ciclo — es el mapa para la persona.
+- Este ADR documenta la metodología — el modelo del ciclo, la división de invocación y el contrato de adaptación.
+
+## Consecuencias
+
+### Positivas
+
+- **Una taxonomía, no una convención por skill**: todos los skills comparten el mismo contrato de adaptación y los mismos límites de escritura.
+- **Descubrimiento determinista**: los puntos de entrada no pagan contexto; las disciplinas se alcanzan por `description`.
+- **Un solo mapa**: el router `workflow` evita que la persona memorice el conjunto de skills.
+
+### Negativas
+
+- **Un conjunto de skills que mantener**: cada skill nuevo o renombrado debe actualizar el router y sus referencias.
+- **Acoplamiento por nombre**: renombrar un skill rompe las referencias `/skill:<name>` en issues y en otros skills.
+- **Carga cognitiva en los puntos de entrada**: los skills de entrada dependen de que la persona los recuerde — mitigada por el router.

package/docs/adr/foundational/A-035-captura-ideas-reanclaje-candies.md

@@ -0,0 +1,51 @@
+# A-035: Captura de ideas y re-anclaje de candies al flujo de agentes
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-17
+
+**originally**: imolko
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El candy es la unidad de complejidad de un issue; las horas sirven para comunicar esa complejidad entre humanos. La escala se mantiene calibrada empíricamente: se registra el tiempo invertido de cada issue y se promedian horas hasta producción por candy.
+
+El ciclo canónico de skills ([A-034](./A-034-canonical-skill-set.md)) necesita una puerta de entrada que convierta una **idea cruda** en un issue aprehensible. Sus etapas — sintetizar el spec, clasificar issues que ya existen, afinar un plan — operan todas después de la idea cruda.
+
+El flujo agéntico desplaza la unidad natural de trabajo a la **sesión de agente**. El candy conserva su significado — complejidad — y re-ancla su unidad a esa sesión.
+
+## Decisión
+
+Re-anclar el candy de horas a **sesiones de agente** y enrutar cada idea por su candy:
+
+1. **El candy**: 1 candy ≈ 1 issue del tamaño de una sesión; `?` significa "no estimable"; 16+ es "demasiado grande → partir". Las labels `candy::N` y `type::idea` las formaliza [A-037](./A-037-formalizacion-taxonomia-labels.md).
+2. **El enrutado**: cada idea lleva la ruta publicada como primera instrucción de `# Skill recomendado` ([A-038](./A-038-issues-referencian-skills-nombre.md)). La **línea de spec** — afinar la idea, sintetizar el spec y las tareas ([A-042](./A-042-formato-documentos-issue-tracker.md)) e implementar ([A-039](./A-039-pipeline-ship-issues-hijos-spec.md)) — es la ruta de las ideas estimables; **wayfinding** ([A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md)) es la ruta de las que necesitan mapa.
+
+| Candy | Ruta |
+|-------|------|
+| 1–4 | la línea de spec |
+| 8 | wayfinding |
+| `?` | wayfinding + `# Pregunta` (la única pregunta cuya respuesta hace estimable la idea); cuando el camino quede claro, la línea de spec |
+| 16+ | no publica issue; remite directamente a wayfinding |
+
+Para aplicar este enrutado, el ciclo gana una **puerta de entrada de captura de ideas** (invocada por la persona, sin carga de contexto): entrevista, mapea al vocabulario del dominio ([A-031](./A-031-ubiquitous-language.md)) y busca issues similares, y publica el issue con su candy y su ruta; la persona decide la estimación y si es duplicado. El skill que la implementa vive en el paquete `@imolko/ultra-agent` ([A-034](./A-034-canonical-skill-set.md)); la estructura del issue sigue la Idea de [A-042](./A-042-formato-documentos-issue-tracker.md).
+
+La **reunión semanal** sobrevive, más ligera: deja de estimar (lo hace la puerta de entrada) y conserva sus dos trabajos genuinamente colectivos — priorizar (`priority::hot`/`warm`, [A-037](./A-037-formalizacion-taxonomia-labels.md)) y **re-estimar** candies cuando el contexto nuevo lo justifica. La re-estimación cambia la label `candy::N` (el tracker lo registra como evento del issue) y añade un comentario con el nuevo enrutado (referenciando el skill por nombre, [A-038](./A-038-issues-referencian-skills-nombre.md)), conservando la redacción original del proponente.
+
+## Consecuencias
+
+### Positivas
+
+- **Las ideas crudas ya no viven solo en cabezas o chats**: se convierten en issues aprehensibles con un enrutado que apunta al afilador correcto.
+- **El candy sobrevive como vocabulario de estimación** del equipo, re-anclado a la unidad agéntica (sesiones), y el bucle de calibración empírico (registrar → promediar → recalibrar) se conserva tal cual, cambiando solo la unidad registrada.
+- **La reunión conserva lo colectivo** (priorizar y re-estimar) y suelta la estimación mecánica.
+
+### Negativas
+
+- **Dos artefactos nuevos que mantener**: el skill y las labels, además de actualizar el router del ciclo.
+- **La unidad "sesión" no es intuitiva** hasta que el bucle de calibración produzca datos; las primeras estimaciones tenderán a `?`.
+- **La re-estimación que cruza la frontera 4/8 exige disciplina** (label + comentario juntos); si se cambia solo la label, el enrutado del issue miente.
+- **La pasada de mapeo añade un paso a la entrevista ligera**: se mitiga proponiendo solo cuando existe un término canónico en los READMEs de `domain/`.
+- **Las ideas `?` pagan la maquinaria de wayfinding** incluso cuando la niebla era una sola pregunta; la escotilla de "sin niebla" de [A-036](./A-036-adopcion-wayfinder-ortogonalidad-labels.md) lo mitiga.

package/docs/adr/foundational/A-036-adopcion-wayfinder-ortogonalidad-labels.md

@@ -0,0 +1,37 @@
+# A-036: Wayfinding y ortogonalidad de labels del issue tracker
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-17
+
+**originally**: mattpocock-skills
+
+**tags**: agentes, tooling
+
+## Contexto
+
+El enrutado de ideas 8+ y de ideas `?` ([A-035](./A-035-captura-ideas-reanclaje-candies.md)) remite a un camino para esfuerzos grandes, multi-sesión o con la ruta poco clara (la niebla). **Ese camino es wayfinding**: planificar un trabajo que no cabe en una sesión de agente como un **mapa** compartido y una serie de **tickets de decisión** hijos, resueltos de a uno por sesión hasta que el camino queda claro.
+
+El tracker ya tiene varias dimensiones de labels; las labels de wayfinding entran en él y necesitan un criterio propio para convivir con las existentes. La formalización completa de la taxonomía la gobierna [A-037](./A-037-formalizacion-taxonomia-labels.md); este ADR fija el criterio con el que entran.
+
+## Decisión
+
+Los artefactos de wayfinding — el mapa y los tickets de decisión — entran en el tracker con una dimensión propia, **`wayfinder::*`**, que responde exactamente "¿qué artefacto de planificación?". Un artefacto de wayfinding no es un work item — nunca lleva `type::` ni `candy::`, y su modo de ejecución reutiliza la dimensión `exec::` ([A-037](./A-037-formalizacion-taxonomia-labels.md)).
+
+Las labels de la dimensión son `wayfinder::map` (el mapa) y `wayfinder::research`/`spike`/`grilling`/`task` (los tickets de decisión), con doble dos-puntos (`::`), la convención del repositorio.
+
+La maquinaria de wayfinding vive en el paquete `@imolko/ultra-agent` ([A-034](./A-034-canonical-skill-set.md)).
+
+La taxonomía completa — las seis dimensiones — la gobierna [A-037](./A-037-formalizacion-taxonomia-labels.md); este ADR fija solo el principio de entrada de wayfinding.
+
+## Consecuencias
+
+### Positivas
+
+- **Una ruta canónica** para esfuerzos grandes, multi-sesión o de ruta poco clara, alcanzada por el enrutado de ideas 8+ y `?` ([A-035](./A-035-captura-ideas-reanclaje-candies.md)).
+- **Labels nuevas ortogonales**: siguen la convención `::` del repositorio y una regla explícita, ortogonales a `type::`, `candy::` y `exec::`.
+
+### Negativas
+
+- **Maquinaria pesada**: las ideas 8+ pagan la maquinaria de wayfinding incluso cuando la ruta resulta clara; la escotilla de "sin niebla" lo mitiga.
+- **Más labels que crear y mantener**.