¿Qué hace imagine-it?
Convierte una especificación en un prototipo especulativo: un pequeño conjunto de archivos .html simples que muestran cómo podría verse una funcionalidad dentro de este producto. Es una pieza de conversación para que los humanos reaccionen, no código de producción, por lo que la velocidad y la plausibilidad priman sobre la completitud.
Entrada (todo opcional, cualquier orden): una URL de incidencia/PR o #123, una clave o URL de Jira, una ruta de archivo, texto libre, más banderas:
--wireframe— fuerza un esquema en escala de grises en lugar del estilo del repositorio.--out <dir>— directorio raíz de salida (por defecto.imagine-it/en la raíz del repositorio). La salida siempre va a<out>/<slug>/.--screens <n>— limita o fuerza el número de archivos de pantalla.--screenshot[=png|jpeg]— también captura imágenes de las pantallas (PNG por defecto).--states— con una captura de pantalla, captura todos los estados, no solo el inicial.--viewport <WxH>— tamaño de captura (por defecto 1440x900; 390x844 para productos mobile-first).--notes— captura con la superposición de notas de especificación activada (desactivada por defecto).
Sin entrada, la especificación es la conversación actual.
Flujo de trabajo
Ejecuta los pasos en orden. Cada uno produce un artefacto que el siguiente consume; mantenlos en tus notas de trabajo; solo el HTML se escribe en disco.
1. Digestión de la especificación
Obtén y destila la especificación en un resumen de especificación: título, slug, objetivo, actores, puntos de entrada, flujo principal, entidades con valores de muestra realistas, estados, criterios de aceptación numerados AC-1…, fuera de alcance, suposiciones, preguntas abiertas.
Cada vacío que llenes se convierte en una suposición; las decisiones que solo un humano puede tomar se convierten en preguntas abiertas. Sigue adelante: pregunta al usuario solo cuando no exista ninguna especificación en ningún lado (sin argumento, nada en la conversación).
Terminado cuando: cada campo del resumen está lleno (o explícitamente "ninguno") y cada AC está numerado. Detalles, obtención fuente por fuente y un ejemplo: references/context-intake.md.
2. Brief de diseño
Recorre el repositorio en modo solo lectura y escribe un brief de diseño: modo (hi-fi o wireframe), pila tecnológica, un bloque de tokens :root listo para pegar usando los nombres de variable canónicos, modo oscuro, shell de la aplicación, notas de componentes, 1–3 pantallas de referencia más cercanas a la funcionalidad, estilo de iconos, locale de la IU y los archivos fuente de los que todo proviene.
Si tu entorno admite subagentes, delega este recorrido a uno y toma solo el brief; si no, haz el recorrido en línea dentro del mismo presupuesto de lectura. El modo es wireframe cuando se pasa --wireframe o el repositorio no tiene una IU que imitar; di por qué en el brief. Luego actualiza los Puntos de entrada del resumen con las rutas/etiquetas reales encontradas.
Terminado cuando: el bloque de tokens usa cada nombre de variable canónico (a menos que sea wireframe: Tokens = ninguno) y cada grupo de tokens cita un archivo fuente. Matriz de detección de pila, dónde se esconden los tokens, nombres canónicos: references/design-discovery.md.
3. Plan de pantallas
Decide los archivos antes de escribir cualquier HTML: una tabla de # | archivo | propósito | estados | ACs cubiertos, en orden de flujo. Un archivo por vista distinta o superposición con mucho contenido; los estados (vacío, cargando, error, éxito…) viven como secciones dentro de su pantalla. Tantos como sea necesario, tan pocos como sea posible, típicamente 2–6.
Terminado cuando: cada AC aparece en la columna "ACs cubiertos" de al menos una fila. Reglas y un ejemplo: references/screen-planning.md.
4. Generar
Escribe en <out>/<slug>/:
index.html hub: resumen del resumen, flujo, cobertura de AC, suposiciones, preguntas abiertas, fuentes de diseño
styles.css tokens del brief de diseño + assets/base.css textual + estilos de componentes de la funcionalidad
ii.js copiado textual de assets/ii.js (barra de herramientas del prototipo: navegación, notas, estados, tema)
01-<pantalla>.html uno por cada fila del plan de pantallas
02-<pantalla>.html
Comienza desde assets/index-template.html y assets/screen-template.html; copia assets/base.css y assets/ii.js de esta carpeta de skill. Imita las pantallas de referencia: mismo shell, etiquetas de navegación, formas de componentes y tono de copia, en el lenguaje de IU del repositorio. Rellena con datos de dominio realistas. Marca cada elemento que cumple un AC con data-note="AC-n: …" y cada elección de diseño especulativa con data-note="NOTA: …".
La salida es HTML/CSS simple autocontenido con JavaScript vainilla pequeño, abierto directamente desde el disco: solo enlaces relativos, iconos SVG en línea, fuentes de respaldo del sistema para las fuentes del repositorio. Contrato completo de salida y lista de verificación previa a la entrega: references/html-conventions.md.
5. Verificar
Ejecuta la lista de verificación previa a la entrega en references/html-conventions.md. Terminado cuando cada elemento de la lista pasa; corrige y vuelve a verificar en caso contrario.
6. Capturar (solo con --screenshot)
Se omite por completo sin una bandera de captura de pantalla. De lo contrario, renderiza las pantallas planificadas (y el hub, al final) como imágenes en <out>/<slug>/screenshots/ y agrega una sección de Capturas de pantalla a index.html. Un problema de captura nunca bloquea la ejecución.
Terminado cuando: cada imagen planificada existe, no está vacía, tiene los bytes mágicos correctos y la primera imagen fue vista; las capturas omitidas se informan con el comando manual. Banderas, claro/oscuro, nomenclatura, escalera de herramientas y alternativas: references/screenshots.md.
7. Entregar
Responde con: la ruta a index.html, la tabla del plan de pantallas, las rutas de las capturas de pantalla (más las capturas omitidas y su comando manual), las suposiciones y preguntas abiertas, y una oferta para abrirlo (start en Windows, open en macOS, xdg-open en Linux). Si <out> está dentro del repositorio y ya no está ignorado, sugiere agregarlo a .gitignore.
Seguimientos: reconstruye el contexto desde <out>/<slug>/index.html (suposiciones, fuentes de diseño) y styles.css; no vuelvas a recorrer el repositorio; conserva el slug; actualiza index.html para que coincida; vuelve a ejecutar el paso 5 (y, si existían capturas de pantalla, vuelve a capturar las pantallas afectadas y el hub).