How should I split dependency upgrades into milestones for a monorepo?
Tares plans work as milestones, each with acceptance checks, so you split dependency upgrades into milestones that each end in something you can check. At the end of every milestone the orchestrator brings you the assumptions the crew made, and you keep or change them in one answer. Put the checks in the spec you write with tares factory spec, and the project page records each milestone, its tickets and your answers.
How it works
The software factory for Claude Code plans a project as a spec, a plan, an AGENTS.md and a set of milestones. Each milestone carries acceptance checks, and the project page lists them in the Tickets fold, together with each ticket, the builder that held it, its pull request and its review rounds.
The example project on A project, end to end shows the shape. Its three milestones were:
- 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. Past weeks stay as they were after a change.
- M3, merged and live. The pull request documented, merged into main and running in production.
Each milestone is named after an outcome you can verify, not after a list of files. That is the unit to plan with for an upgrade too.
Inside a milestone, work runs as tickets. A builder makes a branch, does the work and opens a pull request. The reviewer posts a verdict, and the builder merges once the verdict passes and CI is green. A blocked ticket names the tickets it waits for, and a project can span several repos.
When the crew meets something the plan did not cover, it picks a sensible answer, records it as an assumption and carries on. At the end of each milestone the orchestrator brings you all of that milestone’s assumptions in one question.
Set it up
- Set up the crew as described in Get started. Claude Code must be signed in, and the crew needs access to the repos your monorepo uses.
- Bring up the crew, then plan the project from the repo:
tares factory crew up
tares factory spec "what you want to build"- In the spec session, describe the upgrade as milestones that each end in a check you can run or read. A pattern that follows the example project:
- A milestone for the safety net: the tests and CI check that must be in place on the branch before any version changes.
- One milestone per group of packages or apps that move together. Write the acceptance check as what must stay true, such as the build and tests passing for that group, the way M2 states that payout history stays as it was.
- A final milestone for merged and live, with the change documented, merged into main and running in production.
- Keep each milestone’s tickets small enough that one pull request covers one change. Review then happens ticket by ticket, and the project page shows each ticket’s state: to do, in progress, in review, merged or blocked.
- Answer the challenge questions from the second model, then say yes to handing the project to the crew. The orchestrator picks it up from there.
- When a milestone ends, read the assumptions the orchestrator brings you. Keep the ones you agree with. To make an answer stand from now on, say so, for this project or for every project.
- When the last milestone is done, tell the orchestrator whether the project is finished. If no project is left, run
tares factory crew downto stop every station.
What you get
- A plan where every milestone has acceptance checks, so you can see what each stage of the upgrade is meant to prove.
- One question per milestone that gathers the choices the crew made on its own. In the example project they covered a config file the repo’s Node version could not load, and the Node version used in a CI job. The same kind of choice comes up in an upgrade, and you see it before the next milestone’s assumptions pile on.
- A record on the project page: milestones, tickets with their pull requests and review rounds, every decision in your own words (up to 4,000 characters each), and each assumption with whether you kept it.
- Room for the plan to grow. In the example, the reviewer found smaller issues outside its ticket, and the orchestrator added a ticket for them in the right milestone.
- A project marked Done with your own words, once every ticket is merged.
When something else fits
- If the upgrade is a single small change, one pull request is enough and you do not need milestones.
- If you want to steer a running build, talk to the orchestrator, not the builder holding the ticket.
- To follow a whole project from spec to merge, read A project, end to end.