How do I write a spec a Claude Code crew can build framework migrations from in a Python backend?

Tares writes the spec with you. Run tares factory spec with a short description of the migration, and /tares:spec interviews you one question at a time and has a second model attack the plan. It then saves a Tares project with the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md. You then hand the project to the crew, as described in Get started.

How it works

You do not write the spec by hand. You describe what you want in one sentence, and Claude Code runs /tares:spec in the repo the project builds on, or in a folder that holds its repos.

• One question at a time. The interview asks a single question, you answer, and it moves on. Your answers shape the plan.
• A second model attacks the plan. Before anything is saved, a second model challenges the plan, so weak points surface while you are still planning.
• The plan lands in Tares. The result is a Tares project that holds the spec, the milestones with acceptance checks, the tickets with a working doc each, and an AGENTS.md.
• You decide on 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.

The crew itself is an orchestrator, a reviewer and builders, with a releaser only if you ask for one. Builders are started one per milestone and repo. Because Tares keeps the plan, tickets, reviews and your answers, a crew that restarts carries on where it stopped.

Set it up

1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed.

2. Install the CLI and start Tares locally. On Tares Cloud, run tares login instead and pick your workspace in the browser.

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

3. For a local Tares, start the MCP endpoint in a second terminal. Every crew session shares 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 the repos. On a local Tares, add a GitHub token or App under Settings > GitHub. On Tares Cloud, choose Connect GitHub.

5. Bring up the crew. The first run asks how far it may go: merge on its own or wait for your yes, release or not, whether a second model checks every commit, and how many builders run at once.

   tares factory crew up

6. Run tares factory doctor. For a Python backend, it reads pyproject.toml, setup.py, setup.cfg, Pipfile or requirements.txt and says whether Claude Code has a language server for Python. If it is missing, doctor prints npm install -g pyright, then claude plugin install pyright-lsp@claude-plugins-official. With a server, builders and the reviewer can find definitions, references and callers instead of searching text.

7. In the Python repo, start the interview with the migration as your sentence.

   tares factory spec "what you want to build"

   Replace the text with your migration, in your own words. Answer each question as it comes. When the plan is saved, say yes to hand it to the crew.

8. Answer the crew’s questions in the orchestrator’s session, one at a time, each with a recommendation.

   tares factory crew attach orchestrator

If you would rather keep the tickets 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. Sessions change them with their own tools.

What you get

• A Tares project that holds the spec, so the crew works from a written plan instead of a chat history.
• Milestones with acceptance checks, so each stage of the migration has a stated bar.
• Tickets with a working doc each, which builders take one at a time on their own branches.
• An AGENTS.md that every session in the project reads.
• A plan that a second model has already attacked.
• Pull requests that the reviewer holds to a fixed bar. Builders merge once the reviewer passes the pull request and CI is green, or they wait for your yes if you chose that.
• A written record of the assumptions the crew made, the questions it asked you and your answers, which you can check at the end of each milestone.

When something else fits

• If the change is small, use tares factory session "<idea>". It plans a short spec and ticket list and builds it in your own Claude Code session, and it offers the full spec and crew hand-over if the plan turns out big.
• If you want to drive the work yourself, run tares factory session <project> on a planned project. A crew that holds the project stops when you say yes to taking it over.
• The software factory runs on one machine for solo developers and very small teams. It does not suit a larger team that needs shared control.

Related