How should I split docs updates into milestones for a Python backend?
Tares plans a project as milestones, each with acceptance checks, so split your docs updates where one check can pass or fail and where you can confirm the choices the crew made on its own. For a Python backend, that usually means one milestone per outcome you can verify, not one per docs page. Tares asks you to confirm the crew’s assumptions at the end of each milestone.
How it works
When you run tares factory spec, Claude Code asks you questions and a second model challenges the plan. The result goes into Tares as a spec, a plan, an AGENTS.md for the project and milestones, each with acceptance checks. After you say yes, the orchestrator picks the project up and starts a builder for the first milestone.
A milestone is also a checkpoint with you:
- The builder works through the tickets one at a time. Each ticket gets a branch and a pull request.
- The reviewer reviews every pull request and posts a verdict. Once the verdict passes and CI is green, the builder merges.
- When the crew meets something the plan does not cover, it picks the sensible answer, writes it down as an assumption and carries on.
- At the end of each milestone, the orchestrator brings you its assumptions in one question. You keep them or change them.
That last step is why the milestone boundary matters. Everything the crew guessed during the milestone arrives as one decision, so a milestone with a clear end gives you a clear moment to confirm it.
Set it up
- Decide the outcomes before the pages. For a Python backend, a docs update might split like this. The checks are examples for you to write into the spec, not fixed Tares rules.
- M1, docs build and checks on the branch: the docs build runs in CI on every pull request, and the commands in the docs run as written.
- M2, docs match the code: the API reference and configuration pages describe what the backend does now, for the endpoints and settings you name.
- M3, merged and live: the pull request is described in sections, merged into main and published.
- Write each acceptance check so you can answer yes or no. A check such as “the docs are better” cannot end a milestone. A check such as “every endpoint in the list has a documented request and response” can.
- Put the order in the plan. In the end-to-end example, the reviewer found smaller issues and the orchestrator turned them into a new ticket placed inside the milestone before the integration tests. Leave room for that kind of ticket inside a milestone instead of adding a milestone for it.
- Run the spec in your repo and give the crew your milestones as part of what you want built:
tares factory spec "what you want to build"- Answer the spec questions, then say yes to handing the project to the crew. If you have not brought up the crew yet, follow Get started first.
- At each milestone end, read the assumptions. Each one names the tickets it touches and the builder that made it. Keep the ones you agree with. To make an answer stand from now on, say so, for this project or for every project.
What you get
- A plan you can read. The project page shows milestones with their acceptance checks in the Tickets fold, and each ticket with its builder, pull request and review rounds.
- One confirmation per milestone. Assumptions are collected and brought to you together, so you do not get interrupted for every small choice.
- A record of your answers. Decisions holds every question and your answer in your own words, and Assumptions shows whether you kept each one.
- A visible end. The progress bar has one segment per ticket, and after the last milestone the orchestrator asks whether the project is finished.
In A project, end to end, three milestones took a project to eight merged pull requests in about three hours, with five questions to the person. Two were one-time setup steps and three were the milestone-end assumption checks. Assumptions there were concrete, such as using a different config file name because the first one failed to load on the repo’s Node version. Docs milestones surface the same kind of choice, such as which example the crew documents when the plan did not name one.
When something else fits
- If the update is a single small change with one check, such as fixing one page, one milestone is enough. More milestones only add questions.
- If the work spans several unrelated outcomes, give each its own project, so each has its own spec and its own finish.