Habilidades
Cada habilidad de OpenSpec: argumentos, qué crea y con qué responde.
Las habilidades se agrupan en dos conjuntos:
- Núcleo: se instalan de forma predeterminada, el bucle principal de planificación.
- Opcionales: se instalan solo cuando los añades, mediante Perfiles.
Cada habilidad espera un proyecto que ya use OpenSpec. Antes de su primer paso que escriba algo, una habilidad comprueba que haya una raíz resuelta. Lo que ocurre cuando no la hay depende de cómo se haya invocado la habilidad:
- Seleccionada automáticamente: tu agente eligió la habilidad por su cuenta, sin que nombraras OpenSpec. Descarta OpenSpec y responde a tu solicitud con normalidad, como lo haría si OpenSpec no estuviera instalado.
- Solicitud explícita de OpenSpec: nombraste OpenSpec, nombraste la habilidad o ejecutaste su comando. Se detiene antes de escribir y pregunta cómo proceder: ejecutar
openspec initaquí, apuntar a un store con--store <id>o continuar sin OpenSpec. Espera tu respuesta.
Los comandos siempre corresponden al segundo caso. Un proyecto cuyo openspec/config.yaml nombra un store que esta máquina no puede resolver (no está registrado, o hay una línea store: mal formada) no se trata como no inicializado: la habilidad se detiene y muestra el error del store con su solución. Ninguna habilidad crea un directorio openspec/ por sí sola en ninguno de los dos casos. Las entradas a continuación describen qué hace cada habilidad una vez que hay una raíz disponible.
| Habilidad | Función | Tipo |
|---|---|---|
| openspec-explore | Analizar una idea antes de que se convierta en una propuesta de cambio | Núcleo |
| openspec-propose | Crear una propuesta de cambio con todos sus artefactos de planificación en un solo paso | Núcleo |
| openspec-apply-change | Implementar las tareas de una propuesta de cambio | Núcleo |
| openspec-update-change | Revisar el plan de una propuesta de cambio | Núcleo |
| openspec-sync-specs | Fusionar las actualizaciones de especificaciones de una propuesta de cambio en specs/ | Núcleo |
| openspec-archive-change | Mover una propuesta de cambio finalizada al archivo | Núcleo |
| openspec-new-change | Iniciar una propuesta de cambio como un esqueleto vacío | Opcional |
| openspec-continue-change | Crear el siguiente artefacto de planificación, de uno en uno | Opcional |
| openspec-ff-change | Crear una propuesta de cambio con todos los artefactos que necesita la implementación, en una sola pasada | Opcional |
| openspec-verify-change | Comprobar que la implementación coincide con el plan | Opcional |
| openspec-bulk-archive-change | Archivar varias propuestas de cambio a la vez | Opcional |
| openspec-onboard | Aprender el flujo de trabajo realizando una propuesta de cambio real de principio a fin | Opcional |
Cada entrada a continuación nombra la habilidad responsable del siguiente paso. Cuando tu perfil deja fuera esa habilidad, los archivos instalados nunca la nombran: el traspaso se convierte en el comando openspec equivalente, o en una solicitud directa para ti, y una línea que solo exista para señalar una habilidad ausente no se escribe en absoluto. Así, las habilidades que tienes siempre transfieren el control a habilidades que tienes. El conjunto que obtienes depende de Perfiles.
openspec-explore
Piensa en una idea antes de que se convierta en una propuesta de cambio.
| Contrato | Descripción |
|---|---|
| Argumentos | Un tema: una idea, un problema, una comparación o el nombre de una propuesta de cambio existente para explorar en contexto. Si no se proporciona nada, entra en modo de exploración. |
| Crea | Nada por defecto. Solo lee e investiga. Cuando se le solicita, captura insights: una nueva propuesta de cambio en openspec/changes/<name>/, o actualizaciones en la propuesta, diseño, especificaciones o tareas de una existente. Nunca genera código. |
| Respuesta | Una conversación abierta sin salida requerida. Cuando el pensamiento se cristaliza, resume el problema, el enfoque, las preguntas abiertas y los próximos pasos, y ofrece capturarlos. Tú decides. La implementación nunca comienza aquí. |
openspec-propose
Crea una propuesta de cambio y genera todos sus artefactos de planificación en un solo paso.
| Contrato | Descripción |
|---|---|
| Argumentos | Un nombre en kebab-case (add-dark-mode) o una descripción en lenguaje natural. Pregunta si no se proporciona ninguno de los dos. |
| Crea | openspec/changes/<name>/ con todos los artefactos que define el esquema, en orden de dependencia (orientado a especificaciones: propuesta, deltas de especificación, diseño, tareas). Nunca genera código. |
| Respuesta | Los artefactos creados, listos para revisión, y el siguiente paso. Se detiene ahí; la implementación espera a openspec-apply-change. |
openspec-apply-change
Implementa las tareas de una propuesta de cambio, avanzando por la lista hasta completarlas o quedar bloqueado.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio (add-auth), opcional. Si el objetivo es ambiguo, lista las propuestas de cambio activas y te pide que elijas una. |
| Crea | Código: los cambios mínimos que cada tarea requiere, en los archivos de tu proyecto. En la propuesta de cambio, marca cada tarea finalizada (- [ ] a - [x]) en el archivo rastreado identificado por sourcePath y line basado en uno. Un esquema puede rastrear tareas en múltiples archivos. |
| Respuesta | Progreso por tarea, luego un conteo general (N/M tareas completadas). Todo listo: sugiere openspec-archive-change. Bloqueado por artefactos faltantes: señala openspec-continue-change, o openspec status y openspec instructions cuando esa skill no está instalada (el perfil core la omite). Tareas poco claras o errores: pausa y pregunta. |
openspec-update-change
Revisa los artefactos de planificación existentes de una propuesta de cambio y mantenlos coherentes entre sí.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio, opcional, más la revisión que deseas. Sin una revisión especificada, ejecuta una revisión de coherencia: verifica los artefactos entre sí en busca de contradicciones, vacíos y duplicación. |
| Crea | Edita archivos de artefactos que ya existen. Una excepción: para un artefacto escrito como un glob, como specs/**/*.md, que ya tiene al menos un archivo, puede agregar un archivo complementario faltante una vez que confirmes la ruta. Un artefacto sin archivos todavía es tarea de openspec-continue-change. Sin esa skill (el perfil core la omite), señala openspec status y openspec instructions en su lugar. Nunca genera código. |
| Respuesta | Muestra cada revisión propuesta y la escribe solo después de tu confirmación, un artefacto a la vez. Termina con lo que se revisó y el siguiente paso; la implementación espera a openspec-apply-change. |
openspec-sync-specs
Fusiona las actualizaciones de especificación de una propuesta de cambio en specs/ sin archivarla.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio, opcional. También puedes nombrar un subconjunto de sus deltas de especificación, y solo esos se sincronizan. |
| Crea | Edita o crea openspec/specs/<capability-path>/spec.md para cada delta de especificación, fusionando requisitos agregados, modificados, eliminados y renombrados en la especificación principal. Nunca genera código. |
| Respuesta | Un resumen por capacidad de requisitos agregados, modificados, eliminados o renombrados, después de que las especificaciones actualizadas validen. La propuesta de cambio permanece activa; el archivado espera a openspec-archive-change. |
openspec-archive-change
Mueve una propuesta de cambio finalizada al archivo.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio, opcional. |
| Crea | Mueve la carpeta de la propuesta de cambio a openspec/changes/archive/YYYY-MM-DD-<name>/ (sin fecha agregada si el nombre ya comienza con una). Con tu aprobación, primero sincroniza los deltas de especificación pendientes. Cuando openspec-sync-specs está instalado, ejecuta ese flujo de trabajo. De lo contrario, fusiona los deltas de especificación en las especificaciones principales por sí mismo. Nunca genera código. |
| Respuesta | Advierte y pregunta antes de archivar con artefactos o tareas incompletas, y pregunta si sincronizar cuando existen deltas de especificación. Termina con un resumen: nombre, esquema, ubicación del archivo, estado de sincronización de especificaciones y advertencias. |
openspec-new-change
Inicia una propuesta de cambio como un scaffold vacío.
| Contrato | Descripción |
|---|---|
| Argumentos | Un nombre en kebab-case (add-user-auth) o una descripción en lenguaje natural, más un nombre de esquema solo para un flujo de trabajo no predeterminado. Pregunta qué quieres construir si no proporcionas ninguno de los dos. |
| Crea | openspec/changes/<name>/ como un scaffold vacío: sin artefactos todavía, nunca genera código. |
| Respuesta | El nombre y la ubicación del scaffold, la secuencia de artefactos del flujo de trabajo, el estado (0/N completados) y la plantilla del primer artefacto. La redacción de artefactos espera a openspec-continue-change. |
openspec-continue-change
Crea el siguiente artefacto de planificación en una propuesta de cambio, uno a la vez.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio, opcional. Si sigue siendo ambiguo, te pide que elijas entre las modificadas más recientemente. |
| Crea | El siguiente artefacto listo en la secuencia del esquema, escrito en la carpeta de la propuesta de cambio. Un artefacto por ejecución, nunca genera código. |
| Respuesta | El artefacto creado, progreso (N de M completados) y qué artefactos se desbloquearon. Cuando la planificación está completa, lo indica; la implementación pasa a openspec-apply-change. |
openspec-ff-change
Crea una propuesta de cambio y todos los artefactos de planificación que la implementación necesita, en una sola pasada.
| Contrato | Descripción |
|---|---|
| Argumentos | Un nombre en kebab-case o una descripción en lenguaje natural. Pregunta si no se proporciona ninguno. Si la propuesta de cambio nombrada ya existe, sugiere continuarla en su lugar. |
| Crea | openspec/changes/<name>/ y todos los artefactos de planificación que la implementación requiere, en orden de dependencia (orientado a especificaciones: propuesta, especificaciones, diseño, tareas), omitiendo solo los artefactos marcados como omitidos o condicionales. Nunca genera código. |
| Respuesta | El nombre y la ubicación de la propuesta de cambio, cada artefacto creado y cualquier artefacto condicional omitido y por qué. Se detiene ahí; la implementación espera a openspec-apply-change. |
openspec-verify-change
Verifica que la implementación coincida con los artefactos de la propuesta de cambio.
| Contrato | Descripción |
|---|---|
| Argumentos | El nombre de una propuesta de cambio, opcional. Cuando es ambiguo, pregunta, listando las propuestas de cambio que tienen un artefacto de tareas. |
| Crea | Nada. Lee los artefactos de la propuesta de cambio y la base de código. La verificación es solo un informe. |
| Respuesta | Un informe: una tarjeta de puntuación para Completitud, Corrección y Coherencia, luego problemas CRÍTICOS, ADVERTENCIA y SUGERENCIA con recomendaciones, y una evaluación final de preparación para archivar. No cambia nada y no archiva. |
openspec-bulk-archive-change
Archiva varias propuestas de cambio a la vez.
| Contrato | Descripción |
|---|---|
| Argumentos | Ninguno. Lista las propuestas de cambio activas y te pide que selecciones cualquier cantidad, con una opción para todas. Si ninguna está activa, lo indica y se detiene. |
| Crea | openspec/changes/archive/YYYY-MM-DD-<name>/ por cada propuesta de cambio archivada (los nombres ya fechados conservan su prefijo). Los deltas de especificación de cada una se sincronizan primero mediante openspec-sync-specs. Nunca genera código. |
| Respuesta | Una tabla de estado por propuesta de cambio y una confirmación para todo el lote, luego un resumen de archivadas, omitidas y fallidas, además de los resultados de sincronización de especificaciones. Cuando dos propuestas de cambio tocan la misma especificación, verifica la base de código y sincroniza los deltas implementados de más antigua a más reciente. |
openspec-onboard
Aprende el flujo de trabajo realizando una propuesta de cambio real de principio a fin.
| Contrato | Descripción |
|---|---|
| Argumentos | Ninguno. Escanea tu base de código en busca de tareas pequeñas para comenzar y te pide que elijas una o describas la tuya propia. |
| Crea | Una propuesta de cambio real para la tarea elegida, un artefacto a la vez, y luego código real una vez que confirmes la implementación. Archiva la propuesta de cambio al final. |
| Respuesta | Un recorrido narrado del ciclo completo con pausas para tu input: explorar, crear, construir cada artefacto, implementar, archivar. Termina con un resumen y un puntero a openspec-propose. Toma aproximadamente 15 a 20 minutos. |