El repositorio AI Software Factory describe cómo pasar de la misión del producto y una incidencia a una solicitud de integración construida por Archon. La instalación y las comprobaciones de los flujos son solo el comienzo. La guía de la primera hora del mantenedor dice que todavía falta la validación real de extremo a extremo. Esta guía sigue el commit de la fábrica 9e2d85298b45497031009597a6ae0811b66fe6d6 y su revisión fija de Archon fad09169ea1b43512bc7ee88470d47f960a3e0f8. Es una lectura de documentación y código; BIG CHANGE no ha instalado ni ejecutado la fábrica.

Está dirigida a un equipo que controla el repositorio de una aplicación o un PRD, sus permisos de GitHub y su cuenta del proveedor de modelos. El mantenedor documenta expresamente cómo clonar e instalar la fábrica en tu propio repositorio. El árbol fijado no incluye licencia ni aviso; esta guía no establece derechos más amplios de reutilización o redistribución. La licencia MIT de Archon se aplica al código separado de Archon. No incluyas secretos del proveedor en incidencias, instrucciones, registros ni actas de revisión.

El gran cambio

  • Qué cambia: La implementación conecta alcance del producto, planificación de incidencias, código, revisión independiente y controles de ejecución mediante un pack fijo de flujos Archon. La fábrica aporta entradas y lanzador; el pack compartido contiene los pasos de IA.
  • Por qué importa: El equipo puede seguir una propuesta desde la incidencia hasta unos cambios, un resultado de CI y un candidato ejecutado concretos antes de integrar. Los controles de instalación no completan esa cadena; el mantenedor dice que aún falta validar la integración real.
  • Qué observar: La primera prueba útil es una incidencia real cuya revisión entregada supere recorridos significativos y casos reservados independientes, con costes y registro de revisión visibles. Programación y despliegue siguen siendo decisiones separadas posteriores.

1. Comprobar el repositorio, los permisos y la fuente fijada

Las instrucciones de instalación requieren Git, Python 3.10 o posterior, gh autenticado con el ámbito workflow, un remoto de GitHub, un agente de programación, Bun y uv. Git también debe poder enviar archivos de flujos (gh auth setup-git). Antes de ejecutar el agente, comprueba los comandos existentes de pruebas, inicio y CI, la protección de ramas, el acceso a GitHub, la autenticación del proveedor y la facturación de modelos. Concede únicamente los permisos de repositorio y flujos necesarios.

Clona la fábrica fuera del repositorio de la aplicación y selecciona el commit indicado. Desde la raíz de la aplicación, el comando de instalación documentado es:

Terminal
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init

Usa python3 si hace falta. El instalador copia las plantillas de fábrica y proyecto e instala la fuente de Archon indicada en pack.json. El README y el pack de este commit especifican fad09169ea1b43512bc7ee88470d47f960a3e0f8. El instalador no autentica un proveedor, elige niveles de modelos ni inicia una programación. Inspecciona los cambios de archivos antes de aceptarlos en tu repositorio.

Configura el proveedor elegido y los identificadores de modelos admitidos según la documentación de Archon instalada. Define los comandos reales de análisis estático y pruebas unitarias en harness/harness.config.json. Cuando GitHub no pueda informar de la protección de ramas, indica en required_checks los trabajos de CI necesarios para integrar. Revisa protected_paths para que los cambios en la misión, el sistema de validación y las reglas de la fábrica requieran una persona. La plantilla deja vacíos los comandos normales de comprobación y required_checks: copiarla no crea una barrera de aceptación utilizable.

2. Escribir la misión y las comprobaciones del producto existente

Escribe en MISSION.md el propósito del producto, sus límites estrictos y solicitudes plausibles fuera de alcance. En harness/END-TO-END.md, describe de dos a cinco recorridos que la aplicación actual realmente complete, incluido el valor visible para el usuario. Un recorrido que exija una función sin construir bloquearía la primera entrega. En .factory/holdout/HOLDOUT.md, escribe casos separados que combinen comportamientos o exploren extremos. El nombre del directorio no los oculta al desarrollador con acceso a la misma copia; guarda los casos realmente privados fuera de ella y entrégalos solo a la verificación.

Si el repositorio contiene únicamente un PRD, el README pide derivar del documento la misión, los recorridos previstos y los comandos de validación. La primera incidencia propuesta debe hacer ejecutable el producto e indicar el comando de inicio, las rutas de salud e identidad de compilación, las pruebas y la CI. Revisa la propuesta antes de permitir la publicación de incidencias.

Convierte los recorridos en las entradas de escenario que esperan los flujos de ejecución de Archon. Sigue el archivo instalado factory/RUNTIME_HOST.md para preparar una instantánea desde el commit entregado, un estado nuevo, las comprobaciones de salud e identidad de compilación y los comandos Python o Node permitidos. El anfitrión documentado no admite bases remotas, contenedores ni recursos en la nube como recursos de ejecución que gestione. Una aplicación que los utilice necesita una solución de verificación justificada aparte; una comprobación local correcta no demostraría su aislamiento.

Antes de confiar en el evaluador, establece una referencia que apruebe y ejercite valor real para el usuario, demuestra que un fallo deliberado pertinente no aprueba y comprueba que una identidad de candidato incorrecta devuelve un resultado no concluyente. La guía del anfitrión detalla las entradas y los campos exactos esperados, incluidos expectations_passed: true y baseline_verified: true. Conserva el retorno nativo real y la identidad del candidato como pruebas. Comprobar solo que una página carga, o crear directamente el estado final de una prueba, resulta insuficiente.

3. Comprobar la instalación y elegir una tarea

Ejecuta estos comandos desde la raíz de la aplicación:

Terminal
python factory/consumer.py doctor
python factory/consumer.py list

doctor comprueba la fuente fijada, las capacidades de los comandos y los flujos disponibles. list muestra los flujos descubiertos. Ninguno demuestra que un proveedor termine una incidencia, que la CI apruebe o que la aplicación funcione. Resuelve los errores indicados antes de la entrega y mantén desactivada la programación.

Para una base de código existente, redacta una incidencia pequeña con resultado y criterios de aceptación claros. El README documenta este comando para pasar por clasificación, entrega y revisión hasta una solicitud de integración:

Terminal
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json

Sustituye la URL por una incidencia que controles. discovery_publication=preview evita que los hallazgos adyacentes de la revisión se publiquen como incidencias; el flujo fijado archon-ship utiliza auto de forma predeterminada. Usa archon-lifecycle solo cuando estén listos el escenario de ejecución y los casos reservados. Pasa la incidencia como target, las rutas de entrada como scenario y holdout, además de merge_mode=approve y discovery_publication=preview. Proporciona también un merge_method aprobado por el proyecto: merge, squash o rebase. Por ejemplo, utiliza merge_method=squash solo si tu repositorio lo permite. El flujo incluye verificación de ejecución y casos reservados, reparación y un control de integración. El modo de aprobación mantiene una decisión humana antes de integrar; la etiqueta de preparado del flujo no equivale a ella. La opción documentada --runtime-host funciona solo en primer plano y no puede combinarse con --detach ni --resume.

Para un PRD, el comando documentado del backlog es:

Terminal
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve

Sustituye docs/PRD.md, entre comillas en el comando, por la ruta real del PRD relativa a la copia de la aplicación. Revisa las incidencias ordenadas propuestas antes de publicarlas. Configura el anfitrión de ejecución con el inicio de la aplicación y el contrato de identidad declarados por la primera incidencia; luego procésala mediante archon-lifecycle con los recorridos y casos reservados preparados. La primera tarea exige el mismo cuidado que las siguientes.

4. Evaluar los cambios y el resultado ejecutado antes de aprobar

Conserva el identificador devuelto. El programa de control ofrece get <run-id> --json --events y status --all --json para seguir avances y pruebas. Contrasta la incidencia y el plan con MISSION.md; lee los cambios reales de la solicitud y la revisión independiente de su versión actual; comprueba la CI requerida y el informe de rutas protegidas. Ejecuta los recorridos sobre la revisión entregada e inspecciona los resultados nativos de ejecución y casos reservados, incluida la identidad del candidato. Compara lo observado por el usuario con los criterios de aceptación. El revisor debe devolver una solicitud deficiente para reparación; el README describe archon-deliver --adopt <run id> para una entrega retenida por la cola de integración.

Solo una persona con autoridad sobre el repositorio debe aprobar la integración tras superar las comprobaciones. El despliegue requiere comandos propios de despliegue, salud e identidad y una lectura posterior de la revisión desplegada; integrar una solicitud no demuestra un despliegue. Mantén apagada la programación durante la primera incidencia y decide aparte si activar ejecuciones recurrentes.

La guía de costes del mantenedor no fija un precio por ejecución. Recomienda medir los tokens desde el primer día y observar las llamadas a modelos en una incidencia pequeña antes de activar un bucle. Los cargos dependen del proveedor, los modelos y las condiciones de la cuenta. BIG CHANGE no ha medido el gasto de esta fábrica.

Una ejecución activa también necesita una decisión explícita de parada. El código del programa de control hace que halt bloquee lanzamientos y continuaciones, mientras cancel <run-id> actúa sobre trabajo activo. pause detiene los lanzamientos del temporizador, pero permite reactivar trabajo en curso. Ningún comando sustituye comprobar el estado actual y los cambios del repositorio remoto.

Fuentes y lecturas adicionales