Template Cuarzo, listo para agentes LLM

Tres puntos de entrada equivalentes y 23 guías obligatorias con índice generado.

• CLAUDE.md, OPENCODE.md y AGENTS.md

  Resumen de reglas no negociables para cada agente; CLAUDE.md carga automáticamente las guías 00 y 01.

  CLAUDE.mdOPENCODE.mdAGENTS.md

• Guías obligatorias

  Protocolo paso a paso, recetas, errores frecuentes, mapa real del repo y definición de terminado; cada una ≤77 líneas.

  docs/agentes/

• Índice automático

  INDICE.txt con título, propósito y líneas de cada guía; se pagina solo si crece y se verifica en el pre-commit.

  docs/agentes/INDICE.txtscripts/docs/build-index.mjs

Ningún archivo de texto propio supera 77 líneas: código, CSS, JSON, guías y logs.

• Comprobación global

  check:lines recorre todos los archivos versionados y los logs; las únicas excepciones (generados y plataforma) están justificadas.

  scripts/quality/check-lines.mjsquality/lines-allowlist.json

• ESLint max-lines

  Aviso inmediato en el editor para JS/TS, leyendo el mismo límite y las mismas excepciones.

  tooling/eslint/line-limit.js

• Código modularizado

  El catálogo de 211 líneas pasó a ~15 archivos; Tabs, Pagination y Modal separaron lógica pura y hooks.

  src/showcase/catalog/src/components/cuarzo/navigation/

Dos contextos (librería y showcase) con módulos y capas domain, application, infrastructure y presentation.

• Librería por familias

  actions, forms, feedback, containers, data, navigation y shared; la API publicada sigue en src/index.ts para Canvas.

  src/components/cuarzo/src/index.ts

• Showcase por módulos

  theme, layout, overview, color, typography, shape, catalog y report; las rutas son adaptadores sin JSX.

  src/showcase/src/routes/_showcase/

• Fronteras verificadas

  ESLint prohíbe imports entre capas en sentido incorrecto y entre módulos fuera de su index.ts; check:ddd valida ubicación y pureza.

  tooling/eslint/ddd-layers.jsscripts/quality/ddd-rules.mjs

Todo elemento interactivo tiene un identificador estable y único para Playwright.

• Convención de nombres

  page-<slug>, nav-link-<slug>, catalog-*, demo-<componente>-<caso>; documentada con tabla de prefijos.

  docs/agentes/08-test-ids.md

• Propagación en la librería

  Cada componente declara data-slot y deriva ids de sus subpartes (Modal -close, Tabs -tab-<id>, Pagination -page-<n>).

  src/components/cuarzo/shared/domain/test-id.ts

• Test global

  Recorre todas las rutas del menú y falla si un interactivo no tiene id o si un id se repite.

  tests/e2e/quality/testids.spec.ts

Revisión obligatoria en navegador real, por MCP o por scripts, más una batería e2e.

• MCP configurado

  Claude Code (.mcp.json) y OpenCode (opencode.json) usan el mismo lanzador, que reutiliza el Chromium de los tests.

  .mcp.jsonopencode.jsonscripts/playwright/mcp.mjs

• Inspección por Node

  pw:inspect guarda captura, ids, h1, desborde y errores de consola de cada ruta, en claro u oscuro y a cualquier ancho.

  scripts/playwright/inspect.mjs

• Tests e2e

  Navegación, tema, buscador, modal, controles, testids, responsive y reporte; escritorio y móvil; fallan ante cualquier error de consola.

  tests/e2e/playwright.config.ts

Todo error queda en archivos de texto de ≤77 líneas con un índice que dice qué leer primero.

• Logger paginado

  parte-0001.txt, parte-0002.txt… sin colores ANSI; logs/INDICE.txt se regenera solo.

  scripts/lib/txt-log.mjsscripts/lib/log-index.mjs

• Fuentes capturadas

  Servidor de desarrollo, errores del navegador (plugin de Vite), Playwright, cada paso de verify y un historial común de errores.

  tooling/vite/agent-log-plugin.tslogs/LEEME.txt

• Vista rápida

  npm run logs muestra índice, último resultado y últimos errores de una vez.

  scripts/dev/show-logs.mjs

npm como gestor documentado y un puerto único, poco común y estricto: 43177.

• Puerto 43177 estricto

  Definido en config/dev-server.json; si está ocupado Vite falla en vez de saltar a otro.

  config/dev-server.jsonvite.config.ts

• Servidor sin bloquear

  dev:bg arranca en segundo plano y espera a que responda; dev:stop lo detiene. Detecta sistemas sin IPv6.

  scripts/dev/start-bg.mjstooling/vite/listen-host.ts

• Generadores

  nuevo:componente y nuevo:modulo crean archivos que ya cumplen DDD, 77 líneas y data-testid.

  scripts/scaffold/

Las reglas no dependen de la memoria del agente: se comprueban solas.

• Hooks de Claude Code

  Validación tras cada edición, recordatorio al iniciar y bloqueo al terminar si hay reglas rotas o falta pasar Playwright.

  .claude/settings.jsonscripts/hooks/

• Pre-commit de git

  verify:rapido (índices, líneas, DDD, lint, tipos) antes de cada commit; se activa con npm install.

  .githooks/pre-commit

• npm run verify

  Siete pasos en orden con resumen en logs/ultimo-resultado.txt; build:pages genera el sitio estático de este reporte.

  scripts/quality/verify.mjsscripts/deploy/build-pages.mjs