Software Factory

Team per repo and per request

Which agent and model plays each Software Factory role — the workspace team, `.ghosty/factory.md` in the repo and "@build con opus" in the message.

Updated 2026-10-16

Ask your coding agent

Read https://www.ghosty.studio/en/docs/factory/team-per-repo.md and create this repo's `.ghosty/factory.md` with the conventions you see in the code.

Paste it in Claude Code, Cursor or Codex with the ghosty-agent skill installed.

Arqui covers the plan and review steps (plan and check in the configuration) and Worker the build step (build); that's why those names stay here.

Who plays each role is decided at three levels. The most specific wins:

message > the repo's .ghosty/factory.md > workspace team

Workspace team

In /factory → "Workspace team" (owner only): which Studio agent is @plan, @build and @check by default, plus the optional @eval. Every repo that doesn't say otherwise uses it.

From the CLI: ghosty agents teams on <id> <workspace> --factory plan,build,check gives those roles to an agent (each role keeps its name and avatar). ghosty agents teams ls <id> shows which roles it holds in each workspace.

If nobody asks for a model, @plan and @check run on Opus 5.5 when their agent is a Claude one; @build uses its agent's model. On another engine, each role uses its agent's model.

.ghosty/factory.md in the repo

A file in the repo with frontmatter per role and, below it, the conventions all three roles must know:

markdown
---plan: { agent: Planner }build: { agent: Builder, model: opus }check: { agent: Reviewer, model: flash }---Conventions of this repo that @plan, @build and @check must know:- Tests run with `pnpm test` and use Vitest.- Already-applied migrations in `prisma/migrations/` are never touched.
## @checkA change to `.github/workflows/` or `prisma/` without a test is a finding.
  • agent: name or id of a Studio agent in your workspace.
  • model: alias (opus, sonnet, fable, pro, flash, sol, terra, luna) or full id. It must belong to that agent's engine: changing engine means changing agent.
  • A role that isn't listed uses the workspace's. The body travels with every factory turn and overrides the generic rules.
  • A ## @plan, ## @build or ## @check section goes only to that role: that's where this repo's review rules go, for example. It ends at the next ## .
  • It's read with a 5-minute cache; in /factory, "Team in this repo" → ↻ refreshes it and shows where each role comes from ("from the repo" or "from the workspace").

Test environment: setup:

If the repo's tests need a database, Redis or variables, declare it in the same frontmatter. @build and @check get the exact call that prepares their work box before every run:

markdown
---build: { agent: Constructor }setup:  services: [postgres, redis]  db: fruteria  script: .ghosty/setup.sh  env:    JWT_SECRET: test-actions-jwt-secret---
  • services: postgres, redis and mongo (or mongodb), installed and stopped in the dev box. Anything else is ignored.
  • db: name of the database and its user (the password is the same name). It's dropped and recreated on every run, so the suite always starts with an empty database. The connection arrives as DATABASE_URL; Redis as REDIS_URL.
  • With mongo, the db database (or app) is emptied on every run and arrives as MONGO_URL and MONGODB_URI; also as DATABASE_URL when you didn't ask for postgres, which is what Prisma reads with provider = "mongodb". Mongo runs as a single-node replica set, so Prisma can write.
  • Each PR preview starts the same services. Mongo also starts on its own when the repo uses Prisma with provider = "mongodb" or its .env.example asks for MONGO_*/MONGODB_* variables. The variables you saved for the repo always win.
  • env: test variables, the same ones your CI uses. Never real secrets: the repo's secrets stay in the vault.
  • script: runs from the repo root with that env loaded (migrations, seeds).
  • If the repo doesn't have it and the request touches tests with a database, @plan proposes it from the services: in .github/workflows/.

Required preview and smoke: smoke:

A run requires the preview when @plan marks it (some criterion can only be checked with the app running) or when it is a major Dependabot bump. Then:

  • @check can't approve without the preview ready on the PR's latest commit. Testing in its own box doesn't count: it skips the https proxy and your variables.
  • «Merge» is blocked while the preview builds (it waits in the queue), waits for variables or fails. If you really don't need it, «Merge without preview» lets it through and leaves a record in the run's log.
  • If variables are missing, the factory warns again in the thread when review starts and when the PR is ready.

The «Ghosty · Preview» check on GitHub. The Ghosty App publishes a check with that name on every commit of a run's PR, so the gate also holds when someone merges straight on GitHub or an agent calls github_merge_pr:

Check stateWhen
In progressThe required preview is building for that commit.
✅ SuccessThe preview is ready on that commit and the smoke found no failures.
❌ FailureVariables are missing (with the link to save them), the preview didn't start (with the reason) or the smoke rejected it.
NeutralThe run doesn't require a preview, the repo has it off («No preview») or someone chose «Merge without preview» (it says who). GitHub counts neutral as passing.

It updates on every new commit and every preview change. It's informational: GitHub doesn't require it and automerge doesn't depend on it. The factory enforces the gate when merging (card, «merge it» and automerge), so a missing App permission never leaves a PR stuck.

Production variables. When you save the preview's variables, gs checks which ones touch production: a database URL with a remote host (any mongodb, postgres, mysql or redis that isn't localhost, whatever the database is called), a live payment key (sk_live_, rk_live_, pk_live_, APP_USR-) or a real email service (SES, SMTP other than Mailpit/Mailhog, Resend, SendGrid, Postmark). Only the name and the reason leave gs, never the value. If any are found, «Variables» turns red with «⚠ The preview uses PRODUCTION resources», the preview-ready notice in the thread says «⚠ usa prod», and the agents know before planning: with a remote database, @check doesn't run tests that write; with a live key, it doesn't complete payments. Replace them with test variables so the review can test everything.

Once the preview is ready, the platform sends a POST with the real Origin (as a browser would). On React Router apps it does this on its own against /. To test other routes with forms, declare them:

markdown
---smoke: [/book, /login]---
  • Up to 5 absolute paths. The POST is empty: the origin and CSRF check runs before your action, so nothing is saved.
  • A 400, 403 or 5xx stops the verdict and the merge of that commit. A 2xx, 3xx, 404, 405 or 422 counts as the request getting through.
  • If the app isn't React Router and you declare no routes, nothing is sent.
  • After the merge it runs again against production (the repo's homepage on GitHub), once the deploy is green and the pages load. If a request fails, the card's «Prod» step turns red and the thread gets the route, the status code and a suggestion to revert the PR. Nothing is reverted automatically. Without a homepage, it doesn't run.

A box per run

Each run gets its own computer (4 GB) from the moment you sign the plan until it's merged or cancelled: @build builds there, @check tests there (on a clean clone of the PR) and the preview runs there. Idle, it sleeps; when the run closes, it's deleted. Your factory plan has execution slots (F1: 3, F2: 5, F3: 8) shared by runs and by previews of PRs without a run. A new run displaces a loose preview; a new loose preview replaces the oldest one; if every slot is a run in progress, the run or preview waits ("Waiting for a slot") and starts on its own as soon as one frees up.

In the message

text
@build con opus@plan en agenda@plan en blissito/agenda con sonnet

The keywords stay in Spanish (con = with, en = in):

  • "con <model>" changes that role's model in that thread: later hand-offs of the same request inherit it.
  • "en <repo>" picks the repo when the room has several.
  • A model from another engine or an agent that doesn't exist won't run: the thread says why.

Each reply's footer shows the model that ran that turn, not just the configured one.