Skip to main content

Organizing work

Hyrax organizes your workspace into Areas and Spaces, and the issues you track live in Spaces. Plans sit beside them: a Plan says why a piece of work exists, and its issues can be in any Spaces in your workspace.

What it isWhat it holds
AreaA broad part of your organization, like Product or Go-to-market.Spaces, and the people and repositories its Spaces share.
SpaceA team or a body of work, like Checkout or Payments.Issues, with the people and repositories that work on them.
PlanA goal the work serves, like a migration or a branding update.Issues from one or more Spaces.

Each issue belongs to exactly one Space, and to at most one Plan.

What a new workspace starts with​

A new workspace starts with one Area and one Space, both named Default. 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 there.

People and repositories​

An Area's people and repositories reach every Space in it. A Space can add its own people and repositories on top. Where the Area and the Space both give someone a role, the higher one counts.

  • A Space always keeps its Area's people and repositories, and can only add more.
  • Workspace admins and the account owner can act in every Area and Space without a role there.

Repositories​

Each repository in an Area or a Space has a role there:

RoleWhat it means
WritesAgents may change it and open pull requests against it.
ReadsContext for this Space's work, not a repository it changes.

Placing a repository in a Space 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 Space.

Area and Space roles​

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

RoleWhat it adds
BuilderCan file issues and change team context there, where their workspace role allows it.
LeadEverything a builder can do, plus manage the people and settings. A Space lead approves Plans for the Space. An Area lead can create Spaces in the Area that write to its repositories, and leads every Space in the Area.

What people can do across the whole workspace is set by their workspace role: see Members & roles.

Plans​

A Plan says why a piece of work exists and when it is done. It groups issues that serve one goal, and those issues can be in any Spaces. A Plan's Spaces are the Spaces its issues are in, so you don't need a role in a Space to write a Plan whose work lands there. A lead of each Space, or a workspace admin, approves the Plan for that Space. Approving grants no access. See Plans.

Getting around​

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

  • The rail on the left shows where you are, then that level's pages, such as Overview, Plans, Code health, Activity and Team context. Activity shows what has run at that level and its issues, under Runs and Issues; your role decides which you see. Most pages cover everything inside the level you're at. Plans and What to do next, a button on the Plans page, always cover the whole workspace. Workspace settings, in your account menu (click your name at the bottom of the rail, or ⋯ at the top right), holds the workspace-only pages, Members & invites and Billing among them.
  • The card at the top of the rail names where you are. Open it to switch to another Area or Space. Type to find one, or type an issue's ref, such as ISS-12, to go straight to that issue.

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

Archive and delete​

Each Area and Space has its own Settings, with a Danger zone at the foot.

API keys, and the AI tools that use them, can't create, rename, move, archive, unarchive or delete an Area or a Space. A person does that in the web app.

  • Archive parks a Space. It stays readable at its own address, and Hyrax stops choosing it for issues it files automatically. If it has open issues, you choose first whether to move them to another Space or close them. Archiving an Area also archives the Spaces in it. Hyrax asks you to confirm first.
  • Unarchive brings back that one Area or Space. It won't bring back a Space while its Area is still archived.
  • Delete removes a Space 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. Some deletes are refused, such as an Area that still has live Spaces in it, or your workspace's only Area or only Space.

Every Space 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 Spaces.
  • Plans: group issues around a goal, and say when the work is done.
  • Team context: write down what agents should know, for the workspace, an Area or a Space.
  • Members & roles: what each workspace role can do.