Task keys

A task in Clocktopus is a key such as CLK-12. Clocktopus reads keys from branch names (dana/clk-12-export-invoices), commit scopes (feat(clk-12): …) and pull requests, and books the time, agent spend and delivery behind them to that task (how). Two settings on the project form decide which keys are the project's tasks: its own task key prefix, and the tracker key prefixes of the tickets its work is tracked in.

Task key prefix

The prefix of the tasks created in Clocktopus itself, by an agent's create_task through the MCP server: CLK numbers them CLK-1, CLK-2. Every project has one from the day it is created: taken from its name (Acme Portal → AP, Clocktopus → CLO) unless an admin types one on the project form, and never one another project or a connected tracker's keys already use.

• Changing it leaves existing keys as they are. Their old prefix stays the project's, and no other project can take it.
• A commit, branch or time entry naming a key with it creates the task when it doesn't exist yet, so work started before anyone created the task still counts towards it. The next task created in Clocktopus is numbered past it. A key with an earlier prefix only finds a task that already exists.
• A connected tracker never takes it over. When a connected tracker starts sending tickets with a project's prefix, the project moves on its own to the next free numbered one (CLK → CLK2), and its existing tasks keep their keys.

Tracker key prefixes

A tracker is the issue tracker your team plans its work in: Linear, Jira, or any other whose tickets have keys like BLA-12. A tracker is connected when its webhook sends Clocktopus each ticket's title, description, kind and dates; it doesn't have to be.

A project's tracker key prefixes are the prefixes of the tickets its work is tracked in (BLA for BLA-12), whether or not that tracker is connected. They are what make those tickets this project's tasks:

• A commit, branch or time entry naming one creates the task in the project, if it doesn't exist yet. A key with any other prefix (not the project's own, not declared, not used by a connected tracker's tickets) names no task; the time is still tracked.
• A connected tracker's ticket with one lands in the project. Without one, the ticket waits with no project until work in a project names it.
• Declaring one moves the organisation's tasks under it that have no project into the project.
• Agents decide from them where to create the project's tasks, and can register a ticket from a tracker that isn't connected (how).

No prefix, a project's own or a declared one, is used twice in an organisation, and one a project's existing tasks carry from an earlier prefix can't be declared. An archived project keeps its own prefixes, though a key with one then only finds a task it already has. It doesn't keep the ones it declares: its tracker's new tickets go to no project, and another project can declare them, which takes them off the archived project. Its existing tickets stay with it, and restoring it brings back whichever prefixes nobody took.

An admin sets them on the project form, which also suggests the prefixes the project's commits use that are free to declare, each with one-click Add. clocktopus init declares the ones at least two of the checkout's commits and branches use (CLI).

Delivery branches

The project form sets these beside the tracker key prefixes: a task is delivered once its work reaches one of them. They are described with the stages they decide, in delivery metrics.