> ## 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.
# Adhoc Milestones
> Add new work to your migration as a full milestone — planned, approved, and executed like any other
export const ProductName = "The Morph Platform";
export const productName = "the Morph Platform";
Sometimes you need work that was not part of the original roadmap — a missing feature you noticed during review, a follow-up refactor, or a one-off requirement that does not belong in an existing milestone. **Adhoc milestones** let you describe that work in plain language; {productName} turns it into a full milestone plan, and you run it through the same approve → implement → review → merge flow as every other milestone.
Adhoc milestones appear on the Roadmap under **Ad Hoc Work**, numbered as sub-milestones (for example **3.1** after milestone 3). They are not quick in-place task edits — they are real milestones with their own spec, tasks, validation, and pull request.
***
## When to Use an Adhoc Milestone
* **Scope that deserves its own milestone.** The work is more than a small fix — it needs planning, multiple tasks, or its own PR.
* **Work discovered mid-migration.** You spot a gap during PR review, testing, or demo prep that should ship before you move on.
* **One-off requirements outside the original spec.** You need something done now without re-running roadmap generation for the whole project.
* **At the end of the project, when Final Code Delivery is ready.** All standard milestones are merged and the final delivery PR is open — but you still need an ad hoc fix, refactor, or change before you ship. Create an adhoc milestone to handle that work through the normal milestone pipeline; Final Code Delivery waits until any open ad hoc / upstream milestone completes.
For smaller adjustments inside an *existing* milestone's scope, prefer [editing the milestone spec](/customization/editing-milestones) before approval, or [Code Review Chat](/migration/code-review-chat) to resolve issues on a milestone already in review.
For preferences that should apply across *future* milestones, add a [Rule](/customization/rules) instead.
Adhoc milestones are different from **Ad hoc Validation** and **Upstream Sync** — those are specialized off-sequence milestones for rerunning validation or merging upstream changes. This page covers **Ad hoc Milestone** only.
***
## Creating an Adhoc Milestone
1. Open the project **Roadmap**.
2. In the sidebar, find the **Ad Hoc Work** section.
3. Click **Ad hoc Milestone**.
4. In the drawer, describe your requirement in plain language — what you need, why, and any constraints that matter (files, APIs, test expectations, etc.).
Example requirement:
> Add rate limiting to the public API endpoints. Use a token-bucket per client IP, return HTTP 429 with a clear error body, and cover the happy path and limit-exceeded cases with tests.
5. Click **Create Ad hoc Milestone**.
{productName} creates a placeholder milestone (numbered **X.1**, anchored after the last standard milestone you have started) and runs **adhoc milestone planning** in the background. While planning runs, the milestone card shows **Generating plan…**
When planning finishes:
1. Open the milestone on the Roadmap or in **Project Knowledge**.
2. Review the generated milestone spec — title, description, deliverables, and task breakdown — the same way you would for a standard milestone.
3. Edit the spec if needed, then **approve** it.
4. Start implementation and follow the normal [milestone lifecycle](/migration/milestones-and-tasks).
If planning fails, the milestone card shows a failure state with **Retry**. Fix anything blocking the agent (for example daemon connectivity), then retry planning in place — you do not need to re-enter the requirement.
***
## How Adhoc Milestones Behave
Once the plan is ready, an adhoc milestone behaves like any other milestone:
| Stage | What happens |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| **Planning** | Agent generates a milestone spec from your requirement (automatic for adhoc milestones). |
| **Approval** | You review and approve the spec in Project Knowledge before implementation starts. |
| **Implementation** | Agent executes tasks, commits code, and opens a milestone pull request. |
| **Review & tests** | Automated review and functional tests run according to your [validation level](/setup/validation-level). |
| **Merge** | You triage review issues, merge the PR, and the milestone completes. |
Adhoc milestones participate in the same dependency and sequencing rules as standard milestones. Other milestones that depend on this work stay blocked until the adhoc milestone is merged.
***
## Planning in Parallel, Running One at a Time
Creating an adhoc milestone only **plans** it — nothing runs until you start it. So you can create as many as you like, whenever you like, including while another adhoc milestone is still open or while a standard milestone is in progress. Each new one lands on the Roadmap as the next sub-milestone (**3.1**, then **3.2**, and so on) and waits for you.
Execution is what is serialized. A queued milestone shows as **Pending** with no start action until every earlier off-sequence milestone at the same anchor has finished, and only one off-sequence milestone. You always start each one yourself; a queued milestone never begins on its own.
**Ad hoc Validation** and **Upstream Sync** work differently: those two actions *are* disabled while other milestone is running or any off-sequence milestone is still open.
### Adhoc milestones proposed in chat
[Project Knowledge](/customization/project-knowledge) and [Code Review Chat](/migration/code-review-chat) can also write an adhoc milestone plan for you when you ask for work that is too large for the conversation at hand. The agent writes the plan, and the milestone appears on the Roadmap when the turn ends — queued exactly like one you created from the sidebar.
***
## When You Can (and Cannot) Create One
### You can create an adhoc milestone when
* The project has an active project spec (normal after onboarding).
* Your build environment is ready to accept work — on [Modelcode Hosted](/setup/build-environment/modelcode-hosted) this is automatic; on a [Self-hosted Daemon](/setup/build-environment/self-hosted-daemon), your daemon must be **Online**.
### You cannot create one when
| Blocker | What to do |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Model daemon offline** (self-hosted only) | Start or reconnect your daemon. See [Self-hosted Daemon](/setup/build-environment/self-hosted-daemon#daemon-status). |
***
## Tips for Effective Requirements
* **Be specific.** Name endpoints, files, libraries, or behaviors you care about. "Add rate limiting to `/api/v1/*`" beats "improve the API."
* **State what done looks like.** Include test expectations, status codes, or acceptance criteria the agent should satisfy.
* **Right-size the ask.** One adhoc milestone should cover one coherent piece of work. If the requirement spans multiple unrelated features, split it into separate adhoc milestones or update the [roadmap](/migration/roadmap) instead.
* **Review the generated plan before approving.** Planning aligns the work with your project spec and current migration state — treat the spec like any other milestone and edit it before you approve.
***
## Related Docs
The full milestone lifecycle from approval through merge
How milestones are ordered and unlocked
Adjust a planned milestone before approving it
Resolve review issues on a milestone already in progress
Ad hoc Validation vs. adhoc milestones
Encode recurring preferences across milestones