How should I split docs updates into milestones for a monorepo?

Tares plans a project as milestones, each with acceptance checks, so you split docs updates by outcome and end each milestone where you can confirm its assumptions. At that point the next builder starts. Write each check so you can verify it, and keep each milestone to one result you can say yes or no to.

How it works

The unit of planning in the software factory for Claude Code is the milestone. When you run tares factory spec in your repo, you answer Claude Code’s questions, a second model challenges the plan, and the result goes into Tares: a spec, a plan, an AGENTS.md for the project, and milestones, each with acceptance checks.

After that the flow repeats for every milestone:

• You say yes to handing the project to the crew. 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, it makes a branch, does the work and opens a pull request.
• The reviewer reviews every pull request and posts its verdict. Once the verdict passes and CI is green, the builder merges.
• At the end of the milestone, the orchestrator brings you the assumptions the crew made in one question. These are the choices it made on its own where the plan did not cover something. You keep them or not.

A milestone therefore ends in two things: its tickets are merged, and you have answered the assumptions question. Then the next builder starts on the next milestone.

The project in A project, end to end shows the shape. It had three milestones, each named for a result:

• M1, tests and CI on the branch.
• M2, payout history stays as it was.
• M3, merged and live.

In that project the crew wrote down five assumptions along the way. One example: the working doc named a config file that failed to load on the repo’s Node version, so the builder used a different file name and recorded it. Because assumptions are confirmed at the milestone boundary, a wrong guess like that surfaces before the next builder builds on it.

Set it up

1. Check that Claude Code is signed in, gh is signed in with write access to the repos the crew works in, and git, jq and curl are installed. Start with gh auth login if you need it.
2. Install the CLI and start Tares locally. On Tares Cloud you sign in with tares login instead and skip the local start and the MCP endpoint.
3. In a second terminal, start the MCP endpoint every crew session shares.
4. Give Tares access to GitHub, in Settings > GitHub for a local Tares or Connect GitHub on Tares Cloud.
5. Bring up the crew, then plan the project from the repo.

gh auth login
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"

6. In the spec session, describe the docs work as separate results and ask for one milestone per result. For a monorepo, name the part of the repo each result covers, so a milestone reads as a result you can check and not as a list of files.
7. For each milestone, ask for acceptance checks you can confirm yourself, the way M2 above states what must stay unchanged. Put anything the crew must not touch into the project’s AGENTS.md.
8. Hand the project to the crew when the plan reads right. At the end of each milestone, answer the assumptions question. To make an answer stand from now on, say so, for this project or for every project.

The Get started page covers the same setup in full.

What you get

• A project page with a Tickets fold that lists each milestone with its acceptance checks, and each ticket with its builder, pull request and review rounds.
• A clear stop at the end of every milestone, where the crew asks you once about everything it assumed.
• An Assumptions fold that records every choice the crew made on its own and whether you kept it, and a Decisions fold with your answers in your own words.
• A GitHub fold that shows the repos the project changes, where each is checked out, and its open and merged pull requests.
• A progress bar with one segment per ticket, so you see how far each milestone is.
• Room for the plan to change. In the example project the reviewer found smaller issues, and the orchestrator added a ticket to M2 before the integration tests.

When something else fits

• If you want to change course in the middle of a milestone, talk to the orchestrator. You do not need to replan the whole project.
• When the project is finished and you have more docs work, hand it to the crew again, for example with a follow-up spec, and plan new milestones for it.
• If the work is a single result with one check, one milestone is enough. Add more only where a confirmation point helps you.

Related