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

Tares turns a one-line idea for your documentation website into a spec the crew can build, through the /tares:spec interview. You run tares factory spec in the docs repo and answer 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.

How it works

You do not write the spec by hand. You describe what you want, and /tares:spec builds the spec with you.

• The interview. Claude Code asks about your docs site one question at a time. Your answers become the content of the plan, so answer in the terms your site uses.
• The attack on the plan. Before anything is saved, a second model challenges the plan. Gaps and weak assumptions surface while changing the plan is still cheap.
• What lands in Tares. The result is one Tares project holding the spec, milestones with acceptance checks, tickets with a working doc each, and an AGENTS.md.
• 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.

After the hand-over, the orchestrator starts builders, one per milestone and repo. Each builder takes a ticket, works on its own branch and opens a pull request. The reviewer reviews every pull request to a fixed bar, and a builder merges only once the reviewer passes it and CI is green. Tares keeps the plan, tickets, reviews and your answers, so a crew that restarts carries on where it stopped.

Set it up

Follow these steps in order. Steps marked local apply to a local Tares, and the sign-in step applies to Tares Cloud. The full walkthrough is on Get started.

1. Check that Claude Code is signed in, that gh is signed in with write access to your docs repo, and that git, jq and curl are installed.
2. Install the CLI.
3. Local only: start Tares, then start the MCP endpoint in a second terminal. Every crew session reaches Tares through that endpoint.
4. Tares Cloud only: run tares login and pick your workspace in the browser.
5. Give Tares access to GitHub. On a local Tares use Settings > GitHub. On Tares Cloud choose Connect GitHub.
6. Bring up the crew.
7. From the docs repo, start the interview with your idea in one sentence.

uv tool install tares     # or: brew install glassflow/tap/tares
tares up
tares mcp --transport streamable-http
tares factory crew up
tares factory spec "what you want to build"

Replace the quoted text with your own idea. Keep it to the features you want first, for example a short description of one page or one reader-facing behavior of the site. While you answer, give each feature a plain, checkable outcome. The milestone acceptance checks come from those answers.

If you want the tickets in GitHub Issues, say so during /tares:spec and name the repo. Claude then creates the issues with gh and links them. Linear works too, through the project’s Tickets page.

To answer the crew later, attach to the orchestrator:

tares factory crew attach orchestrator

Questions arrive there one at a time, each with a recommendation. Run tares factory doctor whenever something looks wrong. It checks everything the crew needs and prints the fix for each problem.

What you get

• A Tares project for your docs site, with a spec you shaped through the interview and that a second model has already challenged.
• Milestones with acceptance checks, so each stage of the site has a clear point at which it counts as done.
• Tickets, each with its own working doc, which a builder can take on its own branch.
• An AGENTS.md that every crew session reads, so the builders and the reviewer start from the same instructions.
• Pull requests merged on main after review and green CI, with the Crew page in the Tares console showing each project’s builders and the pull requests waiting for review.
• A written record of the assumptions the crew made, the questions it asked you and your answers in your own words, so you can check them at the end of each milestone.

When something else fits

• For a single quick change, tares factory session lets you plan and build in your own Claude Code session, still recorded on Tares. If the plan turns out big, it offers the full spec and the hand-over to the crew.
• The software factory is for solo developers and very small teams who already use Claude Code, working on one machine against their own GitHub repos.
• If you want a second model to check every commit as well, install the optional Codex CLI and say so when crew up asks about crew settings.

Related