OpenSpec

Glosario ​

Cada término de OpenSpec en un solo lugar, definido en lenguaje sencillo. Léelo una vez y el resto de la documentación se lee más rápido.

Los términos están agrupados por tema y alfabetizados dentro de cada grupo.

Los sustantivos centrales ​

Spec (Especificación). Un documento que describe cómo se comporta parte de tu sistema. Las especificaciones viven en openspec/specs/, están organizadas por dominio y están compuestas de requisitos y escenarios. La especificación es la respuesta acordada a "¿qué hace este software?". Consulta Conceptos.

Fuente de verdad. El directorio openspec/specs/ en su conjunto. Contiene el comportamiento actual y acordado de tu sistema. Los cambios proponen ediciones a él; el archivado las aplica.

Cambio. Una unidad de trabajo, empaquetada como una carpeta bajo openspec/changes/<nombre>/. Un cambio contiene todo sobre ese trabajo: su propuesta, diseño, tareas y las ediciones de especificación que introduce. Un cambio, una característica o corrección.

Artefacto. Un documento dentro de un cambio. Los artefactos estándar son la propuesta, las especificaciones delta, el diseño y las tareas. Se crean en orden de dependencia y se alimentan entre sí.

Especificación delta. Una especificación dentro de un cambio que describe solo lo que está cambiando, usando secciones ADDED, MODIFIED y REMOVED, en lugar de reafirmar toda la especificación. Esto es lo que permite a OpenSpec editar sistemas existentes de manera limpia. Consulta Conceptos.

Dominio. Una agrupación lógica para especificaciones, como auth/, payments/ o ui/. Eliges dominios que coincidan con cómo piensas sobre tu sistema.

Dentro de una especificación ​

Requisito. Un comportamiento único que el sistema debe tener, generalmente escrito con una palabra clave RFC 2119: "El sistema DEBE expirar las sesiones después de 30 minutos". Los requisitos establecen el qué, no el cómo.

Escenario. Un ejemplo concreto y comprobable de un requisito en acción, típicamente en formato Dado/Cuando/Entonces. Los escenarios hacen que un requisito sea verificable: podrías escribir una prueba automatizada a partir de uno.

Palabras clave RFC 2119. Las palabras DEBE, DEBERÍA, y PUEDE, que tienen un significado estandarizado sobre cuán estricto es un requisito. DEBE y DEBERÍA son absolutos. DEBERÍA es recomendado con espacio para excepciones. PUEDE es opcional. El nombre proviene del documento de estándares de internet que las definió.

Los artefactos ​

Propuesta (proposal.md). El por qué y qué de un cambio: su intención, alcance y enfoque de alto nivel. El primer artefacto que creas.

Diseño (design.md). El cómo: enfoque técnico, decisiones de arquitectura y los archivos que esperas tocar. Opcional para cambios simples.

Tareas (tasks.md). La lista de verificación de implementación, con casillas de verificación. La IA la recorre durante /opsx:apply y marca las casillas a medida que avanza.

El ciclo de vida ​

Archivar. El acto de finalizar un cambio. Sus especificaciones delta se fusionan en las especificaciones principales, y la carpeta del cambio se mueve a openspec/changes/archive/YYYY-MM-DD-<nombre>/. Después de archivar, tus especificaciones describen la nueva realidad. Consulta Conceptos.

Sincronizar. Fusionar las especificaciones delta de un cambio en las especificaciones principales sin archivar el cambio. Generalmente automático (el archivado ofrece hacerlo), pero disponible por sí solo como /opsx:sync para cambios de larga duración. Consulta Comandos.

Flujo de trabajo y comandos ​

OPSX. El flujo de trabajo estándar actual de OpenSpec, construido alrededor de acciones fluidas en lugar de fases rígidas. Sus comandos de barra comienzan todos con /opsx:. Consulta Flujo de trabajo OPSX.

Comando de barra. Un comando que escribes en el chat de tu asistente de IA, como /opsx:propose. Los comandos de barra impulsan el flujo de trabajo. No son comandos de terminal. Consulta Cómo funcionan los comandos.

Explorar (/opsx:explore). El comando compañero de pensamiento. Lee tu código base, compara opciones y aclara una idea difusa en un plan concreto, sin crear artefactos ni escribir código. El punto de partida recomendado siempre que tengas un problema pero aún no un plan. Consulta Explora primero.

CLI. El programa openspec que ejecutas en tu terminal. Configura proyectos, lista y valida cambios, abre el panel de control y archiva. La mitad de terminal de OpenSpec. Consulta CLI.

Habilidad (Skill). Una carpeta de instrucciones (.../skills/openspec-*/SKILL.md) que tu asistente de IA detecta automáticamente y sigue. Las habilidades son el estándar emergente entre herramientas para entregar el flujo de trabajo de OpenSpec a tu asistente.

Archivo de comando. Un archivo de comando de barra por herramienta (.../commands/opsx-*). El mecanismo de entrega más antiguo, aún compatible junto con las habilidades. Rara vez los tocas directamente.

Perfil. El conjunto de comandos de barra instalados en tu proyecto. Core (el predeterminado) es propose, explore, apply, update, sync, archive. El conjunto expandido añade new, continue, ff, verify, bulk-archive, onboard. Cámbialo con openspec config profile.

Entrega. Si OpenSpec instala habilidades, archivos de comando o ambos para tus herramientas. Se configura globalmente y se aplica con openspec update.

Personalización ​

Esquema. La definición de qué artefactos tiene un flujo de trabajo y cómo dependen entre sí. El predeterminado integrado es spec-driven (propuesta → especificaciones → diseño → tareas). Puedes bifurcarlo o escribir el tuyo propio. Consulta Personalización.

Plantilla. Un archivo Markdown dentro de un esquema que da forma a lo que la IA genera para un artefacto dado. Editar una plantilla cambia la salida de la IA inmediatamente, sin reconstrucción.

Configuración del proyecto (openspec/config.yaml). Configuración por proyecto: el esquema predeterminado, el context: inyectado en cada solicitud de planificación y rules: por artefacto. La forma más fácil de enseñar a OpenSpec sobre tu stack y convenciones. Consulta Personalización.

Inyección de contexto. Poner los antecedentes del proyecto en el campo context: de config.yaml para que se agreguen automáticamente a cada artefacto que la IA genere. Más confiable que esperar que la IA lea un archivo separado.

Grafo de dependencias. El grafo dirigido formado por las relaciones de requires: de los artefactos. Es un DAG (grafo acíclico dirigido: las flechas solo apuntan hacia adelante, nunca en un bucle), y OpenSpec lo usa para saber qué puedes crear a continuación.

Habilitadores, no barreras. El principio de que las dependencias de artefactos muestran qué se vuelve posible a continuación, no qué es requerido a continuación. Puedes revisar y editar cualquier artefacto en cualquier momento. Consulta Conceptos centrales de un vistazo.

Coordinación entre repos (beta) ​

Estos términos se aplican solo si tu planificación abarca más de un repositorio. Están en beta. La mayoría de los usuarios pueden ignorarlos. Consulta la Guía de usuario de Stores.

Store (Almacén). Un repositorio independiente cuyo único trabajo es la planificación. Tiene la misma forma de openspec/ que ya conoces (especificaciones y cambios) más un pequeño archivo de identidad. Lo registras en tu máquina una vez, por nombre, y luego cualquier comando de OpenSpec puede trabajar en él desde cualquier lugar.

Referencia. Una declaración, en openspec/config.yaml de un repositorio de código, de un store del que ese repositorio se nutre. Las referencias son de solo lectura: el repositorio mantiene su propia raíz, y openspec instructions gana un índice de las especificaciones del store referenciado, cada una con el comando exacto para obtenerlo.

Contexto de trabajo. Lo que openspec context ensambla para el repositorio actual: su raíz de OpenSpec más cada store al que referencia, cada uno con cómo obtenerlo. La respuesta a "¿con qué estoy trabajando?".

Conjunto de trabajo (Workset). Un conjunto personal y local de la máquina de carpetas que abres juntas (un store junto con los repositorios de código en los que trabajas). Se crea explícitamente con openspec workset create; nada de esas rutas locales se compromete en el repositorio de planificación compartido.

Ver también ​