Skip to main content
A Software Factory is a configured pipeline of agents, a runtime, and a repository that turns a labeled issue into a planned change, an implementation, and a reviewed pull request — without you wiring up each piece by hand.

​
Ways to set one up

  • Smith commissioning — describe what you want in chat and Smith drives the setup end to end. See Software Factory commissioning below.
  • Factory setup wizard — a form-based path through the same setup, screen by screen.
  • CLI — run guild factory init to wire a workspace to a repository from your terminal.

​
Software Factory commissioning

Smith can commission a Software Factory for you, so you do not have to wire up its repository, runtimes, labels, agents, contexts, and triggers by hand. When you ask Smith to build a Software Factory, it runs the blueprint_software_factory skill, which drives the setup end to end and stores every configuration value as a workspace variable. Storing configuration this way lets the same blueprint run in any workspace.

​
Workspace variable contract

Smith reads and writes thirteen workspace variables that hold the Factory’s configuration instead of pinning values in agent code. These variables cover four areas:
  • Repository — the repository the Factory operates on, such as FACTORY_REPOSITORY.
  • Coding runtime — the runtime the Factory uses to make code changes, such as FACTORY_RUNTIME_ENVIRONMENT.
  • Read-only runtime — the runtime the Factory uses for read-only inspection.
  • Control labels — the labels that coordinate Factory work, such as FACTORY_LABEL_AUTO.
Because the configuration lives in workspace variables, you can reuse the same Factory blueprint in another workspace by setting that workspace’s variables. See Workspace variables.

​
Two-phase commissioning

Smith commissions a Factory through a smart-default intake process that requires exactly one approval for the complete commissioning plan. Instead of asking you a series of questions about mode, labels, and ownership, Smith applies smart defaults, presents a single compact commissioning plan, and proceeds once you approve it. Smith commissions a Factory in two phases:
  1. Bootstrap Proposal — Smith proposes the Factory setup, including the runtime environment and setup script, and presents the complete commissioning plan for your approval.
  2. Create, Verify, Configure, and Assemble — after this single plan approval, Smith applies the Bootstrap-proposed setup script, creates the runtime, verifies it, configures the workspace variables and labels, and assembles the Factory agents, contexts, and triggers automatically, without prompting you for mid-run approvals.
Smith installs a complete eight-agent runtime roster by default and uses a managed update policy (should_autoupdate: true). Smith uses the public guildai~github-repository-manager@1.x agent to set up and operate repository labels.
Labels, variables, Factory agents, contexts, and triggers stay unreachable until runtime environment verification passes. Env Verify must report a structured pass and confirm container cleanup before Smith commissions any Factory component.

​
Bounded runtime repair loop

If the setup script fails, Smith runs a bounded runtime repair loop instead of stopping. These repairs are automated under the authorization of the initial commissioning plan, so Smith does not prompt you for approval before modifying the runtime environment. The loop runs at most three repair rounds (MAX_FACTORY_RUNTIME_REPAIR_ATTEMPTS = 3). If all three repairs fail, or if Smith encounters a structural or unrepairable error, Smith stops polling and enters a deterministic awaiting_user state, surfacing the verifier evidence and waiting for your explicit direction before resuming a recovery cycle.

​
Optional end-to-end test run

After you commission a Factory, you can run an optional end-to-end test to confirm the full pipeline works before you rely on it. The test creates a throwaway issue, runs the Factory to produce a documentation-only pull request, and then closes the issue and pull request it created. You drive the flow with the guild factory test commands. See guild factory for the full command reference. The flow has four steps:
  1. Preview — run guild factory test preview --workspace <name> to preview the issue the test will create. The command returns a run ID and an approval digest.
  2. Run — run guild factory test run <run-id> --approve <digest> --accept-credits to run the approved test. The run uses agent credits to plan and implement a documentation-only change and open a pull request you can verify.
  3. Status — run guild factory test status <run-id> --watch to observe the run until it finishes.
  4. Cleanup — run guild factory test cleanup <run-id> to preview a close-only cleanup, then re-run it with --approve <digest> to close the generated test issue and pull request.
guild factory test run requires the --accept-credits flag and spends real agent credits with no hard spend cap. Run guild factory test cleanup when the test finishes to close the issue and pull request it created.
Last modified on October 15, 2026