How do I write a spec a Claude Code crew can build bug fixes from in a monorepo?

Run tares factory spec with a short description of the bug fixes, from the monorepo or a folder that holds its repos, and Tares opens /tares:spec in Claude Code. It interviews you one question at a time, has a second model attack the plan, and writes a Tares project: the spec, milestones, tickets and an AGENTS.md. The crew then builds the tickets into pull requests merged on main.

How it works

The spec is not a document you write alone. You describe the work and /tares:spec interviews you for the rest.

• Where you start. Run it in the repo the project builds on, or in a folder that holds its repos. For a monorepo, start in the monorepo.
• One question at a time. The interview asks a single question, you answer, and it moves on. Your answers are what the plan is built from.
• A second model attacks the plan. Before anything is written, a second model challenges the plan so weak spots surface while the plan is still cheap to change.
• What lands in Tares. The plan is written into a Tares project that holds:
  • the spec
  • milestones, each with acceptance checks
  • tickets, each with a working doc
  • an AGENTS.md
• The hand-over. The interview ends by asking whether to hand the project to the crew. If you say yes, the orchestrator picks it up.

After that, the crew works from what Tares holds. The orchestrator hands out work. Builders are started one per milestone and repo of the project. Each builder takes a ticket, works on its own branch and opens a pull request. The reviewer reviews every pull request to a fixed bar. A builder merges once the reviewer passes it and CI is green. Tares keeps the plan, the tickets and their stages, every review, the assumptions the crew made and your answers, so a crew that restarts carries on where it stopped.

Set it up

1. Check what you need. Claude Code must be signed in on a plan that allows background sessions. You also need gh signed in with write access to the repos the crew works in, plus git, jq and curl. The Codex CLI is optional, if you want a second model to check every commit.

2. Install the CLI and start Tares:

   uv tool install tares     # or: brew install glassflow/tap/tares
   tares up

3. In a second terminal, start the MCP endpoint every crew session shares. Stations reach Tares only through it, and crew up and spec stop and tell you when it does not answer.

   tares mcp --transport streamable-http

4. In a third terminal, bring up the crew once. The first run asks how far the crew may go: whether it merges on its own after review and green CI or waits for your yes, whether it releases, whether a second model checks every commit, and how many builders run at once.

   tares factory crew up

5. Give Tares access to the repos so it can read the pull request, CI and merge state of every ticket. On Tares Cloud, choose Connect GitHub in your workspace settings. On a local Tares, add a GitHub token or App under Settings > GitHub.

6. Go to the monorepo and plan the project. Put the bug fixes you want in the description:

   tares factory spec "what you want to build"

7. Answer the interview one question at a time. When it asks whether to hand the project to the crew, say yes.

8. Answer the crew’s questions in the orchestrator’s session:

   tares factory crew attach orchestrator

Run tares factory doctor at any point to check everything the crew needs. The full walkthrough is on Build a software factory with Claude Code.

What you get

• A Tares project with a spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• A plan that a second model has already attacked, so you review a tested plan rather than a first draft.
• Builders that work the tickets on their own branches and open pull requests, with every pull request reviewed to a fixed bar before it merges.
• Questions that reach you one at a time in the orchestrator’s session, each with a recommendation, so you are pulled in only for decisions that are yours.
• A written record of every choice the crew made on its own, so you can check it at the end of each milestone instead of during every step.
• A project that survives restarts, because the plan, tickets, reviews and your answers stay on Tares.

You can also keep the tickets in a Linear project or in GitHub Issues instead of Tares. Sessions change them there and Tares reads them about once a minute. Tares never writes to them.

When something else fits

Not every piece of work needs a crew. For a small project, work in your own Claude Code session, still on Tares, so your shared AGENTS.md and memory apply:

tares factory session "<idea>"

With an idea, the session asks a few questions, writes a short spec and a ticket list on Tares, then builds it right there. If the plan turns out big, it offers the full spec and the hand-over to the crew instead.

The software factory is for solo developers and very small teams who already work with Claude Code. It runs on one machine, on your own Claude Code login, against your own GitHub repos. If you need a different setup, the crew is not the right fit today.

Related