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

Tares writes the spec with you. Run tares factory spec in your Python backend repo, and /tares:spec interviews you one question at a time, has a second model attack the plan, and writes it into a Tares project. That project holds the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md. It ends by asking whether to hand the project to the crew, and a yes starts the build.

How it works

The software factory for Claude Code runs a crew of Claude Code sessions on your machine: an orchestrator, a reviewer and builders. Tares keeps the plan, the tickets and their stages, the reviews and your answers. The planning step is /tares:spec, which tares factory spec opens in Claude Code.

• One question at a time. The interview asks you a single question, then the next, so you never face a wall of questions.
• A second model attacks the plan. Before anything is written, a second model challenges the plan.
• It lands in Tares as a project. You get the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• The hand-over is your call. The last question is whether to give the project to the crew. If you say yes, the orchestrator picks it up. It starts builders, one per milestone and repo, and each builder works a ticket on its own branch and opens a pull request.
• Every pull request is reviewed. The reviewer holds each one to a fixed bar. A builder merges once the reviewer passes it and CI is green.

Run the command in the repo the project builds on, or in a folder that holds its repos. For your case that is the Python backend repo, so the crew knows which code the docs updates describe.

Set it up

Follow the steps in this order. The full walkthrough is on Get started.

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

2. Install the CLI and start Tares locally.

   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. On a local Tares the crew reaches Tares only through it.

   tares mcp --transport streamable-http

   On Tares Cloud, run tares login and pick your workspace in the browser instead. There is no MCP endpoint to start.

4. Give Tares access to GitHub. On a local Tares, add a GitHub token or App under Settings > GitHub. On Tares Cloud, choose Connect GitHub. Tares reads the pull request, CI and merge state of every ticket itself.

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

   If your Python repo has no language server wired in for Claude Code, crew up lists what is missing and offers to install it. It installs only when you say yes.

6. Plan the project from your Python backend repo. Put the docs updates you want in the quoted idea, replacing the example text.

   tares factory spec "what you want to build"

7. Answer the interview, one question at a time. Then read the milestones and their acceptance checks, and say yes to hand the project to the crew.

8. Answer the crew’s questions in the orchestrator’s session with tares factory crew attach orchestrator. Each question comes with a recommendation. Run tares factory doctor at any point to check everything the crew needs.

What you get

• A Tares project with a spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md, all written from one interview.
• A plan that a second model has already attacked, so you review a challenged plan instead of a first draft.
• Docs updates built into pull requests that a reviewer checks to a fixed bar and that merge on main once CI is green. You can also have a project wait for your yes before every merge.
• A record that stays on Tares. Sessions come and go, and a crew that restarts carries on where it stopped.
• Few interruptions. You are pulled in only for decisions that are yours, and every choice the crew made on its own is written down for you to check at the end of each milestone.
• Progress on the Crew page of the Tares console, with tares factory crew status and tares factory projects in the terminal.

When something else fits

• For a small change, use tares factory session "<idea>". It plans a short spec and a ticket list on Tares and builds in your own Claude Code session, with no crew. If the plan turns out big, it offers the full spec and the hand-over to the crew instead.
• If your tickets already live in Linear or GitHub Issues, Tares can read them from there. Sessions change them with their own tools, and Tares only reads them.
• The software factory is for solo developers and very small teams on one machine, using their own Claude Code login and their own GitHub repos.

Related