How should I split docs updates into milestones for a Go microservice?

Tares plans work as milestones, and each milestone carries acceptance checks that say when it is done. For docs updates on a Go microservice, cut milestones so each ends in a state you can check, because the milestone end is where you confirm the crew’s assumptions and the next builder starts. You set the milestones in tares factory spec, and Tares keeps them on the project page.

How it works

A milestone is the unit the software factory for Claude Code plans around. Here is what happens around one:

• In tares factory spec, you answer Claude Code’s questions and a second model challenges the plan. Tares then stores a spec, a plan, an AGENTS.md for the project and the milestones, each with acceptance checks.
• The orchestrator starts a builder for a milestone. The builder works through the tickets one at a time: it makes a branch, does the work and opens a pull request.
• The reviewer reviews every pull request and posts a verdict. Once the verdict passes and CI is green, the builder merges. How far the crew may go on its own is what you choose at crew up.
• When the crew meets something the plan does not cover, it picks the sensible answer, records it as an assumption and carries on.
• At the end of each milestone, the orchestrator brings you its assumptions in one question. You keep or reject them, and the work moves on to the next milestone.

The milestone boundary is therefore the point where your confirmation happens. A milestone that is too large collects many assumptions into one question. A milestone with vague checks leaves nothing to confirm.

The example in A project, end to end shows the shape. Its three milestones were tests and CI on the branch, payout history that stays as it was, and a last one named merged and live, with the pull request documented, merged into main and running in production. Each names an outcome you can check, not an activity.

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.

   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 in a second terminal start the MCP endpoint every crew session shares. On Tares Cloud, run tares login instead and skip both.

   tares up
   tares mcp --transport streamable-http

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 service repo.

   tares factory crew up
   tares factory spec "update the docs for the orders service"

6. In the spec session, shape the milestones with these rules:

   • Write each milestone as an outcome with acceptance checks you can verify, such as a set of docs that is complete for one area of the service and merged.
   • Keep a milestone small enough that you can judge its assumptions in one sitting.
   • End a milestone where the next builder can start from merged work, so the first milestone leaves the next one a settled base.
   • Put the final milestone on merge and release, as the example project does.

7. Say yes when the spec session asks whether to hand the project to the crew. The orchestrator picks it up and starts a builder for the first milestone.

8. Answer the end-of-milestone question about assumptions. 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 milestones with their acceptance checks, and each ticket with its builder, pull request and review rounds.
• An Assumptions fold that records every choice the crew made on its own and whether you kept it. Each assumption names the tickets it touches and the builder that made it.
• A Decisions fold that holds every question the crew asked you and your answer in your own words, up to 4,000 characters.
• A plan that can grow. When the reviewer finds smaller issues outside the ticket it is reviewing, the orchestrator turns them into a new ticket and places it in the milestone.
• A progress bar with one segment per ticket, and the steps Spec, Build, Review and Done across the top.
• A Crew page at http://127.0.0.1:8787/crew on a local Tares, where you see each station’s state and any question waiting for you.

When the last milestone is merged, the orchestrator asks whether the project is finished. Your answer marks it Done. Run tares factory crew down when no project is left, and crew up for the next one.

When something else fits

• If the change is a single small edit, a milestone plan adds little. Hand it to a Claude Code session directly.
• If you want to steer a ticket while it is in progress, talk to the orchestrator. Milestones are for the plan, and the orchestrator is for changes along the way.

Related