agent-mp 0.5.19 → 0.5.21

package/dist/commands/repl.js

@@ -405,12 +405,15 @@ async function cmdSetup(rl) {
     await writeJson(path.join(projectDir, '.agent', 'config.json'), agentConfig);
     console.log(chalk.green('  .agent/config.json generated'));
     const templates = {
-        '.agent/INDEX.md': `# ${projectName} - Agent Entry Point\n\n## Navegacion por rol\n| Si sos... | Lee primero... |\n|-----------|----------------|\n| ORCHESTRATOR | .agent/rules/workflow.md |\n| IMPLEMENTOR | .agent/tasks/{ID}/plan.json |\n| REVIEWER | .agent/rules/workflow.md |\n`,
-        '.agent/rules/workflow.md': '# Agent Workflow Contract\n\n## REGLA #1 - Separacion de roles\nUn rol NUNCA ejecuta acciones de otro rol.\n\n## Roles\n- ORCHESTRATOR: planifica\n- IMPLEMENTOR: ejecuta\n- REVIEWER: valida\n',
-        '.agent/rules/structure.md': '# Estructura\n\n## Aprobados\n.\n\n## Prohibidos\nnode_modules, dist, .git\n',
-        '.agent/rules/patterns.md': '# Patrones\n\n- kebab-case: archivos\n- PascalCase: clases\n- camelCase: variables\n',
-        '.agent/context/architecture.md': '# Arquitectura - NIVEL 0\n\n| Servicio | Stack | Puerto | Detalle |\n|----------|-------|--------|---------|\n| - | - | - | - |\n',
-        '.agent/AGENT.md': '# Sub-Agentes\n\n1. Lee .agent/INDEX.md\n2. Lee .agent/rules/workflow.md\n3. Actua SOLO dentro de tu rol\n',
+        '.agent/INDEX.md': `# ${projectName} — Agent Entry Point\n\n> Leé este archivo antes de cualquier accion.\n\n## Proyecto\n${projectName}\n\n## Navegacion por rol\n| Si sos... | Lee primero... | Luego... |\n|-----------|----------------|----------|\n| ORCHESTRATOR | .agent/rules/workflow.md | .agent/rules/orchestrator.md |\n| IMPLEMENTOR | .agent/rules/implementor.md | .agent/tasks/{ID}/plan.json |\n| REVIEWER | .agent/rules/reviewer.md | .agent/rules/workflow.md |\n\n## Contexto del proyecto\n- Arquitectura: .agent/context/architecture.md\n- Stack: ver .agent/config.json\n`,
+        '.agent/rules/workflow.md': `# Workflow Contract — ${projectName}\n\n## Flujo general\n\`\`\`\n[ORCHESTRATOR] planifica → genera plan.json\n       ↓\n[IMPLEMENTOR] ejecuta el plan → modifica archivos\n       ↓\n[REVIEWER] valida → genera result.md\n\`\`\`\n\n## REGLA #1 — Separacion de roles\nCada CLI opera SOLO en su rol. Nunca ejecuta acciones de otro rol.\n\n## REGLA #2 — Orden estricto\nOrchestrator siempre primero. Implementor no actua sin plan. Reviewer no actua sin implementacion.\n\n## REGLA #3 — Sin inventar\nCada rol trabaja con los archivos reales del proyecto. No asume ni infiere sin leer.\n`,
+        '.agent/rules/orchestrator.md': `# Rol: ORCHESTRATOR — ${projectName}\n\n## Responsabilidad\nAnalizar el requerimiento, leer el contexto del proyecto y generar un plan de tareas claro y ejecutable.\n\n## Antes de planificar\n1. Leer .agent/context/architecture.md para entender los componentes\n2. Leer .agent/rules/structure.md para saber qué dirs son validos\n3. Leer .agent/rules/patterns.md para respetar convenciones del proyecto\n\n## Al generar el plan\n- Dividir el trabajo en pasos atomicos (1 paso = 1 cambio verificable)\n- Especificar rutas de archivos REALES (no genericas)\n- Indicar dependencias entre pasos si las hay\n\n## Prohibido\n- Modificar archivos de codigo directamente\n- Ejecutar comandos de build o test\n`,
+        '.agent/rules/implementor.md': `# Rol: IMPLEMENTOR — ${projectName}\n\n## Responsabilidad\nEjecutar el plan generado por el Orchestrator. Modificar archivos de codigo siguiendo las instrucciones exactas del plan.\n\n## Antes de implementar\n1. Leer .agent/tasks/{ID}/plan.json completo\n2. Leer .agent/rules/structure.md — no crear archivos en dirs prohibidos\n3. Leer .agent/rules/patterns.md — respetar convenciones\n\n## Al implementar\n- Seguir el plan paso a paso, en orden\n- No agregar cambios fuera del scope del plan\n- Marcar cada paso como completado al terminarlo\n\n## Prohibido\n- Modificar el plan\n- Hacer refactors no solicitados\n`,
+        '.agent/rules/reviewer.md': `# Rol: REVIEWER — ${projectName}\n\n## Responsabilidad\nValidar que la implementacion cumple el plan y respeta las reglas del proyecto.\n\n## Checklist de revision\n- [ ] Cada paso del plan fue implementado\n- [ ] No se modificaron archivos fuera del scope\n- [ ] Se respetan las convenciones de .agent/rules/patterns.md\n- [ ] La estructura cumple .agent/rules/structure.md\n- [ ] No hay codigo muerto ni imports sin usar\n\n## Al generar result.md\n- Indicar cada item como OK / FAIL / SKIP con razon\n- Si hay FAILs: describir exactamente que falta y en que archivo\n\n## Prohibido\n- Modificar archivos de codigo directamente\n- Aprobar implementaciones incompletas\n`,
+        '.agent/rules/structure.md': `# Estructura del proyecto — ${projectName}\n\n## Directorios aprobados\n- . (raiz del proyecto)\n\n## Directorios prohibidos\n- node_modules/\n- dist/\n- .git/\n- build/\n- target/\n- __pycache__/\n`,
+        '.agent/rules/patterns.md': `# Patrones y convenciones — ${projectName}\n\n## Nombrado\n- Archivos: kebab-case\n- Clases: PascalCase\n- Variables y funciones: camelCase\n- Constantes: UPPER_SNAKE_CASE\n\n## Reglas generales\n- No dejar console.log de debug en codigo productivo\n- Un archivo = una responsabilidad principal\n`,
+        '.agent/context/architecture.md': '# Arquitectura — NIVEL 0\n\n> Ejecuta `agent-mp explorer` para generar documentacion automatica.\n\n| Componente | Stack | Puerto | Proposito |\n|------------|-------|--------|-----------|\n| - | - | - | - |\n',
+        '.agent/AGENT.md': `# Instrucciones para Sub-Agentes — ${projectName}\n\n## Paso 1: Identificar tu rol\nLee .agent/INDEX.md para saber que archivo leer segun tu rol.\n\n## Paso 2: Leer el contexto\nAntes de cualquier accion, lee .agent/context/architecture.md.\n\n## Paso 3: Actua SOLO dentro de tu rol\nVer .agent/rules/workflow.md para las reglas de separacion de roles.\n`,
     };
     for (const [fp, content] of Object.entries(templates)) {
         await fs.mkdir(path.join(projectDir, path.dirname(fp)), { recursive: true });

package/dist/commands/setup.js

@@ -293,12 +293,15 @@ export function setupCommand(program) {
         console.log(chalk.green('  ✓ .agent/config.json generated'));
         // Generate templates
         const templates = {
-            '.agent/INDEX.md': `# ${projectName} — Agent Entry Point\n\n> Leé este archivo antes de cualquier accion.\n\n## Proyecto\n\n## Navegacion por rol\n| Si sos... | Lee primero... |\n|-----------|----------------|\n| ORCHESTRATOR | .agent/rules/workflow.md |\n| IMPLEMENTOR | .agent/tasks/{ID}/plan.json |\n| REVIEWER | .agent/rules/workflow.md |\n`,
-            '.agent/rules/workflow.md': '# Agent Workflow Contract\n\n## REGLA #1 — Separacion de roles\nUn rol NUNCA ejecuta acciones de otro rol.\n\n## REGLA #2 — Un CLI NO cambia de rol\n\n## Roles\n- ORCHESTRATOR: planifica, genera plan.json\n- IMPLEMENTOR: ejecuta el plan\n- REVIEWER: valida, genera result.md\n',
-            '.agent/rules/structure.md': '# Estructura\n\n## Aprobados\n.\n\n## Prohibidos\nnode_modules, dist, .git\n',
-            '.agent/rules/patterns.md': '# Patrones\n\n- kebab-case para archivos\n- PascalCase para clases\n- camelCase para variables\n',
-            '.agent/context/architecture.md': '# Arquitectura — NIVEL 0\n\n| Servicio | Stack | Puerto | Detalle |\n|----------|-------|--------|---------|\n| - | - | - | - |\n',
-            '.agent/AGENT.md': '# Sub-Agentes\n\n1. Lee .agent/INDEX.md\n2. Lee .agent/rules/workflow.md\n3. Actua SOLO dentro de tu rol\n',
+            '.agent/INDEX.md': `# ${projectName} — Agent Entry Point\n\n> Leé este archivo antes de cualquier accion.\n\n## Proyecto\n${projectName}\n\n## Navegacion por rol\n| Si sos... | Lee primero... | Luego... |\n|-----------|----------------|----------|\n| ORCHESTRATOR | .agent/rules/workflow.md | .agent/rules/orchestrator.md |\n| IMPLEMENTOR | .agent/rules/implementor.md | .agent/tasks/{ID}/plan.json |\n| REVIEWER | .agent/rules/reviewer.md | .agent/rules/workflow.md |\n\n## Contexto del proyecto\n- Arquitectura: .agent/context/architecture.md\n- Stack: ver .agent/config.json\n`,
+            '.agent/rules/workflow.md': `# Workflow Contract — ${projectName}\n\n## Flujo general\n\`\`\`\n[ORCHESTRATOR] planifica → genera plan.json\n       ↓\n[IMPLEMENTOR] ejecuta el plan → modifica archivos\n       ↓\n[REVIEWER] valida → genera result.md\n\`\`\`\n\n## REGLA #1 — Separacion de roles\nCada CLI opera SOLO en su rol. Nunca ejecuta acciones de otro rol.\n\n## REGLA #2 — Orden estricto\nOrchestrator siempre primero. Implementor no actua sin plan. Reviewer no actua sin implementacion.\n\n## REGLA #3 — Sin inventar\nCada rol trabaja con los archivos reales del proyecto. No asume ni infiere sin leer.\n\n## REGLA #4 — Escalada\nSi un rol encuentra un bloqueante, lo reporta. No lo omite ni lo parchea silenciosamente.\n`,
+            '.agent/rules/orchestrator.md': `# Rol: ORCHESTRATOR — ${projectName}\n\n## Responsabilidad\nAnalizar el requerimiento, leer el contexto del proyecto y generar un plan de tareas claro y ejecutable.\n\n## Antes de planificar\n1. Leer .agent/context/architecture.md para entender los componentes\n2. Leer .agent/rules/structure.md para saber qué dirs son validos\n3. Leer .agent/rules/patterns.md para respetar convenciones del proyecto\n\n## Al generar el plan\n- Dividir el trabajo en pasos atómicos (1 paso = 1 cambio verificable)\n- Especificar rutas de archivos REALES (no genéricas)\n- Indicar dependencias entre pasos si las hay\n- Estimar impacto: qué puede romperse con cada cambio\n\n## Prohibido\n- Modificar archivos de código directamente\n- Ejecutar comandos de build o test\n- Tomar decisiones de arquitectura sin documentarlas en el plan\n`,
+            '.agent/rules/implementor.md': `# Rol: IMPLEMENTOR — ${projectName}\n\n## Responsabilidad\nEjecutar el plan generado por el Orchestrator. Modificar archivos de código siguiendo las instrucciones exactas del plan.\n\n## Antes de implementar\n1. Leer .agent/tasks/{ID}/plan.json completo\n2. Leer .agent/rules/structure.md — no crear archivos en dirs prohibidos\n3. Leer .agent/rules/patterns.md — respetar convenciones de nombres y estructura\n\n## Al implementar\n- Seguir el plan paso a paso, en orden\n- Si un paso no es claro, documentar la ambigüedad, no improvisar\n- Marcar cada paso como completado al terminarlo\n- No agregar cambios fuera del scope del plan\n\n## Prohibido\n- Modificar el plan (eso es rol del Orchestrator)\n- Hacer refactors no solicitados\n- Ignorar pasos del plan aunque parezcan redundantes\n`,
+            '.agent/rules/reviewer.md': `# Rol: REVIEWER — ${projectName}\n\n## Responsabilidad\nValidar que la implementacion cumple el plan, no rompe nada existente y respeta las reglas del proyecto.\n\n## Checklist de revision\n- [ ] Cada paso del plan fue implementado\n- [ ] No se modificaron archivos fuera del scope del plan\n- [ ] Se respetan las convenciones de .agent/rules/patterns.md\n- [ ] La estructura de dirs cumple .agent/rules/structure.md\n- [ ] No hay codigo muerto ni imports sin usar introducidos\n- [ ] Si hay tests, pasaron\n\n## Al generar result.md\n- Indicar cada item del checklist como OK / FAIL / SKIP con razon\n- Si hay FAILs: describir exactamente qué falta y en qué archivo\n- Si todo OK: marcar la tarea como DONE\n\n## Prohibido\n- Modificar archivos de código directamente\n- Aprobar implementaciones incompletas\n- Omitir items del checklist\n`,
+            '.agent/rules/structure.md': `# Estructura del proyecto — ${projectName}\n\n## Directorios aprobados\n- . (raiz del proyecto)\n\n## Directorios prohibidos (no crear ni modificar archivos aca)\n- node_modules/\n- dist/\n- .git/\n- build/\n- target/\n- __pycache__/\n- .venv/\n\n## Convenciones de ubicacion\n- Codigo fuente: src/\n- Tests: src/**/*.test.* o tests/\n- Config: raiz del componente\n- Scripts: scripts/\n`,
+            '.agent/rules/patterns.md': `# Patrones y convenciones — ${projectName}\n\n## Nombrado\n- Archivos: kebab-case (mi-archivo.ts)\n- Clases: PascalCase (MiClase)\n- Variables y funciones: camelCase (miVariable)\n- Constantes: UPPER_SNAKE_CASE (MI_CONSTANTE)\n\n## Estructura de commits\n- feat: nueva funcionalidad\n- fix: correccion de bug\n- chore: tareas de mantenimiento\n- docs: solo documentacion\n\n## Reglas generales\n- No dejar console.log / print de debug en código productivo\n- Un archivo = una responsabilidad principal\n- Preferir cambios pequeños y verificables sobre refactors grandes\n`,
+            '.agent/context/architecture.md': '# Arquitectura — NIVEL 0\n\n> Ejecuta `agent-mp explorer` para generar documentacion automatica.\n\n| Componente | Stack | Puerto | Proposito |\n|------------|-------|--------|-----------|\n| - | - | - | - |\n',
+            '.agent/AGENT.md': `# Instrucciones para Sub-Agentes — ${projectName}\n\n## Paso 1: Identificar tu rol\nLee .agent/INDEX.md para saber que archivo leer segun tu rol.\n\n## Paso 2: Leer el contexto\nAntes de cualquier accion, lee .agent/context/architecture.md.\n\n## Paso 3: Actua SOLO dentro de tu rol\nVer .agent/rules/workflow.md para las reglas de separacion de roles.\n`,
         };
         for (const [fp, content] of Object.entries(templates)) {
             await fs.mkdir(path.join(projectDir, path.dirname(fp)), { recursive: true });

package/dist/core/engine.js

@@ -1194,9 +1194,29 @@ INSTRUCCIONES:
         const agentDir = path.join(this.projectDir, '.agent');
         const contextDir = path.join(agentDir, 'context');
         const docsDir = path.join(agentDir, 'docs');
+        const rulesDir = path.join(agentDir, 'rules');
         await fs.mkdir(contextDir, { recursive: true });
         await fs.mkdir(docsDir, { recursive: true });
-        await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
+        await fs.mkdir(rulesDir, { recursive: true });
+        // Seed rules files if they don't exist yet (idempotent — never overwrites)
+        const proj = this.config.project;
+        const rulesSeeds = {
+            'workflow.md': `# Workflow Contract — ${proj}\n\n\`\`\`\n[ORCHESTRATOR] planifica → genera plan.json\n       ↓\n[IMPLEMENTOR] ejecuta el plan → modifica archivos\n       ↓\n[REVIEWER] valida → genera result.md\n\`\`\`\n\n## REGLA #1 — Separacion de roles\nCada CLI opera SOLO en su rol.\n\n## REGLA #2 — Orden estricto\nOrchestrator primero. Implementor no actua sin plan. Reviewer no actua sin implementacion.\n\n## REGLA #3 — Sin inventar\nCada rol trabaja con los archivos reales del proyecto.\n`,
+            'orchestrator.md': `# Rol: ORCHESTRATOR — ${proj}\n\n## Responsabilidad\nAnalizar el requerimiento, leer el contexto y generar un plan de tareas ejecutable.\n\n## Antes de planificar\n1. Leer .agent/context/architecture.md\n2. Leer .agent/rules/structure.md\n3. Leer .agent/rules/patterns.md\n\n## Al generar el plan\n- Pasos atomicos (1 paso = 1 cambio verificable)\n- Rutas de archivos REALES\n- Dependencias entre pasos si las hay\n\n## Prohibido\n- Modificar archivos de codigo directamente\n- Ejecutar comandos de build o test\n`,
+            'implementor.md': `# Rol: IMPLEMENTOR — ${proj}\n\n## Responsabilidad\nEjecutar el plan del Orchestrator. Modificar archivos de codigo siguiendo las instrucciones exactas.\n\n## Antes de implementar\n1. Leer .agent/tasks/{ID}/plan.json completo\n2. Leer .agent/rules/structure.md\n3. Leer .agent/rules/patterns.md\n\n## Al implementar\n- Seguir el plan paso a paso, en orden\n- No agregar cambios fuera del scope\n- Marcar cada paso como completado\n\n## Prohibido\n- Modificar el plan\n- Hacer refactors no solicitados\n`,
+            'reviewer.md': `# Rol: REVIEWER — ${proj}\n\n## Responsabilidad\nValidar que la implementacion cumple el plan y respeta las reglas del proyecto.\n\n## Checklist\n- [ ] Cada paso del plan fue implementado\n- [ ] Sin archivos modificados fuera del scope\n- [ ] Convenciones de patterns.md respetadas\n- [ ] Estructura de structure.md respetada\n- [ ] Sin codigo muerto ni imports sin usar\n\n## Al generar result.md\n- Indicar cada item: OK / FAIL / SKIP con razon\n- Si FAILs: describir qué falta y en qué archivo\n\n## Prohibido\n- Modificar archivos de codigo\n- Aprobar implementaciones incompletas\n`,
+            'structure.md': `# Estructura — ${proj}\n\n## Directorios aprobados\n- . (raiz del proyecto)\n\n## Prohibidos\n- node_modules/, dist/, .git/, build/, target/, __pycache__/, .venv/\n`,
+            'patterns.md': `# Patrones — ${proj}\n\n## Nombrado\n- Archivos: kebab-case\n- Clases: PascalCase\n- Variables/funciones: camelCase\n- Constantes: UPPER_SNAKE_CASE\n\n## Reglas generales\n- Sin console.log de debug en produccion\n- Un archivo = una responsabilidad principal\n`,
+        };
+        for (const [name, content] of Object.entries(rulesSeeds)) {
+            const fp = path.join(rulesDir, name);
+            try {
+                await fs.access(fp);
+            }
+            catch {
+                await writeFile(fp, content);
+            } // only create if missing
+        }
         // NOTE: cleanup of stray files moved to AFTER successful parse, to avoid
         // wiping previous docs when the explorer fails (e.g. tool-call hallucination).
         // Build a quick filesystem snapshot to give the explorer context
@@ -1513,73 +1533,6 @@ QUE NO HACER
 - NO documentar componentes triviales (scripts, docs, configs sueltas) con su propia carpeta — mencionalos en NIVEL 0 y listo
 - NO inventar endpoints, env vars, puertos o schemas que no leiste
 
-================================================================
-DIRECTORIO .agent/docs/ — FLUJOS POR FUNCIONALIDAD (orientado a desarrolladores)
-================================================================
-Ademas de los archivos de context/, generar docs de flujos. Objetivo: un dev que llega al proyecto puede buscar "como funciona el login" o "donde esta el endpoint de clientes" y encontrar exactamente que archivos tocar, en que orden, y por que.
-
-Generar UN archivo por cada flujo funcional principal que puedas identificar de los CONTROLLER/ROUTER leidos.
-Si no hay controllers, inferir los flujos desde el MANIFEST y el ENTRY POINT.
-
-INDICE OBLIGATORIO:
-=== .agent/docs/README.md ===
-# Flujos del proyecto — Indice
-
-| Flujo | Descripcion | Componente(s) |
-|-------|-------------|---------------|
-| [nombre-flujo](nombre-flujo.md) | 1 linea que explica que hace | componente-a, componente-b |
-...
-
-POR CADA FLUJO:
-=== .agent/docs/[nombre-flujo].md ===
-Nombre del archivo: kebab-case del nombre del flujo (auth.md, crear-cliente.md, consulta-ventas.md)
-
-Estructura de cada archivo de flujo:
-
-# Flujo: [Nombre legible]
-
-## Qué hace
-1 linea en lenguaje de negocio: "Permite al usuario X hacer Y"
-
-## Componentes involucrados
-- [componente-a]: rol en este flujo
-- [componente-b]: rol en este flujo
-
-## Traza técnica paso a paso
-Numberar cada paso. Incluir archivo y funcion/clase cuando fue leido.
-1. Cliente/Frontend → METODO /ruta/endpoint (archivo: ruta/al/Controller)
-2. Middleware/Guard/Filter valida/transforma (archivo: ruta/al/Filter o Config)
-3. Service/UseCase ejecuta la logica (archivo: ruta/al/Service)
-4. Repository/DAO consulta o escribe en DB (archivo: ruta/al/Repository → tabla o coleccion)
-5. Respuesta: codigo HTTP + shape de respuesta
-
-## Archivos involucrados y por qué
-Esta tabla es lo mas importante para un dev nuevo: tiene que saber QUE archivo y POR QUE esta en el flujo.
-| Archivo (ruta relativa al componente) | Por que esta en este flujo |
-|---------------------------------------|---------------------------|
-| ruta/Controller | Recibe el request y delega |
-| ruta/Service | Contiene la logica de negocio |
-| ruta/Repository | Lee o escribe en la base de datos |
-| ruta/Entity o Schema | Define la forma del dato |
-| ruta/Config o Filter | Aplica seguridad / transformacion |
-
-## Variables / configuracion relevante
-Solo las que afectan directamente este flujo (env vars, properties, feature flags).
-
-## Como probar este flujo
-- Endpoint: METODO /ruta
-- Body o params de ejemplo
-- Respuesta exitosa: codigo + campos
-- Errores comunes: codigo + cuando ocurre
-
-================================================================
-CALIBRACION DE DETALLE — docs/
-================================================================
-- README.md: una fila por flujo, no mas
-- Por flujo: 30-80 lineas. Concreto. Si un paso no fue leido, omitirlo.
-- NO inventar nombres de archivos. Si no se leyo un Service para este flujo, no lo pongas.
-- Generar entre 2 y 8 flujos segun la cantidad de controllers/features encontrados.
-
 ================================================================
 FORMATO DE SALIDA — OBLIGATORIO
 ================================================================
@@ -1591,9 +1544,8 @@ Ejemplos de marcadores validos:
   === .agent/context/architecture.md ===
   === .agent/context/datamart-data-access-api/architecture.md ===
   === .agent/context/datamart-data-access-api/modules/auth.md ===
-  === .agent/docs/README.md ===
-  === .agent/docs/auth.md ===
-  === .agent/docs/consulta-ventas.md ===
+  === .agent/context/nexus-core-api/architecture.md ===
+  === .agent/context/nexus-core-api/modules/clients.md ===
 
 === .agent/context/architecture.md ===
 [contenido NIVEL 0]
@@ -1604,19 +1556,12 @@ Ejemplos de marcadores validos:
 === .agent/context/nombre-componente/modules/auth.md ===
 [contenido NIVEL 2]
 
-=== .agent/docs/README.md ===
-[indice de flujos]
-
-=== .agent/docs/auth.md ===
-[flujo de autenticacion]
-
 REGLAS DE PATHS:
 - Arquitectura global: === .agent/context/architecture.md ===
 - Por componente: === .agent/context/[nombre-componente]/architecture.md ===
 - Por modulo interno: === .agent/context/[nombre-componente]/modules/[nombre-modulo].md ===
-- Indice de flujos: === .agent/docs/README.md ===
-- Por flujo: === .agent/docs/[nombre-flujo].md ===
 - Documenta TODOS los componentes no triviales del DIRECTORIO_TRABAJO
+- NO escribir nada bajo .agent/docs/ — esa carpeta es de uso manual
 - Si existe documentacion previa, ACTUALIZALA preservando lo que sigue siendo valido y agregando lo nuevo`;
         const res = await this.runWithFallback('explorer', prompt, 'Exploracion');
         const text = extractCliText(res);
@@ -1646,36 +1591,24 @@ REGLAS DE PATHS:
             content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
             if (!content)
                 continue;
-            // Detect routing: .agent/docs/ → docsDir, .agent/context/ → contextDir
-            const isDocsFile = /^\.agent[\/\\]docs[\/\\]/i.test(fileName);
+            // All explorer output goes under .agent/context/ — docs/ is manual-only
+            const relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
             let targetPath = null;
-            if (isDocsFile) {
-                // .agent/docs/README.md → docsDir/README.md
-                // .agent/docs/auth.md  → docsDir/auth.md
-                const docsRel = fileName.replace(/^\.agent[\/\\]docs[\/\\]/i, '').replace(/^\/+/, '');
-                if (docsRel && docsRel.endsWith('.md')) {
-                    targetPath = path.join(docsDir, ...docsRel.split(/[\/\\]/).filter(Boolean));
-                }
+            if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
+                targetPath = mainArchPath;
             }
             else {
-                // .agent/context/ files (existing behaviour)
-                const relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
-                if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
-                    targetPath = mainArchPath;
+                const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
+                if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
                 }
-                else {
-                    const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
-                    if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
-                        targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
-                    }
-                    else if (pathParts.length >= 2) {
-                        targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
-                    }
+                else if (pathParts.length >= 2) {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
                 }
             }
             if (!targetPath)
                 continue;
-            pendingWrites.push({ targetPath, content, label: fileName.trim() });
+            pendingWrites.push({ targetPath, content, label: relPath });
         }
         if (pendingWrites.length === 0) {
             log.error('Explorer devolvio texto pero ningun bloque === *.md === fue parseable.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mp",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "Deterministic multi-agent CLI orchestrator — plan, code, review",
   "type": "module",
   "main": "./dist/index.js",