Plans
A Plan says why a piece of work exists and when it is done. It groups the issues that serve one goal, such as a migration or a branding update, and those issues can be in any Spaces in your workspace. Workspaces with missions have Plans: open Plans in the rail.
A Plan is not a mission's plan. A mission plans its own steps for one issue; a Plan is the goal that a set of issues serves.
What a Plan holds
| Field | What it is |
|---|---|
| Title | The Plan's name. |
| Goal | What the work is for. |
| Summary | A short description. |
| Details | Objectives and non-goals, in Markdown. |
| Done when | Lines that each say one thing that must be true when the Plan is done. |
| Issues | The issues that do the work. An issue belongs to at most one Plan. |
| Spaces | The Spaces its issues are in. Nobody picks them: they follow the issues. |
Each Plan also has a ref such as PLN-3, a version number that goes up with every edit, and a history of every version.
States
A Plan is in one of four states.
| State | In the app | What it means |
|---|---|---|
| Draft | Draft | Being written. Every Plan starts here. |
| Ready | Building | Agreed, and its work is under way. |
| Done | Done | Finished. |
| Archived | Archived | Kept for the record. |
- Go moves a draft to ready. It is for the Plan's author or a workspace admin, and the Plan needs at least one issue first.
- Mark done is for a person who may edit the Plan, on the Plan's page. Once a Plan sent for review has started, its author and editors can mark it done too. An AI tool acting for that person can also mark the Plan done, but only when every done-when line is met and none of the Plan's issues is still open. Hyrax never marks a Plan done on its own. When its work looks finished, the Plan's page tells its author.
- Every move has a way back. Back to draft returns a ready Plan to draft, Reopen returns a done Plan to ready, and an archived Plan comes back as a draft.
A Plan's author, its editors and workspace admins can edit it and move it between states. Only its author or an admin starts it building or reopens it. From Submit for review until the Plan is archived or back in draft, the builders and leads of the Spaces it was sent to can edit it, and its author and editors can't unless they build or lead in one of those Spaces. That holds once it is done too: then only an admin, or its author while they build or lead in one of those Spaces, reopens it, and only a lead of one of those Spaces or an admin archives it. It can't start building or be marked done until each of those Spaces approves it and, where its estimate needs one, a workspace admin does. The people added to a Plan to read it can leave notes on it and change nothing else: they can't answer its questions or add Team context to it.
Done-when lines
Each done-when line is one thing that must be true when the Plan is done. The Plan shows how many of its lines are met.
- Marking a line met by hand. Anyone who can see the Plan and manage issues can mark a line met from the … menu at the end of its row. The Plan's page offers Mark met there only on a line that looks met with none of its work still open, and Unmark undoes a mark made by hand. An AI tool connected to the MCP server can mark a line met for you on a Plan you can edit.
- Marking a line met never moves the Plan. A Plan with every line met stays where it is until someone marks it done.
- Adding, changing, removing or reordering a line is an edit. It ends every Space's approval (see Approval by each Space). Marking a line met does not.
Issues in a Plan
The Plan's page lists its issues and where each one stands, and counts how many are done.
- Hyrax files a Plan's issues from its goals. To change the work, change or correct a goal, or add one, and Hyrax adjusts the issues for it. An AI tool connected to the MCP server can't put an issue in a Plan. You still can if you are the Plan's author, one of its editors or a workspace admin and may change that issue in its Space: a new issue goes in one through the Plan field of New issue, and an existing issue on no Plan goes in a new Plan from its Work on this, which offers Just this fix, a Plan of that issue alone, and Plan it with more work, which opens New plan with the issue in.
- Being in a Plan grants nothing. Working an issue still needs the rights you have in that issue's Space.
- What to do next, a button on the Plans page, lists the issues that are in no Plan yet, beside the plans Hyrax suggests. Until an issue there is on a Plan, nobody can claim it, assign it or start a mission on it. It can still be edited or closed. See Claims.
Approval by each Space
A Plan's issues can be in Spaces where its author can't file issues, so each Space approves the Plan on its own.
- A lead of the Space, or a workspace admin, approves the Plan for that Space on the Plan's page. An AI tool can't approve or decline a Plan for a Space through an API key.
- A lead is asked only where it matters. Waiting on you asks a lead to approve for a Space where the Plan's author can't file issues, and, for a draft out for review, for a Space it was sent to once it is that Space's turn to approve.
- A Space can approve a draft or a ready Plan.
- An approval holds until the Plan's goal or done-when lines change. Editing its title, summary or details, marking a line met, or updating it from answers keeps every approval.
- Approving grants no access. It records that the Space agrees to the work, and nothing more.
Questions
Questions on the Plan's page lists decisions waiting on a person's answer. Most Plans have none, and show No open questions.
When a Plan has questions:
- Answer one in your own words, or select Use recommended to take its recommended answer as it is. If you can't answer a question, the page says so.
- Some questions are required. A required question with no answer counts against the Plan's checks before building.
- Answers go into the Plan's details, under Answers, where everyone who can see the Plan reads them. While the Plan is a draft or ready, this happens on its own when someone who can edit the Plan and see Team context answers a question or opens the Plan. An answer about a repository that some member can't see stays out. Each update rewrites that section rather than adding a second one, and approvals still hold. If the answers still don't match the Plan after an update, the questions may offer Try again.
Checks before building
The Plan's page shows a checklist of what the Plan has and what it is missing before its work is built, such as done-when lines and answers to required questions.
How work starts
Once a Plan is ready, its issues get worked.
- By people. When a Plan has started and is marked as worked outside Hyrax, Hyrax starts no missions on it, and people claim its issues by hand: open one, claim it with Claim in its ⋯ menu, do the work and close it. An AI tool working the Plan with an API key can still start a mission on one of its issues.
- By missions. If your workspace has missions, a mission can work an issue on the Plan and end in a pull request you review. Missions are in beta, and Hyrax support turns them on for a workspace on request.
Waiting on you
Plans add their own asks to Waiting on you, under For you in the top bar:
| Ask | When you see it |
|---|---|
| Approve | A Plan's issues are in a Space you lead where its author can't file issues, or a draft out for review was sent to a Space you lead and it is that Space's turn to approve, or, as a workspace admin, either is true in a Space where no lead could approve it. You see it only when you could approve it there yourself, so a lead whose role only lets them view issues isn't asked. |
| Ready to go | Your draft Plan could be started now: it has done-when lines, every open issue on it has acceptance criteria, and its checks before building are met. Only workspaces with missions get this ask. |
Each ask leaves the list once it's answered.
The Plans page
Plans in the rail lists every Plan you can see, across the whole workspace.
- Board groups Plans by where they stand: Waiting on you, Waiting on others, In progress, Planning, Done and Archived.
- Needs you shows only the Plans waiting on you. All lists every Plan.
- Search the Plans, or use Filters to narrow them by state or Space.
- New plan creates a draft. Writing a Plan needs your workspace role to allow managing issues (Members and Admins do by default), and no role in any Space.
History
Every edit to a Plan is kept as a version. History on the Plan's page shows who changed what and when, and can compare any two versions. Restore on an older version saves its title, goal, summary, details and done-when lines as a new version. The Spaces, the state and the issues stay as they are. If the goal or the lines change, each Space approves again.
Who can see a Plan
A draft Plan is private. Only its author, its editors, the people added to it to read it, workspace admins and the account owner see it, unless it was made from an idea through the REST API, the MCP server or chat and has no issues yet: then the people who can see that idea see it too. The leads asked to approve it for their Space see it too, and once it is submitted to a Space, that Space's builders and leads see it while it is out for review. Once the Plan is started (Building), anyone who can see one of its Spaces sees it as well, and still sees it if it goes back to draft. A Space's approval alone doesn't show it to that Space. Plans made from pull request links, and Plans Hyrax makes on its own, such as a Plan for an alert, are visible to their Spaces from the start. A Plan with no issues yet has no Spaces, so nobody sees it through a Space. If your access is limited to some repositories, you may see fewer Plans.
Where to go next
- Organizing work: Areas and Spaces, and where your repositories sit.
- Issues: file, claim and close the work inside a Plan.
- Missions: have Hyrax carry out an issue, ending in a pull request.