Organizing work

Hyrax organizes your workspace into Areas, Spaces and Projects. Each level groups the one below it, and the issues you track live in projects:

Level	What it is	What it holds
Area	A broad part of your organization, like Product or Go-to-market.	Spaces.
Space	A team or product.	Projects, including the Space's Inbox.
Project	A piece of work with a goal, like Checkout or a migration.	Issues.

Only projects hold issues. Areas and Spaces group the projects beneath them, and you read their pages for a roll-up of everything inside.

What a new workspace starts with

A new workspace starts with one Area and one Space, both named Default, and the Default Space's Inbox. You don't have to arrange anything to get started:

• Every repository you connect is added to the Default Space with the Writes role (see Repositories).
• Everyone in the workspace belongs to the Default Space, so every member can file issues and create projects there.
• Hyrax doesn't name a level you have only one of. With one Area and one Space, the app shows your workspace and its projects, and keeps Areas and Spaces out of the way. Spaces start showing once you create a second Space, and Areas once you create a second Area. Nothing moves when a level appears: it simply gets a name.

When you create your second Space or Area, the dialog offers Rename Default to (optional), so the first one can get a real name at the same time.

The Inbox

Every Space has an Inbox: a project for issues that belong to the Space but not yet to a particular project. It always holds exactly the Space's repositories, and it can't be renamed, moved, archived or deleted. In lists of projects, the Inbox comes first.

Repositories

You add repositories to an Area, a Space or a Project, and each one has a role there:

Role	What it means
Writes	Agents may change it and open pull requests against it.
Reads	Context for this project's work, not a repo it changes.

Repositories pass downward and can only narrow:

• An Area's repositories reach every Space in it. On a Space, they're marked From the Area's name, and you change them on the Area.
• A project's repositories must come from its Space. A project can use some of its Space's repositories, never one the Space doesn't have.

Placing a repository in a project never grants anyone access to its code. What each person can see is still set by their own repository access.

A repository can sit in more than one project. Lists show this as Also in with a count of the other projects you can see.

Getting around

The app keeps you at one level at a time: the workspace, an Area, a Space or a Project.

• The rail on the left shows where you are, then that level's pages: Overview, Issues, Code health, Activity and Reviews, and under Knowledge, Team context. Each page covers everything inside the level you're at. Workspace settings, at the foot of the rail, holds the workspace-only pages, Members & invites and Billing among them.
• The path in the top bar names the levels you're in. Each level above you takes you up to it, on the same page when it has one.
• The card at the top of the rail names where you are. Open it to go somewhere else. Click an Area or a Space to see what's inside it in the next column, then All spaces in … or All projects in … at the top of that column to go there. Click a Project to go to it. Type to find any of them, or type an issue's ref, such as ISS-12, to go straight to that issue. You stay on the same page, when the place you go to has one. It lists only the levels your workspace uses, so with a single Space it lists your Projects. With two or more Areas, All areas takes you to the whole workspace.

An Overview summarizes what's inside the level: issues that need attention, work in progress, issues assigned to you and what's up next.

Creating Areas, Spaces and Projects

To create	Where	Who can
An Area	New area on the workspace Overview, or under Areas in the card at the top of the rail.	Admins.
A Space	+ New space in the Space picker on the New project page. Once Spaces show, also New space under Spaces in the card at the top of the rail, and New space on an Area's Overview.	Admins, and members (who become the new Space's lead).
A Project	New project on an Overview.	Admins, and members of the Space it goes in.

A new project gets a name, a short key made from its name (you can edit it), the Space it belongs to, an optional description, and its repositories with their Writes or Reads role. A member who isn't the Space's lead can add the Space's repositories as Reads. A Space lead or workspace admin can make one Writes, or add another repository.

Space and project roles

Inside a Space or a project, people hold one of two roles:

Role	What it adds
Member	Can file issues in it and everything under it, and change its team context, where their workspace role allows it.
Lead	Everything a member can do, plus create projects in the Space that write to its repositories, and manage the Space's projects and people.

A Space's people are on its Members settings page, and a project's on its People page. Workspace admins and the account owner can act in every Space and project without a role there. What people can do across the whole workspace is set by their workspace role: see Members & roles.

Archive and delete

Each level has its own Settings, with a Danger zone at the foot.

• Archive parks a project. It stays readable at its own address and its issues are untouched, and Hyrax stops choosing it for issues it files automatically. The Archive button also archives everything inside an Area, a Space or a project, apart from a Space's Inbox. It asks you to confirm first, and for a few seconds afterwards you can undo it.
• Unarchive brings it back in the state it had before, or as Active if Hyrax has no record of that state. It brings back that one item alone: when something archived inside it could come back too, you pick which. The Unarchive button won't bring something back while the Area, Space or project it sits in is still archived.
• Delete removes a project from every list, and there is no undo in the app. Its issues aren't deleted: they keep their refs and stay readable. Deleting is an admin action by default. You can't delete anything that still has live projects or Spaces inside it, a Space whose Inbox still has open issues, or your workspace's only Area or only Space.

Every project shows its state: Active (being worked now), Paused (deliberately parked), Done (finished) or Archived (kept for the record).

Where to go next

• Issues: file, triage and close the work inside your projects.
• Team context: write down what agents should know, for the workspace or for one level.
• Members & roles: what each workspace role can do.