# Projects and milestones

Create a project, give it an outcome and milestones, move issues into it, and close it with evidence instead of vibes.

A project is a bounded outcome with issues doing the work. Milestones are the checkpoints on the way. Hydrant counts what actually got done, and asks for proof before anyone declares victory.

## Before you start

- **Admins and the Owner** create and edit projects and milestones, post updates, set project and milestone targets, and run lifecycle actions (Pause, Complete, Cancel, Archive and friends).
- **Members** can read every project and move issues in and out of projects and milestones. The buttons still show; the save is refused with "Your role in this workspace does not allow this action."
- Nothing here needs a paid plan.

[Who can do what](/help/workspace/members#who-can-do-what).

## Steps

### Create a project

1. Open **Projects** in the sidebar.
2. Click **Create project**.
3. Type a **Name**. The dialog's own advice: "Name the thing. We've canceled the 40-slide strategy deck." Pick an icon and color if you like.
4. Click **Create project**.

That's enough. A name alone creates a **Planned** project with no lead, no milestones and no issues. Open **Add context** in the same dialog, or **Edit project** later, to fill in:

| Field | What it's for |
| --- | --- |
| **Summary** | One line for the project list. |
| **Purpose and scope** | What's in, and what isn't. |
| **Outcome** | What changes when this ships. |
| **Definition of done** | How you'll verify the outcome. |
| **Lead** | The person or agent coordinating it. Being lead grants no extra permissions. |

A project needs a lead, an outcome and a definition of done before it can be Active by hand. It can still go Active by itself without them (see below); the page then tells you "It still needs a lead, an outcome and a definition of done." Fix that before the project becomes folklore.

### Know the states

A project is always in one of five states:

| State | Means |
| --- | --- |
| **Planned** | Exists. Nothing has started. |
| **Active** | Work is moving. |
| **Paused** | Deliberately on hold. Issues keep their statuses. |
| **Completed** | Outcome delivered, with evidence on record. |
| **Canceled** | Closed without an outcome. |

A milestone is **Open**, **Achieved** or **Canceled**. Archive is separate from state: it hides a project or milestone from the default list and can be undone.

### Let issues drive the state

You don't flip Planned to Active. Your issues do.

- **Planned becomes Active** as soon as one member issue reaches In Progress, a review stage or Done. This happens even if the project has no lead, outcome or definition of done.
- **Active (or Planned) becomes Completed** when every member issue that isn't in the Trash is Done or Canceled, and at least one is Done. Hydrant records an acceptance with generated evidence, credited to whoever made the final issue change. The page says **Completed automatically**: "Every issue finished, so the project closed itself. New or reopened work makes it Active again."
- **An automatically completed project goes back to Active** when a member issue reopens or open work is added. The earlier completion stays in History.

Iced, snoozed, Backlog, Ready, In Progress and review issues all hold a project open. An empty project, or one where everything was canceled, never completes itself. Paused, Canceled, archived and manually completed projects never change state automatically, and milestones are never achieved automatically.

This runs for anyone allowed to change the issue, Members included.

### Use the Actions menu

Everything deliberate lives in **Actions**, beside **Edit project** at the top of the project page. What's on offer depends on the state:

| State | Actions |
| --- | --- |
| Planned | Pause project, Cancel project…, Archive project… |
| Active | Pause project, Complete project…, Cancel project…, Archive project… |
| Paused | Resume project, Cancel project…, Archive project… |
| Completed or Canceled | Reopen project…, Archive project… |
| Archived | **Restore project** replaces the menu |

Each item opens a dialog for that one action. Hydrant loads the affected work first, then asks for what it needs:

- **Pause** and **Resume** ask for a one-line **Reason**. Resume returns to Active only if work has started *and* the project has a lead, outcome and definition of done. Otherwise it returns to Planned, and goes Active on its own once work moves.
- **Complete** shows the leaf work as **Left behind**, **Done** and **Canceled**, and requires **Evidence**. "Optimism is lovely. Attach evidence." If anything is left behind, canceled, a parent issue or an unfinished milestone, you must also fill in **Scope disposition / reason** to say what happens to it.
- **Cancel** closes the project without an outcome and asks for a reason. Issues keep their statuses.
- **Reopen** puts the project back in play: Active if the lead, outcome and definition of done exist, Planned if not. The earlier outcome stays on the record.
- **Archive** hides the project from the default list. Issues keep their statuses. Restore it before adding new work.

The state chip in the header is a badge, not a control.

### Add milestones

1. On the project page, click **Add milestone**.
2. Give it a **Name** ("A result. 'Phase 2' doesn't count.") and optional **Completion criteria**.
3. Save.

A project holds up to 100 milestones, archived ones included. Order them with **Move up** and **Move down** under **Criteria and actions**. Order never creates dependencies; it only decides which open milestone the page calls the **Next checkpoint**.

When every issue in a milestone is Done or Canceled, it says "All done. Your move." That's a prompt, not a promotion. Click **Review milestone**, set **State** to Achieved, add **Evidence** and confirm with **Mark achieved**. An achieved milestone offers **Reopen milestone**. **Archive milestone** is under **Criteria and actions**.

### Put issues in a project

Each issue belongs to at most one project, and at most one milestone inside that project. Both are optional.

- **From the issue:** use the **Project** and **Milestone** rows in the issue's side panel. Picking a milestone fills in its project. Changing the project clears the old milestone.
- **From the project page:** click **Link existing issues**, find the issue, and click **Move here**. Or use the **+** button beside it to create a new issue already in the project.
- **When creating an issue:** set the project in the new-issue dialog.

Parents and sub-issues don't have to share a project. A sub-issue can live in another project entirely; moving a parent never drags its children along.

Adding work to a **Completed** or **Canceled** project, or an **Achieved** or **Canceled** milestone, asks you to review the destination and give a **Reason for adding work**. The earlier acceptance stays as it was, and the page flags that scope changed since. An automatically completed project is the exception: it just goes Active again. Archived projects don't accept new work until restored.

### Post updates

Under **Updates**, click **Post update** and answer **What changed?** "Spare us 'making progress.' What changed?" Updates are append-only. To correct one, post another.

## What you should see

The **Projects** list groups projects by state, with Completed and Canceled folded away. Each row shows the lead, a progress bar with a done/total count, recent activity as a 12-week strip, and **Stalled. Still waiting.** on anything Active with no activity for 14 days. Filter by **State** or **Lead**, sort by **Name · A–Z**, **Recently updated** or **Most complete first**, and tick **Include archived** to see the attic.

A project page has **Overview**, **Issues**, **Milestones**, **Updates** and **History**. The side panel, **The work**, keeps the counts honest:

- **Progress** counts *leaf* issues: members that have no sub-issues outside the Trash. Parents are listed separately and never counted, so a parent and its three children don't count as four things done.
- The percent is done ÷ (everything not canceled). Canceled leaves get their own segment. The percent rounds down, so 199 of 200 is 99%, never 100%.
- **Points** appear when the workspace uses sizes: size points done out of the total, with a count of unsized issues. See [Labels, sizes and priority](/help/using/labels-sizes-priority).
- **By status**, **Blocked**, **Milestones** (achieved out of open plus achieved), **Last activity** and **Next checkpoint**.
- **Blockers outside this project** lists direct blockers that live elsewhere.

There's no health color, forecast or per-person breakdown. Progress is arithmetic, not a mood.

**History** keeps every acceptance, with the evidence, the reviewed issues and the definition of done at the time. **View all acceptance evidence** shows them all; **Show the receipts** shows every recorded change.

## If it goes sideways

- **"Your role in this workspace does not allow this action."** Project, milestone and target changes need an Admin or the Owner. Moving issues in and out doesn't.
- **The project went Active with no lead or outcome.** Expected: an issue started. Click **Edit project** and add the lead, outcome and definition of done.
- **Everything's Done but the project is still Active.** Something isn't finished. Iced, snoozed and Backlog members hold it open, and so does a parent issue that isn't Done. Check **By status**, or complete it yourself from **Actions**.
- **The milestone says all done but isn't Achieved.** Milestones never grade their own homework. Use **Review milestone**.
- **Complete is greyed out.** It needs **Evidence**, and a disposition if work is left behind. If the review list is long, click **Review more work** until it's all loaded.
- **"Project changed. Load latest state and review draft."** Someone else changed the project or its issues while you were reviewing. Click **Load latest state and review draft**, read it again, then save. Your text is kept.
- **"Restore this project before editing it."** It's archived. Use **Restore project** first.
- **"This project retains 100 milestones. Reuse an existing checkpoint."** The limit counts archived milestones too.
- **The progress bar disagrees with the issue list.** The bar counts leaf issues only; the list shows parents too. **View all project issues** shows everything.

Contact: bots@hydrant.dev