zugzbot 1.0.35 → 1.0.36

package/.opencode/agents/sdd-coder.md

@@ -88,7 +88,7 @@ Eres el Programador de Código (sdd-coder) del arnés SDD. Tu trabajo es codific
 </coding_cheatsheet>
 
 <design_standards>
-  - **Alineación con DESIGN.md**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts de los archivos HTML interactivos (`preview.html` / `preview-dark.html`) para recrear diseños profesionales premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante.
+  - **Alineación con DESIGN.md e Instanciación de Bloques**: Lee obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` y asimila los layouts para recrear diseños premium con grids, sidebars y headers. Quedan prohibidos los MVPs de página flotante. Es **obligatorio** que si la vista requiere un dashboard, panel lateral, login o registro, instales y utilices los bloques prehechos oficiales de Shadcn (`dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`, etc.) usando `npx shadcn@latest add <block-name> --yes` de forma agrupada. Distribuye y compón estos bloques enlazándolos con el backend en lugar de inventar la UI desde cero.
   - **Self-audit pre-transición (BLOQUEANTE)**: Antes de entregar, ejecuta este bloque en una sola corrida de terminal. Si el linter o el tipado TypeScript fallan, debes corregirlos antes de transicionar (el test suite completo queda delegado al Tester en F3 para ahorrar tus turnos):
     ```bash
     HITS=$(grep -rE '#[0-9a-fA-F]{6}\b' src/ --include='*.tsx' --include='*.ts' 2>/dev/null | grep -v 'globals.css' | grep -v 'tailwind.config' | wc -l | tr -d ' ')

package/.opencode/agents/sdd-spec-writer.md

@@ -31,7 +31,7 @@ Eres el Diseñador de Contratos (sdd-spec-writer) del flujo SDD. Tu único traba
 El JSON generado en `contract.json` debe cumplir estrictamente con `.opencode/contract-schema.json`. Asegúrate de definir detalladamente:
 - `contractName` & `description`: Nombre y alcance claro del spec.
 - `settings`: Configuración clave como `verificationMode: "visual" | "console"`, lenguaje y persistencia.
-- `files_affected`: Array obligatorio que define de forma explícita las rutas exactas de los archivos que serán modificados o creados (ej. `["src/components/layout/AppLayout.tsx", "src/components/blocks/SumadoraPanel.tsx", "src/app/page.tsx"]`). Esto es CRÍTICO para permitir la política de Zero-Search y la verificación dirigida de compilación, linter y testing.
+- `files_affected`: Array obligatorio que define de forma explícita las rutas exactas de los archivos que serán modificados o creados (ej. `["src/components/layout/AppLayout.tsx", "src/components/blocks/SumadoraPanel.tsx", "src/app/page.tsx"]`). Si el proyecto vive en un subdirectorio (ej. `next-app` o `frontend`), las rutas **deben** ir obligatoriamente con el prefijo de dicho subdirectorio (ej. `["next-app/src/app/page.tsx"]`). Esto es CRÍTICO para permitir la política de Zero-Search y la verificación dirigida de compilación, linter y testing.
 - `stack`: El framework base, bases de datos y librerías clave.
 - `frontend` / `backend` / `database`: Componentes locales, props, state y endpoints de API. (Usa aliases locales como `@/components/ui/button` para components de Shadcn).
 - `stateFlow`: Owner de estado centralizado, props hacia abajo y transiciones prohibidas (`forbidden[]`).
@@ -54,7 +54,7 @@ Extrae los tokens canónicos (paleta de colores, escala de bordes, tipografía,
 
 <design_standards>
 - **Alineación con DESIGN.md**: Debes leer obligatoriamente `.openspec/design-assets/<brandId>/DESIGN.md` para extraer los tokens de diseño. Basándote además en los ejemplos HTML interactivos (`preview.html`, `preview-dark.html`) correspondientes de la marca, define en el contrato los layouts exactos (sidebars, grids, headers) a implementar.
-- **Diseño Premium**: El contrato debe instruir el uso del skill `shadcn-templates` (Sección 3.5) alineado a la guía del `DESIGN.md`. Quedan prohibidos los MVPs de pantalla única flotante.
+- **Diseño Premium y Bloques Shadcn**: El contrato debe instruir el uso de bloques prehechos oficiales de Shadcn (`dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`, etc.) mediante el skill `shadcn-templates` (Sección 3.1) alineado a la guía del `DESIGN.md`. Quedan prohibidos los MVPs de pantalla única flotante. El spec-writer debe usar proactivamente las herramientas MCP (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) para identificar qué bloques de tipo `registry:block` o `registry:ui` se adecuan a la necesidad y declararlos en `frontend.components` y `files_affected`.
 - **Escenarios de Test**:
   - Si `verificationMode === "console"`, genera únicamente escenarios de tipo `unit` o `integration` (entre 3 y 5 escenarios en total). No generes escenarios de tipo `visual` ni tests basados en browser.
   - Si `verificationMode === "visual"`, incluye los escenarios visuales necesarios con selectores CSS reales.

package/.opencode/rules/sdd-global.md

@@ -21,3 +21,16 @@ Cuando el estado del sistema tiene `loopMode === true` (activado mediante el com
 - **Intercepción de Barrera**: Si algún agente intenta llamar a la herramienta `question` en este modo, el sistema abortará la llamada mecánicamente a través del plugin enforcer.
 - **Specs Incrementales**: Si la petición es grande, el orquestador debe dividirla secuencialmente en contratos incrementales. Completa un spec por completo (F0->F4) y arranca el siguiente de inmediato de forma autónoma hasta finalizar todo el plan.
 - **Rollback de Emergencia**: Si una misma fase falla de forma continua (más de 2 rollbacks), desactiva `loopMode` usando `sdd_set_phase` y solicita asistencia humana en el chat.
+
+## 3. Uso Mandatorio de Bloques Prehechos de Shadcn UI (dashboard, sidebar, login, etc.)
+Para optimizar el tiempo de desarrollo, garantizar una experiencia visual premium y evitar la invención de layouts o formularios comunes desde cero:
+- **Prioridad de Bloques**: Al diseñar cualquier interfaz de usuario (Layouts, Dashboards, Paneles de Control, Vistas de Configuración, Páginas de Autenticación, Tablas de Datos, Gráficos), los agentes **deben** buscar y utilizar de forma prioritaria los bloques prehechos del registro oficial `@shadcn` (como `dashboard-01`, `sidebar-01` al `16`, `login-01` al `05`, `signup-01` al `05`).
+- **Búsqueda Proactiva**: El Spec-Writer **debe** consultar el registro utilizando las herramientas del MCP `shadcn` (`shadcn_search_items_in_registries`, `shadcn_list_items_in_registries`) al redactar el contrato (F1) para identificar qué bloques se ajustan a la necesidad, y declararlos en `frontend.components` y `files_affected` de `contract.json`.
+- **Implementación por Distribución y Composición**: El Coder (F2) **debe** instalar estos bloques usando `npx shadcn@latest add <block-name>` (ej: `dashboard-01`, `login-03`) en su proyecto, integrando y distribuyendo los elementos con el estado y lógica del backend, sin rediseñar o codificar layouts que ya existen de forma oficial.
+
+## 4. Soporte para Subdirectorios, Monorepos (targetDir) y Estándar Corporativo `src/`
+Si el proyecto o aplicación principal vive en un subdirectorio (ej. `next-app`, `frontend`, `backend`), se deben seguir estas directivas estrictas para mantener la consistencia y el "estándar corporativo con carpeta `src/`":
+- **Estructura del Proyecto**: Toda la estructura de código fuente, páginas, componentes, estilos, pruebas y configuraciones debe vivir agrupada dentro de la subcarpeta del proyecto y bajo la carpeta `src/` obligatoriamente (ej. `next-app/src/app/...`, `next-app/src/components/...`, `next-app/tsconfig.json`, `next-app/package.json`).
+- **Rutas de Archivos en el Contrato**: El Spec-Writer (F1) **debe** escribir las rutas del campo `files_affected` del contrato con el prefijo del subdirectorio correspondiente (ej. `["next-app/src/app/page.tsx", "next-app/src/components/blocks/Navbar.tsx"]`).
+- **Ejecución de Comandos**: El Coder (F2), Tester (F3) y Deployer (F4) **deben** ejecutar siempre sus comandos de terminal (`npm install`, `npm run lint`, `npx tsc`, `npx vitest`, `docker compose`) utilizando la subcarpeta como directorio de trabajo (`workdir` en las llamadas a herramientas, o moviéndose a ella).
+- **Consistencia de Configuración**: Está estrictamente prohibido esparcir o duplicar archivos de configuración (como `tsconfig.json`, `eslint.config.mjs`, `vitest.config.ts`, `components.json`) en la raíz del espacio de trabajo si hay un subdirectorio activo. Todo debe quedar encapsulado dentro del subdirectorio del proyecto.

package/.opencode/skills/shadcn-templates/SKILL.md

@@ -72,8 +72,14 @@ npx shadcn@latest add <component-name>
 
 Al diseñar o codificar páginas con Shadcn UI, sigue estas reglas estrictas:
 
-### 3.1 Componer, no reinventar
-Utiliza las plantillas y bloques existentes de Shadcn (como `dashboard-01`, `settings-form`, `login-01`) como punto de partida. Busca layouts de dashboards o formularios complejos en el registro mediante el MCP `shadcn` antes de escribir código personalizado.
+### 3.1 Componer, no reinventar (MANDATORIO)
+Utiliza las plantillas y bloques existentes de Shadcn como el estándar absoluto de tu interfaz. Queda **estrictamente prohibido** escribir layouts, páginas de autenticación o cuadros de mando desde cero si ya existe un bloque oficial que resuelva el caso de uso:
+- **Dashboards**: Utiliza `dashboard-01` como base para cualquier panel de control interactivo.
+- **Sidebars / Barras de Navegación**: Utiliza `sidebar-01` al `16` para paneles laterales funcionales, colapsables, dinámicos o anidados. No programes componentes de navegación complejos a mano.
+- **Login / Registro**: Utiliza `login-01` al `05` y `signup-01` al `05` para flujos de login y registro de usuarios.
+- **Gráficos y Métricas**: Busca y añade bloques de gráficos oficiales de Recharts (`chart-area-*`, `chart-bar-*`, `chart-pie-*`, `chart-radar-*`) para dar vida a la visualización de datos.
+
+Busca layouts de dashboards o formularios complejos en el registro mediante el MCP `shadcn` antes de escribir cualquier código personalizado. Una vez agregado el bloque, distribuye y adapta sus elementos con el estado y la lógica de tu aplicación.
 
 ### 3.2 Form Layouts (FieldGroup + Field)
 Para estructurar campos de formularios, no uses `div`s arbitrarios con clases de espaciado complejas. Usa las composiciones semánticas oficiales de Shadcn:

package/.opencode/templates/nextjs-shadcn/src/components/blocks/.gitkeep

@@ -0,0 +1 @@
+# Carpeta base para bloques complejos y layouts de Shadcn UI

package/.opencode/templates/nextjs-shadcn/src/components/layout/.gitkeep

@@ -0,0 +1 @@
+# Carpeta base para layouts generales de la aplicacion

package/.opencode/templates/nextjs-shadcn/src/components/ui/.gitkeep

@@ -0,0 +1 @@
+# Carpeta base para componentes primitivos de Shadcn UI

package/.opencode/tools/sdd_bootstrap.ts

@@ -145,12 +145,15 @@ export const bootstrap_status = tool({
 export const bootstrap_nextjs_shadcn = tool({
   description: "Inicializa un proyecto Next.js 16 + Shadcn UI + Tailwind v4 + Vitest a partir de la plantilla canónica en .opencode/templates/nextjs-shadcn/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), mergea package.json, y opcionalmente instala dependencias y shadcn components.",
   args: {
+    targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto Next.js (ej: 'next-app' o '.')."),
     components: tool.schema.array(tool.schema.string()).default([]).describe("Lista de shadcn components a instalar (ej: ['button','input','table']). Vacío = no instalar shadcn components."),
     install: tool.schema.boolean().default(true).describe("Si true, ejecuta npm/pnpm/yarn install después de copiar. Si false, solo copia archivos."),
     force: tool.schema.boolean().default(false).describe("Si true, sobrescribe archivos existentes. Si false, los salta (mergea package.json)."),
   },
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = args.targetDir || "."
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
     const start = Date.now()
     const templateDir = path.resolve(root, ".opencode/templates/nextjs-shadcn")
 
@@ -172,9 +175,9 @@ export const bootstrap_nextjs_shadcn = tool({
     }
 
     const isInitialized =
-      fs.existsSync(path.resolve(root, "src/app/page.tsx")) &&
-      fs.existsSync(path.resolve(root, "package.json")) &&
-      fs.existsSync(path.resolve(root, "src/lib/utils.ts"))
+      fs.existsSync(path.resolve(targetPath, "src/app/page.tsx")) &&
+      fs.existsSync(path.resolve(targetPath, "package.json")) &&
+      fs.existsSync(path.resolve(targetPath, "src/lib/utils.ts"))
 
     if (isInitialized && !args.force) {
       return JSON.stringify({
@@ -189,7 +192,7 @@ export const bootstrap_nextjs_shadcn = tool({
     const filesSkipped: string[] = []
     const copyFileSafe = (rel: string) => {
       const src = path.join(templateDir, rel)
-      const dst = path.resolve(root, rel)
+      const dst = path.resolve(targetPath, rel)
       if (!fs.existsSync(src)) return
       const dstExists = fs.existsSync(dst)
       if (dstExists && !args.force) {
@@ -201,7 +204,7 @@ export const bootstrap_nextjs_shadcn = tool({
       filesCopied.push(rel)
     }
 
-    const userPkgPath = path.resolve(root, "package.json")
+    const userPkgPath = path.resolve(targetPath, "package.json")
     let mergedPkg: any = null
     if (fs.existsSync(userPkgPath) && !args.force) {
       try {
@@ -223,7 +226,7 @@ export const bootstrap_nextjs_shadcn = tool({
       copyFileSafe("package.json")
     }
 
-    const userNextConfig = path.resolve(root, "next.config.ts")
+    const userNextConfig = path.resolve(targetPath, "next.config.ts")
     if (fs.existsSync(userNextConfig) && !args.force) {
       try {
         const content = fs.readFileSync(userNextConfig, "utf8")
@@ -255,17 +258,20 @@ export const bootstrap_nextjs_shadcn = tool({
       "src/app/globals.css",
       "src/lib/utils.ts",
       "src/components/theme-provider.tsx",
+      "src/components/ui/.gitkeep",
+      "src/components/blocks/.gitkeep",
+      "src/components/layout/.gitkeep",
       "src/test/setup.ts",
       "public/.gitkeep",
     ]
     for (const f of standardFiles) copyFileSafe(f)
 
-    const pm = detectPackageManager(root)
+    const pm = detectPackageManager(targetPath)
 
     let installDuration = 0
     let installSkipped = false
     let installError: string | null = null
-    const hasNodeModules = fs.existsSync(path.resolve(root, "node_modules"))
+    const hasNodeModules = fs.existsSync(path.resolve(targetPath, "node_modules"))
     if (args.install && (args.force || !hasNodeModules)) {
       const installStart = Date.now()
       const installCmd = pm === "pnpm"
@@ -275,7 +281,7 @@ export const bootstrap_nextjs_shadcn = tool({
           : "npm install --prefer-offline"
       try {
         execSync(installCmd, {
-          cwd: root,
+          cwd: targetPath,
           stdio: "ignore",
           timeout: 300_000,
         })
@@ -293,7 +299,7 @@ export const bootstrap_nextjs_shadcn = tool({
       try {
         const cmd = `npx shadcn@latest add ${args.components.join(" ")} --yes --overwrite`
         execSync(cmd, {
-          cwd: root,
+          cwd: targetPath,
           stdio: "ignore",
           timeout: 180_000,
         })
@@ -314,6 +320,7 @@ export const bootstrap_nextjs_shadcn = tool({
       componentsInstalled,
       installDuration,
       totalDuration: Date.now() - start,
+      targetDir,
     }
     writeBootstrapStatus(root, bootstrapRecord)
 
@@ -348,12 +355,15 @@ export const bootstrap_nextjs_shadcn = tool({
 export const bootstrap_fastapi = tool({
   description: "Inicializa un proyecto FastAPI + Pydantic + Uvicorn + Pytest + Ruff a partir de la plantilla canónica en .opencode/templates/fastapi-sdd/. Es IDEMPOTENTE: si el proyecto ya está inicializado y no se pasa force=true, no toca nada. Copia archivo-por-archivo (sin pisar los existentes), opcionalmente instala dependencias con uv (fallback pip).",
   args: {
+    targetDir: tool.schema.string().default(".").describe("Subdirectorio donde se inicializará el proyecto FastAPI (ej: 'backend' o '.')."),
     extras: tool.schema.array(tool.schema.string()).default([]).describe("Lista de paquetes Python adicionales a instalar (ej: ['sqlalchemy','pydantic-settings','pytest-asyncio']). Vacío = no instalar extras extra."),
     install: tool.schema.boolean().default(true).describe("Si true, ejecuta uv sync (o pip install -e '.[dev]') después de copiar. Si false, solo copia archivos."),
     force: tool.schema.boolean().default(false).describe("Si true, sobrescribe archivos existentes. Si false, los salta."),
   },
   async execute(args, context) {
     const root = getRoot(context)
+    const targetDir = args.targetDir || "."
+    const targetPath = targetDir === "." ? root : path.resolve(root, targetDir)
     const start = Date.now()
     const templateDir = path.resolve(root, ".opencode/templates/fastapi-sdd")
 
@@ -375,8 +385,8 @@ export const bootstrap_fastapi = tool({
     }
 
     const isInitialized =
-      fs.existsSync(path.resolve(root, "src/main.py")) &&
-      fs.existsSync(path.resolve(root, "pyproject.toml"))
+      fs.existsSync(path.resolve(targetPath, "src/main.py")) &&
+      fs.existsSync(path.resolve(targetPath, "pyproject.toml"))
 
     if (isInitialized && !args.force) {
       return JSON.stringify({
@@ -391,7 +401,7 @@ export const bootstrap_fastapi = tool({
     const filesSkipped: string[] = []
     const copyFileSafe = (rel: string) => {
       const src = path.join(templateDir, rel)
-      const dst = path.resolve(root, rel)
+      const dst = path.resolve(targetPath, rel)
       if (!fs.existsSync(src)) return
       const dstExists = fs.existsSync(dst)
       if (dstExists && !args.force) {
@@ -403,7 +413,7 @@ export const bootstrap_fastapi = tool({
       filesCopied.push(rel)
     }
 
-    const userPyprojectPath = path.resolve(root, "pyproject.toml")
+    const userPyprojectPath = path.resolve(targetPath, "pyproject.toml")
     let mergedPyproject: string | null = null
     if (fs.existsSync(userPyprojectPath) && !args.force) {
       try {
@@ -443,13 +453,13 @@ export const bootstrap_fastapi = tool({
     ]
     for (const f of standardFiles) copyFileSafe(f)
 
-    const pm = detectPythonPackageManager(root)
+    const pm = detectPythonPackageManager(targetPath)
 
     let installDuration = 0
     let installSkipped = false
     let installError: string | null = null
-    const hasVenv = fs.existsSync(path.resolve(root, ".venv"))
-    const hasInstalled = fs.existsSync(path.resolve(root, "uv.lock")) || hasVenv
+    const hasVenv = fs.existsSync(path.resolve(targetPath, ".venv"))
+    const hasInstalled = fs.existsSync(path.resolve(targetPath, "uv.lock")) || hasVenv
     if (args.install && (args.force || !hasInstalled)) {
       const installStart = Date.now()
       const installCmd = pm === "uv"
@@ -457,7 +467,7 @@ export const bootstrap_fastapi = tool({
         : "pip install -e '.[dev]'"
       try {
         execSync(installCmd, {
-          cwd: root,
+          cwd: targetPath,
           stdio: "ignore",
           timeout: 300_000,
         })
@@ -466,7 +476,9 @@ export const bootstrap_fastapi = tool({
         installError = e.message?.slice(0, 500) || "unknown error"
       }
     } else if (hasInstalled && !args.force) {
-      installSkipped = true
+      try {
+        installSkipped = true
+      } catch (e) {}
     }
 
     const extrasInstalled: string[] = []
@@ -477,7 +489,7 @@ export const bootstrap_fastapi = tool({
         : `pip install ${args.extras.join(" ")}`
       try {
         execSync(extrasCmd, {
-          cwd: root,
+          cwd: targetPath,
           stdio: "ignore",
           timeout: 180_000,
         })
@@ -498,6 +510,7 @@ export const bootstrap_fastapi = tool({
       extrasInstalled,
       installDuration,
       totalDuration: Date.now() - start,
+      targetDir,
     }
     writeBootstrapStatus(root, bootstrapRecord)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zugzbot",
-  "version": "1.0.35",
+  "version": "1.0.36",
   "description": "Fácil instalador del arnés SDD de Zugzbot para proyectos OpenCode",
   "type": "module",
   "bin": {