🧠 LAZWORK

CLI de agentes cognitivos para desarrollo de software profesional.
No es un generador de código — es un modelo cognitivo que conversa, analiza, cuestiona, decide y planifica.

Filosofía

Este sistema representa cómo razona un desarrollador senior antes de escribir una sola línea de código.

El pipeline completo antes de cualquier acción:

Pensar → Criticar → Decidir → Arquitecturizar → Ejecutar → Recordar

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 20 tests
pnpm type-check   # Chequeo de tipos sin compilar

Uso desde línea de comandos

lazwork                    # ← Iniciar sesión interactiva (REPL)
lazwork config             # ← Wizard de configuración
lazwork config --reset     # ← Resetear toda la config y volver al onboarding
lazwork sync               # ← Sincronizar memorias Engram a Git
lazwork --version          # ← Mostrar versión instalada
lazwork --help             # ← Mostrar ayuda

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...

┌─ 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 5 agentes del pipeline y sus modelos | | /config | Abre el wizard de configuración sin salir | | /sync | Sincroniza memorias Engram + skills + packs 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 | | 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/ + 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 y skill-registry 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

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.

Arquitectura

lazwork-agent-sys/
│
├── core/                        # Cerebro — desacoplado de todo
│   ├── contracts/               # Interfaces: LLMProvider, EngramAdapter, ExecutorAdapter
│   ├── schemas/                 # Contratos de datos con Zod (6 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/                  # 5 agentes cognitivos
│   ├── subagents/               # 5 subagentes especializados
│   ├── 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
│   └── 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-remote/           # Stub preparado para servicio remoto
│   ├── git-pr/                  # ✅ GitPRExecutorAdapter — rama + plan + commit + PR
│   └── openclaw-client/         # Reservado para uso futuro (no activo)
│
├── .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
│   ├── 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 (5 tests)
    ├── parsing/schemas.test.ts  # Validación Zod (10 tests)
    └── rules/enforcement.test.ts # Carga de reglas (5 tests)

Agentes — Pipeline Cognitivo

5 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 |

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 | | Anthropic | próximamente |

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"
  },
  "anthropic": {
    "apiKey": "sk-ant-...",
    "model": "claude-3-5-sonnet-20241022"
  },
  "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"
}

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> { ... }
}

Tests

pnpm test         # 20 tests
pnpm test:watch   # modo watch
pnpm type-check   # chequeo de tipos sin compilar

| Suite | Tests | Qué valida | | --------------------------- | ----- | ----------------------------------------------------------- | | orchestrator.test.ts | 5 | Flujo completo, orden, save en engram, executor condicional | | parsing/schemas.test.ts | 10 | Validación Zod de los 5 schemas de agentes | | rules/enforcement.test.ts | 5 | Carga y contenido de los archivos de reglas |

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

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.
• Developer profile portable: skills (~/.lazwork/skills/), packs (~/.lazwork/packs/) 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.