LAZWORK

Tu agente piensa. LAZWORK ejecuta, valida y entrega.

Motor de ejecución para AI coding agents. Pipeline cognitivo de 6 agentes, codegen con validación real (tsc), fix loop automático, y delivery directo a PR.

Úsalo como CLI standalone o como MCP server para potenciar tu agente favorito (VS Code Copilot, Claude Code, OpenCode, Cursor).

Quick Start

CLI standalone

npm install -g lazwork
lazwork

Como MCP server (VS Code Copilot, Claude Code, OpenCode, Cursor)

npm install -g lazwork
lazwork serve              # MCP server stdio (VS Code Copilot, Claude Code, Cursor...)
lazwork serve --transport http --port 3100  # MCP server HTTP (uso remoto/Docker)

Cómo funciona

tu pedido
    └── ThinkingAgent    → define el problema, detecta riesgos
            └── CriticAgent    → cuestiona supuestos, detecta overengineering
                    └── DecisionAgent  → elige el camino óptimo
                            └── ArchitectAgent → diseña la estructura (Clean Arch)
                                    └── ExecutionAgent → genera el plan de tareas
                                            └── CodegenAgent → escribe el código
                                                    └── Verify → tsc real sobre el código generado
                                                            └── Fix loop → corrige hasta que compila
                                                                    └── PR → branch + commit + PR automático

Cada fase produce artefactos legibles en .lazwork/plans/:
explore.md → design.md → tasks.md → verify.md

Por qué LAZWORK

• Pipeline cognitivo propio — no depende de un solo prompt gigante; cada agente razona con sus propias reglas
• Verificación real — ejecuta tsc sobre el código generado, no simula el chequeo
• Fix loop — detecta errores de compilación y los corrige automáticamente antes de crear el PR
• Git delivery — branch → commit → push → PR, sin intervención manual
• MCP server — lazwork serve lo expone como backend para VS Code Copilot, Claude Code, Cursor, OpenCode
• Context7 — consulta docs actualizadas de librerías antes de generar; elimina alucinaciones de API
• TDD mode — el CodegenAgent genera tests antes de la implementación (tddMode: true)
• Watch mode — lazwork watch monitorea el proyecto y sugiere acciones en tiempo real
• Memoria persistente — Engram recuerda contexto entre sesiones
• Packs de reglas — cambiá el comportamiento de todos los agentes con un comando (/pack python)
• 243 tests — el proyecto se mantiene con cobertura real

Instalación

npm install -g lazwork
# o con pnpm
pnpm add -g lazwork

Desarrollo local

git clone <repo-url>
cd lazwork-agent-sys
pnpm install
pnpm start        # REPL interactivo con tsx (sin compilar)
pnpm start:stub   # REPL con LLM stub (sin API key)
pnpm build        # Compila a dist/ con tsup
pnpm test         # Corre los tests (243 tests)
pnpm type-check   # Chequeo de tipos sin compilar

Uso desde línea de comandos

# — Sesión interactiva
lazwork                          # REPL interactivo
lazwork --version                # Mostrar versión
lazwork --help                   # Mostrar ayuda

# — Setup del proyecto
lazwork init                     # Inicializar LAZWORK en el proyecto actual
lazwork init-mcp <agent>         # Configurar MCP (vscode|claude|cursor|opencode)

# — MCP server
lazwork serve                    # MCP server stdio (VS Code Copilot, Claude Code...)
lazwork serve --transport http [--port N]          # MCP server HTTP (default: 3100)
lazwork serve --transport http --host 0.0.0.0       # Exponer en todas las interfaces

# — Herramientas
lazwork doctor                   # Health check del entorno
lazwork watch [<path>]           # Watch mode: monitorea cambios y sugiere acciones
lazwork config                   # Wizard de configuración (seccional)
lazwork config --reset           # Resetear toda la config
lazwork sync                     # Sincronizar memorias Engram a Git

# — Skills
lazwork skills list              # Listar skills instalados
lazwork skills add <nombre>      # Instalar skill desde el registry
lazwork skills search <query>    # Buscar en el registry
lazwork skills create            # Crear skill custom interactivo

MCP Server — Integración con agentes

LAZWORK expone su pipeline como MCP server. VS Code Copilot, Claude Code, Cursor y OpenCode pueden invocar el pipeline completo como si fuera una tool nativa — sin instalar nada adicional.

Paso 1 — Generar la config (una sola vez por proyecto)

lazwork init-mcp vscode     # VS Code Copilot
lazwork init-mcp claude     # Claude Code
lazwork init-mcp cursor     # Cursor
lazwork init-mcp opencode   # OpenCode

Cada comando escribe el archivo de configuración MCP correspondiente. Para VS Code genera .vscode/mcp.json:

{
  "servers": {
    "lazwork": {
      "command": "lazwork",
      "args": ["serve"]
    }
  }
}

Si prefieres configurarlo a mano, el formato es idéntico para todos los agentes que usan MCP stdio.

Paso 2 — Recargar VS Code

VS Code detecta el archivo automáticamente al crear o modificar .vscode/mcp.json.

Ctrl+Shift+P → "Developer: Reload Window"

No necesitas correr lazwork serve manualmente. VS Code lo arranca como subprocess en background cada vez que necesita invocar una tool.

Paso 3 — Verificar que está conectado

Ctrl+Shift+P → "MCP: List Servers"

Debe aparecer lazwork con estado running. Si aparece stopped o no aparece:

1. Verifica que lazwork está en el PATH: lazwork --version
2. Revisa .vscode/mcp.json — debe existir y tener el formato correcto
3. Reload Window de nuevo

También puedes verlo en el panel de Chat de VS Code: en el input del chat, el icono de tools (⚙) lista todas las tools disponibles — busca lazwork_run, lazwork_plan, lazwork_verify.

Paso 4 — Usar desde el chat

Abre GitHub Copilot Chat en modo Agent (@workspace o modo agente implícito) y pide naturalmente:

"implementa autenticación JWT en este proyecto"
"añade tests para el módulo de usuarios"
"refactoriza src/api/auth.ts para separar capas"

Copilot detecta la intención, invoca lazwork_run automáticamente y muestra el progreso del pipeline en el chat.

Para invocar una tool explícitamente, usa el selector de tools en el input:

Escribe # en el input → selecciona lazwork_run → completa los parámetros

Tools disponibles

| Tool | Cuándo la usa el agente | Parámetros clave | | ---------------- | ------------------------------------------------------ | ------------------------------------ | | lazwork_run | Cuando pides implementar algo (feature, fix, refactor) | task, projectRoot, changeSize? | | lazwork_plan | Cuando pides planificar sin escribir código | task, projectRoot | | lazwork_verify | Cuando pides verificar o encontrar errores | projectRoot, files? |

Ejemplo de respuesta de lazwork_run:

{
  "decision": "Implementar JWT con [email protected] usando middleware de Express",
  "files": [
    { "path": "src/auth/jwt.ts", "action": "create" },
    { "path": "src/auth/middleware.ts", "action": "create" }
  ],
  "verify": { "status": "pass", "initialErrors": 3, "finalErrors": 0 },
  "prUrl": "https://github.com/usuario/repo/pull/42"
}

Modo HTTP — uso remoto o Docker

Para equipos que comparten un servidor LAZWORK o lo corren en contenedor:

# En el servidor
lazwork serve --transport http --port 3100
lazwork serve --transport http --host 0.0.0.0 --port 3100  # expuesto en red

Config del cliente (.vscode/mcp.json):

{
  "servers": {
    "lazwork": {
      "url": "http://tu-servidor:3100/mcp"
    }
  }
}

lazwork init — Setup de proyecto

lazwork init

Detecta el stack del proyecto y configura todo en un paso:

• Detecta: Next.js, Express, Fastify, NestJS, React SPA, Python/FastAPI, Go
• Sugiere e instala skills relevantes desde el registry
• Configura el pack de reglas activo (frontend / backend-node / python / devops)
• Genera .lazwork/config.json con preferencias detectadas

lazwork doctor — Health check

lazwork doctor

✓ Node.js 22.x
✓ tsc disponible (TypeScript 5.9.3)
✓ git configurado
✓ gh CLI disponible
✓ Context7: ● npm registry accesible
✓ LLM provider: github-copilot (claude-sonnet-4-6)
⚠ Engram: no corriendo en puerto 7437

Verifica Node.js, tsc, git, gh CLI, Context7, LLM provider y Engram antes de que el pipeline falle.

lazwork skills — Gestión de skills

Skills = archivos SKILL.md que amplían el conocimiento del CodegenAgent sobre librerías y patrones del proyecto.

lazwork skills list                  # lista skills en ~/.lazwork/skills/
lazwork skills add nextjs-15         # instala desde el registry público
lazwork skills search react          # busca por nombre y tags
lazwork skills create                # TUI para crear un skill custom

$ lazwork skills search react
  react-19        React 19 patterns (hooks, RSC, transitions)    ★ curated
  react-testing   Testing patterns for React components          ★ curated
  tailwind-4      Tailwind CSS v4 utility patterns               ★ curated

Los skills se sincronizan entre máquinas con lazwork sync.

lazwork watch — Watch Mode

lazwork watch              # monitorea el directorio actual
lazwork watch src/         # monitorea una ruta específica

Monitorea .ts/.tsx y sugiere acciones sin interrumpir el flujo. Debounce 400ms. Ignora node_modules/, .git/, dist/, build/.

| Evento | Sugerencia | | ------------------------------- | ----------------------------------------------------------- | | Archivo guardado con errores TS | Preview de errores + lazwork "fix TS errors in <archivo>" | | Directorio vacío creado | lazwork "implement module <directorio>" | | Archivo .test.ts modificado | lazwork doctor o lazwork "fix failing tests" |

Primera ejecución — Wizard de onboarding

Al ejecutar lazwork por primera vez, se lanza el wizard TUI que configura todo:

 🧠 LAZWORK AGENT SYS — Primera Configuración

◆ Selecciona tu proveedor LLM
  ● GitHub Copilot    (usa tu cuenta de GitHub)
  ○ OpenAI            (GPT-4o, o3-mini, etc.)
  ○ Stub (modo dev)   (sin API key)

◆ GitHub Personal Access Token
  ghp_...

◆ Modelo a usar
  ● Claude Sonnet 4.6  (recomendado)
  ○ Claude Opus 4.6
  ○ GPT-5.4
  ○ Gemini 3.1 Pro
  ...

◆ Memoria de trabajo (Engram)
  ● Local — guarda en esta máquina
  ○ Local + Sync a Git — guarda localmente y sincroniza a un repo
  ○ Deshabilitado

La config se guarda en ~/.lazwork/config.json y se reutiliza en todas las sesiones.

Sesión REPL interactiva

Flujo de conversación

LAZWORK usa el LLM para decidir automáticamente si responder en modo chat o activar el pipeline cognitivo. No necesitás usar comandos especiales:

› de qué va este proyecto?
  → respuesta conversacional con contexto del repo

› qué stack usa?
  → respuesta informativa directa

› analicemos cómo mejorar la arquitectura
  → hace preguntas para entender mejor la idea

› agrega autenticación JWT al backend
  → activa el pipeline cognitivo automáticamente

Para forzar el pipeline explícitamente: escribe hazlo, dale, go, ejecuta, arranca, procede o listo.

Pipeline activo — ejemplo completo

Cuando el pipeline se activa, los agentes corren en secuencia y el executor abre el PR automáticamente:

 🧠 LAZWORK — Sesión iniciada
Proveedor: github-copilot | Engram: local-both

› Necesito agregar autenticación a mi Next.js app

  ⠸ ThinkingAgent — analizando el problema...
  ⠸ CriticAgent — revisando supuestos...
  ⠸ DecisionAgent — eligiendo el mejor camino...
  ⠸ ArchitectAgent — estructurando la solución...
  ⠸ ExecutionAgent — planificando ejecución...
  ⠸ CodegenAgent — generando código...
  ⠸ CodeValidator — validando (tsc, eslint, runtime)...
  ⠸ CodegenAgent — corrigiendo causa raíz (fix loop)...

┌─ Resultado ──────────────────────────────────────────────────┐
│ Decisión:     Implementar NextAuth.js con App Router         │
│ Razonamiento: Menor complejidad, soporte nativo Server Actions│
│ Prioridad:    high                                           │
│ Patrones:     Feature-Sliced Design, Repository Pattern      │
└──────────────────────────────────────────────────────────────┘

┌─ Plan de Ejecución ──────────────────────────────────────────┐
│ Tareas:                                                      │
│   • Instalar NextAuth.js v5                                  │
│   • Crear feature/auth con estructura limpia                 │
│   • Configurar providers y callbacks                         │
│   ...                                                        │
└──────────────────────────────────────────────────────────────┘

✔ Plan guardado en .lazwork/plans/instalar-nextauth-js-v5.md
✔ Rama creada: feat/instalar-nextauth-js-v5
✔ Commit: "feat: Instalar NextAuth.js v5"
✔ PR creado: https://github.com/<usuario>/<repo>/pull/42

  ⬡ tokens sesión: ~6,800 / 200k (3% del contexto)

Si el proyecto no tiene git configurado, el executor guarda el plan en .lazwork/plans/ y muestra instrucciones para conectar el repositorio.

Contador de tokens

Después de cada respuesta del LLM se muestra el uso estimado de contexto:

  ⬡ tokens sesión: ~4,200 / 200k (2% del contexto)

Comandos dentro de la sesión

| Comando | Acción | | ----------------- | ------------------------------------------------------------- | | /project [ruta] | Carga un repositorio como contexto activo | | /pack [nombre] | Ver o cambiar el pack de reglas activo | | /agents | Ver los 6 agentes del pipeline y sus modelos | | /usage | Ver consumo detallado de tokens y cuota del LLM | | /config | Abre el wizard de configuración sin salir | | /sync | Sincroniza memorias Engram + skills + packs + subagents a Git | | /help | Muestra todos los comandos disponibles | | /clear | Limpia el historial de chat y contexto de sesión | | /exit | Sale de la sesión |

/project — Contexto del repositorio

/project                          # carga el directorio actual
/project C:\repos\mi-app          # carga una ruta específica
/project /home/user/projects/api  # ruta absoluta en Linux/Mac

Una vez cargado, el LLM conoce la estructura completa del repo (hasta 4 niveles de profundidad, ignora node_modules, .git, dist, etc.) y el package.json. Puede responder preguntas sobre él y el pipeline recibirá ese contexto para planificar tareas.

/pack — Packs de reglas

/pack                   # muestra el pack activo
/pack python            # cambia al pack python en caliente
/pack mi-pack-custom    # activa un pack personalizado tuyo

Configuración desde el wizard (/config)

El wizard permite modificar secciones individuales sin reiniciar la sesión:

| Sección | Qué configura | | --------------------------- | -------------------------------------------------- | | Proveedor LLM | GitHub Copilot / OpenAI / Stub | | Cambiar modelo | Muestra solo los modelos habilitados en tu cuenta | | Memoria de trabajo | Modo Engram: local / local+sync / deshabilitado | | Pack de reglas activo | Selector visual de packs built-in y personalizados | | Modelos por agente | Override de modelo para cada agente del pipeline | | TDD Mode | Fuerza generación de tests antes de implementación | | Resetear toda la config | Vuelve al wizard completo de onboarding |

Sistema de Packs — Reglas y comportamiento

Los packs definen las reglas de razonamiento que usan los agentes. Se cambian sin tocar código.

Packs built-in incluidos

| Pack | Especialidad | | ---------------------- | ------------------------------------------------------------- | | frontend (default) | React, Next.js App Router, componentes, hooks, feature-sliced | | backend-node | Express/NestJS/Fastify, capas, repositories, seguridad | | python | FastAPI/Django, type hints, async, arquitectura por dominio | | devops | CI/CD, IaC, contenedores Docker/K8s, observabilidad |

Crear tu propio pack

~/.lazwork/packs/mi-pack/
  pack.json           ← nombre, descripción, autor
  rules/
    thinking.rules.md
    architecture.rules.md
    code-quality.rules.md
    next.rules.md       ← opcional, solo si aplica

pack.json mínimo:

{
  "name": "mi-pack",
  "label": "Mi Pack Personalizado",
  "description": "Reglas para mi stack específico",
  "author": "tu-nombre"
}

Las reglas son archivos Markdown con bullets. Ejemplo thinking.rules.md:

# Thinking Rules — Mi Pack

- Priorizar la consistencia de datos antes que la velocidad de entrega
- Diseñar contratos de API antes de implementar
- Validar en el borde del sistema, no en funciones internas

Una vez creado aparece automáticamente en /config → Pack de reglas activo y con /pack mi-pack.

Jerarquía de carga de reglas

1. ~/.lazwork/packs/<pack-activo>/rules/   ← tus packs personalizados (máxima prioridad)
2. core/packs/<pack-activo>/rules/          ← packs built-in con ese nombre
3. core/packs/frontend/rules/              ← fallback al pack frontend
4. core/rules/                             ← fallback legacy

Los packs y skills viajan entre máquinas

~/.lazwork/ se sincroniza con tu repo Git vía Engram Sync (/sync o lazwork sync). Tus packs personalizados y tus skills mejorados viajan automáticamente:

lazwork sync   → empuja ~/.lazwork/packs/ + ~/.lazwork/skills/ + ~/.lazwork/subagents/ + memorias Engram
lazwork sync   → en otra máquina, restaura todo al instalar y sincronizar

En el primer arranque (tras npm install -g lazwork), los skills, skill-registry y subagent definitions por defecto se copian automáticamente a ~/.lazwork/. El usuario los personaliza ahí — nunca se sobreescriben en actualizaciones posteriores.

Modelos por agente

Cada agente del pipeline puede usar un modelo diferente. Útil para optimizar costo/calidad:

/config → Modelos por agente

◆ ¿Qué agentes quieres configurar?
  ☑ ThinkingAgent     gpt-4o
  ☑ CriticAgent       ↓ global (claude-sonnet-4-6)
  ☐ DecisionAgent
  ☐ ArchitectAgent
  ☑ ExecutionAgent    gpt-4o-mini

Solo se modifica lo que seleccionás. Los no seleccionados heredan el modelo global del proveedor.

Ver configuración actual:

/agents

Memoria persistente (Engram)

Engram aprende de cada sesión y usa ese contexto en la siguiente. Se configura en el wizard.

| Modo | Comportamiento | | ------------------- | ----------------------------------------------------- | | local (default) | Guarda en ~/.lazwork/engram/ en esta máquina | | local-sync | Igual que local, pero /sync lo empuja a tu repo Git | | disabled | Sin memoria entre sesiones |

Sincronizar el perfil del desarrollador

lazwork sync       # desde CLI
/sync              # desde dentro de la sesión

Sincroniza en un solo comando:

• Memorias Engram — contexto y aprendizaje acumulados
• Skills (~/.lazwork/skills/) — tus personalizaciones de SKILL.md
• Packs (~/.lazwork/packs/) — tus reglas de razonamiento custom
• Subagents (~/.lazwork/subagents/) — definiciones de subagentes personalizados

Requiere local-sync activado y un repo Git configurado en /config → Memoria de trabajo.

Auto-sync al cerrar sesión

Si tienes local-sync configurado con un syncRepo, al escribir /exit se ejecuta el sync automáticamente antes de cerrar.

Context7 — Docs actualizadas en tiempo real

LAZWORK consulta Context7 antes de generar código para obtener la documentación actualizada de las librerías que el plan menciona. El código generado usa la API actual, no training data potencialmente obsoleto.

Flujo automático:

1. El ArchitectAgent diseña la solución mencionando librerías (jose, next, zod, etc.)
2. El orquestador detecta las librerías relevantes del plan (allowlist de 40+ libs, máx. 4 por run)
3. Context7 devuelve los docs actualizados (cacheados por sesión)
4. El CodegenAgent usa esos docs como contexto adicional al generar código

Ejemplo: pedir "auth con jose" genera código para [email protected] (API actual), sin fix loop por APIs obsoletas.

TDD Mode

Con tddMode: true activo, el CodegenAgent genera los archivos de test antes de la implementación (ciclo red-green).

Activar desde el wizard:

lazwork config → TDD Mode

Flujo:

CodegenAgent → *.test.ts  (tests nuevos — fase red, fallan)
             → *.ts       (implementación)
Verify       → tests pasan (fase green)
Fix loop     → si no pasan, corrige automáticamente hasta 2 veces

Config manual (~/.lazwork/config.json):

{ "tddMode": true }

Arquitectura

lazwork-agent-sys/
│
├── core/                        # Cerebro — desacoplado de todo
│   ├── contracts/               # Interfaces: LLMProvider, EngramAdapter, ExecutorAdapter
│   ├── schemas/                 # Contratos de datos con Zod (7 schemas)
│   ├── llm/                     # Capa LLM: prompt builder, rules loader, response parser
│   ├── rules/                   # Reglas legacy (fallback)
│   ├── packs/                   # Packs built-in de reglas por dominio
│   │   ├── frontend/            # React, Next.js
│   │   ├── backend-node/        # Node.js, Express, NestJS
│   │   ├── python/              # FastAPI, Django
│   │   └── devops/              # CI/CD, Docker, IaC
│   ├── agents/                  # 6 agentes cognitivos
│   ├── subagents/               # 5 subagentes especializados
│   │   ├── *.subagent.ts        # Implementaciones TypeScript
│   │   └── definitions/         # Definiciones Markdown (se copian a ~/.lazwork/subagents/)
│   │       ├── architecture.subagent.md
│   │       ├── debug.subagent.md
│   │       ├── frontend.subagent.md
│   │       ├── nextjs.subagent.md
│   │       └── performance.subagent.md
│   ├── skills/                  # 15 capacidades ejecutables (TypeScript)
│   │   ├── core/                # read-project-structure, read-file, write-file
│   │   ├── code/                # generate-code, refactor-code, enforce-types
│   │   ├── analysis/            # analyze-structure, detect-bad-patterns, analyze-dependencies
│   │   ├── nextjs/              # analyze-server-client-split, optimize-server-action
│   │   └── performance/         # analyze-bundle, detect-heavy-dependencies, suggest-lazy-loading
│   ├── orchestrator/            # Coordina el pipeline con onProgress
│   │   ├── orchestrator.ts      # Pipeline principal y fix loop
│   │   ├── code-validator.ts    # Validación post-codegen (tsc, eslint, runtime probe)
│   │   ├── intent-classifier.ts # Clasificación local de intención del usuario
│   │   └── pipeline-resolver.ts # Resolución de fases según intención
│   ├── mcp/                     # MCP server
│   │   ├── server.ts            # MCP server (stdio + HTTP SSE)
│   │   ├── tools.ts             # Tools: lazwork_run, lazwork_plan, lazwork_verify
│   │   └── clients/
│   │       └── context7.ts      # Cliente Context7 — singleton, cache por sesión
│   └── index.ts                 # Exporta run(), RunResult y todos los tipos públicos
│
├── adapters/                    # Implementaciones concretas (fuera del core)
│   ├── llm-stub/                # Mock determinista — sin API key, para dev y CI
│   ├── llm-openai/              # OpenAI real
│   ├── llm-github-copilot/      # GitHub Copilot via PAT (multi-modelo)
│   ├── engram-local/            # Persiste en JSON
│   ├── engram-gentleman/        # Integración con binario Engram (SQLite+FTS5)
│   ├── git-pr/                  # ✅ GitPRExecutorAdapter — rama + plan + commit + PR
│   └── openclaw-client/         # Placeholder interno (no expuesto por la CLI)
│
├── .lazwork/                    # Configuración del agente para VS Code Copilot
│   ├── skill-registry.md        # Catálogo de skills disponibles
│   └── skills/                  # Skills en formato Markdown (cargan como contexto)
│       ├── thinking/SKILL.md
│       ├── architecture/SKILL.md
│       ├── code-quality/SKILL.md
│       ├── nextjs/SKILL.md
│       ├── frontend/SKILL.md
│       ├── debug/SKILL.md
│       ├── performance/SKILL.md
│       └── github-pr/SKILL.md
│
├── .github/
│   └── copilot-instructions.md  # Instrucciones del orquestador para VS Code Copilot
│
├── AGENTS.md                    # Catálogo de agentes para Claude Code / OpenCode
│
├── cli/
│   ├── config/
│   │   ├── types.ts             # LazworkConfig — tipado completo
│   │   ├── manager.ts           # ConfigManager — lee/escribe ~/.lazwork/config.json
│   │   └── profile.ts           # bootstrapGlobalProfile — copia defaults a ~/.lazwork/
│   ├── tui/
│   │   ├── onboarding.ts        # Wizard de primera ejecución
│   │   ├── config-wizard.ts     # Wizard para modificar config seccional
│   │   ├── banner.ts            # Banner, header de sesión, colores
│   │   ├── engram-install.ts    # Auto-instalación y arranque del binario Engram
│   │   ├── engram-sync.ts       # Sync de memorias a Git
│   │   ├── init-project.ts      # lazwork init — setup de proyecto
│   │   ├── init-mcp.ts          # lazwork init-mcp — config MCP por agente
│   │   ├── doctor.ts            # lazwork doctor — health check del entorno
│   │   ├── update-check.ts      # Self-update: chequeo no bloqueante de versión
│   │   ├── skills-manager.ts    # lazwork skills list/add/search/create
│   │   └── watch.ts             # lazwork watch — watch mode
│   ├── repl/
│   │   └── session.ts           # Loop REPL: chat unificado + pipeline cognitivo
│   ├── adapters-factory.ts      # Wiring: crea adapters según config
│   └── index.ts                 # Entry point — flags, comandos CLI
│
└── tests/
    ├── orchestrator.test.ts             # Flujo completo del pipeline
    ├── agents/
    │   ├── codegen.agent.test.ts        # Fix mode con archivos relacionados
    │   └── critic.agent.test.ts         # Reglas de code-quality en CriticAgent
    ├── cli/
    │   └── adapters-factory.test.ts     # USE_STUB y wiring de providers
    ├── llm/
    │   └── prompt-builder.test.ts       # File Access Guarantee
    ├── orchestrator/
    │   ├── code-validator.test.ts       # Lectura de archivos afectados, runtime probe
    │   ├── fix-loop-e2e.test.ts         # Integración: codegen → validación → fix → verde
    │   ├── intent-classifier.test.ts    # Clasificación de intención del usuario
    │   └── pipeline-resolver.test.ts    # Resolución del pipeline según intención
    ├── parsing/schemas.test.ts           # Validación Zod de schemas de agentes
    ├── rules/enforcement.test.ts        # Carga y contenido de reglas
    ├── subagents/
    │   ├── subagent-resolver.test.ts    # Resolución de subagentes por keywords
    │   └── subagent-runner.test.ts      # Ejecución de subagentes con LLM
    └── e2e/
        ├── pipeline-recordings.test.ts  # Pipeline completo con 3 escenarios grabados
        └── recordings/                  # Fixtures JSON de responses del LLM

Agentes — Pipeline Cognitivo

6 agentes secuenciales. Cada uno recibe el output del anterior:

| Agente | Input | Output | | ---------------- | ------------------------------- | ------------------------------------------------------------ | | ThinkingAgent | user_input + engram_context | problem_definition, assumptions, risks, alternatives | | CriticAgent | output de Thinking | issues, anti_patterns, complexity_score | | DecisionAgent | output de Thinking + Critic | decision, reasoning, priority, requires_execution | | ArchitectAgent | output de Decision | structure, boundaries, patterns | | ExecutionAgent | output de Architect | tasks, steps, constraints, requires_execution | | CodegenAgent | output de Execution + Architect | files (filePath + content + action), summary |

Tras el CodegenAgent, el CodeValidator ejecuta automáticamente tsc --noEmit, eslint y un runtime probe (dev/start con timeout). Si hay errores, el fix loop relee los archivos afectados y sus imports relacionados, y llama a CodegenAgent.fix() hasta 2 veces para corregir la causa raíz — incluyendo archivos del proyecto fuera de los generados si ahí está el problema real.

Cada agente carga reglas del pack activo correspondiente a su responsabilidad.

Subagentes — Especialización por dominio

5 subagentes invocables de forma independiente desde el core:

| Subagente | Especialidad | Pack de reglas | | ---------------------- | ----------------------------------- | -------------- | | FrontendSubagent | Componentes React, hooks, UI/lógica | code-quality | | NextjsSubagent | App Router, Server/Client, Caching | next | | ArchitectureSubagent | Clean Architecture, feature-based | architecture | | PerformanceSubagent | Bundle, lazy loading, rendering | next | | DebugSubagent | Logs, hydration, runtime errors | code-quality |

Skills — Capacidades Ejecutables

15 skills organizadas en 5 categorías:

Core

• readProjectStructure(rootPath) — Lee estructura de carpetas recursivamente
• readFile(filePath) — Lee contenido de un archivo
• writeFile(filePath, content) — Crea/modifica archivos

Code (requieren LLMProvider)

• generateCode(spec, llm) — Genera código TypeScript/React desde especificación
• refactorCode(code, context, llm) — Mejora código sin cambiar comportamiento
• enforceTypes(code, llm) — Aplica tipado estricto, elimina any

Analysis (requieren LLMProvider)

• analyzeStructure(structure, llm) → { violations, suggestions, score }
• detectBadPatterns(code, llm) → { anti_patterns, severity, refactor_suggestions }
• analyzeDependencies(depMap, llm) → { circular_dependencies, boundary_violations, recommendations }

Next.js (requieren LLMProvider)

• analyzeServerClientSplit(components, llm) → { server_components, client_components, misclassified }
• optimizeServerAction(code, llm) — Optimiza Server Actions
• detectUnnecessaryClientComponents(components, llm) → componentes que deberían ser Server

Performance (requieren LLMProvider)

• analyzeBundle(bundleInfo, llm) → { heavy_modules, optimization_opportunities }
• detectHeavyDependencies(deps, llm) → { heavy_dependencies, alternatives }
• suggestLazyLoading(components, llm) → { components_to_lazy_load, routes_to_split }

Proveedores LLM

| Proveedor | Modelos disponibles | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | GitHub Copilot | Claude Sonnet 4.6 (default), Claude Opus 4.6, Claude Sonnet 4.5, Claude Sonnet 4, GPT-5.3 Codex, GPT-5.4, Grok Code Fast 1, Gemini 3.1 Pro | | OpenAI | misma lista — seleccionable en wizard | | Stub (dev/CI) | determinista, sin API key |

Los modelos mostrados en el wizard son los realmente habilitados en tu cuenta — se consultan en tiempo real via la API.

Configuración completa (~/.lazwork/config.json)

{
  "provider": "github-copilot",
  "githubCopilot": {
    "token": "ghp_...",
    "model": "claude-sonnet-4-6"
  },
  "openai": {
    "apiKey": "sk-...",
    "model": "gpt-4o"
  },
  "engram": {
    "mode": "local-sync",
    "port": 7437,
    "syncRepo": "https://github.com/tuusuario/lazwork-memory.git"
  },
  "agentModels": {
    "thinking": "gpt-4o",
    "execution": "gpt-4o-mini"
  },
  "activePack": "backend-node",
  "tddMode": false
}

Usar el core como módulo

El core es completamente independiente de la CLI:

import { run } from "lazwork/core";
import { GithubCopilotLLMProvider } from "lazwork/adapters/llm-github-copilot";
import { LocalEngramAdapter } from "lazwork/adapters/engram-local";
import { GitPRExecutorAdapter } from "lazwork/adapters/git-pr";
import { setActivePack } from "lazwork/core/llm/rules-loader";

setActivePack("backend-node"); // ← activar pack antes de correr

const result = await run("mi tarea", {
  llm: new GithubCopilotLLMProvider(
    process.env.GITHUB_TOKEN,
    "claude-sonnet-4-6",
  ),
  engram: new LocalEngramAdapter(["~/.lazwork/engram/global.json"]),
  executor: new GitPRExecutorAdapter(),
  agentLlms: {
    thinking: new GithubCopilotLLMProvider(token, "gpt-4o"),
    execution: new GithubCopilotLLMProvider(token, "gpt-4o-mini"),
  },
  onProgress: (phase, status) => console.log(phase, status),
});

console.log(result.decision);
console.log(result.architecture);
console.log(result.execution);

Usar subagentes de forma independiente

import { NextjsSubagent } from "lazwork/core/subagents/nextjs.subagent";

const subagent = new NextjsSubagent(llm);
const result = await subagent.run({
  components: ["ProductList.tsx", "CartButton.tsx"],
  question: "Which components should be Server Components?",
});
console.log(result.recommendations);

Usar skills de forma independiente

import { analyzeStructure } from "lazwork/core/skills/analysis/analyze-structure.skill";
import { StubLLMProvider } from "lazwork/adapters/llm-stub";

const result = await analyzeStructure(projectStructure, new StubLLMProvider());
console.log(result.violations);

Implementar tus propios adapters

LLM personalizado

import type {
  LLMProvider,
  LLMMessage,
} from "lazwork/core/contracts/llm-provider.contract";

export class MiLLMProvider implements LLMProvider {
  async generate(messages: LLMMessage[]): Promise<string> {
    // tu implementación (Anthropic, Gemini, Ollama, etc.)
  }
}

Engram personalizado

import type { EngramAdapter, EngramContext, EngramEntry } from "lazwork/core/contracts/engram.contract";

export class MiEngramAdapter implements EngramAdapter {
  async retrieve(query: string): Promise<EngramContext> { ... }
  async save(entry: Omit<EngramEntry, "timestamp">): Promise<void> { ... }
  async saveChatTurn(projectRoot: string, turn: Omit<ChatTurn, "timestamp">): Promise<void> { ... }
  async retrieveChatHistory(projectRoot: string, limit?: number): Promise<ChatTurn[]> { ... }
  async savePersonalLearning(learning: { title: string; content: string }): Promise<void> { ... }
}

Tests

pnpm test         # 243 tests (incluye E2E con recordings)
pnpm test:watch   # modo watch
pnpm type-check   # chequeo de tipos sin compilar

| Suite | Tests | Qué valida | | ---------------------------------------- | ----- | ------------------------------------------------------------------ | | orchestrator.test.ts | ~10 | Flujo completo, orden, save en engram, executor condicional | | orchestrator/intent-classifier.test.ts | ~30 | Clasificación de intención (question, feature, bugfix, etc.) | | orchestrator/pipeline-resolver.test.ts | 6 | Resolución del pipeline según intención clasificada | | orchestrator/code-validator.test.ts | 3 | Lectura de archivos afectados, paths runtime, runtime probe | | orchestrator/fix-loop-e2e.test.ts | 1 | Fix loop completo: codegen → validación → reinyección → corrección | | agents/codegen.agent.test.ts | 2 | Fix mode con archivos relacionados del proyecto | | agents/critic.agent.test.ts | 1 | CriticAgent usa reglas de code-quality | | cli/adapters-factory.test.ts | 2 | USE_STUB fuerza stub provider y deshabilita overrides por agente | | llm/prompt-builder.test.ts | 1 | File Access Guarantee cuando se inyecta contexto de proyecto | | parsing/schemas.test.ts | 17 | Validación Zod de los 7 schemas de agentes + JSON repair | | rules/enforcement.test.ts | 5 | Carga y contenido de los archivos de reglas | | subagents/subagent-resolver.test.ts | 2 | Resolución de subagentes por keywords | | subagents/subagent-runner.test.ts | 2 | Ejecución de subagentes con LLM | | e2e/pipeline-recordings.test.ts | 10 | Pipeline completo con 3 escenarios y recordings del LLM |

Build y distribución

pnpm build

Compila a dist/ con tsup. Copia automáticamente:

• .rules.md y packs built-in → dist/packs/, dist/rules/
• Skills y skill-registry por defecto → dist/.lazwork/skills/, dist/.lazwork/skill-registry.md
• Subagent definitions → dist/.lazwork/subagents/

En el primer arranque tras npm install -g, el CLI copia esos defaults a ~/.lazwork/. El entry point es dist/index.js, referenciado en el bin de package.json.

Decisiones de diseño

• Sin coupling al LLM: el core nunca importa OpenAI ni Anthropic directamente. Solo conoce LLMProvider.
• LLM como router de intención: no hay pattern matching de frases. El LLM decide si conversar o activar el pipeline usando una señal estructurada (##PIPELINE##).
• Zod en runtime: cada output de agente es validado antes de pasarse al siguiente. Un JSON malformado lanza error inmediato con el campo exacto que falló.
• Packs en Markdown: las reglas son archivos .md independientes del código. Se editan, crean y distribuyen sin tocar TypeScript.
• Historial de conversación: el chat mantiene contexto entre mensajes. Al activarse el pipeline, la conversación previa se inyecta como contexto de la tarea.
• Contexto de proyecto: /project carga la estructura real del repositorio para que el LLM razone sobre código existente, no hipotético.
• Modelos por agente: cada agente del pipeline puede usar un modelo diferente. Permite optimizar costo vs. calidad por fase.
• Token counter: estimación de uso de contexto en tiempo real (1 token ≈ 4 caracteres) para evitar límites inesperados.
• Git-PR automático: cuando el pipeline produce un plan ejecutable, el GitPRExecutorAdapter crea la rama, escribe el plan en .lazwork/plans/, hace commit con Conventional Commits y abre el PR vía gh pr create — sin prompts intermedios. Si no hay remote o git, degrada graciosamente y muestra instrucciones.
• Engram persistente: el aprendizaje se acumula entre sesiones. Con local-sync viaja entre máquinas vía Git. Engram guarda: decisiones del pipeline (scope proyecto), historial de chat por proyecto, y aprendizaje personal (decisión + razonamiento + patrones, scope personal sincronizable).
• Validación post-codegen: tras generar código, el CodeValidator ejecuta tsc, eslint y un runtime probe (dev/start). Si hay errores, el fix loop reinyecta archivos afectados + imports relacionados y llama a CodegenAgent.fix() hasta 2 veces, permitiendo corregir la causa raíz incluso en módulos existentes del proyecto.
• Developer profile portable: skills (~/.lazwork/skills/), packs (~/.lazwork/packs/), subagent definitions (~/.lazwork/subagents/) y skill-registry se sincronizan junto a las memorias Engram vía Engram Sync. Primer arranque: los defaults del paquete se copian a ~/.lazwork/ sin sobreescribir personalizaciones existentes.
• Core exportable: la CLI es una capa fina de wiring. El core se puede importar en cualquier app sin arrastrar la interfaz.
• Stub determinista: los tests son 100% predecibles sin API key. El stub detecta el agente por su system prompt y devuelve el mock correspondiente. La variable de entorno USE_STUB=1 fuerza el stub en cualquier configuración (pnpm start:stub).

Docs

• Arquitectura interna
• MCP Server
• Skills
• Engram — memoria persistente
• Context7 — docs actualizadas
• CLI — Referencia completa

Contributing

Ver CONTRIBUTING.md para instrucciones de cómo clonar, instalar, correr tests y enviar PRs.

Licencia

MIT © 2026 Lazaro Blanco