How should I split internal refactors into milestones for a monorepo?

Tares plans a project as milestones, each with acceptance checks, so you split an internal refactor in a monorepo into milestones that each end on checks you can confirm. Each milestone holds tickets, and each ticket becomes one reviewed pull request. At the end of a milestone, the orchestrator asks you in one question whether to keep the choices the crew made on its own. Draw each boundary where those checks pass and that question is easy to answer.

How it works

When you run tares factory spec, Claude Code asks you questions and a second model challenges the plan. The result goes into Tares as a spec, a plan, an AGENTS.md for the project and milestones, each with acceptance checks. See Get started for the full setup.

The milestone is the unit you plan around:

• A milestone holds tickets. The builder works through them one at a time. For each, 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.
• A ticket that waits on others shows as blocked and names the tickets it waits for.
• When the crew meets something the plan does not cover, it picks a 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. You keep them or not. To make an answer stand from now on, say so, for this project or for every project.

The example project in A project, end to end used three milestones with checks: M1 tests and CI on the branch, M2 payout history stays as it was, and M3 merged and live. Its crew took it from a spec to eight merged pull requests.

Set it up

1. Bring up the crew, then plan the project. On a local Tares, start tares up and tares mcp --transport streamable-http first, as Get started describes.

tares factory crew up
tares factory spec "what you want to build"

2. Describe the refactor as an outcome in the spec prompt, then answer the questions Claude Code asks. State what must stay the same, because that becomes your acceptance checks.
3. Make the first milestone the safety net. In the example project, M1 added tests and a CI check on every pull request before any behavior work began. For a refactor, that means checks that prove current behavior, so later milestones can be judged against them.
4. Give each following milestone one result you can check. M2 in the example read “payout history stays as it was”: a behavior that must not change, stated as something you can verify. Name milestones by that result, not by the files they touch.
5. End each milestone where the work is merged and its checks pass. The assumptions question comes at that point, so a clean boundary means a short list of choices to confirm.
6. Put a closing milestone on getting the work merged and running, as M3 did. Keep it separate from the refactor work so the last question is only whether the project is done.
7. Order tickets inside a milestone by what depends on what. A ticket that waits on another shows as blocked and names it, so a clear order keeps the build moving.
8. Review the milestones and checks on the project page, in the Tickets fold, before you say yes to handing the project to the crew. Edit the spec, plan or AGENTS.md in the Docs fold if a boundary is wrong.

You can also record a rule of the repo, such as how to run its tests, in the project’s AGENTS.md. Every session that builds the project reads it.

What you get

• A plan where every milestone has acceptance checks, so you know what “done” means before the crew starts.
• One reviewed pull request per ticket, with each ticket’s builder, pull request and review rounds recorded in the Tickets fold.
• One question per milestone about the choices the crew made alone. Each assumption names the tickets it touches and the builder that made it. In the example, five assumptions came up, including a config file renamed to load on the repo’s Node version, and the person kept all five.
• A Decisions fold holding each answer in your own words, so later milestones carry on from what you confirmed.
• A plan that adjusts without a restart. In the example, the reviewer found smaller issues outside the ticket it was reviewing, and the orchestrator added a ticket for them inside M2, before the integration tests.
• A progress bar with one segment per ticket, plus a Standup report of what is done, started, in review, blocked and waiting on you.

When something else fits

• If the refactor is a single small change, one milestone with a few tickets is enough. Splitting it further adds questions without adding checks.
• If you cannot state a check for a slice of the work, merge it into a neighboring milestone, or write the check first. A milestone without a check has no clear end.

Related