Entrada del Usuario
$ARGUMENTS
DEBES considerar la entrada del usuario antes de continuar (si no está vacía).
Comprobaciones Previas a la Ejecución
Verificar hooks de extensión (antes de la convergencia):
-
Comprueba si existe
.specify/extensions.ymlen la raíz del proyecto. -
Si existe, léelo y busca entradas bajo la clave
hooks.before_converge. -
Si el YAML no se puede analizar o no es válido, no lo ignores silenciosamente: dile al usuario que
.specify/extensions.ymlno se pudo leer (incluye el error del analizador) y que no se verificaron hooks, incluidos los obligatorios (optional: false) registrados allí, luego continúa normalmente. -
Filtra los hooks donde
enabledsea explícitamentefalse. Trata los hooks sin un campoenabledcomo habilitados por defecto. -
Para cada hook restante, no intentes interpretar ni evaluar las expresiones de
conditiondel hook:- Si el hook no tiene un campo
condition, o es nulo/vacío, trata el hook como ejecutable. - Si el hook define una
conditionno vacía, salta el hook y deja la evaluación de la condición a la implementación de HookExecutor.
- Si el hook no tiene un campo
-
Al construir invocaciones de comandos a partir de nombres de comandos de hook, reemplaza los puntos (
.) con guiones (-). Por ejemplo,speckit.git.commit→/speckit-git-commit. -
Para cada hook ejecutable, produce el siguiente resultado según su bandera
optional:-
Hook opcional (
optional: true):## Extension Hooks **Pre-Hook Opcional**: {extension} Comando: `/{command}` Descripción: {description} Prompt: {prompt} Para ejecutar: `/{command}` -
Hook obligatorio (
optional: false):## Extension Hooks **Pre-Hook Automático**: {extension} Ejecutando: `/{command}` EXECUTE_COMMAND: {command} Espera el resultado del comando hook antes de proceder al Objetivo.Después de emitir el bloque anterior, DEBES invocar realmente el hook y esperar a que termine antes de continuar. Ejecútalo de la misma manera que ejecutarías el comando tú mismo en este agente/sesión (la invocación puede diferir del id
{command}literal mostrado arriba, por ejemplo, un agente en modo skills lo ejecuta como/skill:speckit-...o$speckit-...). Emitir el bloque solo no ejecuta el hook.
-
-
Si no hay hooks registrados o no existe
.specify/extensions.yml, omítelo silenciosamente.
Objetivo
Cerrar la brecha entre lo que exigen la especificación, el plan y las tareas de una funcionalidad y lo que el código base implementa actualmente. Lee spec.md, plan.md y tasks.md como la única fuente de intención (con la constitución como restricción rectora), evalúa el estado actual del código, determina qué requisitos, criterios de aceptación, decisiones del plan y tareas existentes no se cumplen, están incompletos o solo se satisfacen parcialmente, y agrega cada pieza de trabajo restante como una nueva tarea rastreable al final de tasks.md para que /speckit-implement pueda completarla. Este comando DEBE ejecutarse solo después de que /speckit-implement se haya ejecutado en el tasks.md actual, y después de que /speckit-tasks haya producido un tasks.md completo.
Esto no es una herramienta de diferencias y no rastrea cambios. Evalúa el estado presente del código en relación con los artefactos de la funcionalidad — sin git, sin comparación de ramas, sin historial.
Restricciones Operativas
SOLO AÑADIR, NUNCA REESCRIBIR: La única escritura del comando es agregar una nueva sección ## Phase N: Convergence a tasks.md. NO DEBE:
- modificar
spec.mdoplan.mdde ninguna manera; - reescribir, renumerar, reordenar o eliminar ninguna tarea existente (incluidas las tareas de una fase de Convergencia anterior);
- modificar, crear o eliminar ningún código de aplicación — completar las tareas añadidas es trabajo de
/speckit-implement.
Cuando el código base ya satisface todo, el comando DEBE dejar tasks.md sin cambios byte por byte (sin encabezado de Convergencia vacío) e informar un resultado limpio.
Autoridad de la Constitución: La constitución del proyecto (.specify/memory/constitution.md) es no negociable. El código que viola un principio MUST es el hallazgo de mayor gravedad y produce una tarea de remediación correspondiente. Si la constitución es una plantilla sin rellenar, omite las comprobaciones de la constitución de manera elegante en lugar de fallar.
Pasos de Ejecución
1. Inicializar el Contexto de Convergencia
Ejecuta .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks una vez desde la raíz del repositorio y analiza el JSON para obtener FEATURE_DIR y AVAILABLE_DOCS. Deriva rutas absolutas:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
- CONSTITUTION =
.specify/memory/constitution.md(si está presente) Si faltaspec.md,plan.mdotasks.md, DETENTE con un mensaje claro y procesable que indique el comando prerrequisito a ejecutar (/speckit-specifypara una especificación faltante,/speckit-planpara un plan faltante,/speckit-taskspara tareas faltantes). No produzcas resultados parciales. Para comillas simples en argumentos como "I'm Groot", usa sintaxis de escape: por ejemplo 'I'''m Groot' (o comillas dobles si es posible: "I'm Groot").
2. Cargar Artefactos (Divulgación Progresiva)
Carga solo el contexto mínimo necesario de cada artefacto:
De spec.md:
- Requisitos Funcionales (FR-###)
- Criterios de Éxito (SC-###) — incluye solo elementos que requieran trabajo construible; excluye métricas de resultado posteriores al lanzamiento y KPIs de negocio
- Historias de Usuario y sus Escenarios de Aceptación
- Casos Extremos (si están presentes)
De plan.md:
- Elecciones de arquitectura/stack y decisiones técnicas
- Referencias del Modelo de Datos
- Fases y puntos de contacto nombrados (archivos/componentes que el plan dice que se crearán o editarán)
- Restricciones técnicas
De tasks.md:
- IDs de Tarea (para calcular el siguiente ID y el número de la siguiente fase)
- Descripciones, agrupación de fases y rutas de archivo referenciadas
De la constitución (si no es una plantilla sin rellenar):
- Nombres de principios y declaraciones normativas MUST/SHOULD
3. Construir el Inventario de Intenciones
Crea un modelo interno (no repitas artefactos en bruto):
- Inventario de requisitos: una clave estable por FR-### / SC-### / escenario de aceptación de historia de usuario (por ejemplo,
US1/AC2), más las decisiones del plan y los principios constitucionales que imponen obligaciones construibles. - Mapa de alcance del código: a partir de las rutas de archivo nombradas en
plan.mdytasks.md, más una búsqueda de palabras clave de los conceptos que describe cada requisito, deriva el conjunto de archivos fuente y componentes dentro del alcance para la evaluación. Limita la evaluación a estos — no infieras el alcance más allá de lo que definen los artefactos.
4. Evaluar el Código Base y Clasificar los Hallazgos
Incluye cada tarea existente en el inventario de intenciones, independientemente del estado de la casilla de verificación o la fase de Convergencia: las afirmaciones de finalización no son evidencia. Verifica el comportamiento actual contra la especificación, el plan, las tareas y la constitución; para cadenas de tareas correctivas, evalúa el comportamiento resultante, no los detalles de implementación reemplazados. Verifica tanto las obligaciones incumplidas como la implementación que contradice, excede o queda fuera de la intención declarada.
Para cada elemento del inventario de intenciones, inspecciona el código actual dentro del alcance y produce un Finding solo donde haya una brecha. Clasifica cada hallazgo por tipo de brecha:
missing: el trabajo requerido está ausente por completo del código.partial: el trabajo existe pero aún no satisface completamente el requisito / criterio de aceptación / decisión del plan.contradicts: el código hace algo que entra en conflicto con la intención declarada o un principio MUST de la constitución.unrequested: el código contiene trabajo no solicitado por la especificación, el plan o las tareas (se muestra para concienciación — convergencia no elimina código, solo añade una tarea para revisar/justificar o eliminarlo).
Cada Finding registra: un id estable, la source-ref a la que se remonta, el gap-type, una severidad y una breve descripción legible con la evidencia (el archivo/área observado).
Casos extremos:
- Poco o ningún código aún: trata todo el ámbito especificado como trabajo
missingrestante en lugar de fallar. - No queda nada: produce cero hallazgos y sigue la rama convergida en el Paso 7.
5. Asignar Severidad
- CRITICAL: viola un principio MUST de la constitución, o una brecha
missing/contradictsque bloquea la funcionalidad base de una historia de usuario P1. - HIGH: una brecha
missingopartialen un requisito funcional principal o criterio de aceptación. - MEDIUM: una brecha
partialen un requisito secundario, o una adiciónunrequestedcon justificación poco clara. - LOW: brechas parciales menores, pulido o adiciones
unrequestedde bajo riesgo.
6. Presentar el Resumen de Hallazgos en Sesión
Antes de agregar cualquier cosa, genera un resumen compacto, clasificado por severidad (sin escrituras de archivos aún):
Hallazgos de Convergencia
| ID | Tipo de Brecha | Severidad | Fuente | Evidencia | Trabajo Restante |
|---|---|---|---|---|---|
| F1 | missing | HIGH | FR-008 | Ejemplo: no se detectó protección de solo adición en path/to/module.py al escribir tasks.md | Agregar cumplimiento de solo adición |
Métricas de resumen:
- Requisitos / criterios de aceptación verificados
- Decisiones del plan verificadas
- Principios constitucionales verificados (o "omitido — plantilla")
- Hallazgos por tipo de brecha (missing / partial / contradicts / unrequested)
- Hallazgos por severidad
7. Agregar Tareas de Convergencia (o informar convergido)
Si hay uno o más hallazgos procesables (resultado tasks_appended):
Añade al final de tasks.md, según el contrato de adición:
-
Escanea todos los IDs de tareas existentes; sea
Mel máximo. Determina el número de la siguiente faseN(fase existente más alta + 1). -
Escribe un único encabezado de nueva sección
## Phase N: Convergence. -
Emite un elemento de lista de verificación por hallazgo procesable, ordenados primero los CRITICAL/HIGH, asignando IDs con relleno de ceros
T{M+1:03d}, T{M+2:03d}, …:- [ ] T042 <descripción imperativa> según <source-ref> (<gap-type>)<source-ref>rastrea la tarea hasta su origen: por ejemplo,FR-003,SC-002,US1/AC2,plan: storage decision,Constitution II.<gap-type>es uno demissing,partial,contradicts,unrequested.Las tareas por violación de la constitución DEBEN emitirse primero y describirse como
CRITICAL. -
Nunca reutilices o renumeres IDs existentes. Si existe una fase de Convergencia anterior, agrega una nueva, numerada por separado debajo de ella — no toques la anterior.
Si no hay hallazgos procesables (resultado converged):
- No modifiques
tasks.mden absoluto — sin encabezado de fase vacío. - Informa: "✅ Converged — la implementación satisface la especificación, el plan y las tareas."
- Incluye los recuentos de resumen de lo que se verificó.
8. Proporcionar Próximas Acciones (Traspaso)
- En
tasks_appended: indica cuántas tareas se añadieron y bajo qué fase, y recomienda ejecutar/speckit-implementpara completarlas; ten en cuenta que una ejecución de convergencia posterior encontrará menos elementos o ninguno. - En
converged: recomienda proceder a la revisión / abrir un PR. No se necesita más pase de implementación para el alcance especificado de esta funcionalidad.
9. Verificar hooks de extensión
Después de producir el resultado, comprueba si existe .specify/extensions.yml en la raíz del proyecto.
-
Si existe, léelo y busca entradas bajo la clave
hooks.after_converge. -
Si el YAML no se puede analizar o no es válido, no lo ignores silenciosamente: dile al usuario que
.specify/extensions.ymlno se pudo leer (incluye el error del analizador) y que no se verificaron hooks, incluidos los obligatorios (optional: false) registrados allí, luego continúa normalmente. -
Filtra los hooks donde
enabledsea explícitamentefalse. Trata los hooks sin un campoenabledcomo habilitados por defecto. -
Para cada hook restante, no intentes interpretar ni evaluar las expresiones de
conditiondel hook:- Si el hook no tiene un campo
condition, o es nulo/vacío, trata el hook como ejecutable. - Si el hook define una
conditionno vacía, salta el hook y deja la evaluación de la condición a la implementación de HookExecutor.
- Si el hook no tiene un campo
-
Informa el resultado de la convergencia (
convergedotasks_appended) en la sesión antes de listar cualquier hook, para que los usuarios puedan decidir si ejecutar comandos de seguimiento opcionales. -
Al construir invocaciones de comandos a partir de nombres de comandos de hook, reemplaza los puntos (
.) con guiones (-). Por ejemplo,speckit.git.commit→/speckit-git-commit. -
Para cada hook ejecutable, produce el siguiente resultado según su bandera
optional:-
Hook opcional (
optional: true):## Extension Hooks **Hook Opcional**: {extension} Comando: `/{command}` Descripción: {description} Prompt: {prompt} Para ejecutar: `/{command}` -
Hook obligatorio (
optional: false):## Extension Hooks **Hook Automático**: {extension} Ejecutando: `/{command}` EXECUTE_COMMAND: {command}Después de emitir el bloque anterior, DEBES invocar realmente el hook y esperar a que termine antes de continuar. Ejecútalo de la misma manera que ejecutarías el comando tú mismo en este agente/sesión (la invocación puede diferir del id
{command}literal mostrado arriba, por ejemplo, un agente en modo skills lo ejecuta como/skill:speckit-...o$speckit-...). Emitir el bloque solo no ejecuta el hook.
-
-
Si no hay hooks registrados o no existe
.specify/extensions.yml, omítelo silenciosamente.