How should I split docs updates into milestones for a Node/TypeScript app?

Tares plans docs updates as milestones that each end with acceptance checks, so you confirm the crew’s assumptions before the next builder starts. Make each milestone one outcome you can check: a CI gate on the branch, then accurate content, then merged and live. At the end of each milestone the orchestrator asks you in one question whether to keep the choices the crew made on its own.

How it works

A milestone is the unit of planning in the software factory for Claude Code. Here is how the pieces fit:

• The spec session produces the milestones. You run tares factory spec in the repo and answer Claude Code’s questions. A second model challenges the plan. What goes into Tares is a spec, a plan, an AGENTS.md for the project, and milestones, each with acceptance checks.
• Builders work tickets one at a time. For each ticket the builder makes a branch, does the work and opens a pull request. The reviewer posts a verdict, and once it passes and CI is green, the builder merges.
• A milestone ends with a question. 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 the milestone the orchestrator brings you all of that milestone’s assumptions together. You keep them or not, and the next builder starts from your answer.

The example project in A project, end to end used three milestones:

• M1, tests and CI on the branch: Vitest, unit tests, and a CI check on every pull request.
• M2, payout history stays as it was: the behaviour the work had to preserve.
• M3, merged and live: the pull request documented, merged into main and running in production.

For docs updates in a Node/TypeScript app, follow the same shape:

1. Checks on the branch. The milestone ends when a CI check runs on every pull request and passes on the docs branch.
2. Content that matches the app. Each acceptance check names one thing a docs page must state correctly. Group tickets by area of the app so each pull request stays reviewable.
3. Merged and live. The pull request is described, merged into main and published.

Put anything that depends on your Node version in the first milestone. In the example, the working doc named vitest.config.ts, which fails to load on the repo’s Node version. The builder used vitest.config.mts and recorded it as assumption A1, which the person confirmed at the end of the milestone.

Set it up

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. Start Tares and the crew. On a local Tares, run tares up, then start the MCP endpoint in a second terminal, then bring up the crew. On Tares Cloud, run tares login instead of the first two commands.
3. Plan the project with tares factory spec. Describe the docs update in your own words, and name the Node/TypeScript parts it covers.
4. Answer Claude Code’s questions. Then read the milestones and their acceptance checks on the project page, in the Tickets fold. Each check should be something you can verify, such as a CI check passing or a page matching the app’s behaviour.
5. Say yes to hand the project to the crew. The orchestrator picks it up and starts a builder for the first milestone.
6. 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.
7. When the last milestone is merged, tell the orchestrator whether the project is finished. Tares marks it Done.

tares up
tares mcp --transport streamable-http
tares factory crew up
tares factory spec "what you want to build"

To watch the build, open the Crew page in the console at http://127.0.0.1:8787/crew locally. If you have not run the factory before, start with Get started.

What you get

• A confirmation point per milestone. Every choice the crew made on its own is listed with the tickets it touches and the builder that made it, so you keep or change it before the next builder starts.
• A record of the build. The project page holds the spec, plan and AGENTS.md, the milestones with their checks, each ticket with its pull request and review rounds, and every decision in your own words.
• Reviewed pull requests. The reviewer posts a verdict on every pull request, and the plan can grow when it finds smaller issues. In the example it became a new ticket placed before the integration tests.
• A clear finish. After the last milestone you say whether the project is done, and Tares moves it to the finished list.

When something else fits

• If you want to approve every merge yourself, choose that when you bring up the crew. The example in A project, end to end shows a project that waited for the person’s yes before every merge.
• If you only want to steer one piece of work by hand, talk to the orchestrator rather than reshaping the milestones.

Related