Configura tu proyecto

Añade OpenSpec a un proyecto: ejecuta init, mira lo que escribió y ajústalo.

Elige dónde vive OpenSpec

• En tu repositorio (el valor predeterminado): las especificaciones y los cambios se ubican junto al código que describen y se versionan con él. El resto de esta página sigue esta ruta.
• En un store: un repositorio de planificación separado compartido por los repositorios que lo usan, para configuraciones multi-repositorio o para mantener la planificación fuera del repositorio por completo. Stores (beta) cubre cuándo vale la pena y cómo configurar uno.

Inicializa tu proyecto

Con la CLI instalada (Instalación), ejecuta init en la raíz de tu proyecto. En tu terminal:

cd <your-project>
openspec init

Init pregunta qué herramientas de IA usas, escribe los archivos de flujo de trabajo para las que elijas e informa lo que obtuviste:

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Reinicia tu IDE para que los nuevos comandos surtan efecto.

Volver a ejecutar init es seguro:

• Las herramientas que ya configuraste muestran Refreshed en lugar de Created.
• Ejecutar init de nuevo con una nueva herramienta seleccionada añade esa herramienta.
• La opción --tools omite el selector (Referencia de la CLI).

Migra un project.md existente

Init no copia el openspec/project.md heredado en config.yaml. Conserva el archivo e imprime una solicitud de migración asistida por IA.

En tu chat de IA:

Review openspec/project.md and migrate its useful content to openspec/config.yaml.
Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
Move artifact-specific guidance into rules for the matching artifacts.
Move guidance for apply or archive into the matching operations entry.
Leave out generic, outdated, or verbose material. Do not delete project.md.

Revisa config.yaml y luego elimina project.md cuando estés listo.

Lo que init instala

Ejecutar init crea dos cosas en tu proyecto:

• Una carpeta openspec/ en la raíz del repositorio
• Archivos de flujo de trabajo (skills y comandos) añadidos a la carpeta de tu herramienta de IA (.agents/, .claude/, etc.)

Confirma todo como el resto de tu código fuente. Init no cambia nada más en tu repositorio (si encuentra restos de una versión anterior de OpenSpec, pregunta antes de limpiarlos).

La carpeta openspec/

Cada artefacto de OpenSpec vive aquí, en la raíz de tu proyecto. Así es como se ve:

openspec/
├── config.yaml     project settings and context for the AI
├── specs/          your specs (empty for now)
└── changes/        in-motion changes (empty for now)
    └── archive/    completed changes move here

Configuración del proyecto cubre config.yaml.

Los archivos de flujo de trabajo (skills y comandos)

Estos son los flujos de trabajo de OpenSpec, las acciones que usarás mientras trabajas. Aquí están como skills instalados, en la carpeta compartida .agents/ que la mayoría de las herramientas usan:

.agents/skills/
├── openspec-explore/              think through an idea first
├── openspec-propose/              propose a change
├── openspec-apply-change/         implement a change's tasks
├── openspec-update-change/        revise a change's plan
├── openspec-sync-specs/           sync a change's spec updates into specs/
├── openspec-archive-change/       move a finished change to the archive
├── openspec-verify-change/        check the implementation matches the plan (not included by default)
└── openspec-bulk-archive-change/  archive several changes at once (not included by default)

Este es el conjunto predeterminado más dos flujos de trabajo opcionales. Perfiles enumera los doce.

De forma predeterminada, cada flujo de trabajo se instala en dos formas:

• Skill (openspec-apply-change): instrucciones que tu agente adopta por sí mismo cuando pides el trabajo.
• Comando (/opsx:apply en Claude Code): un punto de entrada tipado para el mismo flujo de trabajo, bajo un nombre más corto.

Ambos son funcionalmente idénticos. El skill y el comando de un flujo de trabajo llevan las mismas instrucciones.

Por qué dos: los comandos vinieron primero, y cada herramienta los escribe a su manera. Los skills son el estándar más reciente compartido entre herramientas, pero no todas las herramientas pueden invocar un skill directamente, por lo que los comandos permanecen como punto de entrada de esas herramientas.

Algunas herramientas se instalan solo en forma de skill. Donde la herramienta ejecuta skills directamente, init omite los comandos y lo indica (Commands skipped for: codex (uses skills)).

Preferimos los skills y esperamos retirar los comandos eventualmente.

Cambia lo que se instala

El selector interactivo cambia la forma de entrega y el conjunto de flujos de trabajo (Perfiles). En tu terminal:

openspec config profile

Aquí se muestra el cambio a solo skills:

Current profile settings
  Delivery: both

? What do you want to configure? Delivery only
? Delivery mode (how workflows are installed): Skills only

Config changes:
  delivery: both -> skills
? Apply changes to this project now? (Y/n) y

Responder sí lo aplica al proyecto actual de inmediato. Otros proyectos lo adoptan en su próximo openspec update. La configuración es global, por máquina.

Claude Code no muestra los flujos de trabajo

Claude Code carga los flujos de trabajo de OpenSpec desde una o ambas de estas rutas del proyecto, según tu configuración de entrega:

• Skills: .claude/skills/openspec-*/SKILL.md
• Comandos: .claude/commands/opsx/<id>.md

Si faltan los archivos, actualiza el proyecto. En tu terminal:

openspec update

Si los archivos de comandos existen pero /opsx: no muestra comandos de OpenSpec, actualiza Claude Code y reinícialo. Si los comandos siguen sin cargarse, activa también los skills. En tu terminal:

openspec config set delivery both
openspec update

Reinicia Claude Code y luego ejecuta /openspec-propose en su chat. Si solo faltan algunos flujos de trabajo, cambia tu perfil.

La configuración está completa. El Inicio rápido lleva tu primer cambio desde aquí.