Speccanvas

Usa esta habilidad para producir y mantener artefactos de Spec Canvas como especificaciones YAML portátiles o para persistirlos a través de un servidor MCP de SpecCanvas configurado.

Trata la especificación como la fuente de verdad para la estructura y la intención. Favorece especificaciones compactas y reutilizables que puedan pegarse en Spec Canvas, un IDE, un agente de terminal o un repositorio sin necesidad de explicaciones adicionales.

Usa los archivos YAML de descripción de formato incluidos en esta habilidad como guía de escritura. Usa las copias del esquema JSON incluidas en esta habilidad junto con la lógica de validación local como verificación posterior.

Filosofía Central

Las especificaciones de Spec Canvas son un puente compacto entre la intención del producto y la implementación. Deben ayudar a los agentes y humanos a acordar la forma del producto antes de los cambios de código, pero no deben convertirse en un registro continuo de cada ajuste de CSS, diseño o componente.

La especificación de UI describe la intención y la estructura. Captura pantallas, bloques principales, navegación, tareas clave del usuario, estados importantes y estructura responsiva significativa.
La especificación de datos describe el dominio lógico. Captura entidades, campos, enumeraciones, relaciones y restricciones de dominio; evita detalles físicos de base de datos o framework.
Spec-first se aplica a cambios semánticos. Actualiza las especificaciones antes de la implementación cuando la solicitud cambia el significado del producto, los recorridos del usuario o la estructura del dominio.
Los micro-cambios de implementación pueden omitir la especificación. Si la solicitud es cosmética, solo de diseño o invisible para los usuarios, cambia la implementación directamente y deja la especificación intacta.
Especificaciones compactas son mejores especificaciones. Prefiere declaraciones de propósito breves que expliquen por qué existe una pantalla o bloque sobre prosa de implementación sobre cómo se construye.

Puerta de Granularidad

Antes de editar una especificación de UI, decide si el cambio solicitado es lo suficientemente semántico como para pertenecer a la especificación.

Actualiza la especificación de UI cuando la solicitud cambia:

pantallas, grupos de pantallas o bloques principales;
recorridos del usuario, navegación, puntos de entrada o acciones disponibles;
estados importantes orientados al usuario, modos, permisos o flujos de vacío/error/recuperación;
el propósito o comportamiento de un componente importante;
estructura responsiva significativa, como experiencias distintas de escritorio/móvil;
terminología o etiquetas del producto cuando su significado cambia;
límites entre áreas públicas, de administración, editor, reproductor, incorporación o similares del producto.

No actualices la especificación de UI para micro-ajustes de implementación:

espaciado: padding, margin, gap, line-height;
tamaños exactos: valores de píxeles, font-size, width/height a menos que expresen intención de diseño de alto nivel;
clases CSS, clases de Tailwind, nombres de componentes, nombres de archivo o estructura específica del framework;
colores exactos, degradados, sombras, border-radius, iconos o estilo decorativo;
alineación local, orden, ajuste de línea o reflujo cosmético dentro de un bloque ya descrito;
tiempos de animación, tiempos de debounce, segundos de fundido cruzado, posiciones de toast, mecánicas de spinner de carga;
detalles de implementación del navegador/plataforma a menos que sean una capacidad central orientada al usuario;
ediciones locales de copia que no cambien el significado;
refactorizaciones invisibles para los usuarios.

Si el usuario solicita un micro-cambio cosmético o de diseño, realiza el cambio de código directamente y evita explícitamente tocar la especificación de UI.

Ubicación de Archivos por Defecto

A menos que el usuario solicite explícitamente una ubicación diferente, crea y actualiza los archivos de Spec Canvas en la raíz del proyecto bajo spec/.

Ruta de la especificación de UI: spec/ui-spec.yaml
Ruta de la especificación de datos: spec/data-spec.yaml

Si el directorio spec/ no existe, créalo. Cuando solo se solicite un artefacto, crea solo el archivo correspondiente.

Modo MCP

Usa el servidor MCP configurado llamado speccanvas cuando el usuario pida trabajar con un proyecto, documento, revisión, implementación o archivo en vivo de SpecCanvas, o cuando las herramientas MCP estén claramente disponibles en el entorno.

Si MCP está disponible, lee references/mcp-workflow.md antes de crear o actualizar datos en vivo de SpecCanvas.
Si la tarea crea o actualiza una especificación de UI, lee también references/ui-spec-workflow.md.
Si la tarea crea una implementación de pantalla, lee también references/implementation-workflow.md.
Si MCP no está disponible, no inventes detalles de conexión. Trabaja con archivos YAML portátiles o pide al usuario que configure el servidor MCP speccanvas.
No almacenes URLs de MCP, tokens de portador, hosts de preparación o secretos locales en esta habilidad. Estos pertenecen a la configuración MCP del agente y las variables de entorno.

Regla de Identidad del Modelo MCP

Al guardar una implementación de pantalla creada por un agente a través de MCP, proporciona siempre una identidad de modelo estable como { identityKey, provider, model, version }.

Resuelve el modelo activo desde las reglas globales del agente, las variables de entorno o la sesión actual antes de llamar a add_implementation.
Para add_implementation, pasa modelIdentity directamente. No lo reemplaces con agentName.
agentName es solo un fallback manual/heredado. Úsalo solo con modelIdentity: null cuando la implementación sea subida por un humano o la identidad del modelo no esté disponible intencionalmente.
Si el modelo activo es desconocido, ambiguo o no está registrado, detente y pide aclaración en lugar de guardar silenciosamente con agentName.

Flujo de Trabajo

Identifica el límite del artefacto. Determina si la tarea necesita:

Solo especificación de UI
Solo especificación de datos
Ambas especificaciones
Explicación, revisión, limpieza o validación de una especificación existente
Ningún cambio de especificación porque la solicitud es un micro-ajuste de implementación
Persistencia MCP en vivo para proyectos, especificaciones, revisiones, implementaciones o archivos

Aplica la puerta de granularidad. Para trabajo de UI, decide si la solicitud cambia la intención/estructura del producto o solo detalles de implementación. Si es solo un micro-ajuste, deja la especificación intacta.
Reúne material fuente. Usa solo las entradas que definen la estructura:

idea del producto o solicitud de funcionalidad
capturas de pantalla o descripciones de UI existentes
estructura del código base
especificación YAML actual
listas de entidades, notas de API o reglas de dominio

Lee las referencias de flujo de trabajo y formato requeridas.

Para creación o revisión de especificación de UI, lee references/ui-spec-workflow.md.
Para creación de implementación de pantalla, lee references/implementation-workflow.md.
Para persistencia MCP en vivo, lee references/mcp-workflow.md.
Para redacción de especificación de UI, lee references/ui-spec-format-0-0-3.yaml.
Para redacción de especificación de datos, lee references/data-spec-format-0-0-1.yaml.
Para comportamiento de validación local y heurísticas de revisión, lee references/workflow.md, references/validation-rules-ui.md y references/validation-rules-data.md según sea necesario.
Los esquemas incluidos actuales están en schemas/ui-spec.schema.json y schemas/data-spec.schema.json.

Redacta o revisa la especificación. Mantén el documento YAML válido y dentro de los campos del formato. No inventes secciones personalizadas de nivel superior a menos que el formato lo permita explícitamente. Haz la actualización semántica más pequeña que preserve la intención; no expandas la especificación con notas de implementación a nivel de píxeles.
Valida el resultado. Si scripts/validate-spec.mjs está disponible, ejecútalo contra el YAML final antes de devolver el resultado. Corrige los errores de validación antes de devolver la especificación.
Devuelve el resultado. Devuelve YAML validado o, para tareas de revisión, primero los problemas y luego el fragmento o archivo corregido.

Reglas Principales

Usa el archivo de formato como fuente de escritura

Los archivos YAML de descripción de formato son la referencia principal de redacción para esta habilidad. Sigue su estructura, nombres de campos, ejemplos y guía primero. Para la especificación de UI, references/ui-spec-format-0-0-3.yaml es la fuente de verdad local actual y se espera que permanezca alineada con el esquema y validador incluidos.

Usa la validación de esquema como verificación posterior

La validación de esquema no es la guía de escritura. Es el paso de verificación final.

Escribe la especificación desde el archivo de formato.
Valida la especificación escrita con scripts/validate-spec.mjs.
Corrige los fallos de esquema y reglas de validación antes de devolver el YAML final.

Los esquemas incluidos en schemas/ deben mantenerse sincronizados con la implementación de Spec Canvas y con las referencias de descripción de formato en esta habilidad. Si parecen diferir, trátalo como un error de la habilidad y señálalo explícitamente en lugar de inventar silenciosamente un compromiso.

Mantén la UI y los datos alineados

Cuando ambas especificaciones existan:

iguala los nombres entre pantallas, entidades y acciones
asegura que las acciones de la UI impliquen entidades o flujos de trabajo reales
asegura que las relaciones de la especificación de datos soporten la estructura de la UI
señala las brechas en lugar de inventar silenciosamente conceptos de backend

Mantén el formato portátil

Produce archivos YAML simples que puedan vivir en un repositorio y ser reutilizados por cualquier agente. No hagas que la especificación dependa del estado de la UI de Spec Canvas, metadatos ocultos o suposiciones solo del chat.

Mantén la especificación de UI por encima del detalle de implementación

No uses la especificación de UI como reemplazo de CSS, documentación de componentes o registros de cambios. Un buen purpose explica para qué sirve la pantalla o el bloque desde el punto de vista del usuario. No debe enumerar espaciado exacto, nombres de clases, tamaños de píxeles, mecánicas de implementación transitorias o cada pequeño control si esos detalles no cambian el significado del producto.

Patrones de Tareas

Crear una nueva especificación de UI

Comienza con docType, format_version y metadata.
En la especificación de UI, metadata.description es obligatorio y debe llevar la intención del producto a nivel superior.
Agrega screens tan pronto como se conozca la forma principal de la aplicación.
Agrega blocks cuando el usuario quiera estructura visible; blocks puede omitirse en la etapa de exploración.
Agrega templates, navigation o campos responsivos solo cuando ayuden materialmente.
La creación responsiva de UI soportada por el formato local actual incluye metadata.breakpoints, screen.template adaptable, block.columns adaptable y block.visible.
Preserva las convenciones del archivo de formato original, incluyendo la guía de comillas del archivo de formato de UI.
Valida el archivo completado con scripts/validate-spec.mjs cuando esté disponible.

Crear una nueva especificación de datos

Describe el modelo de dominio lógico, no la base de datos física.
Agrega enums solo cuando los vocabularios controlados compartidos importen.
Define entities con fields con significado de negocio.
Usa relations para estructura lógica entre entidades.
Evita filtrar preocupaciones solo de implementación como índices, migraciones o sintaxis específica de ORM a menos que el usuario las solicite explícitamente fuera de la especificación.
Valida el archivo completado con scripts/validate-spec.mjs cuando esté disponible.

Revisar o reparar una especificación existente

Verifica:

campos inválidos o no soportados
secciones obligatorias faltantes
referencias rotas de pantalla, plantilla o navegación
errores de enumeración, clave foránea o relación en la especificación de datos
fallos de validación personalizados surgidos por las reglas de validación locales
desajustes entre el esquema-formato y la implementación local actual
texto de purpose demasiado detallado que describe mecánicas de implementación en lugar de intención del producto

Al reparar, preserva la intención original del producto y haz la corrección más pequeña que restaure la claridad.

Compactar una especificación de UI demasiado detallada

Mantén estables los IDs de pantalla, plantilla, región y bloque existentes a menos que la estructura del producto cambie realmente.
Reemplaza párrafos largos de purpose con resúmenes de una oración de la intención orientada al usuario.
Preserva pantallas, bloques principales, navegación, estados importantes y modos significativos.
Elimina microdetalles de CSS/diseño, peculiaridades de plataforma, tiempos exactos, comportamiento de registro y mecánicas internas de componentes.
Evita el reformateo completo del archivo YAML; usa ediciones dirigidas para que los diffs sigan siendo revisables.
Valida después de editar.

Reconstruir una especificación desde una aplicación existente

infiere pantallas a partir de flujos de trabajo visibles
infiere bloques a partir de regiones repetidas y tareas del usuario
infiere entidades a partir de sustantivos de dominio y cambios de estado
separa lo observado de lo supuesto
señala la incertidumbre explícitamente cuando el material fuente está incompleto

Validación

Usa scripts/validate-spec.mjs cuando esté disponible.

Entrada: ruta a un archivo de especificación YAML
Detecta el tipo de documento a partir de docType
Valida contra el esquema JSON incluido de esta habilidad
Ejecuta las reglas de validación personalizadas relevantes
Trata las advertencias como consultivas
Trata los errores como bloqueantes para la salida final cuando estás devolviendo una especificación corregida

Si el script no puede ejecutarse porque faltan las dependencias locales de Spec Canvas, indícalo brevemente y recurre a la revisión manual usando el archivo de formato más las referencias de reglas de validación.

Expectativas de Salida

Al devolver especificaciones:

proporciona YAML válido
mantén los IDs en snake_case donde el formato lo espere
mantén los nombres de campo exactamente como los define el archivo de formato
menciona las suposiciones cuando afecten materialmente la estructura
menciona si se ejecutó la validación

Al devolver una revisión en lugar de un archivo reescrito:

lista primero los problemas estructurales
luego proporciona correcciones concretas
luego proporciona un fragmento corregido o la especificación completa si es útil

speccanvas / lienzo-de-especificaciones

¿Qué es lienzo-de-especificaciones?

Preguntar en tu IA favorita

Documentación