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

Tares turns your idea into a spec through /tares:spec, which interviews you one question at a time and has a second model attack the plan. You describe the dependency upgrades for your documentation website, and Tares writes a project with the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md. The crew then builds the tickets into pull requests merged on main.

How it works

You start the interview with tares factory spec, which opens Claude Code with /tares:spec. From there:

• One question at a time. The interview asks you a single question, you answer it, and the next follows. Your answers about the documentation website and the upgrades are what the plan is built from.
• A second model attacks the plan. Before anything is written, a second model challenges the plan, so weak points surface while you are still in the interview.
• The plan lands in a Tares project. Tares keeps the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• You hand it to the crew. The interview ends by asking whether to hand the project to the crew. If you say yes, the orchestrator picks it up.

Tares holds the plan, the tickets and their stages, every review, the assumptions the crew made and your answers in your own words. Builders take one ticket each, work on their own branch and open a pull request. The reviewer holds every pull request to a fixed bar, and a builder merges once the reviewer passes it and CI is green.

To make the spec useful for your case, answer the interview with the concrete facts of your site. Name the repo that holds the documentation website. Say which dependencies you want upgraded. Say what “done” means, because each milestone gets acceptance checks drawn from your answers. Each ticket’s working doc gives a builder what it needs for one piece of work.

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 the documentation website’s 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 Tares, then start the MCP endpoint every crew session shares in a second terminal. The crew reaches Tares only through this endpoint, so spec stops and tells you when it does not answer.

   tares up
   tares mcp --transport streamable-http

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

   tares login

5. Give Tares access to GitHub, so it can read the pull request, CI and merge state of every ticket. On Tares Cloud, choose Connect GitHub in your workspace settings. On a local Tares, add a token or App under Settings > GitHub.

6. Bring up the crew.

   tares factory crew up

7. Plan the project from the documentation website’s repo, or from a folder that holds its repos. Put your upgrade goal in place of the text in quotes, then answer the interview one question at a time.

   tares factory spec "what you want to build"

8. If you want the tickets in GitHub Issues instead of Tares, say so during the interview and name the repo. Claude then creates the issues with gh and links them. For that, add a GitHub credential in Settings > GitHub and sign in to gh with the repo scope. Tares only reads those issues.

9. If you prefer Linear, connect it in Settings > Linear and, on the project’s Tickets page, click Use a Linear project and pick one. Tares only reads Linear too.

10. When the interview asks whether to hand the project to the crew, say yes. Then open the orchestrator to answer its questions, one at a time, each with a recommendation. Run tares factory doctor at any point to check everything the crew needs.

The Get started page has the full quickstart, including the crew settings you are asked on the first crew up.

What you get

• A Tares project for your documentation website’s dependency upgrades, with the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• A plan that has already been attacked by a second model before the crew starts.
• Pull requests built by the crew, reviewed to a fixed bar and merged on main once CI is green.
• A record on Tares of the assumptions the crew made, the questions it asked you and your answers, so you can check its choices at the end of each milestone instead of during every step.
• A crew that carries on where it stopped if it restarts, because the plan and tickets stay on Tares.

When something else fits

• For a small piece of work, run tares factory session with your idea. You plan a short spec and ticket list and build it in your own Claude Code session, still on Tares.
• If the crew already holds a project and you want to carry it on yourself, tares factory session with the project asks whether to take it over. Say yes and the crew stops.

Related