Just let Claude Code write your software factory

I expected setting up a software factory orchestrator to be a real project: evaluate frameworks, read a lot of docs, glue things together over a few weekends. What actually happened is that I told Claude Code what I wanted and asked it to help me write it. One hour after that first prompt, I had a working pipeline, with planning, parallel execution, and review with a loop back, and a first PR for a new feature in an existing project.

I was surprised it was that simple. The part that took thought wasn’t the code. It was deciding how I wanted the work to flow.

The prompt

This is roughly what I sent, lightly cleaned up:

Help me set up a software factory orchestrator.

Location: [directory]
Isolation: use worktrees so each task runs separately, and explain how that works in the README.
Agent skills to install: [list]

Pipeline:

Stage 0 – Planning and analysis (native plan mode)
- Assess task complexity: single-step or multi-step
- Break complex tasks into atomic phases
- Analyze dependencies to decide what runs in parallel vs. in sequence
- Assign specialized agents by keyword matching
- Write plan assignments for execution

Stage 1 – Execution
- Run in team mode

Stage 2 – QA and acceptance testing
- Code review, looping back to execution when something fails

Nothing clever in there. It’s a page of opinions: tasks shouldn’t touch each other, complex work gets broken down before anyone writes code, independent pieces run in parallel, and nothing is done until it’s reviewed.

If you haven’t used worktrees: git worktree lets you check out multiple branches of the same repo into separate directories at the same time, all sharing one .git. Each task gets its own working copy, so parallel work doesn’t collide.

What came back

Claude Code built the orchestrator as a plugin. Before it did, it read through the documentation and came back with two problems in my design:

Two things I found in the docs that changed the design, and both would have cost you a weekend:

Agent teams ignore isolation: worktree. Teammates always run in the lead’s working directory — the frontmatter field is silently dropped. So you can’t have team mode and per-agent worktrees at the same time in Stage 1. I gave you isolation at two other layers instead: the whole run starts in its own worktree via claude --worktree <task>, and the Stage 2 reviewers are genuinely worktree-isolated since teams are off there. Inside Stage 1, separation comes from owns_files globs that the planner refuses to mark parallel when they overlap.

Teams break anything that waits on a subagent result. With teams enabled, any named subagent launches as a teammate, and teammates return only an idle notification — no output. Stage 2’s entire job is waiting for a verdict, so it would hang on every run. That’s why factory.sh runs each stage as a separate claude -p process with its own CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS value. It’s an environment variable, so there’s no way to flip it mid-session. Keep it out of settings.json — putting it there is the one change that quietly breaks the whole thing.

“Would have cost you a weekend” is fair. Neither problem throws an error. The first one just doesn’t isolate anything, and the second one shows up as a review stage that never finishes. Normally I’d find issues like these by debugging a hang. Here they became design constraints before the first run.

The resulting design shows it. Isolation happens at the run level and in review, not per agent. Parallel work in Stage 1 is kept apart by file ownership rather than separate directories. And each stage is its own process, so team mode is on where it helps and off where something needs to wait for an answer.

If you build something similar, the one thing to remember is to keep CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS out of settings.json.

Two changes I asked for

Once the first version existed, I asked for two things.

First, an optional spec review. I wanted the choice to look at the spec before implementation starts, then let it implement and continue through the rest of the pipeline.

Second, I wanted it to work in my existing project without adding the software factory’s artifacts to that repository. The factory lives in one place, and the project stays clean.

What the hour included

That hour wasn’t all hands-off. Before the agents could compile and test the existing project (a Spring Boot Java application), I had to fine-tune the configuration files and add tools to the list of what they were allowed to use. That was part of the hour, not extra time after it. If you try this, budget some of your hour for it.

What I learned

It’s that simple to build one that does exactly what I want, and I know how it works. I didn’t adopt someone else’s framework and then learn its opinions. I described each stage myself, so I understand every piece and can change any of it.

The opinions are the reusable part. The code came quickly. What I’d want to keep is the thinking about how the work should flow: when to plan, what can run in parallel, what counts as done. If I save that, the next iteration of a custom factory starts from there instead of from scratch.

Pulling work from a ticket system isn’t far off. The pipeline already takes a task and carries it through review. Adding automation to pick up and work through GitHub issues or Jira tickets wouldn’t take much more effort, and that’s probably where I go next.

Agent teams is an experimental Claude Code feature, so the behavior described above may change. This reflects how it worked as of September 2026.