How should I split dependency upgrades into milestones for a documentation website?

In Tares, you split dependency upgrades into milestones that each end at acceptance checks you can verify. At the end of each milestone, the orchestrator brings you the choices the crew made on its own in one question, and you keep or change them. The spec session writes the milestones and checks into the project plan.

How it works

The software factory for Claude Code plans a project as milestones, and each milestone carries acceptance checks. The spec session records them alongside the spec, the plan and the project’s AGENTS.md. When you hand the project over, the orchestrator picks it up and starts a builder for the first milestone.

Inside a 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 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. That makes the milestone boundary the place where your review of the crew’s choices happens.

The project page keeps the record:

• The Tickets fold lists the milestones with their acceptance checks, and each ticket with its builder, pull request and review rounds.
• The Assumptions fold lists every choice the crew made on its own and whether you kept it.
• The Decisions fold lists every question the crew asked you and your answer, in your own words.

The end-to-end project walkthrough shows three milestones this way. M1 was tests and CI on the branch, M2 was that past behavior stays as it was, and M3 was merged and live. Each one names an outcome you can check.

Set it up

1. Run the spec command in the repo of your documentation website and answer Claude Code’s questions.

   tares factory spec

2. Ask for milestones that each end at a checkable result. Following the shape of the example project, a split for dependency upgrades could look like this:

   • M1, a safety net on the branch: tests and a CI check on every pull request, so later upgrades have something to be checked against.
   • M2, the site stays as it was: the upgraded dependencies leave the existing pages and behavior unchanged.
   • M3, merged and live: the pull request is documented, merged into main and running in production.

3. Write each acceptance check as something a person can verify, such as a CI check that passes or a behavior that is unchanged. A check like “upgrades done” tells the builder and you little.

4. Name facts the plan relies on, such as the tool versions in the repo. The example project’s working doc named a config file that failed to load on the repo’s Node version, so the builder used another file and recorded an assumption. Expect that kind of choice at the end of a milestone.

5. Say yes when the spec session asks whether to hand the project to the crew. The orchestrator starts a builder for the first milestone.

6. At the end of each milestone, read the assumptions question and answer it. To make an answer stand from now on, say so, for this project or for every project.

7. After the last milestone, the orchestrator asks whether the project is finished. When you say it is, Tares marks the project Done. If no project is left, stop the crew with tares factory crew down, and start it again with tares factory crew up when you have the next one. Tares keeps the projects, tickets and answers.

What you get

• Milestones with checks. Each milestone in the plan has acceptance checks, so you can see what “this stage is done” means before the build starts.
• One question per milestone for the crew’s choices. The assumptions the crew made during a milestone come to you together at its end, each naming the tickets it touches and the builder that made it.
• A reviewed pull request for every ticket. The reviewer posts a verdict on each one, and a ticket can take more than one review round.
• A plan that can grow. In the example project the reviewer found smaller issues outside its ticket. The orchestrator turned them into a new ticket and placed it in M2 before the integration tests.
• A full record. The project page keeps the plan, tickets, decisions, assumptions and recorded sessions, so you can see why each choice was made.
• A clear end. The project is Done when you confirm it, with every ticket merged.

When something else fits

• Several small upgrades that need no plan. If the change is one pull request, a full spec, plan and milestone cycle may be more structure than you need. Do that one change in a normal Claude Code session.
• Checks you cannot state yet. If you cannot say what a milestone should prove, answer the spec session’s questions first. The spec session is where the checks get written.
• Steering mid-ticket. To change the work in progress, talk to the orchestrator. It answers the builders and brings you what needs you as a question in its session.

Related