How should I split dependency upgrades into milestones for a monorepo?
Tares plans work as milestones, and each milestone ends with acceptance checks that confirm the choices made on the way before the next builder starts. For dependency upgrades in a monorepo, make each milestone one outcome you can check, such as a green CI baseline, then the shared packages upgraded, then the apps upgraded, then merged and live. Describe that split to tares factory spec and the software factory for Claude Code turns it into milestones, tickets and a plan.
How it works
A milestone is the unit of planning in the software factory for Claude Code. The spec session produces a spec, a plan, an AGENTS.md for the project and milestones, each with acceptance checks. The orchestrator then starts a builder for the first milestone.
A milestone is also where assumptions get settled. 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, and you keep them or not. Upgrades surface many such choices, such as a config file that no longer loads on your Node version, so the end of a milestone is the right place to confirm them.
Inside a milestone, work is split into tickets. Each ticket gets a branch and a pull request. The reviewer reviews every pull request, and once the verdict passes and CI is green the builder merges. A ticket that depends on another is marked blocked and names the tickets it waits for. You can follow this on the project page, where the Tickets fold lists milestones with their acceptance checks.
The project walkthrough shows the pattern with three milestones: tests and CI on the branch, a behavior that must stay as it was, and merged and live. Here the same shape is applied to upgrades.
Set it up
- Make sure the crew is running. If you are new to the factory, follow Get started first, then bring up the crew.
tares factory crew up- Plan the project from the repo with
tares factory spec. Put the milestone split in your description, so the spec session can turn it into milestones with acceptance checks.
tares factory spec "upgrade dependencies across the monorepo in four milestones"-
Describe milestones like these. They follow the example project’s pattern of baseline first, then change, then ship.
- M1, a trustworthy baseline. Tests and a CI check run on every pull request, on the current versions. The acceptance check is a green CI run before anything is upgraded, so later failures are attributable to the upgrade.
- M2, shared packages. Upgrade the packages other packages depend on. The acceptance check is that CI is green and the behavior you care about is unchanged.
- M3, the apps. Upgrade the apps that consume those packages. Tickets here wait on the M2 tickets they depend on, so they show as blocked until those merge.
- M4, merged and live. Everything is documented, merged into main and running in production.
-
Answer the crew’s questions in the orchestrator’s session. At the end of the project you are asked whether it is finished, and Tares marks it Done with your answer.
-
Hand the project to the crew when the spec session asks. The spec session ends by asking whether to hand the project over, and the orchestrator picks it up once you say yes.
What you get
- Each milestone ends at a check you can name, so the next builder starts from a confirmed state and not from guesses.
- Assumptions arrive together at the end of each milestone, each naming the tickets it touches and the builder that made it. Your answers are kept in the Decisions fold in your own words.
- Reviewer findings outside a ticket can become a new ticket. In the example project the orchestrator placed one in the second milestone ahead of the integration tests, so the plan can grow without you replanning.
- The project page records the whole build: tickets with their pull requests and review rounds, decisions, assumptions and the sessions that did the work.
When something else fits
- If the upgrade is a single bump with one pull request, a milestone split adds little. Hand it to one builder as one ticket, or make the change yourself.
- If your repo has no tests or CI, make the baseline milestone first. Without it, the acceptance checks of the later milestones have nothing to compare against.