Workflow
El ciclo tiene cuatro comandos y una propiedad que los amarra: cada uno produce un artefacto que el siguiente consume, y todos quedan en tu repositorio. Antes de ellos hay un paso cero opcional — el estudio, para cuando todavía no sabes qué proponer. No es un chat con buena memoria — es una cadena de documentos versionados que sobrevive a la conversación, a la persona y al agente.
Un quinto comando, /pipeline, ejecuta la cadena entera de punta a punta — es retomable desde el punto exacto donde se quedó, y avisa cuándo conviene ejecutar antes el estudio del paso cero.
El ciclo
El paso 00 es opcional — el estudio que se hace cuando todavía no se sabe qué proponer. Los cuatro siguientes tienen puerta: no se implementa sin especificación, no se cierra una fase sin revisión. Las puertas son código, no una recomendación.
No todo trabajo empieza con la solución en la mano. El estudio diverge antes de converger — mapea el territorio, enumera opciones, compara trade-offs o persigue la causa raíz — y sale con las preguntas abiertas numeradas, cada una con dueño, además del mismo bloque de contrato que lee el resto de la cadena. Terminar sin decisión es un resultado válido; lo que no vale es decidir sin haber mirado. La propuesta siguiente hereda el estudio en vez de reexplorar desde cero.
/analysis
Describes lo que quieres. Sale una propuesta con el problema, los escenarios, los principios de diseño, los riesgos y los criterios de aceptación. Junto a ella, incrustado en el mismo archivo, sale un bloque de contrato legible por máquina: las unidades en que se descompone el trabajo, los criterios que las verifican y las anclas que ligan cada escenario al criterio que lo cierra.
/proposal
La propuesta no se ejecuta directamente. Cada unidad del contrato se convierte en una especificación propia, con reglas de negocio numeradas y comprobables, invariantes, y las pruebas determinísticas que probarán cada una. Aquí es donde "el agente entendió" deja de ser una apuesta: lo que va a hacer está escrito de antemano, y lo que cuenta como hecho, también.
/ai-spec
El agente implementa leyendo la especificación de la fase, no la conversación. Nada se escribe sin tu aprobación, y al final se ejecutan la suite de pruebas y el build — no se declaran. Una fase que no produjo los archivos que la spec prometió no se cierra.
/implement
La revisión corre con contexto aislado de quien implementó y devuelve un veredicto: aprobado, aprobado con observaciones, o cambios necesarios. Cambios necesarios devuelve la fase a implementación — y el disparador es el veredicto, no el conteo de hallazgos críticos, porque una regla sin prueba reprueba sin ser crítica.
/review
Cómo se materializa el SDD
El desarrollo guiado por especificación suele morir en el mismo punto: la spec es un documento que nadie puede ejecutar, así que envejece al margen del código. Aquí tiene una mitad que la máquina lee, y es esa mitad la que dirige la ejecución.
Además de la prosa que revisan los humanos, cada artefacto lleva un bloque estructurado con las unidades, los criterios y las anclas. Es ese bloque — no el texto — el que el orquestador consume para decidir en cuántas fases se divide el trabajo y en qué orden dependen unas de otras.
Cuando el contrato existe y es válido, las fases se derivan de él y se firman por checksum. Si la propuesta cambia, la firma deja de coincidir y las fases se recalculan — y el trabajo ya registrado se reencuentra por la identidad de la unidad, nunca por su posición en una lista.
¿Propuesta antigua, sin el bloque? El orquestador cae a la tabla de fases en prosa, y luego a preguntarte a ti — anunciando en qué escalón cayó y por qué. Ninguna ejecución se interrumpe por falta de contrato; lo que no ocurre es la degradación silenciosa.
Una propuesta formal y una user story emiten el mismo contrato. Por eso cambiar la metodología del equipo no reescribe el pipeline: lo que viene después lee el contrato y no sabe de qué origen vino.
La consecuencia práctica: la spec no puede envejecer en silencio. Si cambia, la firma del contrato deja de coincidir, y el orquestador dice que dejó de coincidir — en vez de seguir ejecutando un plan que nadie aprobó.
Ejecución
Cada paso terminado se graba en el estado de la ejecución en cuanto acaba — nunca en lote. El archivo dice qué fase está en qué etapa, qué artefacto salió de cada una, y quién inició la ejecución, con identidad venida del git.
¿Cerraste la terminal, se cayó la conexión, se acabó el día? La siguiente ejecución lee el estado, salta lo que ya está listo y continúa desde el primer paso pendiente. También puedes ejecutar a propósito un rango de fases, para revisar en lotes.
Antes de empezar, el paso se marca como en curso, con hora e intento. Una ejecución que murió a mitad de camino se distingue de una que está trabajando — y quien la retoma sabe en qué intento está, en vez de adivinar.
El paso que falla graba el error y se detiene, en vez de seguir sobre una base rota. La siguiente ejecución encuentra el registro de lo que pasó, no un estado ambiguo que parece progreso.
Personalización
El comportamiento de cada comando se resuelve en tres capas. La del medio se versiona y se revisa como código; la de arriba se queda en tu máquina y no va al repositorio.
| Capa | Quién edita | Dónde vive | Versionada |
|---|---|---|---|
| Base | Quien escribe la skill | viaja con el producto | Sí |
| Equipo | El equipo, por code review | .claude/skill-config/ | Sí |
| Personal | Cada desarrollador, por máquina | .local.json (fuera de git) | No |
El comportamiento por defecto de cada comando. No lo editas — lo recibes, y se actualiza junto con el producto.
La convención del equipo: contexto que todo comando debe llevar, pasos que corren antes o después de una skill, nivel de rigor. Vive en git y se revisa como cualquier archivo — cambiar la convención es un pull request, no un acuerdo verbal.
Tu propia preferencia, en tu máquina, que no va al repositorio y no molesta a nadie. Discrepar del estándar del equipo en algo que solo te afecta a ti no exige convencer al equipo.
Cómo se combinan las capas
Los hechos que todo comando debe conocer y los pasos de preparación se concatenan en el orden base → equipo → personal, preservando el orden de cada capa. Tu preferencia personal se suma a la convención del equipo en vez de sustituirla — que es el comportamiento correcto para el tipo de cosa que llevan estas claves.
En cambio, lo que corre al terminar un comando no se suma — la capa más cercana a ti sustituye el valor entero, sin fusionar. Y declarar explícitamente "ninguno" cuenta como declaración: así es como un equipo apaga un gancho heredado, en vez de convivir con él.
Los comandos que escriben encima de trabajo existente — rotar el historial, reorganizar módulos, preparar el entorno, crear rama, eliminar código obsoleto — no aceptan ganchos de flujo. En ellos, "personalizar" significaría quitar la verificación que impide la pérdida. El rechazo lo ejecuta el motor, no se confía a la disciplina.
Además del comportamiento de las skills, la ejecución tiene perfiles: qué modelo corre cada etapa, si las etapas corren aisladas en subagentes o en la misma sesión, qué hacer con lo pendiente al final. Eliges el perfil activo de tu máquina sin alterar el estándar del repositorio.
Adaptación al equipo
El ciclo de arriba es el mismo en cualquier equipo. Lo que cambia es el vocabulario, el comando con el que especificas, qué se agrupa por qué y la pantalla en la que abre el cockpit — todo configuración, ninguna línea del producto.
En un equipo ágil especificas con /story y ves el trabajo en kanban con velocidad; en un equipo enterprise, el mismo trabajo aparece como matriz de trazabilidad. La etapa de especificar cambia de front-end; las de implementar y revisar no saben de la diferencia, porque leen el contrato y no el documento.
Metodología y rigor son ejes independientes: un equipo ágil puede subir al nivel estricto en una feature de pagos sin dejar de hablar de story y sprint. Quien elige uno no queda atado al otro.
Después del desarrollo
Terminar de implementar no es el fin de la cadena. La pregunta que queda — ¿este requisito está de verdad cubierto por código y por una prueba? — se responde contra el repositorio real.
Las anclas que declaró la especificación — el escenario lleva al caso de uso, que lleva al criterio — se resuelven contra el repositorio real. Cada eslabón recibe un estado: resuelto, parcial o no resuelto, con archivo y línea como evidencia. Lo que quedó sin cubrir aparece por nombre, en vez de descubrirse en producción.
/traceability
Una matriz legible — escenario, caso de uso, criterio, código, prueba, estado — para quien revisa. Y el mismo contenido, estructurado, determinístico y versionable, para quien automatiza. Las dos salen de la misma resolución, así que no pueden divergir.
En el nivel más ligero el gate se salta; en el estándar avisa; en el estricto bloquea cuando existe un eslabón no resuelto. Es la misma dosificación por riesgo que vale en el resto del flujo — quien decide cuándo se cierra el candado es el proyecto, no la herramienta.
Trazabilidad, resultados de los escaneos de seguridad y las revisiones se reúnen en un único paquete de evidencia. Auditar deja de ser una excavación por carpetas y se convierte en un artefacto que se entrega.
El rastro que queda
Cada sesión de trabajo graba inicio y fin, con alcance y resultado, y la autoría viene del git — no de un campo rellenado. Es el registro cronológico de lo que pasó, en el orden en que pasó.
Las decisiones estructurales se convierten en registros fechados con contexto, alternativas descartadas y consecuencias. Una decisión superada gana un aviso arriba y mantiene el cuerpo intacto — el historial de la decisión vale tanto como la decisión.
Hallazgo pospuesto, criterio sin verificar, limitación de entorno: todo entra en un registro central con severidad, dueño y estado, ligado a la feature que lo originó. La deuda deja de depender de que alguien se acuerde.
Descontinuar algo es un registro con ciclo propio — anunciado, obsoleto, en ventana de retiro, retirado — en vez de un comentario que nadie encuentra. Desaparece cuando se decidió que desapareciera, no cuando alguien tropieza con él.
Todo esto se versiona junto con el código y es legible por humanos y por máquinas — incluso si dejas de usar Spaccy. Solicita acceso anticipado y ejecuta el primer ciclo.
