Who writes the spec when the work is docs updates?

With Tares, a spec session writes the spec for docs updates, the same way it does for any other work, by interviewing you one question at a time. You start it with tares factory spec. It writes the spec, the plan, the project’s AGENTS.md and the milestones with their acceptance checks, and the crew builds from those.

How it works

You run the spec session in the repo that holds the docs. You describe the update you want, and Claude Code asks you questions one at a time. Your answers shape what gets written.

• A second model challenges the plan before it is final.
• The result goes into Tares as a spec, a plan, an AGENTS.md for the project, and milestones, each with acceptance checks.
• At the end, the session asks whether to hand the project to the crew. When you say yes, the orchestrator picks it up and starts a builder for the first milestone.
• The builder works through the tickets one at a time. For each ticket it makes a branch, does the work and opens a pull request. The reviewer posts a verdict on every pull request, and once the verdict passes and CI is green, the builder merges.

The spec session is the one place where you write the brief in your own words. After that, the crew reads what the session wrote. The project page keeps all of it in the Docs fold: the starting prompt, the spec, the plan and the project’s AGENTS.md. You can edit any of them there. The page also holds the AGENTS.md and memory shared by every project.

In the worked example on A project, end to end, one spec session produced a spec, a plan, an AGENTS.md and three milestones. Each milestone had acceptance checks, such as tests passing in CI or a pull request merged into main.

Set it up

Follow the order below. A step marked local applies only to a local Tares, and a step marked cloud only to Tares Cloud. The Get started page covers the full setup.

1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed.
2. Install the CLI.
3. Local only: start Tares, then in a second terminal start the MCP endpoint every crew session shares. Cloud only: run tares login and pick your workspace in the browser.
4. Give Tares access to GitHub, in Settings > GitHub for a local Tares or with Connect GitHub on Tares Cloud.
5. Bring up the crew.
6. From the repo with the docs, start the spec session and describe the docs update you want.
7. Answer the questions one at a time. When the spec, plan and milestones look right, say yes to hand the project to the crew.

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

Run tares up and tares mcp --transport streamable-http on a local Tares, and tares login on Tares Cloud. You do not need both. Replace the text in quotes with a plain description of the docs update.

After the hand-off, open the Crew page in the console at http://127.0.0.1:8787/crew on a local Tares. It shows who is on the crew, what each member is doing, and the questions waiting for you.

What you get

• A spec written from your answers, so you do not draft it yourself.
• A plan and a project AGENTS.md that every session building the project reads.
• Milestones with acceptance checks, so each stage of the docs work has a stated test for when it is done.
• A project page that records the whole build: the docs, the tickets with their pull requests and review rounds, and every question the crew asked you with your answer in your own words.
• Assumptions the crew makes on its own are written down, and the orchestrator brings them to you at the end of each milestone so you can keep or change them.
• A way to steer the work later. Talk to the orchestrator, or edit the spec, plan or AGENTS.md from the Docs fold.

When something else fits

• If the docs change is small enough that you would make it yourself in a few minutes, a spec session and a crew add more process than you need.
• If the project is already building and you want to change direction, talk to the orchestrator or edit the docs in the project’s Docs fold instead of starting a new spec session.
• To continue a finished project, hand it to the crew again, for example with a follow-up spec.

Related