@christianmaf80/agentic-workflow 1.24.0-beta.3 → 1.25.0-beta.3

package/dist/agent/artifacts/12-npm-workspaces/analysis.md

@@ -0,0 +1,179 @@
+🏛️ **architect-agent**: Análisis técnico para T012 — Migración a npm workspaces.
+
+---
+artifact: analysis
+phase: phase-2-analysis
+owner: architect-agent
+status: draft
+related_task: 12-npm-workspaces
+---
+
+# Analysis — 12-npm-workspaces
+
+## 1. Resumen ejecutivo
+
+**Problema**
+El proyecto es un monolito TypeScript donde todas las dependencias están centralizadas en un único `package.json` y los módulos se comunican mediante rutas relativas. Esto impide el aislamiento de dependencias y dificulta la escalabilidad.
+
+**Objetivo**
+Convertir `app`, `core` y `cli` en packages npm privados dentro de un monorepo con npm workspaces.
+
+**Criterio de éxito**
+Los tests e2e deben seguir pasando idénticamente tras la migración.
+
+---
+
+## 2. Estado del proyecto (As-Is)
+
+- **Estructura relevante**
+  - `src/extension/modules/app/` — módulo App (hereda de core)
+  - `src/extension/modules/core/` — módulo Core (base classes, logger, messaging, view)
+  - `src/cli/` — CLI con 3 comandos (init, create, mcp)
+  - `src/infrastructure/` — utilidades de migración y mapping
+  - `src/runtime/` — MCP server runtime
+
+- **Componentes existentes**
+  - **app**: depende de core (4 imports directos con rutas relativas `../core/`)
+  - **core**: autónomo, sin dependencias a otros módulos internos
+  - **cli**: depende de infrastructure y runtime (rutas `../../infrastructure/`, `../../runtime/`)
+
+- **Nucleo / capas base**
+  - `tsconfig.json` único con `rootDir: ./src`, `outDir: ./dist`
+  - `tsconfig.build.json` excluye `src/extension/**` (solo compila cli/runtime/infra)
+  - Build: `tsc -p ./` para extensión, `tsc -p tsconfig.build.json` para npm package
+
+- **Limitaciones detectadas**
+  - `cli` importa `infrastructure` y `runtime` que NO serán workspaces — rutas relativas deben mantenerse o necesitan otro enfoque
+  - `extension.ts` vive fuera de modules y es el entry point de VSCode
+  - El output `dist/extension/extension.js` debe mantenerse para que VSCode funcione
+
+---
+
+## 3. Cobertura de Acceptance Criteria
+
+### AC-1: Tests e2e pasan idénticamente
+- **Interpretación**: `npm run test:e2e` (Playwright) debe producir el mismo resultado antes y después
+- **Verificación**: Ejecutar `npx playwright test` antes y después de la migración
+- **Riesgos**: Si la ruta de resolución de módulos cambia, la extensión podría no compilar
+
+### AC-2: `npm install` instala todos los workspaces
+- **Interpretación**: Un solo `npm install` en root resuelve deps de app, core y cli
+- **Verificación**: `npm install && npm ls --ws`
+- **Riesgos**: Versiones conflictivas de la misma dependencia entre packages
+
+### AC-3: `npm run compile` compila todos los workspaces
+- **Interpretación**: El comando root debe compilar TypeScript de todos los packages
+- **Verificación**: `npm run compile` debe exit 0
+- **Riesgos**: `tsconfig.json` actual asume `rootDir: ./src` — necesita ajuste
+
+### AC-4: Cada package tiene `package.json` con `"private": true`
+- **Interpretación**: Crear 3 package.json independientes
+- **Verificación**: Verificar existencia y contenido de cada archivo
+- **Riesgos**: Bajo
+
+### AC-5: Root `package.json` contiene `"workspaces"`
+- **Interpretación**: Configurar el campo `workspaces` apuntando a los 3 packages
+- **Verificación**: Verificar campo en package.json
+- **Riesgos**: Bajo
+
+### AC-6: Dependencias inter-package vía `workspace:*`
+- **Interpretación**: app debe declarar `"@agentic-workflow/core": "workspace:*"` en sus deps
+- **Verificación**: `npm ls @agentic-workflow/core`
+- **Riesgos**: Las rutas relativas de import en TypeScript deben cambiar de `../core/` a `@agentic-workflow/core`
+
+### AC-7: Extensión VSCode funciona tras migración
+- **Interpretación**: `npm run compile` + F5 Launch Extension funciona
+- **Verificación**: Tests e2e (gate principal)
+- **Riesgos**: El entry point `dist/extension/extension.js` debe seguir existiendo en la misma ruta
+
+---
+
+## 4. Research técnico — Alternativas
+
+- **Alternativa A: npm workspaces sin TypeScript project references**
+  - Cada package tiene `package.json` pero comparten un `tsconfig.json` root
+  - Los imports cambian de rutas relativas a package names (`@agentic-workflow/core`)
+  - TypeScript resuelve vía `node_modules` symlinks creados por npm workspaces
+  - Ventajas: Más simple, menos configuración TypeScript
+  - Inconvenientes: Sin compilación incremental, un tsconfig
+
+- **Alternativa B: npm workspaces + TypeScript project references**
+  - Cada package tiene `package.json` Y `tsconfig.json` propio con `composite: true`
+  - Root tsconfig usa `references` para compilar en orden
+  - Ventajas: Compilación incremental, mejor aislamiento de tipos
+  - Inconvenientes: Mayor complejidad de configuración, cada package necesita `declaration: true`
+
+**Decisión recomendada**: **Alternativa A** (npm workspaces sin TS project references), por minimizar cambios y riesgos. La Alternativa B se puede adoptar incrementalmente después.
+
+---
+
+## 5. Agentes participantes
+
+- **🏛️ architect-agent**
+  - Diseño de la estructura de workspaces
+  - Configuración de package.json files
+  - Actualización de tsconfig
+  - Actualización de import paths
+
+- **🛡️ qa-agent**
+  - Verificación de tests e2e
+  - Validación de que compile funciona
+
+**Handoffs**
+- architect implementa → qa verifica con tests e2e
+
+**Componentes necesarios**
+- **Crear**: 3 `package.json` (app, core, cli)
+- **Modificar**: Root `package.json`, `tsconfig.json`, imports en app (de relativo a package name)
+- **Eliminar**: Ninguno
+
+**Demo**: No aplica.
+
+---
+
+## 6. Impacto de la tarea
+
+- **Arquitectura**: Se añaden 3 packages internos al monorepo. No cambia la estructura de carpetas.
+- **APIs / contratos**: Los exports de cada package se definen en su `package.json`. Las interfaces TS no cambian.
+- **Compatibilidad**: Los imports cambian de `../core/` a `@agentic-workflow/core`. Es un breaking change interno pero no afecta APIs externas.
+- **Testing**: Los tests e2e son el gate. Los unit tests de app necesitarán ajustar imports.
+
+---
+
+## 7. Riesgos y mitigaciones
+
+| Riesgo | Impacto | Mitigación |
+|--------|---------|------------|
+| `cli` importa `infrastructure` y `runtime` con rutas relativas — no son workspaces | Medio | Mantener rutas relativas en cli (no cambiar lo que no es workspace) |
+| `tsconfig.json` rootDir/outDir debe ajustarse para workspaces | Alto | Mantener tsconfig root, los packages heredan o aplican paths |
+| Ruta `dist/extension/extension.js` debe existir para VSCode | Alto | Asegurar que compile produce output en la misma ubicación |
+| Symlinks de npm workspaces pueden causar issues en VSCode bundling | Medio | Verificar con test e2e completo |
+
+---
+
+## 8. Preguntas abiertas
+Ninguna tras Fase 0.
+
+---
+
+## 9. TODO Backlog
+
+**Referencia**: `.agent/todo/`
+**Estado actual**: No existe directorio todo
+**Items relevantes para esta tarea**: Ninguno
+**Impacto en el análisis**: Sin impacto
+
+---
+
+## 10. Aprobación
+Este análisis **requiere aprobación explícita del desarrollador**.
+
+```yaml
+approval:
+  developer:
+    decision: SI
+    date: "2026-02-16T07:39:57+01:00"
+    comments: null
+```
+
+> Sin aprobación, esta fase **NO puede darse por completada** ni avanzar a Phase 3.

package/dist/agent/artifacts/12-npm-workspaces/plan.md

@@ -0,0 +1,237 @@
+🏛️ **architect-agent**: Plan de implementación para T012 — Migración a npm workspaces.
+
+---
+artifact: plan
+phase: phase-3-planning
+owner: architect-agent
+status: draft
+related_task: 12-npm-workspaces
+---
+
+# Implementation Plan — 12-npm-workspaces
+
+## 1. Resumen del plan
+- **Contexto**: Convertir los módulos app, core y cli en packages npm privados dentro de un monorepo con npm workspaces.
+- **Resultado esperado**: Proyecto configurado como npm workspaces con 3 packages independientes, build unificado funcional y tests e2e pasando.
+- **Alcance**:
+  - **Incluye**: Crear 3 `package.json`, configurar workspaces en root, actualizar imports de app→core a package name, ajustar tsconfig
+  - **Excluye**: TypeScript project references (se puede adoptar después), cambio de rutas en cli (mantiene relativas a infrastructure/runtime)
+
+---
+
+## 2. Inputs contractuales
+- **Task**: `.agent/artifacts/12-npm-workspaces/task.md`
+- **Analysis**: `.agent/artifacts/12-npm-workspaces/analysis.md`
+- **Acceptance Criteria**: AC-1 a AC-7 (tests e2e como gate principal)
+
+```yaml
+plan:
+  workflows:
+    - domain: extension-modules
+      action: refactor
+      workflow: tasklifecycle-long
+
+  dispatch:
+    - domain: core-package
+      action: create
+      workflow: tasklifecycle-long
+    - domain: app-package
+      action: refactor
+      workflow: tasklifecycle-long
+    - domain: cli-package
+      action: create
+      workflow: tasklifecycle-long
+    - domain: root-config
+      action: refactor
+      workflow: tasklifecycle-long
+```
+
+---
+
+## 3. Desglose de implementación (pasos)
+
+### Paso 1: Crear `package.json` para `@agentic-workflow/core`
+- **Descripción**: Crear `src/extension/modules/core/package.json` con nombre `@agentic-workflow/core`, `private: true`, y las dependencias que usa core (`vscode` como peer, `@fastify/cors`, `fastify` si aplica)
+- **Dependencias**: Ninguna
+- **Entregables**: `src/extension/modules/core/package.json`
+- **Agente responsable**: architect-agent
+
+### Paso 2: Crear `package.json` para `@agentic-workflow/app`
+- **Descripción**: Crear `src/extension/modules/app/package.json` con nombre `@agentic-workflow/app`, `private: true`, dependencia a `@agentic-workflow/core` via `workspace:*`, y sus propias deps
+- **Dependencias**: Paso 1 (core package existe)
+- **Entregables**: `src/extension/modules/app/package.json`
+- **Agente responsable**: architect-agent
+
+### Paso 3: Crear `package.json` para `@agentic-workflow/cli`
+- **Descripción**: Crear `src/cli/package.json` con nombre `@agentic-workflow/cli`, `private: true`, y sus dependencias de CLI (`commander`, `@clack/prompts`)
+- **Dependencias**: Ninguna
+- **Entregables**: `src/cli/package.json`
+- **Agente responsable**: architect-agent
+
+### Paso 4: Configurar workspaces en root `package.json`
+- **Descripción**: Añadir campo `"workspaces"` al root `package.json` apuntando a los 3 packages. Mover dependencias exclusivas de cada package a sus respectivos `package.json`
+- **Dependencias**: Pasos 1-3
+- **Entregables**: Root `package.json` actualizado
+- **Agente responsable**: architect-agent
+
+### Paso 5: Actualizar imports en `app` (de relativos a package name)
+- **Descripción**: Cambiar todos los imports de `../core/...` y `../../core/...` en app a `@agentic-workflow/core`. Archivos afectados:
+  - `app/index.ts`: `'../core/index.js'` → `'@agentic-workflow/core'`
+  - `app/backend/index.ts`: `'../../core/backend/index.js'` → `'@agentic-workflow/core/backend'` o `'@agentic-workflow/core'`
+  - `app/background/index.ts`: `'../../core/index.js'` → `'@agentic-workflow/core'`
+  - `app/view/index.ts`: `'../../core/view/index.js'` → `'@agentic-workflow/core'`
+  - `app/test/unit/background.test.ts`: imports de core → package name
+- **Dependencias**: Paso 4
+- **Entregables**: Imports actualizados en 5 archivos
+- **Agente responsable**: architect-agent
+
+### Paso 6: Configurar exports en core `package.json`
+- **Descripción**: Definir `"exports"` en core package.json para exponer los submodules necesarios (backend, view, messaging, etc.) via subpath exports
+- **Dependencias**: Paso 5 (saber qué subpaths se necesitan)
+- **Entregables**: `src/extension/modules/core/package.json` con exports map
+- **Agente responsable**: architect-agent
+
+### Paso 7: Ejecutar `npm install` y verificar symlinks
+- **Descripción**: Ejecutar `npm install` desde root para que npm cree los symlinks de workspace. Verificar que `node_modules/@agentic-workflow/core` y `@agentic-workflow/app` existen
+- **Dependencias**: Paso 6
+- **Entregables**: `npm install` exitoso
+- **Agente responsable**: architect-agent
+
+### Paso 8: Verificar compilación
+- **Descripción**: Ejecutar `npm run compile` y solucionar errores TypeScript si los hay
+- **Dependencias**: Paso 7
+- **Entregables**: Build exitoso
+- **Agente responsable**: architect-agent
+
+### Paso 9: Ejecutar tests e2e
+- **Descripción**: Ejecutar `npm run test:e2e` (Playwright) y verificar que pasan
+- **Dependencias**: Paso 8
+- **Entregables**: Tests e2e passing
+- **Agente responsable**: qa-agent
+
+---
+
+## 4. Asignación de responsabilidades (Agentes)
+
+- **🏛️ architect-agent**
+  - Crear package.json files (Pasos 1-4)
+  - Actualizar imports y exports (Pasos 5-6)
+  - Configurar y verificar build (Pasos 7-8)
+
+- **🛡️ qa-agent**
+  - Ejecutar y verificar tests e2e (Paso 9)
+  - Validar todos los AC
+
+**Handoffs**
+- architect-agent → qa-agent: al completar Paso 8 (build exitoso)
+
+**Componentes**
+- **Crear**: 3 `package.json` (core, app, cli) — herramienta: editor de archivos
+- **Modificar**: Root `package.json`, imports en app (5 archivos) — herramienta: editor de archivos
+- **Eliminar**: Ninguno
+
+**Demo**: No aplica.
+
+---
+
+## 5. Estrategia de testing y validación
+
+- **E2E (Gate principal)**
+  - Comando: `npx playwright test`
+  - Cobertura: Extensión VSCode se activa, módulos se registran, UI funciona
+  - Trazabilidad: AC-1
+
+- **Unit tests**
+  - Comando: `npm run test:unit`
+  - Cobertura: `background.test.ts` — verificar que imports de core funcionan con package name
+  - Trazabilidad: AC-3, AC-6
+
+- **Build verification**
+  - Comando: `npm run compile`
+  - Cobertura: TypeScript compila sin errores
+  - Trazabilidad: AC-3
+
+- **Workspace verification**
+  - Comando: `npm ls --ws`
+  - Cobertura: Todos los workspaces resueltos correctamente
+  - Trazabilidad: AC-2, AC-5
+
+**Trazabilidad AC → Tests**:
+| AC | Test |
+|----|------|
+| AC-1: Tests e2e pasan | `npx playwright test` |
+| AC-2: npm install funciona | `npm install && npm ls --ws` |
+| AC-3: compile funciona | `npm run compile` |
+| AC-4: package.json con private | Verificación manual de archivos |
+| AC-5: workspaces configurado | `cat package.json \| grep workspaces` |
+| AC-6: deps via workspace:* | `npm ls @agentic-workflow/core` |
+| AC-7: VSCode funciona | `npx playwright test` (e2e) |
+
+---
+
+## 6. Plan de demo
+No aplica (cambio de infraestructura sin impacto visible en UI).
+
+---
+
+## 7. Estimaciones y pesos de implementación
+
+| Paso | Esfuerzo | Notas |
+|------|----------|-------|
+| 1-3: Crear package.json | Bajo | Archivos nuevos simples |
+| 4: Configurar root workspaces | Bajo | Un campo en package.json |
+| 5: Actualizar imports | Medio | 5 archivos, requiere cuidado |
+| 6: Configurar exports | Medio | Subpath exports pueden ser complejos |
+| 7: npm install | Bajo | Verificación |
+| 8: Verificar compilación | Medio | Posibles errores de resolución |
+| 9: Tests e2e | Bajo | Ejecución y validación |
+
+**Suposiciones**: La estructura de carpetas no cambia. Los outputs de compilación deben mantenerse en las mismas rutas.
+
+---
+
+## 8. Puntos críticos y resolución
+
+- **Punto crítico 1: Resolución de módulos TypeScript**
+  - Riesgo: TypeScript puede no resolver `@agentic-workflow/core` sin TS project references
+  - Impacto: Alto — build falla
+  - Estrategia: npm workspaces crea symlinks en `node_modules/`, TypeScript con `moduleResolution: NodeNext` los resuelve. Si falla, añadir `paths` en tsconfig.
+
+- **Punto crítico 2: Output path de extensión VSCode**
+  - Riesgo: El `dist/extension/extension.js` podría generarse en otra ruta
+  - Impacto: Alto — extensión no arranca
+  - Estrategia: Mantener `rootDir: ./src` y `outDir: ./dist` en el tsconfig root. No crear tsconfig por package.
+
+- **Punto crítico 3: Imports de subpaths en core**
+  - Riesgo: app importa de `core/backend/index.js` directamente — requiere subpath exports
+  - Impacto: Medio — imports específicos fallan
+  - Estrategia: Configurar `"exports"` en core package.json para cada subpath usado, o consolidar re-exports en core/index.ts.
+
+---
+
+## 9. Dependencias y compatibilidad
+- **Dependencias internas**: app → core (workspace:*), cli → infrastructure/runtime (rutas relativas, sin cambio)
+- **Dependencias externas**: npm 9+, Node 20+, TypeScript 5.9.3 — todas compatibles
+- **Restricciones arquitectónicas**: Entry point VSCode (`main` en root package.json) debe apuntar a `./dist/extension/extension.js`
+
+---
+
+## 10. Criterios de finalización
+- [ ] `npm install` exitoso desde root
+- [ ] `npm run compile` exitoso
+- [ ] `npx playwright test` pasa idénticamente
+- [ ] 3 package.json creados con `"private": true`
+- [ ] Root package.json tiene `"workspaces"` configurado
+- [ ] Imports de app→core usan `@agentic-workflow/core`
+
+---
+
+## 11. Aprobación del desarrollador (OBLIGATORIA)
+
+```yaml
+approval:
+  developer:
+    decision: SI
+    date: "2026-02-16T07:42:30+01:00"
+    comments: null
+```

package/dist/agent/artifacts/12-npm-workspaces/researcher/research.md

@@ -0,0 +1,186 @@
+🔬 **researcher-agent**: Informe de investigación técnica para T012 — npm-workspaces.
+
+---
+artifact: research
+phase: phase-1-research
+owner: researcher-agent
+status: draft
+related_task: 12-npm-workspaces
+---
+
+# Research Report — 12-npm-workspaces
+
+> [!CAUTION]
+> **REGLA PERMANENT**: Este documento es SOLO documentación.
+> El researcher-agent documenta hallazgos SIN analizar, SIN recomendar, SIN proponer soluciones.
+> El análisis corresponde a Phase 2.
+
+## 1. Resumen ejecutivo
+- **Problema investigado**: Migración del proyecto monolítico a npm workspaces con packages independientes
+- **Objetivo de la investigación**: Documentar la estructura actual, dependencias entre módulos, y las capacidades de npm workspaces
+- **Principales hallazgos**: El proyecto tiene dependencias cruzadas entre `app→core` y `cli→infrastructure+runtime`. npm workspaces soporta este patrón de forma nativa desde Node 16+
+
+---
+
+## 2. Necesidades detectadas
+
+### Estructura actual del proyecto
+```
+src/
+├── extension/
+│   ├── extension.ts          → entry point VSCode (importa app)
+│   └── modules/
+│       ├── app/              → Package candidato @agentic-workflow/app
+│       │   ├── index.ts      → importa '../core/index.js'
+│       │   ├── backend/      → importa '../../core/backend/index.js'
+│       │   ├── background/   → importa '../../core/index.js'
+│       │   ├── view/         → importa '../../core/view/index.js'
+│       │   └── test/unit/    → importa '../../../core/...'
+│       └── core/             → Package candidato @agentic-workflow/core
+│           ├── index.ts      → re-exports de submodules
+│           ├── backend/      → AbstractBackend, VirtualServer
+│           ├── background/   → Background base class
+│           ├── messaging/    → Transport layer
+│           ├── view/         → View base + templates
+│           ├── logger.ts
+│           ├── constants.ts
+│           └── types.d.ts
+├── cli/                      → Package candidato @agentic-workflow/cli
+│   ├── index.ts              → re-exports commands
+│   └── commands/
+│       ├── init.ts           → importa '../../infrastructure/...'
+│       ├── create.ts         → importa '../../infrastructure/...'
+│       └── mcp.ts            → importa '../../runtime/...'
+├── infrastructure/           → NO es package (dependencia de cli)
+└── runtime/                  → NO es package (dependencia de cli)
+```
+
+### Mapa de dependencias cruzadas entre módulos
+| Origen | Destino | Archivos que importan |
+|--------|---------|----------------------|
+| `app/index.ts` | `core/index.js` | `App extends CoreApp` |
+| `app/backend/index.ts` | `core/backend/index.js` | `AbstractBackend` |
+| `app/background/index.ts` | `core/index.js` | `Background, ViewHtml, Message` |
+| `app/view/index.ts` | `core/view/index.js` | `View` |
+| `app/test/unit/background.test.ts` | `core/messaging/background.js`, `core/index.js` | Test imports |
+| `cli/commands/init.ts` | `infrastructure/...`, `runtime/...` | `detectAgentSystem`, `resolver`, `backup`, `startRuntimeMcpServer` |
+| `cli/commands/create.ts` | `infrastructure/mapping/resolver.js` | Resolver |
+| `cli/commands/mcp.ts` | `runtime/mcp/server.js` | `startRuntimeMcpServer` |
+
+### Configuración TypeScript actual
+- **tsconfig.json**: `rootDir: ./src`, `outDir: ./dist`, `module: NodeNext`
+- **tsconfig.build.json**: Excluye `src/extension/**` y tests (build solo cli/runtime/infra)
+- Sin TypeScript project references configuradas
+
+### Tests existentes
+- **E2E**: `test/e2e/extension.spec.ts` — Playwright, 1 archivo, config en `playwright.config.ts` (testDir: `./test/e2e`)
+- **Unit**: `src/extension/modules/app/test/unit/background.test.ts` — Vitest
+- **Scripts**: `npm run test:e2e` (Playwright), `npm run test:unit` (Vitest), `npm run compile` (tsc + build-view.mjs)
+
+### Build pipeline actual
+- `compile`: `tsc -p ./ && node scripts/build-view.mjs`
+- `build`: `clean-dist && tsc -p tsconfig.build.json && copy-assets`
+- `watch`: `tsc -watch -p ./ & node scripts/build-view.mjs --watch`
+
+---
+
+## 3. Hallazgos técnicos
+
+### 3.1 npm Workspaces
+- **Descripción**: Funcionalidad nativa de npm (desde v7 / Node 16) que permite gestionar múltiples packages dentro de un mismo repositorio.
+- **Estado**: Estable, soportado en producción
+- **Documentación oficial**: https://docs.npmjs.com/cli/v10/using-npm/workspaces
+- **Limitaciones conocidas**:
+  - Hoisting por defecto; se puede controlar con `.npmrc` (`install-strategy=nested`)
+  - `node_modules` compartido en root por defecto
+  - Requiere que cada workspace tenga su propio `package.json` con campo `name`
+
+### 3.2 workspace: protocol
+- **Descripción**: Protocolo para referenciar packages del workspace como dependencias (`"@agentic-workflow/core": "workspace:*"`)
+- **Estado**: Soportado nativamente por npm desde v9+
+- **Documentación**: https://docs.npmjs.com/cli/v10/configuring-npm/package-json#workspace-dependencies
+- **Limitaciones**: Packages con `workspace:*` no se pueden publicar directamente; npm los reemplaza en `npm pack`/`npm publish`
+
+### 3.3 TypeScript Project References
+- **Descripción**: Mecanismo nativo de TypeScript para compilar múltiples proyectos con dependencias entre ellos
+- **Estado**: Estable desde TypeScript 3.0+
+- **Documentación**: https://www.typescriptlang.org/docs/handbook/project-references.html
+- **Limitaciones**: Requiere `composite: true` y `declaration: true` en cada sub-proyecto
+
+### 3.4 VSCode Extension con Workspaces
+- **Descripción**: Las extensiones VSCode usan webpack/esbuild para bundling; npm workspaces puede coexistir
+- **Estado**: No documentado oficialmente por VSCode
+- **Documentación**: https://code.visualstudio.com/api/working-with-extensions/bundling-extension
+- **Limitaciones**: El entry point (`main` en package.json root) debe seguir apuntando al bundle final
+
+---
+
+## 4. APIs relevantes
+
+### npm CLI workspace commands
+| Comando | Descripción |
+|---------|-------------|
+| `npm install` | Instala deps de todos los workspaces automáticamente |
+| `npm run -w <name> <script>` | Ejecuta script en un workspace específico |
+| `npm run --ws <script>` | Ejecuta script en todos los workspaces |
+| `npm ls --ws` | Lista dependencias de workspaces |
+
+### package.json `workspaces` field
+```json
+{
+  "workspaces": [
+    "src/extension/modules/app",
+    "src/extension/modules/core",
+    "src/cli"
+  ]
+}
+```
+
+---
+
+## 5. Compatibilidad
+
+### Node.js / npm versions
+| Feature | Mínimo requerido | Actual en proyecto |
+|---------|:---:|:---:|
+| npm workspaces | npm 7+ / Node 16+ | Node 20+ (by engines) |
+| workspace: protocol | npm 9+ | Compatible |
+| TypeScript project references | TS 3.0+ | TS 5.9.3 |
+
+---
+
+## 6. Oportunidades detectadas
+- TypeScript project references podrían acelerar compilación incremental en monorepos
+- npm workspace symlinking automático elimina necesidad de `npm link` manual
+
+---
+
+## 7. Riesgos identificados
+
+| Riesgo | Severidad | Fuente |
+|--------|:---------:|--------|
+| `cli` importa `infrastructure` y `runtime` con rutas relativas `../../` — no son workspaces | Alta | Análisis de imports |
+| `extension.ts` importa `./modules/app/index.js` — ruta relativa que depende de la estructura de carpetas | Media | Código fuente |
+| Unit tests en app importan core con rutas relativas `../../../core/` | Media | Código fuente |
+| El `tsconfig.json` tiene `rootDir: ./src` — habrá que ajustar si cada package tiene su propio tsconfig | Alta | tsconfig.json |
+| VSCode extension main apunta a `./dist/extension/extension.js` — la ruta de output debe mantenerse | Alta | package.json |
+
+---
+
+## 8. Fuentes
+- [npm Workspaces](https://docs.npmjs.com/cli/v10/using-npm/workspaces)
+- [npm workspace: protocol](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
+- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)
+- [VSCode Extension Bundling](https://code.visualstudio.com/api/working-with-extensions/bundling-extension)
+- [Node.js Subpath Exports](https://nodejs.org/api/packages.html#subpath-exports)
+
+---
+
+## 9. Aprobacion del desarrollador (OBLIGATORIA)
+```yaml
+approval:
+  developer:
+    decision: SI
+    date: "2026-02-16T07:35:37+01:00"
+    comments: null
+```