# Work tree

The **work tree** is how hlix organizes everything you build: four levels, each nested in the one above, each mapping to a real object you can read over the API.

```text
Workspace                 the tenant — your team, your billing, your audit trail
└── Project               a unit of intent — one product or client engagement
    └── Cycle             a feature, release, or phase — the unit that EXECUTES
        └── Task          one worker agent, one git worktree, one branch
```

## When this matters to you

- You cannot work out why a task will not run — execution belongs to the cycle level, not the task level.
- You are wiring permissions and need to know what a client collaborator can reach — access is granted per project, not per task.
- You are reading the API and want to know which id goes where.

## The four levels

### Workspace

Your team's tenant: everyone you invite, every project, every agent, and the shared audit trail. One workspace is one organization, and it is the `X-Organization-Id` header on every API call.
**Workspace and Coding Workspace are different things:** A **Workspace** is the tenant. A **Coding Workspace** is one project's durable execution sandbox. They are unrelated concepts that share a word, and conflating them is the most common misreading of this product. When a page says "Workspace" with no qualifier, it means the tenant. See [The Coding Workspace](/concepts/coding-workspace/).

### Project

A unit of intent — one product, one client engagement, one initiative. A project owns exactly one [team of agents](/concepts/agents/), exactly one Coding Workspace, its repositories, its secrets, and its environment configuration. It is also the unit of access: a client collaborator is granted a project, and sees nothing outside it.

### Cycle

A meaningful chunk of a project. **This is the level that executes.** The orchestrator plans a project into cycles and works them in sequence, replanning as results arrive. A cycle owns its task set, its QA pass, and its approval gate.

Every cycle is created at the `triage` stage and admitted — or refused — by the [Triage Agent](/concepts/triage/) before any of that begins. It carries the classification that decision produced: a `lane`, a `priority`, and a stage history recording every status move it has made since.

### Task

The atomic unit of execution: one worker agent, one git worktree, one branch, one outcome. Tasks fan out in parallel — they are what makes a wave a wave. A task never executes on its own; `POST /v1/api/tasks/:id/execute` returns `501` by design.

## The same tree, as objects

The four levels nest: a Workspace contains Projects, a Project contains Cycles, and a Cycle contains Tasks — and each level is one API object.

| Level | API object | Read it with | Who can change it |
| --- | --- | --- | --- |
| Workspace | Organization | `X-Organization-Id` header on every call | Workspace owner / admin |
| Project | `/v1/api/projects/:id` | `hlix projects list` | Agency roles; clients get view or steer |
| Cycle | `/v1/api/cycles/:id` | `GET …?projectId=…` | Agency roles |
| Task | `/v1/api/tasks/:id` | `hlix tasks get <id>` | Agency creates; clients comment |

## A worked example

You import an invoicing app and start a run with the brief *"add multi-currency invoices"*.

```text
Workspace  acme-agency                       (X-Organization-Id: org_…)
└── Project  acme-invoices                   (created by `hlix import .`)
    ├── Cycle  "Currency model"              status: pr_created
    │   ├── Task  "Add currency to schema"   → done
    │   └── Task  "Migrate existing rows"    → done
    └── Cycle  "Invoice rendering"           status: executing
        ├── Task  "Format amounts by locale" → building
        └── Task  "Update PDF template"      → queued
```

The two tasks in "Currency model" ran at the same time, in separate git worktrees, against the same shared clone. Neither could see the other's edits until they merged.

A task's branch name is **derived from the two ids**, never stored — `hlix/ms-<cycleId>/task-<first 12 characters of the task id>`. The `ms-` segment is a fixed literal in that template; it does not abbreviate anything you will see elsewhere in the product. So "Add currency to schema" lands on:

```text
hlix/ms-0a9b8c7d-6e5f-4a3b-8c9d-0e1f2a3b4c5d/task-b4a1f0d23c77
```

## Branches and previews

The tree maps onto your repository topology without forcing every project into one egress model.

- **Repository-backed projects** get a task branch per task, pushed to the connected provider so your existing pull-request workflow applies unchanged.
- **Repo-less projects** have nowhere to push, so hlix merges each successful task branch into the project's internal default branch under a lock, then snapshots both the deliverable and the full git history. The result is downloadable rather than pushed.

Either way, cycle QA evaluates the collected work, and an optional [approval gate](/running/approvals/) can pause dispatch before a gated cycle proceeds.

## Where to go next

| If you want to… | Read |
| --- | --- |
| Meet the team that walks this tree | [Agents & orchestration](/concepts/agents/) |
| Know what decides whether a cycle exists at all | [Triage](/concepts/triage/) |
| See where a task's worktree physically lives | [The Coding Workspace](/concepts/coding-workspace/) |
| Create and run work at the right level | [Cycles](/running/cycles/) |

## Next steps

[Agents & orchestration](/concepts/agents/)
  [Triage](/concepts/triage/)
  [The Coding Workspace](/concepts/coding-workspace/)
  [Tasks](/running/tasks/)