Introduction
The factory is a way to build a product with coding agents. You decide what the product does. Agents write the code. Checks test the code before you merge it.
This guide takes you from an empty computer to a daily routine. Read the pages in order. Each page says what to do, what you should see, and how you know that you are done. The examples build one small product, fieldnote, an app where field officers log their visits.
#The path
| Page | What you do | What you have at the end |
|---|---|---|
| 1. Set up your computer | Install the tools | The commands work |
| 2. Set up AWS and GitHub | Connect the accounts, once | Your account is ready for CI and reviews |
| 3. Create the product | Run one command | A hub, an app and the panel |
| 4. Set the direction | Answer an agent's questions | What the product is, and a short list of next work |
| 5. Build your first task | Press the buttons for one small change | A merged pull request, and proof that the checks work |
| 6. Explore | Run research and design | Answers to your open questions |
| 7. Plan the work | Review a list with an agent | Milestones and tasks |
| 8. Your daily routine | Follow the same order each day | A product that moves |
Pages 1 and 2 happen once. Pages 3 to 7 happen once for each product. Page 8 is most of the work.
#Six words
You need these words for the rest of the guide.
| Word | It means |
|---|---|
| App | The repository with the code of your product. |
| Hub | A second repository. It holds what the product is, and the work to do. Agents run here. |
| Change task | One file in the hub that describes one change. Its code ends in one pull request. |
| Exploration | One folder in the hub that answers one question. It changes no code in the app. |
| Session | One run of Claude Code that does one step. It stays open until you close it. |
| Panel | A tab in the Herdr app. It shows the hub, and has a button for each step. |
#The loop
After setup, each change goes through the same six steps. The steps in colour need you. Agents do the others with nobody there.
- IntakeTurns an input into a task
- ProbeYou settle each open question
- BuildAn agent builds it and opens a pull request
- GatesCI and the Flow review
- MergeYou merge on GitHub
- AcceptFacts go to the context
You press a button for each step. A step never starts the next one by itself.
#Where it comes from
The factory is built from factories-hub, the software factory of Harminder Virk. His article A practical look at software factories explains the ideas. These docs describe factory-kit, which uses Herdr in place of Paseo, and AWS CodeBuild in place of GitHub Actions and the hosted reviewer.
#Next
Start with 1. Set up your computer.