Extiende GitHub Spec Kit: agrega los modos Explore y Alternatives-Review

GitHub Spec Kit te lleva de una idea a la implementación con un flujo de comandos bien definido. Pero comienza en /speckit.specify: da por hecho que ya sabes qué construir y qué enfoque ganó. Herramientas como OpenSpec agregan una fase previa: un espacio para pensar en voz alta y otro para registrar qué alternativas descartaste y por qué.

No tienes que crear un fork de Spec Kit ni cambiar de herramienta para obtener esas dos fases. Puedes agregarlas como dos pequeños comandos de extensión:

• explore — un modo para pensar antes de comprometerte con una especificación
• alternatives-review — un modo que compara opciones y registra la decisión

Este artículo muestra cómo construir ambos, y nada más. El objetivo es un Spec Kit más pequeño y preciso, no uno más grande.

En resumen

• A Spec Kit le faltan dos fases que tienen los flujos de trabajo al estilo de OpenSpec: la exploración abierta y el registro de la decisión entre alternativas.
• Agrégalas como dos pequeños comandos, explore y alternatives-review (con el espacio de nombres /speckit.adaptive-workflow.* una vez empaquetados).
• Para un solo repo, no instales nada: coloca los archivos de los comandos directamente en el directorio de comandos de tu agente (.claude/commands/, .cursor/commands/) y hazles commit.
• Usa una extensión (no un fork) solo cuando los comandos deban compartirse entre repos o con un equipo; un fork es excesivo y un preset solo modifica artefactos existentes.
• Explore es una forma de pensar: investiga, identifica supuestos y riesgos, no escribe código y solo guarda un documento cuando se le pide.
• Alternatives-review compara dos o más opciones y escribe un artefacto que registra el camino elegido, las opciones descartadas y las concesiones aceptadas.
• ¿Archivos demasiado largos? Ese es un problema aparte: reduce la plantilla y el comando (con un preset o una sobrescritura local del proyecto), porque la verbosidad proviene de las instrucciones del comando, no solo de las plantillas.
• No intentes reconstruir todo OpenSpec dentro de Spec Kit. Toma prestados estos dos comportamientos y detente ahí.
• Trata cualquier extensión de la comunidad que instales como una dependencia de terceros: lee sus archivos de comandos antes de confiar en ella.

Qué aprenderás aquí

• Qué dos fases le faltan a Spec Kit y por qué una extensión (no un fork) es la herramienta adecuada
• Cómo construir un comando explore que piense en lugar de implementar
• Cómo construir un comando alternatives-review que registre una decisión, no solo más documentación
• Cómo agregar ambos a un repo de dos maneras —ad hoc, sin instalación, o como una extensión empaquetada— y probarlos
• Cuándo una salida demasiado extensa es un problema aparte y dónde resolverlo (en una guía complementaria enlazada)
• Cómo conectar las tareas aprobadas con GitHub Issues y Projects, y qué no hace el puente integrado
• Un despliegue por etapas para adoptar todo esto de forma segura
• Dónde detenerte para mantener el flujo de trabajo simple

Audiencia: ingenieros y arquitectos que usan Spec Kit y quieren un paso de descubrimiento más ligero antes de la especificación. Esta es una guía práctica y enfocada, no una guía de migración a OpenSpec.

Fuentes y alcance de la versión

Volví a verificar esto con GitHub Spec Kit v0.10.1 (publicado el June 9, 2026) y su documentación oficial de extensiones, el July 20, 2026.

Los campos del manifiesto y los comandos de CLI que aparecen a continuación están respaldados por las fuentes para esa versión. Los dos comandos, sus contratos y la recomendación de «tomar prestado, no reconstruir» son mi criterio editorial. Valida los ejemplos con la versión exacta de Spec Kit que instales, porque el comportamiento de las extensiones puede cambiar entre versiones.

Si primero necesitas conocer el flujo de trabajo principal, lee GitHub Spec Kit: cómo empezar con Cursor o Claude Code. Este artículo comienza donde el flujo predeterminado se siente demasiado abrupto.

Las dos etapas que faltan

El flujo predeterminado de Spec Kit da por sentada una claridad que rara vez existe al comienzo del trabajo:

Spec Kit today:      idea ──▶ /speckit.specify ──▶ /speckit.plan ──▶ tasks

What is missing:     idea ──▶ [ explore ] ──▶ [ alternatives-review ] ──▶ /speckit.specify ──▶ ...
                              └ think first ┘   └ decide on purpose ┘

Ambas son adiciones, no reemplazos. Todo lo demás en Spec Kit permanece exactamente igual.

Por qué una extensión y no un fork o un preset

Spec Kit ofrece tres maneras de personalizarlo. La elección es simple:

Add a new command or phase?          Extension  (to reuse across repos/teams)
Add a command in one repo only?      Ad-hoc command file — no install
Change an existing template's shape? Preset, or a project-local override for one repo

explore y alternatives-review son comandos completamente nuevos, así que no corresponden a un preset (los presets solo modifican artefactos que Spec Kit ya genera) ni justifican un fork (un fork te hace responsable de incorporar cada cambio del proyecto original para siempre; dos comandos no justifican eso).

Quedan dos caminos, y la única diferencia es hasta dónde se comparten los comandos. Empaquétalos como una extensión cuando los necesiten varios repos o un equipo. Agrégalos ad hoc —como archivos de comandos simples guardados en un solo repo— cuando solo quieras probarlos. Ambos usan exactamente el mismo contenido de comandos que escribirás a continuación, y la opción ad hoc no necesita empaquetado ni la CLI de specify. La sección Agrega los comandos a un repo explica cómo hacerlo.

Una regla más que vale la pena expresar con claridad: no intentes reconstruir OpenSpec dentro de Spec Kit. OpenSpec tiene contenedores persistentes de cambios, especificaciones delta, estado de tareas y archivado: todo un modelo de operación. Copiar todo eso recrearía la complejidad que intentamos evitar. Toma prestados los dos comportamientos anteriores y detente ahí. Si quieres el modelo completo de OpenSpec, compara directamente las dos herramientas en lugar de clonar una dentro de la otra.

El paquete de extensión

Todo está en una pequeña extensión con dos comandos:

spec-kit-adaptive-workflow/
├── extension.yml
├── commands/
│   ├── explore.md
│   └── alternatives-review.md
└── templates/
    └── alternatives-review-template.md

El manifiesto sigue el esquema de extensiones de v0.10.1:

schema_version: "1.0"

extension:
  id: "adaptive-workflow"
  name: "Adaptive Workflow"
  version: "0.1.0"
  description: "Add explore and alternatives-review phases before specification."
  author: "Your Organization"
  license: "MIT"

requires:
  speckit_version: ">=0.10.1"
  commands:
    - "speckit.specify"

provides:
  commands:
    - name: "speckit.adaptive-workflow.explore"
      file: "commands/explore.md"
      description: "Explore a problem before specification."
    - name: "speckit.adaptive-workflow.alternatives-review"
      file: "commands/alternatives-review.md"
      description: "Compare options and record the decision."

Los nombres con espacio de nombres (speckit.adaptive-workflow.explore) dejan claro el límite: son tus adiciones, no comandos principales de Spec Kit. Configura speckit_version con la versión que realmente pruebes.

Comando 1: modo Explore

Explore debe ser una forma de pensar, no un comando de implementación anticipada. Su único propósito es ayudar a una persona a pensar antes de que la especificación fije cualquier decisión.

Su contrato:

• inspeccionar el repositorio y los artefactos actuales de la funcionalidad cuando corresponda
• identificar supuestos, restricciones, alternativas, riesgos e incógnitas
• no escribir código
• no reescribir especificaciones sin avisar
• escribir un documento de exploración solo después de que el usuario lo confirme
• terminar recomendando el siguiente paso: seguir explorando, especificar o detenerse

Un commands/explore.md compacto:

---
description: "Explore a problem before committing to a feature specification."
---

# Adaptive Workflow: Explore

## Input

$ARGUMENTS

## Rules

1. Investigate relevant repository context before recommending a direction.
2. Separate observed facts, assumptions, and editorial recommendations.
3. Compare meaningful alternatives and expose their trade-offs.
4. Do not implement code.
5. Do not modify feature artifacts without explicit user confirmation.
6. Use an ASCII diagram when relationships are hard to scan in prose.

## Response

- Problem as currently understood
- Constraints and affected boundaries
- Alternatives worth weighing
- Risks and unknowns
- One recommended next move: continue exploring, run /speckit.specify, or stop

¿Debería Explore escribir un archivo?

Por defecto, usa solo la conversación y guarda un documento únicamente cuando el usuario lo pida. Guardar automáticamente cada lluvia de ideas crea un problema nuevo: las ideas temporales comienzan a parecer decisiones aprobadas. Cuando la exploración llegue a una conclusión estable, escribe un specs/<feature>/exploration.md breve que capture únicamente el planteamiento del problema, las restricciones clave, las alternativas consideradas y la pregunta abierta o la decisión, nada más.

Comando 2: modo Alternatives-Review

Explore es abierto. Alternatives-review es el momento de tomar una decisión deliberada y registrarla. Esta es la pieza para la que Spec Kit hoy no tiene un lugar: una especificación captura qué construyes, pero no qué descartaste y por qué.

Su contrato:

• leer la especificación activa (y las notas de exploración, si existen)
• comparar al menos dos opciones reales con los mismos criterios
• recomendar una, pero exigir que una persona la acepte, cambie el alcance o elija otra con una razón por escrito
• escribir exactamente un artefacto: specs/<feature>/reviews/alternatives-review.md
• nunca escribir código ni marcar la decisión como aprobada por su cuenta

Un commands/alternatives-review.md compacto:

---
description: "Compare options and record the decision before implementation."
---

# Adaptive Workflow: Alternatives Review

## Input

$ARGUMENTS

## Steps

1. Read the active feature spec and any exploration notes.
2. Identify at least two serious alternatives (not one plan plus strawmen).
3. Score each against the same criteria; mark low-confidence scores.
4. Recommend one path and state the trade-offs it accepts.
5. Write only specs/<feature>/reviews/alternatives-review.md.
6. Leave the Decision field for a human. Do not implement code.

## Output

- Comparison table across shared criteria
- Recommended path and the trade-offs it accepts
- Rejected options with a one-line reason each
- Human decision: accept, reduce scope, or override with rationale

El templates/alternatives-review-template.md al que se hace referencia:

# Alternatives Review: [feature]

## Decision Requested

[The concrete choice reviewers must make.]

## Options Compared

| Criterion            | Option A | Option B | Option C |
|----------------------|:--------:|:--------:|:--------:|
| Fit for the problem  |          |          |          |
| Implementation cost  |          |          |          |
| Migration / rollback |          |          |          |
| Operational risk     |          |          |          |
| Reversibility        |          |          |          |

## Recommendation

[Which option and why. Name the trade-off you are accepting.]

## Rejected Alternatives

- Option X — rejected because ... (reconsider if ...)

## Decision

- Status: Pending | Accepted | Accepted with changes | Rejected
- Decided by:
- Date:

Esto es deliberadamente distinto de «generar más documentación». El artefacto existe para respaldar una decisión específica, con una comparación y un responsable. Si se ejecuta de nuevo, conserva el bloque Decision escrito por una persona y actualiza solo el análisis generado que está encima. Si quieres conocer patrones de prompt más profundos para generar y cuestionar alternativas, consulta Cómo usar GitHub Spec Kit para investigar alternativas antes de construir.

Agrega los comandos a un repo

Ya tienes lo único que importa: los dos archivos de comandos anteriores. Hay dos maneras de incorporarlos a un repositorio, y la opción adecuada depende únicamente de hasta dónde necesiten compartirse:

One repo, just trying it?   Ad-hoc — commit the files, install nothing
Many repos or a team?       Package as an extension

Ad hoc: haz commit de los archivos de comandos directamente (sin instalación)

Un comando slash de Spec Kit es simplemente un archivo Markdown en el directorio de comandos de tu agente. Spec Kit escribe ahí sus propios comandos cuando ejecutas specify init, y un archivo que agregues a mano se comporta de la misma manera. Así que, para ejecutar explore y alternatives-review en un solo repo, coloca el mismo Markdown directamente en ese directorio, sin manifiesto ni CLI de specify:

.claude/commands/explore.md               # Claude Code
.cursor/commands/explore.md               # Cursor
.claude/commands/alternatives-review.md
.cursor/commands/alternatives-review.md

El nombre del archivo se convierte en el comando, así que obtienes /explore y /alternatives-review sin prefijo. Pierdes el espacio de nombres speckit.adaptive-workflow., lo cual está bien para un solo repo. Haz commit de los archivos y todos los que usen ese repo tendrán los comandos en su próximo git pull. Spec Kit crea los comandos en los directorios de los agentes que detecta, usando el formato de cada agente: Markdown o TOML para algunas CLI. Usa el formato que tu agente ya utiliza.

Si, en cambio, quieres modificar un artefacto existente de Spec Kit en un repo —por ejemplo, acortar el plan-template.md de este proyecto—, usa una sobrescritura local del proyecto en lugar de un comando nuevo:

.specify/templates/overrides/templates/plan-template.md

Las sobrescrituras tienen la máxima prioridad en la pila de resolución de Spec Kit y se leen en tiempo de ejecución, por lo que el cambio se aplica de inmediato, sin instalación ni fork. Esa es la herramienta adecuada para cambiar las salidas existentes; el directorio de comandos del agente es la herramienta adecuada para comandos completamente nuevos como estos dos.

Empaquetados: instálalos como extensión (para reutilizarlos entre repos)

Cuando los comandos deban compartirse —entre varios repos o un equipo, con versiones fijadas y una eliminación limpia—, inclúyelos en el manifiesto extension.yml mostrado antes e instálalos en modo de desarrollo:

specify extension add --dev /path/to/spec-kit-adaptive-workflow
specify extension list

El empaquetado te da los nombres con espacio de nombres, el ciclo de vida de specify extension list / remove, el versionado y la distribución mediante un catálogo. Vale la pena para estandarizar, pero es excesivo para un solo experimento.

Prueba el comportamiento

Cualquiera que sea el camino que hayas elegido, ejecuta un caso exitoso y confirma el comportamiento, no solo que los comandos aparecieron:

1. /explore "replace session storage"     (packaged: /speckit.adaptive-workflow.explore)
   -> conversation only, unless you approve a file
2. /alternatives-review
   -> writes specs/<feature>/reviews/alternatives-review.md with a Pending decision
3. /speckit.specify
   -> normal Spec Kit flow, now grounded by a recorded decision

Las pruebas que realmente importan:

La pregunta de aceptación es simple: ¿esta adición mejora la siguiente decisión humana sin agregar más proceso del que el cambio justifica?

Reduce la extensión de los archivos generados

Una queja común sobre Spec Kit es lo opuesto a una fase faltante: para un cambio pequeño produce una pila de archivos largos —spec.md, plan.md, research.md, data-model.md, contracts/, quickstart.md, tasks.md y una lista de verificación—. Esa verbosidad proviene de las instrucciones del comando, no solo de las plantillas, así que una plantilla más corta por sí sola no la resolverá.

Reducir esa salida es un problema de personalización por derecho propio, con cuatro mecanismos —prompts en línea, una sobrescritura de plantilla más concisa, un comando reducido y la asignación a Lean/Standard/Governed según el impacto—, por lo que ahora tiene un artículo complementario dedicado:

→ Cómo hacer que GitHub Spec Kit produzca archivos más concisos

La versión corta: corrige la verbosidad con un preset o una sobrescritura local del proyecto (nunca con una extensión), asigna un límite de extensión a cada archivo, omite las secciones vacías, enlaza en lugar de copiar y genera un artefacto solo si influye en una decisión.

Conecta Spec Kit con GitHub Issues y Projects

Un tercer problema que enfrentan los equipos: las tareas de Spec Kit viven en Git, pero la entrega se sigue en GitHub Issues y Projects, y ambos se desincronizan. Spec Kit incluye un puente —/speckit.taskstoissues—, pero es deliberadamente limitado. En v0.10.1 ese comando:

• requiere un tasks.md existente
• lee el remoto origin y se niega a continuar a menos que sea una URL de GitHub
• usa la herramienta issue_write del servidor GitHub MCP para crear un issue por tarea

Es un comienzo útil. No crea un issue padre a nivel de funcionalidad, relaciones entre sub-issues o de bloqueo, campos de Project, IDs estables entre requisitos e issues ni una política para ejecuciones repetidas. No asumas que volver a ejecutarlo es seguro.

La trazabilidad real requiere construir una extensión propia; llamémosla github-traceability. Necesita dos comandos y una cadena canónica, almacenada en specs/<feature>/traceability.json:

/speckit.github-traceability.publish   -> dry-run, create/reconcile issues, set Project fields, persist a mapping
/speckit.github-traceability.status    -> read relationships, report gaps, write nothing remotely

Requirement R001 -> Task T001 -> Issue #381 -> PR #402 -> test/review evidence

Qué te ofrece el servidor GitHub MCP

A July 2026, el conjunto de herramientas issues del servidor GitHub MCP proporciona issue_write y sub_issue_write (la jerarquía entre issues padre y sub-issues). Ambas necesitan el scope repo. GitHub Projects está en un conjunto de herramientas projects separado (projects_list, projects_get, projects_write) que no está habilitado por defecto. Actívalo con --toolsets default,projects (o el encabezado X-MCP-Toolsets) y concede read:project para lectura y project para escritura.

Una limitación condiciona el diseño: no hay una herramienta para escribir dependencias de bloqueo entre issues. sub_issue_write cubre la jerarquía, no las dependencias, así que los enlaces de «bloqueado por» necesitan la CLI de GitHub o la API REST.

Por lo tanto, un comando de publicación puede crear issues, anidar sub-issues y establecer campos de Project mediante MCP, pero recurre a gh para los enlaces de bloqueo. Mantén los artefactos bajo seguimiento de Git como fuente de verdad de la intención. Usa los issues como registros de ejecución y Projects como vista operativa; nunca copies toda la especificación en un issue.

Antes de instalar la extensión de otra persona

Si obtienes una extensión de un catálogo de la comunidad en lugar de escribir la tuya, trátala como una dependencia de terceros. La inclusión en un catálogo es metadato para facilitar su descubrimiento, no una auditoría de código: los responsables de Spec Kit verifican los metadatos del catálogo, pero no revisan, avalan ni brindan soporte para el código de las extensiones. Antes de confiar en una, lee sus archivos de comandos y su manifiesto para entender qué se le indica al agente que haga, qué herramientas solicita y dónde escribe. Si no supera alguna de esas verificaciones, no la instales.

Un despliegue práctico

Cualquiera que sea la opción que adoptes —los dos comandos, una salida más concisa o la trazabilidad con GitHub—, incorpora un comportamiento a la vez en lugar de desplegar toda la capa de golpe:

1. Línea base — identifica el problema real: falta de exploración, ausencia de una decisión registrada, salida verbosa o desincronización con GitHub. Resuelve primero ese problema.
2. Piloto local — pruébalo ad hoc en un repo de pruebas (un archivo de comando o una sobrescritura local del proyecto) antes de empaquetar nada.
3. Revisión de la salida — compara los artefactos de algunos cambios representativos; conserva lo que mejore una decisión y elimina el resto.
4. Pruebas de fallas — revisa los escenarios difíciles: entradas ambiguas, archivos faltantes, ejecuciones repetidas, presets en conflicto, eliminación y reversión.
5. Aprobación del equipo — para cada comando o artefacto agregado, identifica su responsable, disparador, salida y la decisión que respalda.
6. Distribución controlada — solo entonces empáquétalo y publica una versión revisada mediante un catálogo que permita la instalación.
7. Mide y depura — elimina los comandos y documentos que no influyan en las decisiones.

Algunas señales que vale la pena observar:

• proporción de secciones generadas que los revisores eliminan por irrelevantes
• preguntas de aclaración planteadas antes de la planificación
• condiciones de revisión identificadas antes de la implementación
• tiempo dedicado a reconciliar artefactos contradictorios

Estas señales no demuestran causalidad, pero muestran si el flujo de trabajo se está volviendo más claro o solo más grande.

Dónde detenerse

Con una herramienta extensible, la tentación es seguir agregando cosas. Resístela. Dos fases resuelven el problema real:

missing thinking phase   -> explore command
missing decision record  -> alternatives-review command

Reducir la salida verbosa y asignar un cambio al nivel adecuado (como explica la guía complementaria anterior) vale la pena porque elimina proceso o lo ajusta a la medida. Construir un pipeline de revisión especializada o trazabilidad con GitHub Issues/Projects es distinto: cada uno es un problema legítimo pero aparte que merece su propia decisión, no una razón para inflar esta extensión. Agrega un comando, prueba sus modos de falla y consérvalo solo si el artefacto resultante ayuda a una persona a tomar la siguiente decisión.

Esa es la promesa útil de las extensiones de Spec Kit: no más comandos ni más documentos, sino las dos fases faltantes que hacen que la especificación posterior sea mejor.

Fuentes

• README de GitHub Spec Kit v0.10.1: flujo de trabajo publicado, integraciones compatibles y contexto de la versión.
• Referencia de extensiones de Spec Kit v0.10.1: búsqueda, instalación y configuración de extensiones, y administración de comandos.
• Guía de desarrollo de extensiones de Spec Kit v0.10.1: esquema del manifiesto, comandos con espacio de nombres, pruebas locales y recomendaciones de seguridad.
• README de extensiones de Spec Kit v0.10.1: modelo de catálogo seleccionado y límite de confianza del catálogo de la comunidad.
• Referencia de presets de Spec Kit: pila de resolución de personalización, sobrescrituras locales del proyecto (.specify/templates/overrides/) y cómo se crean los comandos en los directorios de los agentes durante la instalación, frente a las plantillas que se resuelven en tiempo de ejecución.
• Plantillas de comandos principales de Spec Kit v0.10.1: la instrucción del comando plan para generar research.md, data-model.md, contracts/ y quickstart.md, y la lista de verificación de requisitos del comando specify: la fuente de la verbosidad que un preset o una sobrescritura más concisos deben reducir.
• Comando de tareas a issues de Spec Kit v0.10.1: el requisito previo de tasks.md, la validación del remoto de GitHub y la creación de un issue por tarea mediante la herramienta issue_write de MCP.
• Servidor oficial GitHub MCP: capacidades actuales de las herramientas issue_write / sub_issue_write / projects_*, los conjuntos de herramientas predeterminados (el conjunto projects no está entre ellos) y los requisitos de scopes de OAuth (repo, read:project, project).
• Repositorio de OpenSpec: el flujo de trabajo basado en cambios cuyas fases de exploración y registro de decisiones inspiraron estos dos comandos.