VARIAS PERSONAS / SUS AGENTES / UN PRODUCTO

Factory,
en equipo.

Cada persona trabaja con sus propios agentes, en su checkout o en su máquina. Los agentes construyen y proponen; las personas deciden, y cada decisión queda registrada a nombre de quien la tomó. Una persona integra y cierra.

Factory 0.1.0a8Probado con agentes y en contenedoresPiloto con personas pendiente

EL EJEMPLO

Ana, Bruno y un repositorio en común.

Ana y Bruno mantienen una app de notas. Cada uno trabaja en su máquina con un agente de código, y comparten un remoto de Git. Ana va a agregar la consulta de notas; Bruno, la pantalla que las muestra. Las dos cosas dependen de un contrato común: qué campos tiene una nota.

Factory no reparte el trabajo ni lanza a los agentes: eso lo acuerdan las personas. Lo que hace es que cada cambio tenga un acuerdo escrito, requisitos medibles, una revisión registrada y un cierre decidido por una persona, y que todo eso viaje en Git para que el otro lo vea.

La guía completa, con plantillas y comandos para cada paso, está en docs/colaboracion.md. Esta página es el recorrido.

PASO 01

Repartir antes de escribir.

Cada frente es un cambio de Factory, con su propia tarea y su propio acuerdo. Ana y Bruno los crean antes de implementar:

oracle-factory nuevo --capacidad consulta "Agregar consulta de notas"
oracle-factory nuevo --capacidad pantalla "Mostrar notas en pantalla"

Los crea una persona del equipo en la rama principal, revisa y acepta cada acuerdo, importa sus requisitos y sube todo al remoto antes de repartir; así los dos parten del mismo punto. El ID de cada cambio termina en su capacidad (…-consulta, …-pantalla), o en lo que elijan con --sufijo.

oracle-factory aprobar-spec ID_DEL_CAMBIO
oracle-factory importar ID_DEL_CAMBIO
git add .
git commit -m "Acuerdos de la consulta y la pantalla"
git push

aprobar-spec pregunta con un menú de opciones: es una decisión de persona y se responde desde la terminal. importar imprime el ID de cada requisito. Copian la plantilla de reparto a la tarea y anotan quién es responsable, qué agente escribe, sobre qué commit base, en qué rama y qué archivos toca cada uno. Lo que comparten —el contrato de una nota, los catálogos de Oracle, la configuración— lo dejan escrito como interfaz: cambiar titulo por nombre puede romper la pantalla aunque Git fusione sin conflictos.

Para que dos frentes no pisen los mismos archivos, cada capacidad usa su propio prefijo: sensor_consulta.py, catálogos consulta.*, una relación consulta_comprobacion. Si aparece una superposición, se detiene ese trabajo y se acuerda de nuevo antes de editar.

PASO 02

Un lugar por persona.

En máquinas distintas, cada persona clona el repositorio y trabaja en su rama. En una sola máquina, cada frente usa su propio git worktree. Nunca dos frentes en la misma carpeta.

Factory calcula una huella con los archivos del producto (código, pruebas, specs y medidas; no los registros, la evidencia ni la spec consolidada que genera): por eso un cambio ajeno en la misma carpeta puede vencer una revisión. Los registros de Factory guardan rutas relativas al proyecto, así que un cambio que Ana juzgó en su máquina se puede revisar y cerrar desde la de Bruno. Los comandos encuentran el proyecto desde cualquier subcarpeta, como Git, y .factory/local/ —los checkouts de revisión de cada máquina— queda fuera de Git.

# En la máquina de Ana
git clone URL_DEL_REPOSITORIO notas-ana
cd notas-ana
git switch -c trabajo/consulta
oracle-factory donde ID_DEL_CAMBIO

# En la máquina de Bruno
git clone URL_DEL_REPOSITORIO notas-bruno
cd notas-bruno
git switch -c trabajo/pantalla

donde lista cada artefacto del cambio con su ruta y el gate que respalda; ruta dice dónde guardar la evidencia, el paquete de Clue o el checkout de revisión de un candidato.

PASO 03

Quién decide qué.

Cada cambio tiene un modo de trabajo que fija cuánto decide una persona. Los agentes trabajan con --agente y quedan registrados como agentes; las personas deciden desde su propia terminal, y una entrada por tubería no cuenta como persona.

Modo	Aceptar la spec y elegir medidas	Cuándo conviene
`confirmacion` (por defecto)	El agente propone; una persona confirma todo repitiendo el comando sin `--agente`.	Trabajo nuevo, equipos que recién empiezan, cualquier cosa que importe.
`funcional`	Una persona decide los requisitos funcionales; el agente puede decidir los no funcionales.	Cuando el equipo confía en el agente para lo técnico pero no para el qué.
`autonomo`	El agente decide, y queda registrado que lo hizo un agente.	Pruebas, prototipos o tareas mecánicas. Elegirlo lo decide una persona.

En todos los modos, estado muestra quién propuso, quién confirmó y quién decidió cada cosa. En equipo esto importa: Bruno puede ver qué aceptó Ana y qué propuso el agente de Ana, sin preguntarle.

oracle-factory --agente agente-de-ana medir ID_DEL_CAMBIO --requisito ID_DEL_REQUISITO --medida consulta.casos
oracle-factory estado ID_DEL_CAMBIO

PASO 04

Pasar el trabajo sin perder contexto.

Si Ana tiene que dejar su frente a Bruno, copia la plantilla de relevo a la tarea y anota base y commit, qué terminó, qué falta, cómo se prueba y qué decisiones quedaron pendientes. Ana deja de escribir en ese frente al ofrecer el relevo; Bruno lo lee sobre el commit indicado y confirma la recepción. Quien recibe actualiza el reparto (el escritor activo y el estado del frente) en el mismo commit en que lo acepta. Que nadie conteste no es una recepción.

Conviene separar dos commits: el del producto (código, pruebas, spec) y el de la evidencia (hechos del sensor, informes). Se ofrece y se revisa el commit del producto; la evidencia lo cita. Un relevo commiteado no puede contener su propio hash, y como los registros y la evidencia no cuentan en la huella del producto, guardarlos después no vence la revisión.

PASO 05

Revisar el trabajo del otro.

Lo ideal es que revise alguien distinto de quien escribió: otra persona, u otro agente de una familia de modelo distinta a la del que escribió el código. Son dos herramientas separadas. Oracle Clue prepara el contexto de un candidato para el revisor y después valida su informe:

oracle-clue preparar --repo . --base BASE_DE_REVISION --salida /ruta/fuera/del/repo/contexto.json

Factory no llama a Clue: deja preparada la revisión guiada, un informe y un documento de decisiones por completar con lo que surgió de la revisión.

oracle-factory revision-preparar ID_DEL_CAMBIO

El revisor completa el informe con lo que realmente revisó, sus comprobaciones y sus límites; una persona decide cada hallazgo —corregido, descartado o riesgo aceptado— en un documento aparte, y registra la revisión:

oracle-factory revision ID_DEL_CAMBIO --formato guiado --informe RUTA_INFORME --decisiones RUTA_DECISIONES --revisor "Bruno" --decision aprobar

Factory comprueba la estructura del informe y calcula los hallazgos abiertos; no juzga si el análisis es bueno. Una corrección cambia el candidato: se prepara y se revisa de nuevo.

PASO 06

Integrar una entrega por vez.

Una persona integra, desde un checkout limpio, una entrega por vez y en el orden acordado:

git switch main
git pull
git merge --no-ff trabajo/consulta

El registro de la integración va en la tarea del primer cambio integrado y la otra lo referencia (Oracle Task sólo acepta IDs de tareas, no carpetas sueltas).

Después de integrar, se vuelve a correr el sensor sobre el candidato integrado. Una revisión sigue vigente si los archivos del producto no cambiaron, aunque cambie el commit; si el merge cambió algo, hay que revisar otra vez. Los riesgos que cada frente aceptó por separado se vuelven a mirar contra el candidato integrado: algo aceptable en la consulta sola puede no serlo con la pantalla al lado.

Antes de registrar nada, cada uno puede verificarse sin dejar rastro con oracle cobertura --con HECHOS: muestra qué requisitos se cumplen con esos hechos sin registrar un veredicto.

oracle-factory juzgar ID_DEL_CAMBIO --con RUTA_DE_LOS_HECHOS
oracle-factory estado ID_DEL_CAMBIO

PASO 07

Cierra una persona.

Con la revisión registrada y el veredicto de Oracle verde, una persona decide el cierre desde su terminal (sólo en modo autonomo puede cerrar un agente, y queda registrado así). Al cerrar, la spec del cambio se fusiona en openspec/specs/ —lo vigente de cada capacidad— y se regenera .factory/resumen.md: el estado de todo el proyecto en una lectura, con los cambios abiertos de los demás y lo que les falta.

oracle-factory cerrar ID_DEL_CAMBIO
oracle-factory resumen --verificar

Así, cuando Bruno hace git pull, no tiene que leer las propuestas de Ana para saber qué cambió: lee la spec consolidada de la consulta y el resumen (con formato, glow -p .factory/resumen.md).

LO QUE NO SE PROBÓ

Hasta dónde llega lo comprobado.

No se probó todavía con personas reales. El recorrido de esta página se comprobó así:

Un piloto con sesiones reales de agentes, coordinadas por un agente en lugar de personas: dos frentes, un relevo, un solapamiento y una integración. Sus fricciones están corregidas en la guía.
Una demostración automática en repositorios temporales: aislamiento, conflictos, relevos, clones divergentes, revisión con Clue, vigencia tras integrar y cierres rechazados.
Dos «máquinas» en contenedores (Ana y Bruno) sin archivos compartidos, con un remoto Git común: un cambio juzgado en una se cierra desde la otra.

Lo que falta medir: cuánto esperan las personas, dónde se confunden y si el reparto escrito alcanza en la práctica. También queda fuera que dos personas modifiquen a la vez el registro de un mismo cambio (la regla es un frente, un escritor) y Windows y macOS, que no se probaron. Factory tampoco autentica a las personas: el nombre registrado es el de la configuración de Git de quien tiene la terminal.

Volver a la portada

Factory,en equipo.