How do I write a spec a Claude Code crew can build bug fixes from in a monorepo?
Tares writes the spec with you: run tares factory spec in your monorepo and /tares:spec interviews you one question at a time, then a second model attacks the plan. The result is a Tares project with the spec, milestones, tickets and an AGENTS.md. The interview ends by asking whether to hand the project to the crew, and the crew builds the tickets into pull requests merged on main.
How it works
You do not write the spec by hand. You start the interview and answer it, and Tares writes the plan into a project.
- The interview.
/tares:specasks you one question at a time. Your answers are kept on Tares in your own words. - The attack. A second model attacks the plan before it is written, so weak points surface while you are still planning.
- What lands in Tares. A project with the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
- The hand-over. The interview ends by asking whether to give the project to the crew. If you say yes, the orchestrator picks it up.
Run the command in the repo the project builds on, or in a folder that holds its repos. For a monorepo, start in the monorepo. The orchestrator then starts builders 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, and a builder merges once the reviewer passes it and CI is green.
For bug fixes, put the bugs in the idea you pass to the command and in your answers to the interview. The acceptance checks on each milestone are what the crew’s work is held to. See Get started for the full picture of the crew.
Set it up
These steps are for a local Tares. Steps that only apply to Tares Cloud are marked.
-
Check that Claude Code is signed in on a plan that allows background sessions. Sign in to
ghwith write access to the monorepo, and make suregit,jqandcurlare installed.gh auth login -
Install the CLI.
uv tool install tares # or: brew install glassflow/tap/tares -
Start Tares locally. The console is at
http://127.0.0.1:8787.tares up -
In a second terminal, start the MCP endpoint every crew session shares. Crew sessions reach Tares only through it, and
crew upandspecstop and tell you when it does not answer.tares mcp --transport streamable-httpOn Tares Cloud, skip steps 3 and 4. Run
tares logininstead and pick your workspace in the browser. -
Give Tares access to GitHub, so it can read the pull request, CI and merge state of every ticket. On a local Tares, add a token or App under Settings > GitHub. On Tares Cloud, choose Connect GitHub. Pick the monorepo.
-
Bring up the crew. The first run asks how far the crew may go, such as whether it merges on its own after review and green CI or waits for your yes, and how many builders run at once.
tares factory crew up -
In the monorepo, start the planning interview. Replace the placeholder with your own description of the bug fixes you want.
tares factory spec "what you want to build" -
Answer the questions one at a time. When the plan is written, say yes to the hand-over. Then answer the crew’s questions in the orchestrator’s session.
tares factory crew attach orchestrator
If you want a small fix built in your own session instead, use tares factory session with your idea. It plans a small project and builds it right there.
What you get
- A Tares project that holds the spec, so the plan survives restarts. The sessions come and go, and the record stays on Tares.
- Milestones with acceptance checks, so each stage of the work has a stated bar.
- Tickets with a working doc each, which builders pick up one at a time.
- An AGENTS.md that the crew’s sessions work from.
- A plan that a second model has already attacked before any builder starts.
- Pull requests merged on main once the reviewer passes them and CI is green. You can also have a project wait for your yes before every merge.
- Progress on the Crew page of the console at
http://127.0.0.1:8787/crew. Questions that need you reach you one at a time, each with a recommendation.
When something else fits
- For one small fix,
tares factory sessionwith your idea plans and builds it in your own Claude Code session, without the crew. If the plan turns out big, it offers the full spec and the hand-over instead. - If your tickets already live in Linear or GitHub Issues, say so when you run the interview, or link them on the project’s Tickets page. Tares reads them and does not write to them.
- The software factory is for solo developers and very small teams. It runs on one machine, on your own Claude Code login, against your own GitHub repos.
Related
- Build a software factory with Claude Code
- How do I write a spec a Claude Code crew can build bug fixes from in a Python backend?
- How do I write a spec a Claude Code crew can build bug fixes from in a Go microservice?
- How do I write a spec a Claude Code crew can build dependency upgrades from in a monorepo?
Still stuck? Get help