Specs vivas y cambios
El SDD de agent-kit está anclado a specs: las specs no son documentos de planificación desechables; siguen siendo ciertas mientras viva el código.
Specs vivas
work/specs/<capacidad>/spec.md dice cómo se comporta hoy un área del sistema. Una capacidad es un área que los usuarios reconocen —auth, invoices, user-roles—, no una página ni una tabla.
---
capability: auth
retired: [auth.R1]
---
# Auth
## Purpose
Who can sign in and how.
## Requirements
### auth.R2 — Session restore
While a session is stored, the app shall restore it on reload.
#### auth.R2.S1 — Reload keeps the user signed in @simple
- Given a signed-in user
- When the page reloads
- Then the user is still signed in
El contexto de sesión lista las capacidades (una línea); el agente lee la spec de una capacidad antes de cambiar su comportamiento. La notación se describe en Notación.
Cambios
El trabajo complejo es un cambio en work/changes/NNN-slug/, creado con agent-kit work new change <slug>:
| Archivo | Qué es |
|---|---|
proposal.md | Por qué, qué cambia (dentro / fuera), capacidades afectadas, preguntas abiertas. El primer artefacto que apruebas. |
specs/<capacidad>.md | Spec delta: ## ADDED, ## MODIFIED (el bloque completo como debe quedar) y ## REMOVED Requirements (con un motivo). |
plan.md | Archivos, cambios de esquema / RPC, decisiones, riesgos. |
tasks.md | Tareas ordenadas con los ids de escenario que cubren, la evidencia bajo cada una y una tabla de verificación. |
Fusión
Cuando el cambio está verificado, agent-kit specs merge NNN:
- aplica todos los deltas del cambio o ninguno: se niega y nombra el conflicto cuando falta un requisito MODIFIED o REMOVED, o cuando un id ADDED está tomado o retirado;
- retira los ids de requisitos eliminados y los escenarios que faltan en un bloque MODIFIED (nunca se reutilizan, así los tests, las pasadas de QA y los fixtures antiguos no apuntan al comportamiento equivocado);
- marca la propuesta con
merged: <fecha>y renueva el checklist de QA.
La carpeta del cambio se queda como registro de por qué cambió el comportamiento.
Ids
agent-kit specs next <capacidad> da el siguiente id de requisito; agent-kit specs next <capacidad>.R<n>, el siguiente id de escenario. Ambos cuentan los ids vivos, retirados y de deltas pendientes, para que dos cambios abiertos no choquen.
Herramientas
| Comando | Hace |
|---|---|
agent-kit specs lint [cap|NNN] | Revisa la notación y los ids (sale con 1 si hay errores). |
agent-kit specs list | Capacidades con su número de requisitos y escenarios. |
agent-kit specs trace [NNN|cap] | Escenario → tests o comprobaciones ✅. |
agent-kit work status / board | Trabajo activo y su próxima tarea. |