Software Factory

Equipo por repo y por pedido

Qué agente y qué modelo hace cada rol de la Software Factory — el equipo del espacio, `.ghosty/factory.md` en el repo y «@build con opus» en el mensaje.

Actualizado 2026-10-16

Pídeselo a tu agente de código

Léete https://www.ghosty.studio/docs/fabrica/equipo-por-repo.md y crea el `.ghosty/factory.md` de este repo con las convenciones que veas en el código.

Pégalo en Claude Code, Cursor o Codex con la skill ghosty-agent instalada.

Arqui cubre los pasos de plan y revisión (plan y check en la configuración) y Worker el de construcción (build); por eso aquí siguen esos nombres.

Quién hace cada rol se decide en tres niveles. Gana el más específico:

mensaje > .ghosty/factory.md del repo > equipo del espacio

Equipo del espacio

En /factory → «Equipo del espacio» (sólo el dueño): qué agente de Studio es @plan, @build y @check por defecto, y el @eval opcional. Es lo que usan todos los repos que no dicen otra cosa.

Desde el CLI: ghosty agents teams on <id> <equipo> --factory plan,build,check le pasa esos roles a un agente (cada rol conserva su nombre y avatar). ghosty agents teams ls <id> enseña qué roles lleva en cada equipo.

Si nadie pide modelo, @plan y @check corren en Opus 5.5 cuando su agente es de Claude; @build usa el modelo de su agente. Con otro motor, cada rol usa el modelo de su agente.

.ghosty/factory.md en el repo

Un archivo en el repo con frontmatter por rol y, debajo, las convenciones que deben saber los tres roles:

markdown
---plan: { agent: Planeador }build: { agent: Constructor, model: opus }check: { agent: Revisor, model: flash }---Convenciones de este repo que deben saber @plan, @build y @check:- Las pruebas se corren con `pnpm test` y usan Vitest.- No se tocan las migraciones ya aplicadas en `prisma/migrations/`.
## @checkUn cambio a `.github/workflows/` o a `prisma/` sin prueba es hallazgo.
  • agent: nombre o id de un agente de Studio de tu espacio.
  • model: alias (opus, sonnet, fable, pro, flash, sol, terra, luna) o id completo. Tiene que ser del motor de ese agente: cambiar de motor es cambiar de agente.
  • Un rol que no aparece usa el del espacio. El cuerpo viaja en cada turno de la fábrica y le gana a lo genérico.
  • Una sección ## @plan, ## @build o ## @check va sólo a ese rol: ahí van, por ejemplo, las reglas de revisión de este repo. Termina en el siguiente ## .
  • Se lee con caché de 5 minutos; en /factory, «Equipo en este repo» → ↻ la refresca y dice de dónde sale cada rol («del repo» o «del espacio»).

Entorno de pruebas: setup:

Si las pruebas del repo piden base de datos, Redis o variables, decláralo en el mismo frontmatter. @build y @check reciben la llamada exacta que deja su caja de trabajo lista antes de cada corrida:

markdown
---build: { agent: Constructor }setup:  services: [postgres, redis]  db: fruteria  script: .ghosty/setup.sh  env:    JWT_SECRET: test-actions-jwt-secret---
  • services: postgres, redis y mongo (o mongodb); vienen instalados y apagados en la caja dev. Otros se ignoran.
  • db: nombre de la base y de su usuario (la contraseña es el mismo nombre). Se borra y recrea en cada corrida, así que la suite siempre arranca con la base vacía. La conexión llega como DATABASE_URL; Redis como REDIS_URL.
  • Con mongo, la base db (o app) se vacía en cada corrida y llega como MONGO_URL y MONGODB_URI; también como DATABASE_URL si no pediste postgres, que es la que lee Prisma con provider = "mongodb". Mongo corre como réplica de un nodo, así que Prisma puede escribir.
  • La preview de cada PR arranca los mismos servicios. Mongo además se enciende solo si el repo usa Prisma con provider = "mongodb" o su .env.example pide variables MONGO_*/MONGODB_*. Las variables que guardaste para el repo siempre ganan.
  • env: variables de prueba, las mismas que usa tu CI. Nunca secretos reales: los del repo siguen en la bóveda.
  • script: se corre desde la raíz del repo con ese env cargado (migraciones, semillas).
  • memory: memoria de la caja del pedido y de su preview, de 4gb (la de siempre) a 8gb (el tope), en GB enteros. Para builds pesados: el heap de Node sale solo del ~75 % de la caja (3 GB en 4 GB, 6 GB en 8 GB), así que no hace falta NODE_OPTIONS en las variables. Una caja de 8 GB ocupa dos lugares de tu tier. Un valor que no se entiende usa 4 GB; se lee de la rama principal al crear la caja del pedido.
  • Si el repo no lo trae y el pedido toca pruebas con base de datos, @plan lo propone a partir de los services: de .github/workflows/.

Preview exigida y smoke: smoke:

Un pedido exige la preview cuando @plan lo marca (algún criterio sólo se comprueba con la app corriendo) o cuando es una subida mayor de Dependabot. Entonces:

  • @check no puede aprobar sin la preview lista en el último commit del PR. Probar en su caja no la sustituye: no pasa por el proxy https ni lleva tus variables.
  • «Merge» se bloquea mientras la preview se construye (queda en cola), espera variables o falla. Si de verdad no hace falta, «Mezclar sin preview» lo deja pasar y queda en la bitácora del pedido.
  • Si faltan variables, la fábrica lo vuelve a avisar en el hilo al entrar a revisión y al quedar el PR listo.

El check «Ghosty · Preview» en GitHub. La App de Ghosty publica un check con ese nombre en cada commit del PR de un pedido, así la puerta también aplica si alguien mezcla directo en GitHub o un agente usa github_merge_pr:

Estado del checkCuándo
En cursoLa preview exigida se está construyendo para ese commit.
✅ ÉxitoLa preview está lista en ese commit y el smoke no encontró fallos.
❌ FallóFaltan variables (con la liga para guardarlas), la preview no arrancó (con el motivo) o el smoke la rechazó.
NeutralEl pedido no exige preview, el repo la tiene apagada («Sin preview») o alguien eligió «Mezclar sin preview» (dice quién). GitHub cuenta neutral como pasado.

Se actualiza con cada commit nuevo y con cada cambio de la preview. Es informativo: GitHub no lo exige y el automerge no depende de él. La puerta la aplica la fábrica al mezclar (tarjeta, «mézclalo» y automerge), así que un permiso faltante de la App nunca deja un PR bloqueado.

Variables de producción. Al guardar las variables de la preview, gs revisa cuáles tocan producción: una URL de base de datos con host remoto (cualquier mongodb, postgres, mysql o redis que no sea localhost, se llame como se llame la base), una llave live de pagos (sk_live_, rk_live_, pk_live_, APP_USR-) o un servicio de correo real (SES, SMTP que no sea Mailpit/Mailhog, Resend, SendGrid, Postmark). Sólo el nombre y el motivo salen de gs, nunca el valor. Si hay alguna, «Variables» se marca en rojo con «⚠ La preview usa recursos de PRODUCCIÓN», el aviso de preview lista en el hilo dice «⚠ usa prod», y los agentes lo saben antes de planear: con una base remota, @check no hace pruebas que escriban; con una llave live, no completa pagos. Reemplázalas por variables de prueba para que la revisión pueda probar todo.

Con la preview lista, la plataforma manda un POST con el Origin real (como el navegador). En apps de React Router lo hace sola sobre /. Para probar otras rutas con formulario, decláralas:

markdown
---smoke: [/reservar, /login]---
  • Hasta 5 rutas absolutas. El POST va vacío: el chequeo de origen y CSRF corre antes que tu acción, así que no guarda nada.
  • Un 400, un 403 o un 5xx frenan el veredicto y el merge de ese commit. Un 2xx, 3xx, 404, 405 o 422 cuentan como que el envío pasó.
  • Si la app no es de React Router y no declaras rutas, no se manda nada.
  • Después del merge se repite contra producción (el homepage del repo en GitHub), tras el deploy verde y la revisión de que las páginas cargan. Si un envío falla, el paso «Prod» de la tarjeta queda en rojo y el hilo avisa con la ruta, el código y la sugerencia de revertir el PR. No se revierte solo. Sin homepage, no corre.

Caja por pedido

Cada pedido tiene su propia computadora (4 GB) desde que firmas el plan hasta que se mezcla o se cancela: ahí construye @build, ahí prueba @check (en un clon limpio del PR) y ahí sale la preview. Si nadie la usa, se duerme; al cerrar el pedido se borra. Tu plan de fábrica tiene lugares de ejecución (F1: 3, F2: 5, F3: 8) que comparten los pedidos y las previews de PRs sin pedido. Un pedido nuevo desplaza a una preview suelta; una preview suelta nueva reemplaza a la más vieja; si todos los lugares son pedidos en curso, el pedido o la preview esperan («En espera de lugar») y arrancan solos en cuanto se libera uno.

En el mensaje

text
@build con opus@plan en agenda@plan en blissito/agenda con sonnet
  • «con <modelo>» cambia el modelo de ese rol en ese hilo: los relevos siguientes del mismo pedido lo heredan.
  • «en <repo>» elige el repo cuando el room tiene varios.
  • Un modelo de otro motor o un agente que no existe no se corre: el hilo dice por qué.

El pie de cada respuesta dice el modelo que corrió ese turno, no sólo el configurado.