How do I write a spec a Claude Code crew can build internal refactors from in a monorepo?

Tares turns your idea into a spec through /tares:spec, which you start with tares factory spec from the monorepo. It interviews you one question at a time, has a second model attack the plan, and writes a Tares project with a spec, milestones, tickets and an AGENTS.md. You then hand the project to the software factory for Claude Code, and the crew builds the tickets into pull requests merged on main.

How it works

You run the spec command in the repo the project builds on, or in a folder that holds its repos. For a monorepo, that is the monorepo itself. Claude Code opens with /tares:spec and the work runs in this order:

• Interview. It asks you one question at a time. Your answers are kept on Tares in your own words.
• Attack. A second model attacks the plan before anything is written.
• Write-up. The plan is written into a Tares project: the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• Hand-over. It ends by asking whether to hand the project to the crew. If you say yes, the orchestrator picks it up.

The crew is an orchestrator, a reviewer and builders, plus a releaser only if you ask for one. The orchestrator starts builders, one per milestone and repo of the project. Each builder takes a ticket, works on its own branch, opens a pull request, and merges it once the reviewer passes it and CI is green. Tares holds the plan, the tickets and their stages, every review and the assumptions the crew made, so a crew that restarts carries on where it stopped.

Set it up

1. Check that Claude Code is signed in on a plan that allows background sessions. Check that gh is signed in with write access to the monorepo, and that git, jq and curl are installed.

   gh auth login

2. Install the CLI and start Tares locally. Instead of a local Tares you can run tares login to use Tares Cloud, and then there is no MCP endpoint to start.

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

3. On a local Tares, start the MCP endpoint every crew session shares in a second terminal. 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. 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.

5. Bring up the crew. 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

6. Change into the monorepo and start the interview. Make the idea sentence name the refactor and the part of the monorepo it touches.

   tares factory spec "what you want to build"

7. Answer each question concretely as it comes, and read the plan the second model has attacked before you accept it. Your answers are what the milestones, acceptance checks and tickets are written from.

8. Say yes when it asks whether to hand the project to the crew. Then open the orchestrator to answer the crew’s questions, which reach you there one at a time, each with a recommendation.

   tares factory crew attach orchestrator

Run tares factory doctor at any point to check everything the crew needs. It also reads each handed-over repo’s languages from its manifests, at the repo root or one folder down, and tells you which language servers Claude Code is missing. The full walkthrough is on Get started.

What you get

• A Tares project with the spec, milestones that each carry acceptance checks, and tickets that each have a working doc.
• An AGENTS.md written for the project, so the crew works from a shared set of instructions.
• A plan that a second model has already attacked, before any builder starts.
• Pull requests that the reviewer holds to a fixed bar and that merge on main only after review and green CI. If you want to approve each merge yourself, you can set the project to wait for your yes.
• A written record on Tares of the assumptions the crew made and your answers, so you check choices at the end of each milestone instead of during every step.
• Progress on the Crew page of the Tares console, with the question waiting for you at the top.

When something else fits

• For a small refactor, plan and build it in one Claude Code session with tares factory session. It writes a short spec and a ticket list on Tares, then builds right there.
• If you want the tickets to live in Linear or GitHub Issues, say so when you run /tares:spec, or link them from the project’s Tickets page. Tares only reads them.
• The software factory is for solo developers and very small teams working with Claude Code on one machine against their own GitHub repos.

Related