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

Tares turns your idea into a crew-ready spec when you run tares factory spec in your Python repo, which opens the /tares:spec interview in Claude Code. It asks one question at a time and has a second model attack the plan. It then writes a Tares project with the spec, milestones, tickets and an AGENTS.md, and asks whether to hand the project to the crew.

How it works

You do not write the spec file by hand. /tares:spec runs the planning with you:

• One question at a time. The interview asks a single question, you answer it, and it moves on. You describe the internal refactors you want in your own words.
• A second model attacks the plan. Before anything is saved, a second model challenges the plan, so weak spots surface while you can still change them.
• The plan lands in a Tares project. Tares holds the spec, the milestones with their acceptance checks, the tickets with a working doc each, and an AGENTS.md.
• A hand-over question. The interview ends by asking whether to give the project to the crew. If you say yes, the orchestrator picks it up.

From there the crew builds the tickets. The orchestrator hands out work, builders open pull requests (one builder per milestone and repo), and the reviewer reviews every pull request to a fixed bar. A builder merges once the reviewer passes the pull request and CI is green. Tares keeps the plan, tickets, reviews and your answers, so a crew that restarts carries on where it stopped.

Run the command in the repo the project builds on, or in a folder that holds its repos. For a Python backend, that is your backend repo.

Set it up

The steps below are for a local Tares. For the full walkthrough see Get started.

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

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. Crew sessions reach Tares only through it, and crew up and spec stop and tell you when it does not answer:

   tares mcp --transport streamable-http

   On Tares Cloud you run tares login instead and there is no MCP endpoint to start.

4. Give Tares access to GitHub, under Settings > GitHub for a local Tares or with Connect GitHub on Tares Cloud. Tares reads the pull request, CI and merge state of every ticket itself.

5. In a third terminal, 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:

   tares factory crew up

6. Go to your Python backend repo and plan the project. Put your own refactoring goal where the example text is:

   tares factory spec "what you want to build"

7. Answer the interview. When it asks whether to hand the project to the crew, say yes.

8. Open the orchestrator to answer the crew’s questions. They arrive one at a time, each with a recommendation:

   tares factory crew attach orchestrator

For Python, run tares factory doctor. Builders and the reviewer search less when Claude Code can find definitions, references and callers through a language server. Doctor detects a Python repo from pyproject.toml, setup.py, setup.cfg, Pipfile or requirements.txt, says whether Claude Code has a server for it, and prints what to run if one is missing. crew up offers the same install and runs it only when you say yes.

What you get

• A Tares project holding the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• A plan that a second model has already attacked, before the crew starts building.
• A crew that builds the tickets into pull requests, with the reviewer checking each one and merges happening on main once it passes and CI is green.
• A record on Tares of the assumptions the crew made, the questions it asked you and your answers in your own words, so you can check its choices at the end of each milestone.
• The Crew page in the Tares console, which shows the question waiting for you, the stations, each project’s builders and the pull requests waiting for review.

When something else fits

• For a small change, run tares factory session with an idea. It asks a few questions, writes a short spec and a ticket list on Tares, and builds in your own Claude Code session, with no crew.
• If your tickets should live in Linear or GitHub Issues, say so when you run /tares:spec, or link them from the project’s Tickets page. Tares reads them and never writes to them.

Related