Personalización

OpenSpec ofrece tres niveles de personalización:

Nivel	Qué hace	Ideal para
Configuración de proyecto	Establecer valores predeterminados, inyectar contexto/reglas	La mayoría de los equipos
Esquemas personalizados	Definir tus propios artefactos de flujo de trabajo	Equipos con procesos únicos
Anulaciones globales	Compartir esquemas entre todos los proyectos	Usuarios avanzados

---

Configuración de proyecto

El archivo openspec/config.yaml es la forma más sencilla de personalizar OpenSpec para tu equipo. Te permite:

• Establecer un esquema predeterminado - Omitir --schema en cada comando
• Inyectar contexto del proyecto - La IA ve tu stack tecnológico, convenciones, etc.
• Agregar reglas por artefacto - Reglas personalizadas para artefactos específicos
• Agregar orientación por operación - Preferencias consultivas para el trabajo de apply y archive
• Recordar decisiones de integración - Por ejemplo, la opción de GitHub Copilot cloud coding agent

Configuración rápida

openspec init

Esto te guía paso a paso para crear una configuración de forma interactiva. O créala manualmente:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

Cómo funciona

Esquema predeterminado:

# Sin configuración
openspec new change my-feature --schema spec-driven

# Con configuración - el esquema es automático
openspec new change my-feature

Inyección de contexto y reglas:

Al generar cualquier artefacto, tu contexto y reglas se inyectan en el prompt de la IA:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• Contexto aparece en TODOS los artefactos
• Reglas solo aparecen para el artefacto correspondiente

Orientación de operaciones:

operations.apply.guidance y operations.archive.guidance son matrices opcionales de instrucciones consultivas sobre cómo un agente debe realizar esas operaciones. Son independientes de rules: la orientación de operaciones no restringe el contenido de los artefactos, y las reglas de artefactos nunca se reetiquetan como orientación de operaciones.

Apply y archive obtienen estas entradas en tiempo de ejecución:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

Ambas superficies devuelven el context actual del proyecto y la operationGuidance correspondiente como campos opcionales separados. Cada invocación lee una instantánea fresca desde la raíz resuelta. Cuando se selecciona --store <id>, el cambio, el contexto y la orientación provienen de ese almacén en lugar del repositorio actual. El comando de instrucciones de archive es de solo lectura: no inspecciona ni fusiona especificaciones delta, no escribe especificaciones principales, no mueve el cambio ni ejecuta el flujo de trabajo de archive estático.

El contexto del proyecto es una entrada obligatoria a nivel de prompt. Los flujos de trabajo generados lo leen y aplican los hechos, convenciones y restricciones relevantes del proyecto. La orientación de operaciones es un consejo opcional y aditivo: los flujos de trabajo consideran cada entrada y siguen las entradas que son aplicables y compatibles con el flujo de trabajo integrado.

Ambos campos permanecen separados del estado controlado por CLI, las rutas resueltas, los pasos integrados, las elecciones explícitas del usuario y las reglas de artefactos. Un flujo de trabajo informa conflictos de contexto preservando el valor controlador. No sigue orientación inaplicable o en conflicto y explica por qué. Ninguno de los dos campos es una verificación ejecutable, y los flujos de trabajo no copian su texto en archivos de implementación, especificaciones, artefactos de cambio o resúmenes, a menos que el usuario solicite ese contenido por separado.

Seguridad de entradas para archive y sincronización de especificaciones:

Archive, archive masivo y sincronización independiente utilizan artifactPaths.specs.existingOutputPaths de openspec status --json como la única fuente de especificaciones delta. Un esquema sin un artefacto specs, o un cambio cuya lista de salidas concretas esté vacía, no tiene nada que sincronizar; otros artefactos no se utilizan para inferir especificaciones delta.

Antes de que una fusión semántica escriba una especificación principal, el flujo de trabajo consume la salida actual de openspec instructions specs --change <name> --json. Las reglas specs devueltas restringen solo las especificaciones principales producidas por esa fusión. Un solo paso de archive pasa esa instantánea a la sincronización en línea, la sincronización independiente la obtiene directamente, y el archive masivo obtiene todas las instantáneas necesarias antes de su primera escritura de especificación. Una respuesta de instrucciones de archive/especificaciones con JSON no nulo o inválido es un fallo de consulta, no una entrada vacía: el flujo de trabajo se detiene antes de la escritura de la especificación afectada o del movimiento del cambio (para archive masivo, antes de cualquier escritura o movimiento por lotes).

Esta configuración no cambia las fases de ejecución de archive, los prompts del usuario, las operaciones del sistema de archivos, la propiedad de la fusión semántica, el comando directo openspec archive, ni la estructura y salida de las rules de artefactos.

Orden de resolución de esquemas

Cuando OpenSpec necesita un esquema, lo verifica en este orden:

1. Bandera de CLI: --schema <name>
2. Metadatos del cambio (.openspec.yaml en la carpeta del cambio)
3. Configuración del proyecto (openspec/config.yaml)
4. Predeterminado (spec-driven)

---

Esquemas personalizados

Cuando la configuración del proyecto no es suficiente, cree su propio esquema con un flujo de trabajo completamente personalizado. Los esquemas personalizados se encuentran en el directorio openspec/schemas/ de su proyecto y se controlan de versiones junto con su código.

your-project/
├── openspec/
│   ├── config.yaml        # Configuración del proyecto
│   ├── schemas/           # Los esquemas personalizados se encuentran aquí
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Sus cambios
└── src/

Clonar un esquema existente

La forma más rápida de personalizar es clonar un esquema integrado:

openspec schema fork spec-driven my-workflow

Esto copia todo el esquema spec-driven a openspec/schemas/my-workflow/, donde puede editarlo libremente.

Lo que obtiene:

openspec/schemas/my-workflow/
├── schema.yaml           # Definición del flujo de trabajo
└── templates/
    ├── proposal.md       # Plantilla para el artefacto de propuesta
    ├── spec.md           # Plantilla para especificaciones
    ├── design.md         # Plantilla para diseño
    └── tasks.md          # Plantilla para tareas

Ahora edite schema.yaml para cambiar el flujo de trabajo, o edite las plantillas para cambiar lo que genera la IA.

Crear un esquema desde cero

Para un flujo de trabajo completamente nuevo:

# Interactivo
openspec schema init research-first

# No interactivo
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Estructura del esquema

Un esquema define los artefactos de su flujo de trabajo y cómo dependen entre sí:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

Campos clave:

Campo	Propósito
id	Identificador único, usado en comandos y reglas
generates	Nombre del archivo de salida (admite globales como specs/**/*.md)
template	Archivo de plantilla en el directorio templates/
instruction	Instrucciones de IA para crear este artefacto
requires	Dependencias: qué artefactos deben existir primero

Liste los artefactos en el orden en que desea que se escriban. requires determina qué es posible; el orden de la lista artifacts: determina qué viene primero cuando varios artefactos están listos al mismo tiempo.

Plantillas

Las plantillas son archivos markdown que guían a la IA. Se inyectan en el prompt al crear ese artefacto.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Las plantillas pueden incluir:

• Encabezados de sección que la IA debe completar
• Comentarios HTML con orientación para la IA
• Formatos de ejemplo que muestran la estructura esperada

Validar su esquema

Antes de usar un esquema personalizado, valídalo:

openspec schema validate my-workflow

Esto verifica:

• La sintaxis de schema.yaml es correcta
• Todas las plantillas referenciadas existen
• No hay dependencias circulares
• Los IDs de artefactos son válidos

Usar su esquema personalizado

Una vez creado, use su esquema con:

# Especificar en el comando
openspec new change feature --schema my-workflow

# O establecer como predeterminado en config.yaml
schema: my-workflow

Depurar la resolución de esquemas

¿No está seguro de qué esquema se está usando? Verifique con:

# Ver desde dónde se resuelve un esquema específico
openspec schema which my-workflow

# Listar todos los esquemas disponibles
openspec schema which --all

La salida muestra si proviene de su proyecto, del directorio de usuario o del paquete:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Nota: OpenSpec también admite esquemas a nivel de usuario en ~/.local/share/openspec/schemas/ para compartir entre proyectos, pero se recomiendan los esquemas a nivel de proyecto en openspec/schemas/ ya que se controlan de versiones junto con su código.

---

Ejemplos

Flujo de trabajo de iteración rápida

Un flujo de trabajo mínimo para iteraciones rápidas:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Agregar un artefacto de revisión

Clone el esquema predeterminado y agregue un paso de revisión:

openspec schema fork spec-driven with-review

Luego edite schema.yaml para agregar:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

Esquemas de la comunidad

OpenSpec también admite esquemas mantenidos por la comunidad distribuidos a través de repositorios independientes. Estos proporcionan flujos de trabajo con opiniones que integran OpenSpec con otras herramientas o sistemas, de manera similar a cómo funciona el catálogo de extensiones de la comunidad de github/spec-kit para spec-kit.

Los esquemas de la comunidad no se incluyen en el núcleo de OpenSpec: se encuentran en sus propios repositorios con su propio calendario de lanzamientos. Para usar uno, copie el paquete del esquema al directorio openspec/schemas/<schema-name>/ de su proyecto (el README de cada repositorio tiene instrucciones de instalación).

Esquema	Mantenedor	Repositorio	Descripción
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Captura la intención del cambio, el comportamiento observable, el diseño técnico y las decisiones arquitectónicas duraderas antes de la implementación. Agrega un manifiesto de revisión de ADR local al cambio y escribe decisiones de larga vida calificadas como ADR inmutables y reemplazables.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	Integra la gobernanza de artefactos de OpenSpec con las habilidades de ejecución de obra/superpowers (lluvia de ideas, planes de escritura, TDD mediante subagentes, revisión de código, finalización). Agrega un artefacto retrospective basado en evidencia que cubre una brecha que Superpowers no cubre de forma nativa.
nanopm	@nmrtn	nmrtn/nanopm	Flujo de trabajo centrado en PM. Ejecuta la tubería de planificación de nanopm (auditoría → estrategia → hoja de ruta → PRD) aguas arriba de la implementación. Conecta la planificación de producto con el flujo de trabajo de ingeniería basado en especificaciones de OpenSpec. Los artefactos se leen de .nanopm/ si está presente: la propuesta toma la auditoría, el diseño toma la estrategia y las tareas toman el desglose del PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Runbooks de pruebas de extremo a extremo a nivel de capacidad. Cada capacidad obtiene una especificación inmutable, una plantilla de tareas inmutable y un registro de ejecución con marca de tiempo por ejecución. Las aserciones son solo comportamiento observable (código HTTP, cuerpo de respuesta, estado persistido — nunca subcadenas de registros); cada ejecución registra inicio/fin UTC, duración y consumo estimado de tokens de LLM.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	Flujo de trabajo basado en especificaciones con disciplina TDD y un paso de revisión adversarial. Flujo: proposal → specs → design → review → test-plan → tasks → apply → verify. review es escrito por un revisor de solo lectura con contexto fresco (un segundo modelo cuando está disponible) y emite una línea VERDICT: que le indica al agente que controle test-plan, tasks y apply; OpenSpec solo verifica que los artefactos existan, así que ejecute el control con su propio CI o hook. test-plan mapea cada escenario de especificación a una prueba nombrada y sirve como un libro de contabilidad rojo/verde que verify audita.

¿Desea contribuir con un esquema de la comunidad? Abra un issue con un enlace a su repositorio, o envíe un PR agregando una fila a esta tabla.

---

Ver también

• Referencia CLI: Comandos de esquema - Documentación completa de comandos