@christianmaf80/agentic-workflow 1.14.0-beta.1 → 1.14.0-beta.3

package/dist/artifacts/4-adr-workflows-modulos/researcher/research.md

@@ -1,253 +0,0 @@
----
-artifact: research
-phase: phase-1-research
-owner: researcher-agent
-status: draft
-related_task: 4-adr-workflows-modulos
----
-
-# Research Report — 4-adr-workflows-modulos
-
-## 1. Resumen ejecutivo
-
-### Problema investigado
-Diseñar el sistema de workflows para gestionar el ciclo de vida de módulos en Extensio, siguiendo el modelo establecido para drivers.
-
-### Objetivo de la investigación
-Identificar los componentes necesarios (agentes, workflows, templates, reglas, MCP) y las diferencias arquitectónicas clave entre drivers y módulos para producir un ADR completo.
-
-### Principales hallazgos
-
-1. **El CLI ya soporta módulos**: `extensio-cli` tiene generadores para `module`, `driver` y `project`. Los comandos `create`, `build`, `test` y `demo` funcionan para módulos.
-
-2. **Estructura de drivers como modelo**: El sistema de drivers es maduro y comprende:
-   - 3 workflows: `create`, `refactor`, `delete`
-   - 3 templates: `driver-create.md`, `driver-refactor.md`, `driver-delete.md`
-   - 1 constitution: `drivers.md` (295 líneas)
-   - 1 rol: `driver-agent`
-
-3. **Diferencias arquitectónicas críticas**: Los módulos tienen mayor complejidad que los drivers:
-   - Módulos pueden tener **Engine**, **Context** y **Surfaces** (Shards/Pages)
-   - Módulos usan **@property** y **@onChanged** para reactividad
-   - Módulos tienen ciclo de vida complejo: `run() → _setup() → _listen() → setup() → listen() → loadProps() → start()`
-   - Los drivers son fachadas simples sin estado de negocio
-
-4. **No existe directorio `packages/modules`**: Los módulos del proyecto actual parecen estar integrados en aplicaciones (`apps/`) o en `core`.
-
----
-
-## 2. Necesidades detectadas
-
-### Requisitos técnicos identificados
-
-| Componente | Driver (existente) | Módulo (necesario) |
-|------------|--------------------|--------------------|
-| Agente especializado | `driver-agent` | `module-agent` |
-| Workflows | create, refactor, delete | create, refactor, delete |
-| Constitution | `drivers.md` | `modules.md` (nueva) |
-| Templates | 3 (create/refactor/delete) | 3 (create/refactor/delete) |
-| MCP tools | Ya soportados | Ya soportados |
-
-### Suposiciones
-- Los módulos se crearán en `packages/modules/` (directorio a crear).
-- El ciclo de vida de módulos es más complejo pero sigue el mismo patrón de workflows.
-- La validación de módulos requiere verificar: scopes, decoradores, integración con Core.
-
-### Límites
-- El ADR no implementa código, solo especifica la arquitectura.
-- La constitución de módulos debe complementar `extensio-architecture.md`, no duplicarla.
-
----
-
-## 3. Alternativas técnicas
-
-### 3.1 Estructura de workflows
-
-**Opción A: Paralelismo con drivers (RECOMENDADA)**
-- Crear `.agent/workflows/modules/` con `index.md`, `create.md`, `refactor.md`, `delete.md`
-- Idéntica estructura a drivers, adaptada para módulos
-
-Pros:
-- Consistencia con el modelo existente
-- Curva de aprendizaje baja
-- Reutilización de patrones probados
-
-Contras:
-- Ninguno significativo
-
-**Opción B: Workflows unificados**
-- Un único dominio `entities/` para drivers y módulos
-
-Pros:
-- Menos duplicación
-
-Contras:
-- Pierde especificidad
-- Mezcla responsabilidades
-- Dificulta evolución independiente
-
-### 3.2 Constitution de módulos
-
-**Opción A: Constitution dedicada (RECOMENDADA)**
-- Crear `constitution.modules` en `.agent/rules/constitution/modules.md`
-- Reglas específicas para scopes, decoradores, ciclo de vida
-
-Pros:
-- Claridad contractual
-- Auditoría específica
-- Consistencia con drivers
-
-**Opción B: Extender extensio-architecture.md**
-- Añadir secciones de módulos al documento existente
-
-Contras:
-- Documento demasiado largo
-- Mezcla niveles de abstracción
-
-### 3.3 Rol module-agent
-
-**Opción A: Rol dedicado (RECOMENDADA)**
-- Crear `role.module-agent` en `.agent/rules/roles/module.md`
-- Owner del ciclo de vida de módulos
-- Delegación desde architect-agent
-
-Pros:
-- Separación de responsabilidades
-- Paralelismo con driver-agent
-- Escalabilidad
-
----
-
-## 4. APIs Web / WebExtensions relevantes
-
-Los módulos en Extensio no interactúan directamente con APIs del navegador (eso es responsabilidad de los drivers). Sin embargo, los módulos dependen de:
-
-| API/Componente | Estado de soporte | Uso en módulos |
-|----------------|-------------------|----------------|
-| Storage API | Chrome/Firefox/Safari ✓ | Persistencia de @property |
-| Service Worker | Chrome/Firefox ✓ Safari parcial | Engine scope |
-| Content Scripts | Todos ✓ | Context scope |
-| Messaging | Todos ✓ | Comunicación Engine↔Context |
-
-### Restricciones conocidas
-- Safari: limitaciones en Service Worker lifecycle
-- Firefox: diferencias en storage events
-
----
-
-## 5. Compatibilidad multi-browser
-
-| Aspecto | Chrome | Firefox | Safari | Edge |
-|---------|--------|---------|--------|------|
-| Engine (SW) | ✓ | ✓ | Parcial | ✓ |
-| Context | ✓ | ✓ | ✓ | ✓ |
-| @property persistence | ✓ | ✓ | ✓ | ✓ |
-| Surfaces/Shards | ✓ | ✓ | ✓ | ✓ |
-
-### Estrategias de mitigación
-- Safari SW: documentar limitaciones y fallbacks
-- Usar drivers como capa de abstracción
-
----
-
-## 6. Recomendaciones AI-first
-
-### 6.1 Herramientas MCP
-El CLI `extensio-cli` ya expone herramientas útiles para agentes:
-- `extensio_create`: soporta `type: module`
-- `extensio_build`: compila módulos
-- `extensio_test`: ejecuta tests
-- `extensio_demo`: genera demos
-
-**Recomendación**: No se requieren nuevas herramientas MCP. Los comandos existentes cubren el ciclo de vida.
-
-### 6.2 Recursos MCP
-El recurso `extensio://modules` ya existe pero retorna array vacío (no hay módulos aún).
-
-**Recomendación**: Cuando existan módulos, el recurso los listará automáticamente.
-
-### 6.3 Automatización del module-agent
-El `module-agent` debería:
-- Validar automáticamente la estructura de módulos
-- Verificar uso correcto de decoradores (@property, @onChanged)
-- Auditar ciclo de vida (métodos obligatorios)
-- Detectar dependencias cruzadas prohibidas
-
----
-
-## 7. Riesgos y trade-offs
-
-| Riesgo | Severidad | Probabilidad | Mitigación |
-|--------|-----------|--------------|------------|
-| Duplicación de documentación entre constitution de módulos y extensio-architecture | Media | Alta | La constitution de módulos DEBE referenciar extensio-architecture como source of truth, solo añadir reglas operativas |
-| Confusión entre Engine/Context/Surface | Media | Media | Templates con ejemplos claros |
-| Módulos con dependencias cruzadas | Alta | Media | Auditoría obligatoria del module-agent |
-| Ciclo de vida incompleto | Alta | Baja | Checklist en template de creación |
-
----
-
-## 8. Fuentes
-
-### Documentación interna (Source of Truth)
-- [extensio-architecture.md](file:///Users/milos/Documents/workspace/extensio/.agent/rules/constitution/extensio-architecture.md) — Arquitectura base del framework
-- [drivers.md](file:///Users/milos/Documents/workspace/extensio/.agent/rules/constitution/drivers.md) — Constitution de drivers (modelo)
-- [driver-agent](file:///Users/milos/Documents/workspace/extensio/.agent/rules/roles/driver.md) — Rol de agente (modelo)
-- [drivers/create.md](file:///Users/milos/Documents/workspace/extensio/.agent/workflows/drivers/create.md) — Workflow de creación (modelo)
-
-### Código del proyecto
-- [CLI index.mts](file:///Users/milos/Documents/workspace/extensio/packages/cli/src/index.mts) — Comandos disponibles
-- [Core types](file:///Users/milos/Documents/workspace/extensio/packages/core/src/types.d.mts) — Tipos del framework
-
-### Documentación externa
-- [Chrome Extensions API](https://developer.chrome.com/docs/extensions/)
-- [MDN WebExtensions](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions)
-
----
-
-## 9. Inventario de componentes propuestos
-
-### Workflows (`.agent/workflows/modules/`)
-| Archivo | Descripción |
-|---------|-------------|
-| `index.md` | Índice del dominio modules |
-| `create.md` | Workflow de creación de módulos |
-| `refactor.md` | Workflow de refactorización |
-| `delete.md` | Workflow de eliminación |
-
-### Templates (`.agent/templates/`)
-| Archivo | Descripción |
-|---------|-------------|
-| `module-create.md` | Informe de creación de módulo |
-| `module-refactor.md` | Informe de refactorización |
-| `module-delete.md` | Informe de eliminación |
-
-### Constitution (`.agent/rules/constitution/`)
-| Archivo | Descripción |
-|---------|-------------|
-| `modules.md` | Reglas contractuales para módulos |
-
-### Roles (`.agent/rules/roles/`)
-| Archivo | Descripción |
-|---------|-------------|
-| `module.md` | Rol module-agent |
-
-### MCP
-| Componente | Estado |
-|------------|--------|
-| `extensio_create --type module` | Ya existe ✓ |
-| `extensio_build` | Ya existe ✓ |
-| `extensio_test` | Ya existe ✓ |
-| `extensio_demo --type module` | Ya existe ✓ |
-| `extensio://modules` | Ya existe ✓ |
-
----
-
-## 10. Aprobación del desarrollador (OBLIGATORIA)
-
-```yaml
-approval:
-  developer:
-    decision: SI
-    date: "2026-01-07T07:30:07+01:00"
-    comments: "Aprobado para avanzar a Phase 2"
-```

package/dist/artifacts/4-adr-workflows-modulos/results.md

@@ -1,202 +0,0 @@
----
-artifact: results_acceptance
-phase: phase-6-results-acceptance
-owner: architect-agent
-status: pending
-related_task: 4-adr-workflows-modulos
-related_plan: .agent/artifacts/4-adr-workflows-modulos/plan.md
-related_review: N/A (ADR - documentación)
-related_verification: .agent/artifacts/4-adr-workflows-modulos/verification.md
----
-
-# Final Results Report — 4-adr-workflows-modulos
-
-## 1. Resumen ejecutivo (para decisión)
-
-Este documento presenta **el resultado final completo de la tarea**, consolidando:
-- lo que se planificó
-- lo que se implementó
-- cómo se revisó
-- cómo se verificó
-
-**Conclusión rápida**
-- Estado general: ☑ SATISFACTORIO
-- Recomendación del arquitecto: ☑ Aceptar
-
----
-
-## 2. Contexto de la tarea
-
-### 2.1 Objetivo original
-(Extraído de `task.md`)
-
-- **Objetivo**: Diseñar y documentar la arquitectura completa para gestionar el ciclo de vida de módulos
-- **Alcance definido**: ADR con especificación técnica de agentes, workflows, templates, constitution y MCP
-- **Fuera de alcance**: Implementación real de los componentes (será tarea futura)
-
-### 2.2 Acceptance Criteria acordados
-
-| ID | Descripción | Estado final |
-|----|-------------|--------------|
-| AC-1 | ADR completo con especificación técnica de todos los componentes | ✅ Cumplido |
-| AC-2 | Documentación del rol `module-agent` y su relación con `architect-agent` | ✅ Cumplido |
-| AC-3 | Especificación de workflows (create, refactor, delete) | ✅ Cumplido |
-| AC-4 | Especificación de templates necesarios | ✅ Cumplido |
-| AC-5 | Especificación de reglas de constitución | ✅ Cumplido |
-| AC-6 | Especificación de extensiones MCP en `extensio-cli` | ✅ Cumplido |
-| AC-7 | ADR aprobado explícitamente por el desarrollador | ✅ Cumplido |
-
----
-
-## 3. Planificación (qué se acordó hacer)
-
-### Estrategia general
-Crear un ADR que documente exhaustivamente la arquitectura para workflows de módulos, siguiendo el modelo existente de drivers.
-
-### Fases y pasos principales
-1. Phase 0: Definir acceptance criteria (5 preguntas)
-2. Phase 1: Investigación técnica del sistema existente
-3. Phase 2: Análisis de componentes necesarios
-4. Phase 3: Plan de implementación
-5. Phase 4: Creación del ADR
-6. Phase 5: Verificación de completitud
-
-### Agentes involucrados
-- **architect-agent**: Owner de toda la tarea, creación del ADR
-- **researcher-agent**: Investigación técnica en Phase 1
-
-### Estrategia de testing
-No aplica — El entregable es documentación.
-
-### Plan de demo
-No aplica — El entregable es documentación.
-
-> Referencia: `plan.md`
-
----
-
-## 4. Implementación (qué se hizo realmente)
-
-### 4.1 Subtareas por agente
-
-**Agente:** `architect-agent`
-- Responsabilidad asignada: Owner completo de la tarea
-- Subtareas ejecutadas:
-  - Definición de acceptance criteria
-  - Análisis del sistema existente
-  - Creación del plan de implementación
-  - Creación del ADR-004
-  - Verificación de completitud
-- Artefactos generados:
-  - `task.md`
-  - `analysis.md`
-  - `plan.md`
-  - `adr.md`
-  - `verification.md`
-  - `results.md` (este documento)
-
-**Agente:** `researcher-agent`
-- Responsabilidad asignada: Investigación técnica
-- Subtareas ejecutadas:
-  - Análisis del sistema de drivers existente
-  - Análisis de capacidades MCP
-  - Identificación de diferencias driver vs módulo
-- Artefactos generados:
-  - `researcher/research.md`
-
-### 4.2 Cambios técnicos relevantes
-- **Nuevos módulos/drivers**: Ninguno (ADR es documentación)
-- **Cambios estructurales**: Ninguno
-- **APIs afectadas**: Ninguna
-- **Compatibilidad**: No aplica
-
----
-
-## 5. Revisión arquitectónica
-
-- Coherencia con el plan: ☑ Sí
-- Cumplimiento de arquitectura: ☑ Sí
-- Cumplimiento de clean code: ☑ Sí
-- Desviaciones detectadas: Ninguna
-
-**Conclusiones del arquitecto**
-- **Impacto en el sistema**: El ADR proporciona la especificación para una futura implementación
-- **Riesgos residuales**: Posible desactualización si cambia la arquitectura base
-- **Deuda técnica**: Ninguna
-
----
-
-## 6. Verificación y validación
-
-### 6.1 Tests ejecutados
-- Unitarios: No aplica (documentación)
-- Integración: No aplica (documentación)
-- End-to-End / Manual: No aplica (documentación)
-- Resultado global: ☑ OK (verificación documental)
-
-### 6.2 Demo
-No aplica — El entregable es documentación.
-
-> Referencia: `verification.md`
-
----
-
-## 7. Estado final de Acceptance Criteria
-
-| Acceptance Criteria | Resultado | Evidencia |
-|---------------------|-----------|-----------|
-| AC-1 | ✅ | ADR contiene 6 secciones de componentes |
-| AC-2 | ✅ | ADR Sección 2: Rol module-agent |
-| AC-3 | ✅ | ADR Sección 3: Workflows (index, create, refactor, delete) |
-| AC-4 | ✅ | ADR Sección 4: Templates (create, refactor, delete) |
-| AC-5 | ✅ | ADR Sección 1: Constitution modules.md |
-| AC-6 | ✅ | ADR Sección 6: MCP (herramientas existentes) |
-| AC-7 | ✅ | ADR aprobado 2026-01-07T07:43:59+01:00 |
-
-**Resultado: 7/7 AC cumplidos (100%)**
-
----
-
-## 8. Incidencias y desviaciones
-
-> "No se detectaron incidencias relevantes".
-
-La única clarificación fue confirmar que el objetivo era crear un ADR (documentación), no la implementación real de los componentes, lo cual se ajustó correctamente.
-
----
-
-## 9. Valoración global
-
-- Calidad técnica: ☑ Alta
-- Alineación con lo solicitado: ☑ Total
-- Estabilidad de la solución: ☑ Alta (es documentación)
-- Mantenibilidad: ☑ Alta (estructura clara, referencias explícitas)
-
----
-
-## 10. Entregables finales
-
-| Artefacto | Ubicación | Estado |
-|-----------|-----------|--------|
-| ADR-004 | `adr.md` | ✅ Aprobado |
-| Task | `task.md` | ✅ Completo |
-| Research | `researcher/research.md` | ✅ Aprobado |
-| Analysis | `analysis.md` | ✅ Aprobado |
-| Plan | `plan.md` | ✅ Aprobado |
-| Verification | `verification.md` | ✅ Completo |
-
----
-
-## 11. Decisión final del desarrollador (OBLIGATORIA)
-
-Esta decisión **cierra la fase**.
-
-```yaml
-approval:
-  developer:
-    decision: SI
-    date: "2026-01-07T07:46:41+01:00"
-    comments: "Resultados aceptados"
-```
-
-> Sin esta aprobación, la tarea NO puede considerarse terminada.

package/dist/artifacts/4-adr-workflows-modulos/task.md

@@ -1,143 +0,0 @@
-# Task
-
-## Identificación
-- id: 4
-- title: ADR Workflows Módulos
-- scope: current
-- owner: architect-agent
-
-## Origen
-- created_from:
-  - workflow: tasklifecycle
-  - source: artifacts.candidate.task
-  - candidate_path: .agent/artifacts/candidate/task.md
-
-## Descripción de la tarea
-Crear un ADR (Architecture Decision Record) para implementar un sistema de workflows para crear, modificar y eliminar módulos en Extensio. El sistema debe seguir un modelo similar al existente para drivers.
-
-## Objetivo
-Diseñar y documentar la arquitectura completa para gestionar el ciclo de vida de módulos, incluyendo:
-- Agentes necesarios
-- Workflows necesarios
-- Templates necesarios
-- Constitution (reglas) necesarias
-- Herramientas MCP necesarias
-
-## Estado del ciclo de vida (FUENTE ÚNICA DE VERDAD)
-
-```yaml
-task:
-  id: "4"
-  title: "ADR Workflows Módulos"
-  phase:
-    current: "completed"
-    validated_by: "architect-agent"
-    updated_at: "2026-01-07T07:46:41+01:00"
-  lifecycle:
-    phases:
-      phase-0-acceptance-criteria:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:23:53+01:00"
-      phase-1-research:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:30:07+01:00"
-      phase-2-analysis:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:35:17+01:00"
-      phase-3-planning:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:37:29+01:00"
-      phase-4-implementation:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:43:59+01:00"
-      phase-5-verification:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:43:59+01:00"
-      phase-6-results-acceptance:
-        completed: true
-        validated_by: architect-agent
-        validated_at: "2026-01-07T07:46:41+01:00"
-      phase-7-evaluation:
-        completed: false
-        validated_by: null
-        validated_at: null
-      phase-8-commit-push:
-        completed: false
-        validated_by: null
-        validated_at: null
-```
-
-## Acceptance Criteria (OBLIGATORIO)
-
-### 1. Alcance
-- El ADR debe incluir **documentación técnica y funcional detallada** de cada componente:
-  - Workflows (create, refactor, delete)
-  - Templates
-  - Reglas de constitución
-  - Herramientas MCP
-- NO es solo un design doc; es especificación técnica completa.
-
-### 2. Entradas / Datos
-- Arquitectura existente de drivers como modelo de referencia:
-  - `.agent/workflows/drivers/` (create, refactor, delete)
-  - `.agent/templates/driver-*.md`
-  - `.agent/rules/constitution/drivers.md`
-  - `extensio-cli` MCP tools
-- Constitución de Extensio (`extensio-architecture.md`)
-- Diferencias arquitectónicas entre drivers y módulos
-
-### 3. Salidas / Resultado esperado
-- **ADR documentado y aprobado** que especifique:
-  - `module-agent` como owner del dominio de módulos
-  - Workflows: create, refactor, delete (mismo ciclo que drivers)
-  - Templates necesarios para módulos
-  - Reglas de constitución para módulos
-  - Extensiones del MCP `extensio-cli` existente
-
-### 4. Restricciones
-- El `module-agent` es owner del scope de módulos y su ciclo de vida
-- El `architect-agent` detecta qué agente necesita y delega a `module-agent`
-- Las herramientas MCP se integran en `extensio-cli` existente (ya dispone de comandos para crear módulos)
-- Debe respetarse la separación arquitectónica entre drivers y módulos según la constitución
-
-### 5. Criterio de aceptación (Done)
-- [ ] ADR completo con especificación técnica de todos los componentes
-- [ ] Documentación del rol `module-agent` y su relación con `architect-agent`
-- [ ] Especificación de workflows (create, refactor, delete)
-- [ ] Especificación de templates necesarios
-- [ ] Especificación de reglas de constitución
-- [ ] Especificación de extensiones MCP en `extensio-cli`
-- [ ] ADR aprobado explícitamente por el desarrollador
-
-## Historial de validaciones (append-only)
-```yaml
-history:
-  - phase: "phase-0-acceptance-criteria"
-    action: "completed"
-    validated_by: "architect-agent"
-    timestamp: "2026-01-07T07:23:53+01:00"
-    notes: "Acceptance criteria definidos. 5 preguntas respondidas por el desarrollador."
-```
-
-## Respuestas del desarrollador (referencia)
-1. **Alcance**: Documentación detallada técnica y funcional de cada workflow, template, regla y MCP
-2. **Ciclo de vida**: Mismo ciclo que drivers (create → refactor → delete)
-3. **Agentes**: `module-agent` como owner, delegado por `architect-agent`
-4. **MCP**: Integrar en `extensio-cli` existente
-5. **Done**: Solo el ADR documentado y aprobado (opción A)
-
-## Reglas contractuales
-- Este fichero es la **fuente única de verdad** del estado de la tarea.
-- El campo `task.phase.current` **SOLO puede ser modificado por `architect-agent`**.
-- El campo `task.lifecycle.phases.*` **SOLO puede ser marcado como completed por `architect-agent`**.
-- Una fase **NO puede marcarse como completed** si no es la fase actual.
-- El avance de fase requiere:
-  1. Marcar la fase actual como `completed: true`
-  2. Validación explícita del architect
-  3. Actualización de `task.phase.current` a la siguiente fase