Configuración del proyecto (config.yaml)

Todos los campos de openspec/config.yaml: el esquema, el contexto y las reglas con las que planifica este proyecto.

Ubicación

Cada proyecto de OpenSpec guarda su archivo de configuración en openspec/config.yaml, en la raíz del proyecto.

Campos

Clave	Tipo	Obligatorio	Efecto
schema	string	Sí	El esquema de flujo de trabajo que siguen los cambios de este proyecto
context	string	No	Se inyecta en cada artefacto, en apply y en archive
rules	map: ID de artefacto → lista de strings	No	Reglas adicionales añadidas a la guía integrada de un artefacto
operations	map: operación → lista de guías	No	Guía orientativa para el trabajo de apply y archive
store	string	No	Raíz de OpenSpec de reserva cuando este openspec/ es solo configuración
references	list	No	Stores cuyos specs se indexan en las instrucciones

Los campos no válidos nunca hacen fallar un comando. Cada campo se valida por separado, y un valor incorrecto se descarta con una advertencia. Un archivo que no se puede leer o que no es YAML válido se ignora con una advertencia, excepto por openspec validate, que termina con código 1 para que CI lo detecte.

Qué escribir en estos campos se trata en Configuración del proyecto.

schema

El esquema de flujo de trabajo que sigue cada cambio de este proyecto. Los valores válidos son spec-driven o un nombre de esquema definido por el proyecto. Ejecuta openspec schemas para listar los nombres de esquema disponibles.

context

Texto libre que se inyecta en las instrucciones de cada artefacto y se proporciona a apply y archive. El límite es de 50 KB, y un valor mayor se ignora con una advertencia.

rules

Reglas adicionales para un artefacto, añadidas a la guía integrada del esquema:

rules:
  proposal:
    - Keep proposals under 500 words

Los ID de artefacto no están restringidos a los nombres integrados, por lo que los artefactos de esquemas personalizados funcionan como claves.

operations

Guía orientativa sobre cómo se lleva a cabo el trabajo de apply y archive, independiente de las reglas de artefacto:

operations:
  apply:
    guidance:
      - Keep test summaries concise

Solo se leen apply y archive.

store

Un id de store usado como raíz de OpenSpec, que solo se consulta cuando este directorio openspec/ es solo de configuración (sin specs/ ni changes/). Es un fallback, nunca una anulación. La secuencia completa está en Resolución de la raíz.

references

IDs de store cuyos specs utiliza el trabajo de este proyecto. Se añade un índice de los specs de cada store (id, resumen, comando de obtención) a la salida de las instrucciones. El contenido de los specs nunca se incluye en línea, y la resolución de la raíz nunca se ve afectada. Una entrada es un id de store o un map con id y una fuente de clonación remote opcional:

references:
  - platform-specs
  - id: billing-specs
    remote: git@github.com:acme/billing-specs.git

Ejemplo

Un config.yaml completo:

schema: spec-driven

context: |
  Designs and tasks must cover Windows, macOS, and Linux
  Write all artifacts in Spanish

rules:
  proposal:
    - Keep proposals under 500 words
    - Always state what is out of scope
  tasks:
    - Break tasks into chunks of max 2 hours

operations:
  apply:
    guidance:
      - Keep test summaries concise
  archive:
    guidance:
      - Summarize the archive outcome before finishing

Nombres heredados

openspec/config.yml se lee como alias cuando config.yaml no existe. Cuando ambos archivos existen, prevalece config.yaml y se ignora config.yml. openspec init crea config.yaml.