How should I split bug fixes into milestones for a Node/TypeScript app?

Tares plans bug fixes as milestones that each end with acceptance checks, so you confirm the crew’s assumptions and the next builder starts from a settled base. Group fixes by what must be true when the milestone ends: tests and CI first, then the behavior fixes, then merged and live. The spec session writes the milestones and checks with you before the crew starts.

How it works

The spec session turns your starting point into a spec, a plan, an AGENTS.md for the project and a set of milestones. Each milestone carries its own acceptance checks, and the project page lists them in the Tickets fold. A builder works the tickets of a milestone one at a time. For each ticket it makes a branch, does the work and opens a pull request. The reviewer posts a verdict on every pull request, and the builder merges once the verdict passes and CI is green.

The milestone end is where planning meets reality. When the crew meets something the plan did 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 its assumptions in one question. You keep them or change them, and the crew carries on from your answer.

The project walkthrough shows this on a real Node/TypeScript project, a pull request with no tests and a few bugs in how it paid shifts. It used three milestones:

• M1, tests and CI on the branch: Vitest, unit tests for the logic under repair, and a CI check on every pull request.
• M2, payout history stays as it was: deactivating a sitter or changing a rate leaves past weeks unchanged, and “today” is the household’s date.
• M3, merged and live: the pull request documented, merged into main and running in production.

Set it up

1. Run the spec session in the repo that holds the bugs, and answer Claude Code’s questions. A second model challenges the plan before it goes into Tares.

tares factory spec

2. Make the first milestone the safety net. Ask for a test runner, unit tests around the code the bugs live in, and a CI check on every pull request. Every later fix then has a check to pass.
3. Group the bug fixes by behavior, not by file. One milestone gets one outcome you can state in a sentence and verify, such as “payout history stays as it was”. Write the acceptance checks as things you can observe.
4. Put the release in its own last milestone. “Merged and live” is a separate outcome from “fixed”, so you confirm the deploy on its own.
5. Read the milestones and checks in the plan. When they match what you want, say yes to hand the project to the crew.
6. Start the crew and choose how far it may go.

tares factory crew up

7. Watch the project page. Answer the crew’s questions in the orchestrator’s session. At each milestone end, go through the assumptions it lists and keep or change each one. To make an answer stand from now on, say so, for this project or for every project.

Expect the plan to grow. In the walkthrough, the reviewer found smaller issues outside the ticket it was reviewing. The orchestrator turned them into one new ticket and placed it in M2 before the integration tests, so the fixes landed inside the milestone where they belonged.

What you get

• A clear stop at every milestone. The crew’s assumptions come to you in one question, so you confirm them before the work builds on them.
• Assumptions with names. In the walkthrough, a working doc named vitest.config.ts, which fails to load on the repo’s Node version. The builder used vitest.config.mts and recorded it as an assumption. Another assumption left existing production data alone, flagged it in the pull request and left any production fix to the person.
• A record of the build. The project page shows the steps from Spec to Done, a progress bar with one segment per ticket, each ticket’s pull request and review rounds, every decision in your own words, and every assumption with whether you kept it.
• Checked merges. Each pull request gets a reviewer verdict and green CI before it merges. Some tickets take a second review round, and the next round passes.
• A finished project you can mark done. After the last milestone the orchestrator asks whether the project is finished, and Tares marks it Done with your words.

If you are new to the factory, start with Get started.

When something else fits

• For a single small fix, one milestone with a couple of checks is enough. Do not split work that has one outcome.
• If you want to approve every merge yourself, say so when you start the crew. The walkthrough’s second project waited for the person’s yes before every merge.
• If the bugs are still unclear, spend the spec session pinning them down before you cut milestones, because the checks depend on knowing what “fixed” means.

Related