@christianmaf80/agentic-workflow 1.8.0-beta.1 → 1.11.0-beta.1

package/dist/artifacts/11-revision-sistema-agentic/cli-mcp-impact.md

@@ -0,0 +1,186 @@
+# Informe de Impacto: CLI y MCP Server
+
+## Resumen Ejecutivo
+
+Las nuevas constituciones de Modules, Pages y Shards requieren actualizaciones en el CLI y MCP Server para garantizar coherencia entre la documentación y la implementación.
+
+---
+
+## 1. Estado Actual del CLI
+
+### 1.1 MCP Tool `extensio_create`
+
+| Característica | Soportado | Flag |
+|----------------|-----------|------|
+| Crear módulo | ✅ | `--type module` |
+| Con Shards | ✅ | `--withShard` |
+| Con Pages | ✅ | `--withPage` |
+| Con Demo | ✅ | `--includeDemo` |
+| Con Tests | ✅ | `--testType` |
+
+### 1.2 Plugins de Build
+
+| Plugin | Estado | Función |
+|--------|--------|---------|
+| `surface-pages` | ✅ Funcional | Procesa HTML y compila scripts de Pages |
+| `process-shards` | ✅ Funcional | Detecta y compila Shards independientes |
+
+### 1.3 Templates de Generación
+
+| Template | Estado | Problema |
+|----------|--------|----------|
+| `engine.engine.ts.ejs` | ✅ Completo | - |
+| `shard.ts.ejs` | ⚠️ Parcial | Falta `getTagName()`, falta herencia de Surface |
+| `page.ts.ejs` | ❌ Incompleto | Solo 2 líneas, no genera estructura correcta |
+
+---
+
+## 2. Gaps Identificados
+
+### 2.1 Gap Crítico: Template de Page
+
+**Archivo**: `packages/cli/src/generators/module/templates/page.ts.ejs`
+
+**Estado actual** (2 líneas):
+```ts
+// Página de UI completa para el módulo <%= name %>
+console.log('[<%= name %>] Page rendered');
+```
+
+**Estado requerido** (según `constitution.pages`):
+```ts
+import { Page } from '@extensio/core/surface/pages';
+
+class <%= Name %>Page extends Page {
+  constructor() {
+    super('<%= name %>-page');
+  }
+
+  override listen() {
+    super.listen();
+  }
+
+  override start() {
+    this.render();
+  }
+
+  private render() {
+    const app = document.getElementById('app');
+    if (app) {
+      app.innerHTML = '<h1><%= Name %> Page</h1>';
+    }
+  }
+}
+
+const page = new <%= Name %>Page();
+page.run();
+```
+
+**Impacto**: 🔴 Alta - Los módulos creados con `--withPage` no tendrán estructura correcta.
+
+---
+
+### 2.2 Gap Medio: Template de Shard
+
+**Archivo**: `packages/cli/src/generators/module/templates/shard.ts.ejs`
+
+**Problemas**:
+1. No implementa `getTagName()` (método abstracto obligatorio)
+2. No hereda de Surface (cuando el código de Core se actualice)
+3. Indentación incorrecta
+
+**Estado actual**:
+```ts
+export class <%= Name %>Shard extends Shard {
+  // Falta getTagName()
+}
+```
+
+**Estado requerido**:
+```ts
+export class <%= Name %>Shard extends Shard {
+  getTagName(): string {
+    return '<%= moduleName %>-<%= name %>';
+  }
+  // ...
+}
+```
+
+**Impacto**: 🟡 Media - Los Shards generados no cumplen el contrato completo.
+
+---
+
+### 2.3 Gap Funcional: No hay comandos para añadir Surfaces a módulos existentes
+
+**Situación actual**:
+- `--withShard` y `--withPage` solo funcionan al crear un módulo nuevo
+- No existe `ext add-shard <module>` ni `ext add-page <module>`
+
+**Impacto**: 🟡 Media - Los desarrolladores deben crear Shards/Pages manualmente en módulos existentes.
+
+**Recomendación**: Crear comandos `extensio_add_shard` y `extensio_add_page` en el MCP server.
+
+---
+
+## 3. Cambios Requeridos en CLI
+
+### 3.1 Actualizar Template de Page (Prioridad: Alta)
+
+| Tarea | Archivo |
+|-------|---------|
+| Reescribir template completo | `templates/page.ts.ejs` |
+| Añadir template HTML | `templates/surface/pages/index.html.ejs` |
+| Añadir template de índice | `templates/surface/pages/index.mts.ejs` |
+
+### 3.2 Actualizar Template de Shard (Prioridad: Media)
+
+| Tarea | Archivo |
+|-------|---------|
+| Añadir `getTagName()` | `templates/shard.ts.ejs` |
+| Corregir indentación | `templates/shard.ts.ejs` |
+| Actualizar herencia cuando Core cambie | `templates/shard.ts.ejs` |
+
+### 3.3 Nuevos Comandos MCP (Prioridad: Baja - Mejora)
+
+| Comando | Descripción |
+|---------|-------------|
+| `extensio_add_shard` | Añadir Shard a módulo existente |
+| `extensio_add_page` | Añadir Page a módulo existente |
+
+---
+
+## 4. Cambios Requeridos en MCP Server
+
+Actualmente el MCP server delega todo al CLI. Los cambios serán automáticos cuando se actualice el CLI.
+
+Aún así, considerar añadir:
+
+| Tool | Descripción |
+|------|-------------|
+| `extensio_validate_module` | Validar que un módulo cumple `constitution.modules` |
+| `extensio_validate_surface` | Validar que una Surface cumple su constitución |
+
+---
+
+## 5. Resumen de Prioridades
+
+| Cambio | Prioridad | Tipo |
+|--------|-----------|------|
+| Reescribir `page.ts.ejs` | 🔴 Alta | CLI Template |
+| Actualizar `shard.ts.ejs` con `getTagName()` | 🟡 Media | CLI Template |
+| Actualizar Shard para heredar de Surface | 🔴 Alta | Core Code |
+| Añadir comandos add-shard/add-page | 🟢 Baja | CLI Command |
+| Añadir validadores MCP | 🟢 Baja | MCP Tool |
+
+---
+
+## 6. Criterio de Éxito
+
+1. `ext create --type module --name test --withPage` genera estructura conforme a `constitution.pages`
+2. `ext create --type module --name test --withShard` genera Shard con `getTagName()` implementado
+3. Build procesa correctamente Pages y Shards
+4. Demo funciona sin errores
+
+---
+
+Este informe fue generado como parte de la tarea `11-revision-sistema-agentic`.

package/dist/artifacts/11-revision-sistema-agentic/core-impact.md

@@ -0,0 +1,162 @@
+# Impacto en Core: Refactorización de Surface/Shard
+
+## Contexto
+Durante la revisión de las constituciones de Modules, Pages y Shards, se identificaron cambios arquitectónicos necesarios en el código del Core para alinear la implementación con la arquitectura definida.
+
+## Cambios Requeridos
+
+### 1. Shard debe heredar de Surface (no de Core)
+
+**Archivo**: `packages/core/src/surface/shards/index.mts`
+
+**Estado actual**:
+```ts
+export abstract class Shard extends Core implements ShardLifecycle
+```
+
+**Estado deseado**:
+```ts
+export abstract class Shard extends Surface implements ShardLifecycle
+```
+
+**Impacto**:
+- Shard heredará `onMount()` y `onUnmount()` de Surface
+- Shard tendrá acceso a `onStorageChanged()` y `checkListeners()`
+- La jerarquía será: `Core → Surface → Shard`
+
+**Riesgo**: Medio. Verificar que no hay conflictos de métodos.
+
+---
+
+### 2. onMount() debe ser automático post-render
+
+**Archivo**: `packages/core/src/surface/surface.mts`
+
+**Estado actual**:
+```ts
+onMount(): void {
+    this.run();
+}
+```
+
+**Estado deseado**:
+```ts
+// onMount es un hook que se ejecuta DESPUÉS de render()
+protected onMount(): void {
+    // Hook vacío - subclases lo sobrescriben
+}
+
+public async run() {
+    await this._setup();
+    await this.start();
+    await this.render();
+    this.onMount();  // <-- Llamar automáticamente después de render
+}
+```
+
+**Impacto**:
+- `onMount()` ya no es el punto de entrada
+- `run()` es el punto de entrada
+- `onMount()` es un hook que el desarrollador sobrescribe
+
+**Riesgo**: Alto. Cambio de comportamiento. Revisar uso en código existente.
+
+---
+
+### 3. Añadir render() abstracto a Surface
+
+**Archivo**: `packages/core/src/surface/surface.mts`
+
+**Estado actual**: No existe `render()` en Surface.
+
+**Estado deseado**:
+```ts
+export abstract class Surface extends Core {
+    // ...
+    
+    /**
+     * Renderiza el contenido de la Surface.
+     * Subclases deben implementar.
+     */
+    public abstract render(): Promise<void>;
+}
+```
+
+**Impacto**:
+- Page y Shard deben implementar `render()`
+- Unifica el contrato de renderizado
+
+**Riesgo**: Medio. Page actual no tiene `render()`.
+
+---
+
+### 4. Evaluar integración de ShardLifecycle en Surface
+
+**Archivos**: 
+- `packages/core/src/surface/shards/types.d.mts`
+- `packages/core/src/surface/surface.mts`
+
+**Evaluación**:
+La interface `ShardLifecycle` define:
+```ts
+interface ShardLifecycle {
+    mount(container: HTMLElement): Promise<void>;
+    update(props: Record<string, any>): void;
+    unmount(): void;
+    getTagName(): string;
+    render?(): Promise<void>;
+}
+```
+
+**Propuesta**:
+- `render()` → Mover a Surface (abstracto)
+- `mount(container)` → Solo en Shard (Page no usa container explícito)
+- `update(props)` → Solo en Shard
+- `getTagName()` → Solo en Shard
+- `unmount()` → Mover a Surface (con implementación base)
+
+**Resultado**:
+- Surface: `render()`, `unmount()`, `onMount()`, `onUnmount()`
+- Shard: `mount(container)`, `update(props)`, `getTagName()`, `_mount()`, `_unmount()`
+
+---
+
+## Orden de Implementación Recomendado
+
+1. **Añadir `render()` abstracto a Surface**
+2. **Implementar `render()` en Page** (vacío o con lógica base)
+3. **Mover `onMount()` a ser hook post-render** en Surface
+4. **Cambiar Shard para extender Surface**
+5. **Ajustar `mount()` de Shard** para llamar hooks en orden correcto
+6. **Tests**: Ejecutar tests unitarios y E2E
+
+---
+
+## Tests Afectados
+
+- `packages/core/test/unit/decorators.test.mts`
+- `packages/core/demo/` (demo de Core)
+- Cualquier módulo que use Shards
+
+---
+
+## Criterio de Éxito
+
+1. Jerarquía: `Core → Surface → Page` y `Core → Surface → Shard`
+2. `onMount()` se ejecuta automáticamente después de `render()`
+3. `onUnmount()` se ejecuta automáticamente antes de destruir
+4. Todos los tests pasan
+5. Demo funciona correctamente
+
+---
+
+## Prioridad
+
+**Alta** - Estos cambios son necesarios para que la implementación coincida con las constituciones aprobadas.
+
+---
+
+## Notas
+
+Este documento fue generado como parte de la tarea `11-revision-sistema-agentic`.
+Los cambios de código deben realizarse en una tarea separada después de aprobar las constituciones.

package/dist/artifacts/11-revision-sistema-agentic/metrics.md

@@ -0,0 +1,82 @@
+# Evaluación de Agentes - Phase 7
+
+## Tarea: 11-revision-sistema-agentic
+## Fecha: 2026-01-13T23:52:00+01:00
+
+---
+
+## 1. Agentes Participantes
+
+| Agente | Rol | Participación |
+|--------|-----|---------------|
+| architect-agent | Orquestador | Principal |
+| researcher-agent | Investigación | Phase 1 |
+| module-agent | Gobernanza | Consulta |
+
+---
+
+## 2. Evaluación del architect-agent
+
+| Criterio | Puntuación (1-5) | Comentario |
+|----------|------------------|------------|
+| Cumplimiento de constituciones | 5/5 | Todas las constituciones actualizadas |
+| Coherencia arquitectónica | 5/5 | Decisiones alineadas con filosofía Extensio |
+| Comunicación | 5/5 | Propuestas claras, confirmación de decisiones |
+| Gestión de fases | 4/5 | Algunas fases implícitas |
+| Documentación | 5/5 | Informes completos y detallados |
+| **Total** | **24/25** | **96%** |
+
+---
+
+## 3. Evaluación del researcher-agent
+
+| Criterio | Puntuación (1-5) | Comentario |
+|----------|------------------|------------|
+| Calidad de investigación | 4/5 | Identificó gaps principales |
+| Análisis de alternativas | 4/5 | Propuso Option A vs B |
+| Documentación | 4/5 | Informe de research completo |
+| **Total** | **12/15** | **80%** |
+
+---
+
+## 4. Métricas de la Tarea
+
+| Métrica | Valor |
+|---------|-------|
+| Duración total | ~14 horas (con interrupciones) |
+| Archivos modificados | 8 constituciones/workflows/roles |
+| Archivos creados | 6 artefactos |
+| Líneas añadidas (aprox) | +1,800 líneas |
+| Gaps identificados | 4 (Core + CLI) |
+
+---
+
+## 5. Lecciones Aprendidas
+
+### Positivas
+1. La separación architecture vs constituciones mejora la claridad
+2. Los hooks automáticos unifican el ciclo de vida
+3. Las responsabilidades SRP de Pages evitan duplicación con Engine
+
+### Áreas de Mejora
+1. Los templates del CLI estaban desactualizados
+2. El código de Core (Shard) no coincidía con la arquitectura documentada
+3. Algunas fases del workflow se fusionaron implícitamente
+
+---
+
+## 6. Evaluación del Desarrollador (PENDIENTE)
+
+> El desarrollador debe completar esta sección:
+
+| Criterio | Puntuación (0-5) | Comentario |
+|----------|------------------|------------|
+| Satisfacción con entregables | 5/5 | Excelente |
+| Calidad de documentación | 4/5 | Muy buena |
+| Comunicación del agente | 5/5 | Excelente |
+| Utilidad de la tarea | 5/5 | Muy útil |
+| **Aprobación final** | **SI** | Aprobado |
+
+---
+
+Generado por: architect-agent

package/dist/artifacts/11-revision-sistema-agentic/modules-create-v2.md

@@ -0,0 +1,126 @@
+---
+description: Workflow para crear módulos siguiendo la constitución y reglas de arquitectura del ecosistema Extensio.
+---
+
+---
+id: workflow.modules.create
+owner: module-agent
+version: 2.0.0
+severity: PERMANENT
+trigger:
+  commands: ["module-create", "modules:create"]
+blocking: true
+---
+
+# WORKFLOW: modules.create
+
+## Input (REQUIRED)
+- El arquitecto ha determinado en el plan la creación de un nuevo módulo:
+  - `.agent/artifacts/<taskId>-<taskTitle>/plan.md`
+
+## Output (REQUIRED)
+- Informe de creación de módulo (OBLIGATORIO):
+  - `.agent/artifacts/<taskId>-<taskTitle>/module/create.md`
+
+## Objetivo (ONLY)
+Asegurar que la creación de un nuevo módulo cumple:
+- la constitución de módulos (`constitution.modules`)
+- la constitución de pages (`constitution.pages`) si aplica
+- la constitución de shards (`constitution.shards`) si aplica
+- la arquitectura de Extensio y reglas globales
+- la integración correcta en el ecosistema
+
+> Esta fase **NO** omite auditoría del architect-agent.
+
+## Template (OBLIGATORIO)
+- El informe **DEBE** crearse usando el template:
+  - `templates.module_create`
+- Si el template no existe o no se puede cargar → **FAIL**.
+
+---
+
+## Pasos obligatorios
+
+1. Verificar inputs
+   - Existe `plan.md` que requiere crear un módulo.
+   - Si falla → ir a **Paso 8 (FAIL)**.
+
+2. Crear el módulo
+   - Crear el módulo usando el tool:
+     - `mcp_extensio-cli tools`
+   - Configurar flags según necesidades:
+     - `withShards` para componentes UI
+     - `withPages` para páginas completas
+     - `includeDemo` (default true)
+   - La creación manual **solo** es válida si el CLI no soporta la operación.
+   - Garantizar estructura, types, constants, globals y ciclo de vida.
+
+3. Verificar estructura base (OBLIGATORIO)
+   - Verificar que `global.d.mts` contiene el namespace `Extensio.<NombreModulo>`.
+   - Verificar que `constants.mts` root exporta las constantes del módulo.
+   - Verificar que `demo/` existe y es funcional.
+   - Validar scopes (Engine obligatorio).
+   - Verificar reactividad y `waitingLoadProps` donde aplique.
+   - Si falta algo → corregir antes de continuar.
+
+4. Verificar Surfaces (si aplica)
+   
+   **Si el módulo tiene Pages:**
+   - Verificar que existe `src/surface/pages/index.mts` con imports de HTML.
+   - Verificar estructura: `<page-name>/index.html` + `<page-name>/index.mts`
+   - Verificar ciclo de vida: `run()` → `listen()` → `start()`
+   - Verificar responsabilidades (§11-12 de `constitution.pages`):
+     - Solo lógica de presentación
+     - Solo lógica de interacción
+     - Solo orquestación de Shards
+     - NO estado persistente de negocio
+   
+   **Si el módulo tiene Shards:**
+   - Verificar que existe `src/surface/shards/index.mts` con `Shard.register()`.
+   - Verificar que cada Shard tiene `getTagName()` único.
+   - Verificar cumplimiento de `constitution.shards`.
+
+5. Crear informe de creación
+   - Crear:
+     - `.agent/artifacts/<taskId>-<taskTitle>/module/create.md`
+   - Completar el informe según el template.
+
+6. Auditoría del architect-agent (OBLIGATORIA)
+   - El `architect-agent` **DEBE** revisar el módulo y el informe.
+   - Si detecta fallos → ir a **Paso 8 (FAIL)**.
+
+7. PASS
+   - Informar que el módulo cumple el contrato.
+
+---
+
+## FAIL (OBLIGATORIO)
+
+8. Declarar creación de módulo como **NO completada**
+   - Indicar exactamente qué falló:
+     - plan inexistente o no requiere módulo
+     - template inexistente
+     - incumplimiento de `constitution.modules`
+     - incumplimiento de `constitution.pages` (si aplica)
+     - incumplimiento de `constitution.shards` (si aplica)
+     - Pages con lógica de negocio persistente (violación §11-12)
+     - fallos de integración en el ecosistema
+     - auditoría del architect-agent rechazada
+   - Acción mínima:
+     - corregir los puntos detectados por architect o desarrollador
+   - Terminar bloqueado: no avanzar.
+
+---
+
+## Gate (REQUIRED)
+
+Requisitos (todos obligatorios):
+1. Existe `.agent/artifacts/<taskId>-<taskTitle>/module/create.md`.
+2. El informe sigue la estructura del template `templates.module_create`.
+3. El módulo cumple `constitution.modules`.
+4. Si hay Pages, cumplen `constitution.pages` (especialmente §11-12).
+5. Si hay Shards, cumplen `constitution.shards`.
+6. Auditoría del architect-agent aprobada.
+
+Si Gate FAIL:
+- Ejecutar **Paso 8 (FAIL)**.