Skip to Content

How should I split framework migrations into milestones for a monorepo?

In Tares, you split a framework migration into milestones that each end on acceptance checks, so the crew’s assumptions get confirmed before the next step. Every milestone in the spec carries its own checks, and the orchestrator brings you the assumptions made during a milestone in one question at its end. Cut the migration where a check can prove the step is done.

How it works

The factory plans in milestones. When you run tares factory spec, the spec session asks you questions, a second model challenges the plan, and Tares stores a spec, a plan, an AGENTS.md for the project and the milestones, each with acceptance checks. You then say yes to hand the project to the crew, and the orchestrator starts a builder for the first milestone.

Inside a milestone, the builder works through tickets one at a time. Each ticket gets a branch and a pull request. The reviewer posts a verdict on every pull request, and the builder merges once the verdict passes and CI is green.

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 all of that milestone’s assumptions in one question, and you keep them or not. So the end of a milestone is the point where unknowns turn into confirmed decisions.

The worked example in A project, end to end shows the shape. Its three milestones were:

  • M1, tests and CI on the branch. A safety net first.
  • M2, payout history stays as it was. Behavior that must not change.
  • M3, merged and live. Documented, merged into main and running in production.

Each milestone ended on something you can check, not on an amount of work. The same page describes a project of 20 tickets over three milestones and three repos, so one project can span several repos.

Set it up

  1. Bring up the crew as described in Get started, then start planning from the repo:
tares factory crew up
tares factory spec "what you want to build"
  1. In the spec session, describe the migration and its end state, and ask for milestones that each end on an acceptance check you can verify. Following the example project, a useful order is:
    • A first milestone that puts tests and CI in place, so later milestones have something to prove them against.
    • Middle milestones that each cover one slice of the migration, with a check that behavior you care about stays as it was.
    • A last milestone for documenting, merging and running it live.
  2. Keep each milestone small enough that its checks fit in a sentence or two. Write checks as observable results, such as tests passing and CI running on every pull request.
  3. For a monorepo, give each milestone a boundary you can name, such as one slice of the migration. The project page’s GitHub fold lists the repos the project changes and where each is checked out.
  4. Let the challenge step push back on the plan, then answer yes to hand the project to the crew.
  5. At the end of each milestone, answer the orchestrator’s question about its assumptions. If you want an answer to stand from now on, say so, for this project or for every project.
  6. Watch progress on the project page. Its four steps are Spec, Build, Review and Done, with one progress bar segment per ticket, and the Tickets fold shows each milestone with its acceptance checks.

What you get

  • A plan you can verify. Each milestone’s acceptance checks are stored with the project and shown in the Tickets fold, next to each ticket, its builder, its pull request and its review rounds.
  • Confirmed assumptions at every boundary. In the example, the working doc named vitest.config.ts, which fails to load on the repo’s Node version, so the builder used vitest.config.mts and recorded it as an assumption. You saw it, with the tickets it touched, at the end of the milestone.
  • A record of your decisions. Every question the crew asked and your answer, in your own words, goes into the Decisions fold, newest first.
  • A plan that can grow. When the reviewer found smaller issues outside the ticket it was reviewing, the orchestrator turned them into a new ticket and placed it in the right milestone. The plan grew by one ticket without a re-plan.
  • Clear blockers. A blocked ticket names the tickets it waits for, so you see the order of work inside a milestone.
  • A finished state. After the last milestone, the orchestrator asks whether the project is done, and Tares marks it Done with your words once every ticket is merged.

When something else fits

  • If the migration is small, one or two milestones are enough. The example project used three for a fix, test and ship job, so match the count to the checks you need.
  • If you only want to adjust work in progress, talk to the orchestrator instead of re-planning. To pick up a finished project again, hand it to the crew again, for example with a follow-up spec.
  • If a check cannot be stated, the milestone is not ready yet. Keep refining it in the spec session before you hand it over.

Still stuck? Get help

Last updated on