The Software Factory is a ready-to-use Hubzoid hub that turns engineering requests into reviewed draft pull requests. It classifies the work, plans in a real checkout of your repository, builds in an isolated sandbox, and has an independent reviewer check the exact commit. A person approves the plan, reviews the draft, marks it ready and merges.
How it works
- Classifier triages the request: type, priority, complexity, and whether it is actionable. When it is not, the factory asks the requester instead of building the wrong thing.
- Analyst writes a plan with acceptance criteria, working from a real checkout of your repository. Attended requests wait here for the requester to approve the exact plan.
- Implementer carries out the plan in its own Docker sandbox, with no network and no credentials, and runs your repository's own checks. Workflow code checks the patch and pushes it to a factory branch. The agent never holds a GitHub token.
- Reviewer judges the pushed commit in a fresh checkout against every acceptance criterion, with evidence for each verdict. At most two revisions. The draft pull request opens only when the branch, the pushed commit and the reviewed commit are the same.
- Factory brain. Durable facts about your repository in
knowledge/factory-brain/, which every station reads and only reviewed hub changes update.
Every request is one work item. A restart resumes it from its last saved step, and nothing runs or posts twice. Every run ends in an answer, a plan, a reviewed draft or a stated stop reason with the next step. Architecture
Quick start
You need Python 3.12, Git, a running Docker engine, and Claude Code or Codex signed in on this machine. No API key. For the first run you also need the GitHub CLI (gh) signed in, to create a private scratch repository for the sample.
Paste this into Claude Code or Codex:
Clone https://github.com/hubzoid/software-factory-hub into a folder called
software-factory, cd in, and follow demo/PROMPT.md to run the labelled sample
on a new private scratch repository. Show me the plan before you build.
Do not merge anything.
Or by hand:
git clone https://github.com/hubzoid/software-factory-hub software-factory
cd software-factory
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
Keep the folder name software-factory: it is the hub's name, and the channel files use it. .env uses Claude Code (MODEL=claude-local). For Codex, set MODEL=codex-local.
Create the scratch repository from the labelled sample, with a planted rounding bug and a failing regression test, and add its issues:
cp -R fixtures/sample-repo ../factory-sample
(cd ../factory-sample && git init -q -b main && git add -A && git commit -qm "Sample" && gh repo create factory-sample --private --source . --push)
python demo/seed_issues.py OWNER/factory-sample
Point the factory at OWNER/factory-sample and connect GitHub (SETUP.md, steps 2 and 3). Then check and start:
hubzoid hub doctor .
hubzoid run . --port 8701 --bridge-port 8702
In the web chat at http://127.0.0.1:8701, ask:
Plan a fix for issue #1. Stop after the plan.
You get a plan with acceptance criteria, built from a real checkout. Then ask "Implement the fix for issue #1. Show me the plan first.", approve the exact plan in your Inbox, and you get a reviewed draft pull request with the reviewer's result for each acceptance criterion.
The builder skill holds the same steps for your coding assistant. Full setup
Integrations
| Works with | What the factory does |
|---|
| GitHub | Label an issue factory and it runs on its own, posting progress on the issue. Mention it (@your-app plan this) to ask, triage, plan or implement. It repairs failing CI on its own branches, at most twice, and posts one orientation comment on each new pull request. |
| Linear | Assign it a task. The plan comes back for you to approve in your Hubzoid Inbox. |
| The web chat and Slack | Ask for work or its status. Plans wait for your approval in the Inbox. |
| Claude Code, ChatGPT and Codex, over MCP | The same requests from your own assistant, with the plan waiting for your approval. |
| Another tracker | Ask in chat, and the factory pulls the issue in through that tracker's MCP server. |
Label and mention intake need a GitHub App. Chat and MCP intake can start with a token you type yourself. Channels · SETUP.md, step 3
Make it yours
The files you will edit, and what each one changes:
software-factory/
├── AGENTS.md the chat agent: answers questions, hands work to the factory
├── agents/
│ ├── classifier/AGENTS.md how requests are triaged
│ ├── analyst/AGENTS.md how plans are written
│ ├── implementer/AGENTS.md how the sandbox build runs
│ └── reviewer/AGENTS.md how the review judges a commit. Set engine: codex-local for a cross-vendor review
├── knowledge/factory-brain/ durable facts about each repository, one file per owner-repo
├── hub.settings.yaml FACTORY_REPO, channels, whether plans need approval
├── sandboxes/factory.yaml the Docker sandbox and its reviewed setup command
└── channels/ the GitHub, Linear and Slack connections
Each station is one page of instructions. Edit it in your checkout and review the change like any commit.
To point it at your own repository, set FACTORY_REPO in hub.settings.yaml and replace the install in sandboxes/factory.yaml with your repository's locked install, such as npm ci or uv sync --frozen. Then bootstrap a source-linked brief from committed files you choose:
python scripts/factory_setup.py context --checkout PATH --repository OWNER/REPO --source FILE --test-command 'CMD'
Review the preview, then store it as a pending hub change for a hub manager to apply. Start with plan-only requests, and move to implementation once the plans read right. SETUP.md, steps 2 and 4
To save a team rule from chat, tell the factory "Remember for the team: run the tests with pnpm test --runInBand." It proposes the exact edit to knowledge/factory-brain/<owner>-<repo>.md, a hub manager applies it, and every station sees it on the next run. A correction in chat is not shared until that edit is applied. Settings
Safety
- No merge, no push to a protected branch, no repository administration. A person marks a draft ready and merges in GitHub. Writes go only to
FACTORY_REPO, and unattended work writes only on the issue or pull request it came from.
- The person who asked decides. Attended implementation waits for the requester to approve the exact plan. An administrator cannot approve for them.
- Inputs are data, never instructions. Issue text, comments, repository files and web pages are read as data. Hidden HTML comments and invisible characters are removed before a model reads them.
An implement request is about five agent turns plus small routing calls, more with research or revisions. Budgets are opt-in in Hubzoid. Security details
Host it for your team
The factory runs on a server the same way any Hubzoid hub does: one image built from this repository, one durable folder at /data, sign-in on, and one public address. Three things are specific to the factory:
- A Docker engine the hub can reach, for the sandbox.
HUBZOID_SCHEDULES=1, so work items run in the background. It is set in .env.example.HUBZOID_PUBLIC_URL, your hub's HTTPS address, which the GitHub App webhook posts to.
Grant teammates access to the hub and to wf_factory. Linked GitHub, Slack and Linear identities get no rights from text in a ticket. Operations covers pause, recovery, backup and upgrade. Hubzoid deployment lists the hosting options and which are verified.
Go further
| Next step | Guide |
|---|
| Install, connect GitHub and get a first result | Setup |
| Every setting and its check | Settings |
| Connect GitHub, Linear and Slack | Channels |
| How routes, stations and publishing fit together | Architecture |
| Run it, back it up and upgrade it | Operations |
| Fix a failed station, intake or webhook | Troubleshooting |
| Behaviour checks | Evals |
Questions go to GitHub Discussions. Bugs in the factory go to this repository's issues.
The Software Factory is Apache-2.0. Built on Hubzoid. Need it running for your team? Build with us.
