Fábrica de Software

Resuelve toda duda de alcance primero. Congela las obligaciones. Delega cada fase intensiva a un subagente nuevo. Demuestra la finalización con un Verificador independiente que no escribió el código.

┌──────────┐   ┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ DESCUBRIR │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────────┘   └──────┘   └────────┘   └───────┘   └────────┘
 0 dudas       confirmar   obligaciones  lotes      autor != verificador

Cinco movimientos, tres artefactos duraderos bajo .specs/features/<feature>/, y un Orquestador Delgado en el chat principal que nunca infla su ventana de contexto.

DESCUBRIR: Un subagente scout de solo lectura escanea el código base y devuelve un informe de ambigüedad compacto (~30 líneas). El chat principal entrevista al usuario con opciones concretas y valores predeterminados recomendados hasta que no queden supuestos no confirmados (¿Confirmado? s para cada fila). Ver discovery.md.
PLANIFICAR: Un subagente planner escribe .specs/features/<feature>/plan.md (Problema, Flujo, Impacto, Relaciones, Superficie, Aterrizaje, Criterios, Fuera de alcance, Supuestos, Observable, Fuentes) y ejecuta validate_plan.py. El usuario da una aprobación rápida en plan.md. Ver plan.md.
VERIFICACIONES: Después de la aprobación de plan.md, comienza el bucle autónomo posterior al plan. Un subagente specifier deriva .specs/features/<feature>/checks.md (afirmaciones + pruebas, unión de Cobertura, Política de prueba, Barrido, Aritmética de traspaso) y ejecuta validate_checks.py. Ver checks.md.
CONSTRUIR: Un subagente builder por lote/tanda escribe pruebas estrictamente a partir de las verificaciones, implementa el código, ejecuta las pruebas, actualiza checks.md y confirma los cambios usando check_commit.py. Ver build.md.
VERIFICAR (y bucle de REPARACIÓN): Un subagente verifier independiente (nunca el constructor) audita <feature base>..HEAD contra cada verificación, escribe .specs/features/<feature>/verification.md y ejecuta validate_verification.py. Si falla alguna verificación, un subagente fixer resuelve las brechas clasificadas y un nuevo verifier vuelve a verificar (hasta 3 rondas). Ver verify.md y orchestration.md.

Por qué esta forma

Los agentes de codificación fallan en características complejas por dos razones predecibles:

Saturación de la ventana de contexto: Cuando una sola sesión de chat explora el repositorio, entrevista al usuario, escribe el plan, deriva verificaciones, escribe pruebas y código, y verifica su propio trabajo, la ventana de contexto se llena y desencadena una compactación con pérdida.
Requisitos no confirmados y puntos ciegos de autoevaluación: Adivinar en silencio el comportamiento del producto (¿Confirmado? n) o permitir que el autor se autocertifique la finalización, incluye los propios puntos ciegos del autor.

software-factory resuelve ambos:

Orquestador Delgado (<15k tokens en el chat principal): El chat principal actúa estrictamente como coordinador y entrevistador del usuario. Toda la lectura del código base, la creación de artefactos, la codificación, las pruebas y la verificación se ejecutan dentro de subagentes efímeros aislados (scout, planner, specifier, builder, verifier, fixer) que se comunican exclusivamente a través de archivos .specs/features/<feature>/ en disco y commits de git. Protocolo de despacho completo: orchestration.md.
Conjunto pequeño y congelado de obligaciones + Verificador independiente: No hay una lista de verificación de tareas granular o un catálogo de componentes (Propósito/Ubicación/Interfaces por clase) que quede obsoleto. Las puertas unidireccionales obtienen una forma literal en Aterrizaje; la colocación reversible se decide en el diff.

Reglas críticas

El conjunto fijo. Estas se mantienen en cada perfil:

Cero supuestos no confirmados (¿Confirmado? s). Nunca adivines el comportamiento del producto o del alcance en silencio. Cada área gris que surja durante DESCUBRIR debe preguntarse con opciones concretas y un valor predeterminado recomendado, o delegarse explícitamente por el usuario (¿Confirmado? s). validate_plan.py rechaza cualquier fila donde ¿Confirmado? sea n o esté en blanco.
Orquestador Delgado y Límite Estricto de 1 Subagente por Fase (scout != planner != specifier != builder != verifier). Mantén el chat principal por debajo de ~15k tokens. Nunca combines dos fases en una sola llamada a un subagente:
- scout SÓLO explora y devuelve el informe de ambigüedad de ~30 líneas.
- planner SÓLO escribe plan.md + ejecuta validate_plan.py, luego se detiene y sale.
- specifier SÓLO escribe checks.md + ejecuta validate_checks.py, luego se detiene y sale (NUNCA DEBE escribir archivos de prueba o código de implementación ni continuar en CONSTRUIR).
- builder SÓLO se ejecuta después de que specifier haya regresado. Para características de múltiples segmentos (S1, S2, ...), despacha un subagente builder separado por segmento secuencialmente para que cada segmento se ejecute en una ventana de contexto nueva e informe del progreso al usuario.
- verifier SÓLO se ejecuta en un subagente nuevo después de que el builder final confirme los cambios.
Cada verificación es una afirmación observable con un valor concreto más la prueba — el selector de prueba exacto o comando cuyo código de salida la resuelve. Sin prueba, no hay verificación.
Las pruebas afirman lo que dicen las verificaciones, nunca lo que el código hace. Nunca escribas una prueba leyendo la implementación.
Nunca debilites una aserción, elimines una prueba o te saltes una para que una suite pase. Una verificación genuinamente incorrecta es una parada y una pregunta, no una edición.
Las verificaciones y las filas de Política de prueba son fijas una vez aprobadas. En plan.md, Aterrizaje, Relaciones, y Superficie son aditivos: una puerta descubierta durante la construcción obtiene una fila antes del código que la cierra, y una fila que el usuario aprobó nunca se reescribe. Flujo e Impacto se mantienen verdaderos en el commit que cambia la ruta.
El Verificador es un subagente nuevo, nunca el autor, nunca opcional, nunca espera a que se le pregunte. El Orquestador lo despacha inmediatamente después de que el último commit de la característica aterrice sobre <feature base>..HEAD con cada verificación.
El perfil es un piso y es aplicado por validate_verification.py.
La puerta de finalización es un script, no una sensación: validate_verification.py debe terminar con código 0.
Radio de explosión: una especificación aprobada autoriza ediciones locales y commits locales. git push, despliegue y cambios en los datos de producción necesitan una autorización explícita para esa acción.

Perfil

El proyecto declara cuánto se ejecuta, en AGENTS.md o equivalente. En ausencia de una declaración: light.

## software-factory

profile: light
budget: 150k

Perfil	Añade	No puede detectar
`light` (predeterminado)	las pruebas se ejecutan en `HEAD` y se muestra que cada prueba nombrada existe y se ejecuta, una aserción localizada por verificación, brechas de nivel y muestreo, `Barrido existente` releído	un miembro del conjunto sin prueba; una prueba que pasaría bajo una implementación incorrecta
`standard`	la unión de `Cobertura` recalculada, filas de `Política de prueba` con un veredicto cada una, un fallo por superficie de aserción	una verificación que contradice una fuente vinculante; una pantalla que nadie construyó
`ui`	fuentes vinculantes abiertas y comparadas, enumeración por pantalla de copia y disposición	solo espaciado, color y peso de tipo, enumerado por pantalla

validate_verification.py rechaza un informe cuyo perfil difiera de aquel bajo el cual se aprobó checks.md, rechaza un informe standard sin filas de fallo o cobertura recalculada, y rechaza un informe ui sin una sección de fuentes vinculantes.

Artefactos

.specs/
├── STATE.md                    # Registro de decisiones (AD-NNN) + Instantánea de traspaso
├── LESSONS.md                  # renderizado por scripts/lessons.py - nunca editar a mano
├── lessons.json                # propiedad de la máquina
└── features/<feature>/
    ├── plan.md                 # problema, flujo, impacto, relaciones, superficie, aterrizaje, criterios, supuestos (todos s), observable
    ├── checks.md               # afirmaciones + pruebas, unión de cobertura, política de prueba, barrido, lotes de traspaso
    └── verification.md         # el informe del Verificador independiente

Crea cada archivo cuando su fase produzca contenido. Para un cambio de aproximadamente tres archivos sin puerta unidireccional y sin ambigüedad de alcance, escribe solo checks.md con un párrafo ## Intención y omite plan.md.

Cinco secciones de diseño acotadas en `plan.md`

Sección	Revisa	Se mantiene fuera
`Flujo`	la ruta, una línea por salto	cualquier módulo que ni exista ni sea creado por una puerta - eso es colocación
`Impacto`	qué cambia por debajo: términos y datos existentes	registros de riesgo
`Relaciones`	entidades, cardinalidad, restricciones unidireccionales	columnas y tipos
`Superficie`	ruta, entrada, salida, estados	especificación del cuerpo de la solicitud e identificadores de verificación - esos aún no existen
`Aterrizaje`	las puertas unidireccionales, con la forma literal y la alternativa rechazada	cualquier cosa que una refactorización revierta

Flujo

Descubrir — Despacha el subagente scout de solo lectura para inspeccionar el repo, .specs/STATE.md y .specs/LESSONS.md y devolver un informe de ambigüedad de ~30 líneas. Guía al usuario a través de áreas grises genuinas del producto y el alcance (como máximo 2 preguntas por turno, opciones concretas con valor predeterminado recomendado) a través de las superficies Observable y las 9 dimensiones implícitas hasta que no queden dudas: discovery.md.
Planificar — Despacha el subagente planner con las decisiones de descubrimiento confirmadas para escribir .specs/features/<feature>/plan.md y pasar validate_plan.py. Presenta plan.md al usuario para una aprobación rápida: plan.md.
Verificaciones — Una vez que plan.md está aprobado, se ejecuta autónomamente. Despacha un subagente specifier dedicado para derivar .specs/features/<feature>/checks.md (afirmaciones + pruebas, unión de Cobertura, Barrido, y tamaño de lote ## Traspaso) y pasar validate_checks.py, luego termina ese subagente antes de que se escriba cualquier código o prueba: checks.md.
Construir — Después de que specifier termine, despacha un subagente builder nuevo por segmento (S1, S2, ...) secuencialmente. Cada constructor escribe pruebas a partir de las verificaciones para su segmento asignado, implementa, ejecuta pruebas, registra Límite en checks.md, confirma con check_commit.py y sale: build.md.
Verificar y Reparar — Despacha un subagente verifier nuevo sobre <feature base>..HEAD para escribir verification.md y ejecutar validate_verification.py. Si FALLA, despacha un subagente fixer y vuelve a verificar (hasta 3 rondas): verify.md.
Orquestación y Despacho de Subagentes — Reglas del Orquestador Delgado, presupuestos de ventana de contexto y mapeos multi-agente (antigravity, claude, codex): orchestration.md.
Memoria Duradera — Decisiones del proyecto (STATE.md), traspaso de sesión y lecciones fundamentadas en verificación (lessons.py): memory.md.

Scripts

Resuelve <skill-dir> como el directorio que contiene este SKILL.md e invoca python3 <skill-dir>/scripts/<nombre>.py. Pasa --root cuando el directorio de trabajo difiera de la raíz del proyecto. Una salida distinta de cero significa DETENERSE y arreglar.

Cuándo	Comando
Inspeccionar la fase del pipeline y el siguiente rol del subagente	`orchestrate.py status <feature> --root <dir>`
Generar un prompt de subagente aislado	`orchestrate.py prompt --role <scout
Ejecutar la compuerta de fase a través del orquestador	`orchestrate.py gate --phase <plan
Despachar subagente a través de CLI (o `--dry-run`)	`orchestrate.py dispatch --role --agent <antigravity
Antes de presentar `plan.md`	`validate_plan.py <feature>`
Antes de comenzar `CONSTRUIR`	`validate_checks.py <feature>`
Antes de cada commit	`check_commit.py --message "<msg>"`
Antes de declarar terminado	`validate_verification.py <feature>`
Al destilar	`lessons.py add ...`
Después de editar un validador, script o plantilla	`selftest.py`

Subagentes y traspaso

Cada fase está estrictamente aislada en su propia invocación de subagente (scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer). Nunca combines specifier (VERIFICACIONES) y builder (CONSTRUIR) en el mismo subagente. Durante CONSTRUIR, cuando una característica tiene múltiples segmentos (S1, S2, ...), despacha un subagente builder separado por segmento secuencialmente para que cada constructor comience con una ventana de contexto limpia, termine rápidamente, confirme su segmento en verde y devuelva una actualización de progreso al Orquestador Delgado.

Cuando el segmento constructor final regresa en verde, el Orquestador despacha inmediatamente el subagente verifier independiente en el mismo turno sin preguntar al usuario.

Cadena de conocimiento

En orden estricto: código existente y convenciones, docs del proyecto, documentación de librerías (Context7 donde esté disponible), búsqueda web, luego marcar como incierto. Nunca inventes una API, una bandera, un comando o un comportamiento.

Comportamiento de salida

Produce el artefacto; no narres la fase. Comienza con el veredicto. Expresa las decisiones de manera definitiva. Elimina relleno y ambigüedad mecánica. Mantén los encabezados de las secciones en inglés (son un esquema verificado por las compuertas).

brenoacker/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación