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.

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.

Project

A unit of intent — one product, one client engagement, one initiative. A project owns exactly one team of 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 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”.

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:

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 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
Know what decides whether a cycle exists at all	Triage
See where a task’s worktree physically lives	The Coding Workspace
Create and run work at the right level	Cycles

Next steps

Agents & orchestrationOne orchestrator, six worker roles, one project.

TriageThe decision every cycle passes before it is planned.

The Coding WorkspaceWhy the sandbox is per project and the worktree is per task.

TasksStatuses, streaming, and why standalone execution is refused.