Projects
Projects are durable containers for an initiative — they sit above boards and tasks and gather goals, constraints, linked boards/repos, milestones, risks, success metrics, and (on a full deployment) decisions in one place. Projects live at the workspace level and are reached from Projects in the workspace navigation.
A full deployment adds the Decision Register alongside them — structured records of the choices a team makes, with options, rationale, dissent, supersession lineage, and an immutable audit trail. It is documented in Platform UI.
Projects
Creating a project
Open Projects and click New project (workspace admins only — see Permissions). A project needs a name and an accountable owner (any workspace member); a goal statement is optional. The slug is derived from the name and is unique within the workspace.
A "program" is just a project with sub-projects: set a project's parent in Settings to group related projects. There is no separate Program entity.
The project page
The project detail page has up to nine tabs — Agents and Decisions appear only where the deployment carries those planes, and Runs shows agent jobs only on a full deployment:
| Tab | What it shows |
|---|---|
| Overview | Goal, owner, status, link/risk counts, and program grouping. |
| Work | Open tasks from linked boards and directly linked tasks, grouped by board and column. |
| Agents (full only) | Preferred and fallback agents approved for the project, from the agent registry — see Platform UI. |
| Decisions (full only) | Decisions attached to this project. |
| Runs | Connected Claude/Codex sessions, and on a full deployment the workflow runs (agent jobs) correlated to the project, clearly distinguished — with provider-reported tokens, wall/active durations, and usage coverage (a missing value renders "Not reported", never 0). |
| Artifacts | Every artifact linked to the project through the shared evidence projection — diffs, logs, session TRACE parts you are authorized to see, and RUN_SUMMARY documents. Redacted and quarantined rows stay listable as tombstones. |
| Metrics | Success metrics defined in Settings. |
| Risks | The project risk register. |
| Settings | Edit fields, links, milestones; archive (admin). |
Connected sessions (CLI guide) bind to one
confirmed project — the project determines the workspace — and lifecycle status
and captureComplete are independent dimensions, so a normally ended session
with missing evidence shows as completed with capture debt, never as a
workflow failure. A full deployment also surfaces that debt in the Control
Tower's session-capture queue.
Links
In Settings → Linked items an admin can link a project to:
- a board or task (validated against your access — linking a task makes it appear in the project's Work view, and the task's detail panel shows a live Projects badge),
- a repo, doc, decision, metric, or agent (free-form references).
Linking an item you already linked is a no-op, and unlinking something that isn't linked is a no-op. Link a task to a project directly from the task detail panel's Projects section.
A repo link's target is the normalized lowercase owner/name — the
identity connected sessions match against.
When no project in the workspace carries an explicit repo link, the session
repo gate falls back to the workspace default repository: the workspace's
defaultRepo (set via update_workspace), or — when unset — the workspace's
sole linked GitHub repository, inferred at read time. Project Settings shows
the default a session would inherit (and its source) whenever the project has
no repo link of its own; the moment any project links a repo explicitly, links
filter again and the default stops applying.
Milestones, risks, and success metrics
- Milestones (Settings) are named checkpoints with an optional due date and
a status (
planned/in progress/done/missed). - Risks (Risks tab) carry a severity (
low–critical), status (open/mitigating/resolved/accepted), optional owner, and mitigation. High/critical open risks surface as at risk on the workspace home digest. - Success metrics (Settings) are quantitative or qualitative outcome targets shown on the Metrics tab.
Archiving
Projects are never deleted in v1 — archive (Settings, admin only) hides a project from default lists but preserves all activity and links for audit.
Permissions
Workspace roles remain the base permission model — project membership does not narrow workspace roles.
- Create / update / archive a project, and add/remove project links require the workspace admin role.
- Add/update milestones and risks are open to any member.
MCP tools
Projects are exposed over the MCP server: list_projects, get_project,
create_project, update_project, add_project_link, remove_project_link,
and resolve_projects_for_repo. A full deployment adds the Decision Register
tools.
Scopes, arguments, and return shapes are generated from the live registration — see the MCP tool reference, which cannot drift from what the server actually serves. (This page used to carry its own copy of that table; it disagreed with the server on two scopes by the time it was removed.)
Notes worth keeping next to the projects model:
add_project_linknormalizes aREPOtarget to lowercaseowner/name— the identity connected sessions match against. Adding an existing edge is a no-op.remove_project_linkmatches exactly, but a case-variantREPOid still finds the normalized edge. Removing a missing edge is a no-op.