zugzbot 1.0.0 → 1.0.2

package/README.md

@@ -1,63 +1,139 @@
 # 🤖 Zugzbot Harness
 
-> El instalador definitivo de arneses SDD (Spec-Driven Development) para proyectos con OpenCode.
+> El instalador definitivo de arneses **SDD (Spec-Driven Development)** para proyectos potenciados por OpenCode.
 
-Este paquete NPM te permite inicializar y actualizar instantáneamente el arnés de desarrollo de **Zugzbot** en cualquier proyecto nuevo o existente en segundos.
+**Zugzbot Harness** es un ecosistema autónomo de agentes de inteligencia artificial y herramientas diseñados para programar de forma rigurosa, segura y 100% autodirigida. El corazón de este arnés es la metodología **SDD**, un flujo de trabajo estructurado en el que ningún agente escribe una sola línea de código sin antes validar un contrato estricto de especificación.
+
+Este repositorio ha sido empaquetado como un instalador interactivo global de NPM para que puedas inyectar este poderoso entorno de desarrollo en cualquier proyecto nuevo o existente en cuestión de segundos.
 
 ---
 
 ## 🚀 Instalación y Uso Rápido
 
-Para instalar el arnés de Zugzbot en cualquier proyecto, simplemente abre una terminal en la raíz de tu proyecto de destino y ejecuta:
+Para inyectar el arnés de Zugzbot en cualquier directorio o proyecto de tu computadora, simplemente abre una terminal en la carpeta raíz de tu proyecto de destino y ejecuta:
 
 ```bash
 npx zugzbot
 ```
 
-¡Eso es todo! El instalador se encargará de copiar y configurar:
-*   📁 `.opencode/` — Todo el sistema de agentes, comandos, skills y herramientas personalizadas (incluyendo el catálogo offline de **Oh My Design** con 246 marcas).
-*   ⚙️ `opencode.json` — La configuración de seguridad, permisos y servidores MCP de tu bot.
-*   🖥️ `tui.json` — Configuración opcional para interfaces TUI.
-*   🛡️ `.utils/` — Tus scripts de utilidad ocultos (como exportadores de sesiones y conmutadores de modelos).
+¡Eso es todo! El instalador automatizado copiará de forma no destructiva y fusionará los siguientes recursos en tu proyecto:
+
+*   📁 **`.opencode/`** — El núcleo del sistema: agentes, comandos, skills y herramientas personalizadas (incluyendo el catálogo offline de **Oh My Design** con 246 marcas).
+*   ⚙️ **`opencode.json`** — La configuración maestra de seguridad, variables de entorno, plugins y servidores MCP de tu bot.
+*   🖥️ **`tui.json`** — Configuración personalizada para la interfaz interactiva de terminal (TUI).
+
+---
+
+## 🏗️ ¿Cómo Funciona el Arnés? (Arquitectura bajo el capó)
+
+El arnés se compone de tres pilares fundamentales que garantizan un desarrollo libre de errores, regresiones o improvisaciones:
+
+### 1. Las 5 Fases del Ciclo SDD (Spec-Driven Development)
+El desarrollo se ejecuta secuencialmente a través de cinco fases estrictas, controladas por el estado global de la sesión (`sdd_get_state` y `sdd_set_phase`):
+
+```
+ ┌──────────────┐      ┌────────────────┐      ┌────────────────────┐      ┌─────────────────┐      ┌───────────────┐
+ │  F0_DETECT   │ ───> │  F1_CONTRACT   │ ───> │ F2_IMPLEMENTATION  │ ───> │ F3_VERIFICATION │ ───> │ F4_DEPLOYMENT │
+ └──────────────┘      └────────────────┘      └────────────────────┘      └─────────────────┘      └───────────────┘
+  Descubrimiento         Especificación             Codificación                Validación              Despliegue
+  Stack & Diseño         Crear contrato         Fuerza de Coder & UI         Unit/Visual tests         Docker/Build
+```
+
+*   **`F0_DETECT` (Descubrimiento)**: Se analiza el código actual, se detecta el stack base (ej. Next.js 16 + Tailwind v4 o FastAPI + Pydantic) y se busca la marca visual deseada (Toss, Stripe, Vercel, etc.) usando el catálogo de diseño.
+*   **`F1_CONTRACT` (Especificación)**: El agente redactor genera un archivo estricto de contrato en `.openspec/specs/XXXX_contract.json` (OpenAPI, esquemas de entrada/salida, requerimientos de UI exactos y casos de prueba detallados). El desarrollo no avanza hasta que este contrato esté validado y sellado.
+*   **`F2_IMPLEMENTATION` (Codificación)**: El programador arranca la infraestructura y codifica los archivos ajustándose estrictamente a los tipos, rutas y componentes del contrato aprobado en la fase F1.
+*   **`F3_VERIFICATION` (Validación)**: Se corren pruebas unitarias, de integración y visuales (utilizando Playwright). El compilador de TypeScript (`tsc`) y el linter (`eslint`) actúan como gates de control Shift-Left automáticos.
+*   **`F4_DEPLOYMENT` (Despliegue)**: Se genera la build de producción, se limpia el entorno de Docker de forma agresiva y se levanta la aplicación localmente en contenedores optimizados.
+
+---
+
+### 2. El Ecosistema de Sub-Agentes Autónomos
+
+`opencode.json` registra y configura un equipo especializado de agentes, cada uno con prompts personalizados, temperaturas específicas y permisos de seguridad acotados para evitar efectos colaterales no deseados:
+
+*   👤 **`sdd-orchestrator` (El Director)**: Es el coordinador de alto nivel del flujo completo. Lee el Brain, coordina las transiciones de fases y delega las tareas técnicas a los sub-agentes correspondientes. No tiene permisos de escritura o ejecución de comandos directos para garantizar la seguridad.
+*   ✍️ **`sdd-spec-writer` (El Arquitecto)**: Redacta y valida de forma matemática las especificaciones OpenAPI y los escenarios de prueba en `.openspec/specs/`.
+*   💻 **`sdd-coder` (El Desarrollador)**: Implementa la lógica de backend y los componentes de frontend (Shadcn/Tailwind) respetando al 100% los contratos de F1. Tiene permisos controlados para ejecutar linters y comandos de compilación.
+*   🧪 **`sdd-tester` (El Auditor de Calidad)**: Diseña las suites de pruebas y las ejecuta de forma concurrente, recopilando evidencias visuales, reportes y traces.
+*   🚢 **`sdd-deployer` (El DevOps)**: Gestiona la infraestructura, empaquetado multi-stage, configuraciones de red y levantamiento local mediante contenedores Docker.
+
+---
+
+### 3. Servidores MCP (Model Context Protocol) de Clase Mundial
+
+El arnés inyecta y habilita automáticamente varios servidores MCP avanzados en tu espacio de trabajo para dar soporte contextual al bot:
+
+*   📚 **`oh-my-design` (MCP de Diseño Offline)**:
+    Servidor oficial que empaqueta **246 marcas de diseño icónicas** (Toss, Stripe, Supabase, Linear, etc.). Permite buscar especificaciones estéticas (`DESIGN.md`), paletas de colores exactas, tipografía y plantillas HTML interactivas de previsualización 100% offline (sin llamadas a APIs ni coste de tokens).
+*   🎨 **`shadcn` (MCP de Interfaz de Usuario)**:
+    Permite explorar, buscar e instalar de forma instantánea componentes del registro oficial de Shadcn UI (botones, inputs, cards, dashboards completos) directamente desde la terminal.
+*   🔍 **`context7` (MCP de Consultas de Documentación)**:
+    Realiza búsquedas contextuales de APIs actualizadas para librerías y frameworks directamente en la nube, previniendo que los agentes utilicen sintaxis obsoletas o inventadas.
+*   🎭 **`playwright` (MCP de Navegador y Automatización)**:
+    Ejecuta pruebas visuales de extremo a extremo, realiza capturas de pantalla, toma videos de interacciones y genera traces de auditoría visuales para guardarlos ordenadamente en `.openspec/`.
+*   ✨ **`lucide-icons` (MCP de Iconos)**:
+    Valida de forma exacta nombres de iconos de Lucide React y obtiene ejemplos de código JSX listos para copiar y pegar.
+
+---
+
+## 🧠 Sistema de Memoria Compartida (Shared Brain)
+
+Para evitar la pérdida de contexto entre turnos y agentes, el arnés implementa un sistema de memoria centralizado en `.openspec/brain.md` (o archivo similar configurado), gestionado por las herramientas `brain_save_memory` y `brain_read_memory`.
+
+*   **Guardar Lecciones**: Cuando un agente soluciona un bug complejo de ruteo, un error visual en Tailwind, o define una decisión clave de arquitectura, la registra de forma concisa y acumulativa con marca de tiempo en categorías como `learnings`, `design`, `routing`, o `errors`.
+*   **Lectura al Inicio**: Al arrancar una nueva sesión, el orquestador lee selectivamente las categorías de memoria activa para absorber aprendizajes previos y evitar cometer el mismo error dos veces.
+
+---
+
+## 🔄 Modo Autopiloto (/loop)
+
+El arnés de Zugzbot viene preparado de forma nativa para soportar el **Modo Autopiloto** mediante el comando `/loop` en OpenCode.
+
+Cuando `loopMode === true`:
+1.  **Cero Preguntas**: Los agentes tienen estrictamente prohibido usar la herramienta `question` para interrumpir el flujo. Toman decisiones óptimas por defecto de forma autónoma.
+2.  **Enforcer de Barrera**: Cualquier intento de lanzar preguntas al usuario es cancelado mecánicamente por el plugin de OpenCode.
+3.  **Bucle de Corrección Continua**: Si una fase de pruebas o compilación falla, el arnés realiza rollbacks incrementales, autodiagnostica el error con las herramientas de validación, corrige el código y vuelve a probar de forma recursiva hasta lograr la estabilidad.
 
 ---
 
-## 🛠️ Desarrollo Local e Instalación para Pruebas
+## 🛠️ Desarrollo Local (Para Desarrolladores del Arnés)
 
-Si deseas realizar modificaciones en este arnés y probarlas localmente antes de publicarlas:
+Si deseas realizar modificaciones en este instalador o probar el código localmente:
 
-1.  Clona este repositorio:
+1.  Clona el repositorio:
     ```bash
     git clone https://github.com/Danielisla96/zugzbot.git
     cd zugzbot
     ```
-2.  Enlaza el paquete de forma global:
+2.  Instala las dependencias y crea el enlace local global:
     ```bash
+    npm install
     npm link
     ```
-3.  Ahora puedes ejecutar el comando `zugzbot` de forma global en cualquier parte de tu computadora para probar la instalación.
+3.  Prueba el instalador en cualquier directorio ejecutando directamente:
+    ```bash
+    zugzbot
+    ```
 
 ---
 
-## 📦 Publicar en NPM (Para Desarrolladores)
+## 📦 Publicación de Actualizaciones en NPM
 
-El nombre de paquete **`zugzbot`** se encuentra totalmente disponible en el registro público de NPM. Para publicarlo por primera vez y dejarlo disponible para todos:
+Para publicar una nueva versión de Zugzbot en el registro público de NPM:
 
-1.  **Inicia sesión en tu cuenta de NPM** (si no tienes una, créala gratis en [npmjs.com](https://www.npmjs.com/)):
+1.  Incrementa la versión en el `package.json` de la raíz (ej. `1.0.1`).
+2.  Compila el servidor standalone de `oh-my-design` (si modificaste código TypeScript del MCP) ejecutando en la carpeta `.opencode/oh-my-design/packages/mcp`:
     ```bash
-    npm login
+    npm run build
     ```
-2.  **Publica el paquete de forma pública**:
+3.  Inicia sesión y publica desde la raíz de tu proyecto:
     ```bash
+    npm login
     npm publish --access public
     ```
 
-Cada vez que quieras subir una nueva actualización:
-1. Incrementa la versión en el `package.json` (ej: `1.0.1`).
-2. Ejecuta `npm publish`.
-
 ---
 
 ## 📄 Licencia
 
-Este proyecto está bajo la Licencia MIT.
+Este proyecto se distribuye bajo la licencia **MIT**. Siéntete libre de clonarlo, modificarlo y adaptarlo para construir tus propios equipos de agentes automatizados.

package/bin/init.js

@@ -24,15 +24,17 @@ const targetDir = process.cwd();
 const itemsToCopy = [
   { name: '.opencode', src: join(pkgRoot, '.opencode'), dest: join(targetDir, '.opencode'), type: 'dir' },
   { name: 'opencode.json', src: join(pkgRoot, 'opencode.json'), dest: join(targetDir, 'opencode.json'), type: 'file' },
-  { name: 'tui.json', src: join(pkgRoot, 'tui.json'), dest: join(targetDir, 'tui.json'), type: 'file' },
-  { name: '.utils', src: join(pkgRoot, '.utils'), dest: join(targetDir, '.utils'), type: 'dir' }
+  { name: 'tui.json', src: join(pkgRoot, 'tui.json'), dest: join(targetDir, 'tui.json'), type: 'file' }
 ];
 
-// Helper to filter out node_modules and .git files
+// Helper to filter out node_modules and .git files relative to the package root
 const filterFunc = (srcPath) => {
-  const isIgnored = srcPath.includes('node_modules') || 
-                    srcPath.includes('.git') || 
-                    srcPath.includes('.openspec');
+  const relativeSrc = relative(pkgRoot, srcPath);
+  const isIgnored = relativeSrc.split(/[/\\]/).some(part => 
+    part === 'node_modules' || 
+    part === '.git' || 
+    part === '.openspec'
+  );
   return !isIgnored;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zugzbot",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {
@@ -10,8 +10,7 @@
     "bin/",
     ".opencode/",
     "opencode.json",
-    "tui.json",
-    ".utils/"
+    "tui.json"
   ],
   "engines": {
     "node": ">=16.0.0"

package/.utils/docs_opencode/acp.md

@@ -1,165 +0,0 @@
-# Soporte ACP
-
-Utilice OpenCode en cualquier editor compatible con ACP.
-
-OpenCode admite el [Agent Client Protocol](https://agentclientprotocol.com) o (ACP), lo que le permite usarlo directamente en editores e IDE compatibles.
-
-> [!TIP]
-> Para obtener una lista de editores y herramientas compatibles con ACP, consulte el [informe de progreso de ACP](https://zed.dev/blog/acp-progress-report#available-now).
-
-ACP es un protocolo abierto que estandariza la comunicación entre editores de código y agentes de codificación de IA.
-
----
-
-## [Configuración](#configuración)
-
-Para usar OpenCode a través de ACP, configure su editor para ejecutar el comando `opencode acp`.
-
-El comando inicia OpenCode como un subproceso compatible con ACP que se comunica con su editor a través de JSON-RPC a través de stdio.
-
-A continuación se muestran ejemplos de editores populares que admiten ACP.
-
----
-
-### [Zed](#zed)
-
-Agregue a su configuración [Zed](https://zed.dev) (`~/.config/zed/settings.json`):
-
-**File**: ~/.config/zed/settings.json
-
-```json
-{
-  "agent_servers": {
-    "OpenCode": {
-      "command": "opencode",
-      "args": ["acp"]
-    }
-  }
-}
-```
-
-Para abrirlo, use la acción `agent: new thread` en la **Paleta de comandos**.
-
-También puedes vincular un atajo de teclado editando tu `keymap.json`:
-
-**File**: keymap.json
-
-```json
-[
-  {
-    "bindings": {
-      "cmd-alt-o": [
-        "agent::NewExternalAgentThread",
-        {
-          "agent": {
-            "custom": {
-              "name": "OpenCode",
-              "command": {
-                "command": "opencode",
-                "args": ["acp"]
-              }
-            }
-          }
-        }
-      ]
-    }
-  }
-]
-```
-
----
-
-### [JetBrains IDEs](#jetbrains-ides)
-
-Agregue a su [JetBrains IDE](https://www.jetbrains.com/) acp.json de acuerdo con la [documentación](https://www.jetbrains.com/help/ai-assistant/acp.html):
-
-**File**: acp.json
-
-```json
-{
-  "agent_servers": {
-    "OpenCode": {
-      "command": "/absolute/path/bin/opencode",
-      "args": ["acp"]
-    }
-  }
-}
-```
-
-Para abrirlo, use el nuevo agente ‘OpenCode’ en el selector de agentes de AI Chat.
-
----
-
-### [Avante.nvim](#avantenvim)
-
-Agregue a su configuración [Avante.nvim](https://github.com/yetone/avante.nvim):
-
-**File**:
-
-```lua
-{
-  acp_providers = {
-    ["opencode"] = {
-      command = "opencode",
-      args = { "acp" }
-    }
-  }
-}
-```
-
-Si necesita pasar variables de entorno:
-
-**File**:
-
-```lua
-{
-  acp_providers = {
-    ["opencode"] = {
-      command = "opencode",
-      args = { "acp" },
-      env = {
-        OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY")
-      }
-    }
-  }
-}
-```
-
----
-
-### [CodeCompanion.nvim](#codecompanionnvim)
-
-Para usar OpenCode como agente ACP en [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim), agregue lo siguiente a su configuración de Neovim:
-
-**File**:
-
-```lua
-require("codecompanion").setup({
-  interactions = {
-    chat = {
-      adapter = {
-        name = "opencode",
-        model = "claude-sonnet-4",
-      },
-    },
-  },
-})
-```
-
-Esta configuración configura CodeCompanion para usar OpenCode como agente ACP para el chat.
-
-Si necesita pasar variables de entorno (como `OPENCODE_API_KEY`), consulte [Configuración de adaptadores: variables de entorno](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key) en la documentación de CodeCompanion.nvim para obtener detalles completos.
-
-## [Soporte](#soporte)
-
-OpenCode funciona igual a través de ACP que en la terminal. Todas las funciones son compatibles:
-
-> [!NOTE]
-> Algunos comandos de barra integrados como `/undo` y `/redo` no son compatibles actualmente.
-
-- Herramientas integradas (operaciones de archivos, comandos de terminal, etc.)
-- Herramientas personalizadas y comandos de barra
-- Servidores MCP configurados en su configuración OpenCode
-- Reglas específicas del proyecto de `AGENTS.md`
-- Formateadores y linters personalizados
-- Sistema de agentes y permisos.