A Software Factory Is a Workflow, Not a Product. Build One in 20 Minutes.

"Software factory" is a buzzword, but it doesn't have to be. Building software is a well-understood process: we know every activity involved and every tool required. A software factory just automates it. In this post we'll describe the process and list the capabilities needed to automate it. Then we'll build a software factory and discuss when using one is a good idea. We'll see that a software factory isn't a product but a workflow, and it only succeeds when you think of it this way. And building one is pretty easy. We'll also touch on why software factories fail in real organizations and how to make them work. How We Build Software These are the steps: - FIND WORK. You go to an issue tracker (e.g., Linear) to see what needs to be done. - GET DEBRIEFED. You read the issue and find related past work. Maybe you talk to other engineers to fill in the gaps. - SET UP REPOS. You figure out which repositories are relevant for the change, clone them, install dependencies, etc. - IMPLEMENT. You make the change across all the relevant repos. - REVIEW. You do a thorough review of the code before opening PRs. - OPEN PRs. You open the relevant PRs and make sure CI is green for all of them. - RECORD. You write down the decisions made, the design, so others can find it later. - COMPLETE. You mark the item as complete in the issue tracker. ## The Capabilities We Need To implement the steps above with an agent we need the following: - VCS - CI - Issue Tracker - PR and CI Orchestrator - Institutional Memory - Ephemeral Workspaces - Cross-repo Orchestrator - Adversarial Reviews - Trigger Note, it's very unlikely all of these will be provided by a single tool. VCS, CI, issue tracking are each deep, complex products, so the chances of your VCS provider also being the best CI and the best issue tracker are low. But they don't need to be. One of the nicer things about agentic development is that agents compose external systems well, as long as each one has a well-defined agentic API. Whether that's MCP or a CLI doesn't matter. How Agents Build Software (aka Factory) - FIND WORK. An agent accesses the Issue Tracker through an MCP server to see what needs to be done. - GET DEBRIEFED. An agent reads the issue and queries Institutional Memory for everything relevant: related past work, decisions, gotchas. - SET UP REPOS. An agent uses Institutional Memory to figure out which repos are relevant and uses Ephemeral Workspaces to provision fresh copies. - IMPLEMENT. An agent uses the Cross-repo Orchestrator to implement the change. Without it, the agent can only update one repo at a time. - REVIEW. An agent invokes Adversarial Reviews to analyze the source code and address the feedback. - OPEN PRs. An agent uses the PR and CI Orchestrator to create PRs and make sure CI is green. - RECORD. An agent uses Institutional Memory to record what it has done, both the high-level picture and the details. This is how Institutional Memory stays up to date. - COMPLETE. An agent marks the item as complete in the Issue Tracker. The Cross-repo Orchestrator matters more than it may seem. Humans carry cross-repo context in their heads, so even when changing a single repo, we have deep cross-repo awareness. Agents have to actually look at the other repos to get that. Let's Build It Once we have the capabilities, building a factory. It's just a script that wires everything together. It's more of a workflow, not a product. We are going to use Github for VCS (and whatever CI is connected to that repo). We will use Linear as an issue tracker, and Polygraph for "PR and CI Orchestrator", "Institutional Memory", "Ephemeral Workspaces", "Cross-repo Orchestrator" and "Adversarial Reviews". Polygraph is an agent-agnostic meta-harness. This is the script here. It's about 400 lines. Most of it is our integration with Linear and formatting. This is the high-level view of what the script does: main(): if already ran today: exit # LaunchAgent fires morning + wake; dedupe via stamp file issues = linear.query("my Todo issues in $LINEAR_PROJECT_NAME labeled 'factory'") for issue in issues: processIssue(issue) # errors logged, loop continues processIssue(issue): # CLASSIFY - cheap go/no-go screen verdict = claude -p "can a coding agent solve this autonomously?" if verdict != "yes": return skipped # DO THE WORK - one step; everything happens inside Polygraph sessionId = polygraph session start -- prompt . # prompt = issue context + "complete the task; # adversarial-review it if non-trivial; open PRs, CI green; # link this issue to the session" # the session agent picks its own repos, implements, reviews, opens PRs if no sessionId (timeout / failure): return error # COMPLETE linear.attachToIssue(issue, session url) linear.moveTo(issue, "In Progress") All the these steps (GET DEBRIEFED, SET UP REPOS, IMPLEMENT, REVIEW, OPEN PRs, and RECORD) are done with the following prompt: You are working on a Linear issue. All context is below. Linear issue: ${issue.identifier} - ${issue.title} Linear issue id: ${issue.id} Linear issue URL: ${issue.url} Description: ${issue.description} Complete this task. After you are done with the implementation, check whether it is trivial; if it is not, use the adversarial review skill to review the changes and address the feedback it provides. Open pull requests with your changes, mark them ready for review, and make sure CI is green. Link the Linear issue as a reference on this session. On PRDs and Markdown Files Much of the conversation around Software Factories is around PRDs and design documents, basically moving software development from code to high-level markdown files. Design documents have a place in this process. The Issue Tracker can and probably should contain them. But design documents by themselves aren't enough. Software engineers tried this many times, and it has never worked, and for good reasons. First, you cannot plan complex things separately from implementation, because the implementation is what reveals what actually needs to happen. Second, however accurate the plan was at first, it drifts away from the code. Documentation rots and code does not, because code is what actually runs. So instead of plans and PRDs, record what has actually occurred. Capture the design after it has been implemented. Capture agent traces for more detail. That's what the RECORD step does. Workflow, Not a Product There is some skepticism about Software Factories. Even the biggest proponents are admitting that "they failed." If you think a Software Factory is a product that will write 100% of your code, it will not work. A lot of work still needs a human developer to be engaged. It is just very hard to plan in advance. If you instead think about it as a workflow, a pattern, then suddenly it can be used effectively for a good number of issues (but not all of them). Using Software Factories in real organizations hits a lot of wall: - Most organizations cannot move their issue tracker to a new tool. - Most organizations already have some form of company brain. You can easily integrate Slack, Notion, or ClickUp into the script above. - Most organizations have complex cross-repo relationships, which software factory products can't handle. - Most organizations don't build greenfield projects, which software factory products are optimized for. None of these problems exist with the script above, if you look at it as just one way of automating your software production, not the only way. For instance, the script above only takes issues labeled with "factory" and even for those assesses how much input will be required. Also, any item implemented by the script above can be resumed on the same or a different machine if some changes are required. A lot of the times some changes will be required, but having a change that is 90% there still saves a ton of time. You can build other workflows using the exact same building blocks. For instance, I have a workflow that looks at all the PRs and sessions I need to review: - It gets the relevant data from Linear - It resumes those sessions for review locally using Polygraph - It does an adversarial review via Polygraph - It creates a summary of the change - It creates a dashboard file I can open I then open the dashboard to see what PRs are on my plate. Each of them is already prereviewed. I can quickly scan to see what needs my attention and what doesn't. I can resume complex sessions to ask the agent more questions about the change, about how things work. This drastically cuts down on review time without sacrificing quality. Summary Whether you like it or not, more of software production will be automated: producing code, testing it, reviewing it. To maximize your chance of success, think of these automations as workflows built on top of powerful primitives, not as products. To try it yourself: - Create an account on https://trypolygraph.com - Take the script above and modify it to fit your workflow. Top comments (0)