Esquemas

Cambia lo que produce OpenSpec: los artefactos, su orden y sus plantillas.

Un esquema define lo que produce una propuesta de cambio: qué artefactos, en qué orden, desde qué plantillas. Por ejemplo, spec-driven, el esquema incluido por defecto, produce estos cuatro aproximadamente en este orden, cada uno basándose en el anterior:

proposal → specs → design → tasks

Haz un fork de un esquema cuando quieras que estos sean documentos diferentes, ya sea que signifique menos de ellos, nombres diferentes o una estructura diferente.

Dónde residen los esquemas

OpenSpec busca un esquema en tres lugares, en orden, y usa el primero que encuentra:

1. Tu proyecto: openspec/schemas/, incluido en el repositorio para que todo tu equipo lo tenga.
2. Tu máquina: ~/.local/share/openspec/schemas en macOS y Linux (o bajo $XDG_DATA_HOME si lo configuras), o %LOCALAPPDATA%\openspec\schemas en Windows. Los esquemas aquí están disponibles en todos los proyectos en los que trabajes.
3. El paquete: los esquemas incorporados, como spec-driven, se incluyen en el propio openspec.

El mismo nombre puede existir en más de un lugar, y la ubicación más específica prevalece. openspec schema which muestra qué copia está en uso:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

Qué contiene un esquema

Un esquema se define mediante una carpeta de archivos simples: un schema.yaml que declara los artefactos, y una plantilla para cada uno. Aquí está el spec-driven incorporado:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: declara cada artefacto, el archivo que genera, la plantilla de la que parte, lo que requiere previamente y la instrucción que recibe el agente al crearlo. El contrato de cada campo está en schema.yaml.
• templates/: un esqueleto markdown por artefacto, que el agente rellena.

Aquí está la entrada del artefacto tasks en schema.yaml, recortada:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Lista de verificación de implementación con tareas rastreables
    template: tasks.md
    instruction: |
      ...lo que se le dice al agente al crear tasks.md...
    requires:
      - specs
      - design

Los esquemas incorporados se distribuyen dentro del paquete openspec, por lo que nunca los editas en su lugar. Obtienes tu propia copia haciendo un fork.

Crear tu propio esquema personalizado

Hay dos formas de obtener tu propio esquema:

1. Haz un fork de un esquema existente y edita tu copia. Empieza aquí cuando un esquema existente se acerca a lo que quieres, porque todo en él ya funciona.
2. Empieza desde cero cuando ninguno encaje, creando un esquema vacío con openspec schema init.

Hacer un fork de un esquema existente

1. Haz un fork del esquema del que quieras partir, ejecutando desde la raíz de tu proyecto:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   Pasa un segundo argumento para elegir el nombre (openspec schema fork spec-driven team-flow). Los nombres están en kebab-case.

2. Edita la copia: schema.yaml y las plantillas. Editar tu fork cubre qué cambiar.

3. Valídalo:

   openspec schema validate spec-driven-custom

   Este es el comando que detecta un esquema roto (plantillas faltantes, YAML incorrecto, ciclos de dependencia) antes de que estés en medio de un cambio.

4. Apunta tu proyecto a él en openspec/config.yaml. Este paso es tuyo porque fork deja config.yaml intacto:

   schema: spec-driven-custom

5. Las nuevas propuestas de cambio ahora siguen tu esquema. Los cambios creados anteriormente mantienen el esquema con el que empezaron.

Para reemplazar el predeterminado en todas partes sin tocar config.yaml, haz un fork con el mismo nombre: openspec schema fork spec-driven spec-driven. La copia de tu proyecto entonces sombrea al incorporado, como se explica en Dónde residen los esquemas.

Empezar desde cero

openspec schema init genera un nuevo esquema en lugar de copiar uno:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

El andamio está desnudo. Los artefactos provienen solo de los cuatro identificadores incorporados, y las plantillas generadas no contienen instrucciones, por lo que el agente recibe menos orientación hasta que escribas las tuyas. A partir de ahí, los pasos de fork se aplican sin cambios: valídalo, luego apunta config.yaml a él.

Editar tu fork

Un fork tiene dos tipos de archivos para editar:

• templates/ cambian el esqueleto de cada documento. Añade una sección a la plantilla de tareas y cada nuevo tasks.md empezará con ella. Mantén el título # en la primera línea: el artefacto lo hereda, por lo que cada archivo generado se abre como un documento titulado.
• schema.yaml cambia el flujo de trabajo en sí: qué artefactos existen, qué requiere cada uno previamente y la instrucción que recibe el agente al crearlo.

Por ejemplo, para eliminar el documento de diseño para un flujo más ligero:

1. Elimina la entrada design de schema.yaml.

2. Elimina design de la lista requires de tasks.

3. Valida:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

Omite el paso 2 y la validación lo detecta:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

Valida después de cada edición manual. Un esquema roto aparece en medio de un cambio, cuando un flujo de trabajo pide un archivo que no existe. Al igual que config.yaml, las ediciones del esquema llegan al agente en la siguiente ejecución.

Un fork es una instantánea

openspec update actualiza las habilidades y comandos instalados, y nunca toca openspec/schemas/. Tu fork sigue funcionando exactamente como lo dejaste, lo que también significa que deja de recibir mejoras cuando el esquema incorporado evoluciona. Para recogerlas más tarde, haz un fork del incorporado de nuevo con un nuevo nombre y traslada las diferencias.

Compartir esquemas

Compartir un esquema significa copiar su carpeta.

• Con tu equipo: sube openspec/schemas/ al repositorio y todos en él lo usarán.
• Entre tus proyectos: coloca la carpeta en el directorio de nivel de usuario de Dónde residen los esquemas.
• De la comunidad: el catálogo de la comunidad lista esquemas compartidos. Copia uno en openspec/schemas/<nombre> y funcionará como el tuyo.

Estamos trabajando en un registro de esquemas, público y privado, para que los esquemas se puedan instalar por nombre en lugar de copiarlos manualmente.

Usar OpenSpec con Superpowers

El esquema superpowers-bridge, mantenido por la comunidad, conecta los artefactos de OpenSpec con las habilidades de ejecución de Superpowers. Sigue las notas de instalación y compatibilidad del puente antes de copiarlo en tu proyecto.

El puente se publica fuera de OpenSpec. OpenSpec no prueba ni versiona su integración con Superpowers.