Milestones

Documentation Index

Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt

Use this file to discover all available pages before exploring further.

Milestones are the heart of your migration. Each one delivers a working increment that you review before proceeding, so changes stay small, reviewable, and safe. Within each milestone, the agent breaks the work into tasks and handles them automatically. After tasks finish, runs an automated milestone review and surfaces functional test results before you merge. Once you merge, learns from your changes and updates project knowledge so the next milestone doesn’t repeat the same mistakes. For a high-level overview of the roadmap, see the Roadmap page.

---

​

The Milestone Lifecycle

Each milestone moves through these phases:

1. Review the Milestone Spec in Project Knowledge.
2. Approve & Start — the agent plans and executes tasks.
3. Automated Review & Tests — milestone review and functional testing run automatically and surface in dedicated tabs.
4. Triage the Review and Merge the Milestone — open the Review page to triage issues with chat, then jump to the pull request(s) and merge.
5. Milestone Learning — after merge, learns from the PR review and your edits and updates project wikis and rules so future milestones avoid the same issues.

The expanded milestone card on the Roadmap exposes these as up to three tabs — Tasks, Review, and Tests — that appear as each phase becomes relevant.

---

​

Step 1: Review the Milestone Spec

Before any code is generated, understand what the milestone will accomplish. Click a milestone on the Roadmap to expand it, then click Review & Approve (or Milestone Plan) on the milestone action row. Both buttons open the Project Knowledge drawer with the Milestone Spec selected in the tree — this is where milestone review now lives, alongside the rest of your project’s knowledge (project spec, rules, wikis, lifecycle setup). In the drawer you can:

• Read the full Milestone Spec — scope, relevant files, design decisions, and risks the agent will follow.
• Refine via Knowledge chat — ask to clarify, expand, or adjust the spec. The agent updates the Milestone Spec in place.
• Approve — when you’re satisfied, approve the milestone from the drawer to unlock Approve & Start on the Roadmap.

For deeper guidance on editing the Milestone Spec — including Validate following milestones to make sure your edits don’t break later milestones — see Editing Milestones. For the drawer itself, see Project Knowledge.

---

​

Step 2: Approve and Start

Once you’re happy with the spec, click Approve & Start on the milestone. prepares a sandbox and the agent begins working autonomously: it plans tasks, works through them one by one, and commits code after each task. A Tasks tab appears on the expanded milestone where you can watch progress in real time. Each task shows its ID (e.g., M1-TA002), title, and status badge. You don’t need to babysit execution — the agent runs autonomously and progress is persisted. Open the milestone whenever you want to check on it; the Tasks tab keeps updating in the background.

---

​

Step 3: Automated Review & Tests

After the agent finishes implementation, runs two automated passes before the milestone is ready to merge — and both surface as dedicated tabs on the expanded milestone card:

​

The Review tab

The Review tab tracks the milestone’s automated review tasks — the pipeline that inspects the agent’s output and raises issues against the migrated code. Once review tasks finish, the milestone exposes a Code Review button on its action row that opens the dedicated Review page (see Step 4).

​

The Tests tab

The Tests tab shows the functional testing summary for the milestone — passed/total counts for backend (API/CLI) and frontend (visual) test runs, with comparison indicators when origin output is available for reference. From here you can jump into the full breakdown:

---

​

Step 4: Triage the Review and Merge the Milestone

Once the automated review finishes and the pull request(s) are generated, the milestone moves to Pending Review: Everything from here happens through the Review drawer. Click Code Review on the milestone action row to open it — this is the single entry point for both triaging review issues and reaching the underlying pull requests (there’s no separate “open PR” button on the milestone). Triage the review. The Review drawer is an interactive hub for every issue raised on the milestone, with a chat panel for working through them. On this page you can:

• Browse review issues across every repository in the milestone, filtered by status, severity, tags, and resolution.
• Chat with to resolve issues, create new ones, add review criteria, or re-run the review against your latest changes.
• Inspect the Milestone Spec and Project Spec in side tabs without leaving the page.

Merge the milestone. When the review looks good and tests pass, jump to the PRs from the same drawer:

1. Click View Pull Requests in the Review drawer header. A popover lists every PR in the milestone, each linking out to GitHub.
2. Open each PR, review the code as you would any PR — leave comments, request changes, push fixups, or open adhoc tasks for anything you’d rather have the agent handle.
3. Merge when satisfied.

After every PR in the milestone is merged, the milestone is complete and the next one is ready to go.

---

​

Step 5: Milestone Learning

Merging the PR is the signal that the final state of the milestone is what you wanted — including every change you applied on top of the agent’s output (review comments accepted, fixups you pushed, criteria you added, manual edits). treats that signal as a teaching moment. As soon as a milestone PR is merged, a background Milestone Learning task runs automatically. An agent opens a sandbox with full access to the merged PR (review comments, inline feedback, the final diff, your follow-up commits) and looks for patterns worth keeping — corrections, conventions, architectural constraints, or anti-patterns that future milestones should respect. Anything it finds gets written back to your project as updates to:

• Wikis — when the PR reveals new context about the codebase or how a subsystem actually works.
• Rules — when the PR enforces a convention, constraint, or fix-up pattern that should apply to future work.

Both update Project Knowledge directly, so the next milestone’s agent loads them automatically — no copy-pasting feedback, no repeating the same correction across milestones. You don’t have to do anything to trigger this — merging the PR is enough. If you want to see what was learned, open Project Knowledge after the next milestone starts and check Rules and Wikis for recent updates.

---

​

The Foundation Milestone

Milestone 1 (the foundation milestone) includes an extra automated step: lifecycle discovery for the target repository. Before the agent starts writing migration code, analyzes the target repo to determine how it should be installed, built, run, and tested. The discovered configuration is saved as a Lifecycle Setup that you can review and edit through the Project Knowledge drawer. If discovery cannot get the target application healthy automatically, the configuration is saved as Draft and a warning appears so you can fix it before proceeding.

---

​

Milestone Statuses

As a milestone moves through its lifecycle, its status badge updates on the Roadmap. Here’s what each one means:

---

​

Tasks

You don’t need to interact with individual tasks. They execute automatically as part of the milestone. But here’s how they work under the hood.

​

Task Statuses

​

Task Dependencies

Tasks can depend on other tasks. For example, “Implement authentication middleware” might need “Create project scaffolding” to finish first. handles execution order automatically:

• A task stays in Ready until all of its dependencies have completed.
• Once a dependency finishes, tasks waiting on it become eligible to run.
• If a dependency fails, all tasks waiting on it are skipped. This prevents the agent from building on top of work that didn’t succeed.
• Tasks with no dependencies can run in parallel.
• If dependencies form a loop (Task A needs Task B, which needs Task A), catches this and stops with an error.

---

​

Tips

• Review before approving. It’s much cheaper to fix the plan in the Milestone Spec than to fix generated code. Use Knowledge chat to refine if anything looks off.
• Use the Review tab before the PR. The automated review surfaces issues before you spend time in GitHub. Triage them on the Review page, then read the diff in the PR.
• Don’t rush merges. Review carefully. It’s easier to catch issues now than after several milestones have built on top.
• Let Milestone Learning do the bookkeeping. Corrections, fixups, and accepted review comments on a merged PR are automatically distilled into wiki and rule updates — you don’t need to write rules by hand for every recurring issue. For conventions you want enforced now (before the next merge), you can still add a Rule manually.
• One milestone at a time. Complete each milestone before starting the next to keep changes properly integrated.

---

​

Related Docs