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

Tares turns your docs updates idea into a plan the crew can build when you run tares factory spec in your docs repo and answer the interview one question at a time. A second model attacks the plan, and Tares stores the spec, milestones, tickets and an AGENTS.md. You then hand the project to the crew, and it builds the tickets into pull requests merged on main.

How it works

You do not write the spec as a document yourself. You start /tares:spec (or tares factory spec) in Claude Code, and it interviews you.

• One question at a time. You describe the docs updates and the documentation website, and the interview asks what it needs to turn that into a plan. Your answers are kept in your own words on Tares.
• A second model attacks the plan. Before anything is written, a second model challenges the draft plan.
• The plan lands in a Tares project. You get the spec, milestones with acceptance checks, 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. Say yes and the orchestrator picks it up.

The crew is a set of Claude Code sessions on your machine. The orchestrator hands out work and is the only session you talk to. Builders, one per milestone and repo, each take a ticket, work on their own branch and open 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. Tares holds the plan, tickets, reviews and your answers, 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, that gh is signed in with write access to your docs repo, and that git, jq and curl are installed.

   gh auth login

2. Install the CLI.

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

3. On a local Tares, start it, then start the MCP endpoint every crew session shares in a second terminal. The crew reaches Tares only through that endpoint.

   tares up
   tares mcp --transport streamable-http

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

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 and pick the repos.

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. From the docs repo, or a folder that holds its repos, start the interview. Replace the text in quotes with your docs updates.

   tares factory spec "what you want to build"

7. Answer each question, review the plan, and say yes when asked whether to hand the project to the crew.

8. Answer the crew’s later questions in the orchestrator’s session.

   tares factory crew attach orchestrator

If you want the tickets in GitHub Issues instead of Tares, say so during /tares:spec and name the repo. Claude creates the issues with gh and links them. Run gh auth login --scopes repo first on the machine that runs the sessions. Tares reads the issues and never writes to GitHub. The full walkthrough is on Get started.

What you get

• A Tares project with a spec, milestones that carry acceptance checks, and tickets that each have a working doc.
• An AGENTS.md that the crew’s sessions share.
• A plan that a second model has already challenged, before any builder starts.
• Builders working on their own branches, one per milestone and repo, opening pull requests that the reviewer checks.
• Questions that reach you one at a time in the orchestrator, each with a recommendation, while the Crew page in the Tares console shows progress and the pull requests waiting for review.
• A written record of the assumptions the crew made, so you can check them at the end of each milestone.

Tickets end at merged on main. If you want tagging and deploying, ask for a releaser when the crew asks how far it may go.

When something else fits

• For a small change, use tares factory session "<idea>". It plans a small project and builds it in your own Claude Code session, with a short spec and a ticket list on Tares.
• If you want a pull request merged only after your yes, set that when crew up asks how far the crew may go. A single project can also wait for your approval before every merge.
• Run tares factory doctor if a station misbehaves or the setup looks incomplete.

Related