Skip to content

task command

Command

Add, select, start, complete, or reopen local work through its owning store.

Invoke it
Claude Code/ca:task
Codex$ca-task
Pi/ca-task

Availability is read from each shipped host catalog. Preview-only commands are marked on the page.

Use it when
You need to add, start, complete or reopen a piece of local work, in a native project or on a legacy board.
Don't use it for
Only reading the board and its counts, which is /ca:status; or archiving finished work, which is /ca:standup.
What it asks you
The action and, for start, done and reopen, the WORK-ID that the listing returned; add takes a description. Select work by its returned WORK-ID, not by a title or a dotted legacy ID.
What it produces
One lifecycle change (add, start, complete or reopen) saved through the work helper in the store the project already uses, native work or the legacy board. New work gets a stable WORK-ID. It records local progress only, and archiving is left to /ca:standup.

Adds, selects, starts, completes or reopens local work through the one store that owns it. The command runs the installed hooks/work.py helper, which selects the project’s current owner, gives new work a stable WORK-ID, and performs a single action through that owner. A project with a legacy board stays on that board until it is explicitly adopted into native work. The command never creates a board beside native work, never writes both owners for one action, and never edits either store by hand.

A start, a completion or a new piece of work is meant to ride the same commit as the work it tracks. A separate chore(board) pull request for an ordinary transition is the anti-pattern, because it can claim progress before the work lands.

/ca:task add <description> | list | start <WORK-ID> | done <WORK-ID> | reopen <WORK-ID>
  • list pages through the listing until the item is found or the listing ends. The selected item is then read by its returned WORK-ID. If nothing matches, or the selection is ambiguous, the command stops and reports it.
  • add creates new work from your description with the type unknown and returns its WORK-ID. Use that ID for every later action. When the work comes from a durable source, the source key is recorded as its origin.
  • start, done and reopen take the returned WORK-ID, never a title or a dotted legacy ID. Queued work that was already performed can be recorded complete directly, with no invented start event. done records local progress only: checks stay unknown until their evidence is assessed, and it is not remote sync or delivery.

Every change carries a stable request ID. A new action gets a new one, and an uncertain retry keeps the original so the change is not applied twice. When the caller already holds the item’s preimage, it is passed with the change: native work checks its revision and model hash, and a legacy board checks its board hash and refuses a stale one, even one that was already applied. Inspect the selected row before acting again. A changed item is never overwritten by minting a fresh request ID.

In a native project that has configured a transition map, starting, completing or reopening work also saves the configured issue and Project intent, or a specific waiting reason, in the same local transaction. That makes no GitHub request. Mapped targets are sent only when you explicitly ask for it, and each target reports separately.

/ca:task has no archive action. /ca:standup owns archival: it proposes completed work for a named subset you choose, and it preserves undated historical rows. Native items are archived through work.py, and legacy rows through taskwrite.py.

A historical legacy row that cannot be selected by a stable WORK-ID, including an originless row that has a dotted ID, is an explicit compatibility or repair path through hooks/taskwrite.py. Inspect the exact row first, then use its dotted ID, or the unique title for a row with no ID. That is not the normal route for ordinary work.

Illustrative exchange, not captured execution:
> /ca:task add "Update the contributor guide"
Created the work through the project's store. Its WORK-ID is <the ID the helper returns>.
> /ca:task start <WORK-ID>
Started. The change was saved through the work helper, under a new request ID.
GateWhenEffect
one owner, no hand editsany add, start, done or reopenthe change goes through the work helper to the single selected owner, never a hand edit and never two owners for one action; a mixed or unsafe store or an ambiguous selection is reported as a stop, not worked around by switching writers

Find this entry in the workflow atlas. Compare its related teaching maps, host spelling and context inputs. The exact procedure below remains the owner.

Source — plugins/ca/commands/task.md (v3.8.9)
---
description: Add, select, start, complete, or reopen local work through its owning store.
argument-hint: "add <description> | list | start <WORK-ID> | done <WORK-ID> | reopen <WORK-ID>"
---
# /ca:task — selected local work
Use the installed `hooks/work.py` facade for ordinary work in both native and
legacy projects. It selects the current owner, gives new work a stable `WORK-ID`,
and performs one semantic action through that owner. Existing boards stay
legacy until an explicit adoption. Do not create a board beside native work or
write both owners. A mixed or unsafe store is a refusal to report, not a reason
to switch writers.
Before invoking the helper, read the installed helper card:
[helper-invocation.md](../includes/helper-invocation.md) relative to this loaded command.
Use this loaded command or skill as the card's resource input and resolve
`hooks/work.py` exactly once. Run it with the card's selected Python interpreter
from the intended project worktree. Keep caller text in literal arguments; do
not interpolate it into shell syntax or search for a source/cache copy.
## Ordinary actions
- **List or select:** `work.py list --limit 32`; continue with
`work.py list --offset <next_offset> --membership-sha256 <returned-sha256>`
until the item is found or the listing is exhausted. Then use
`work.py get <WORK-ID>` for the selected item. Use the returned `work_id`,
not a title or dotted legacy alias. If the complete
listing has no item or selection is ambiguous, stop and report it.
- **Add:** `work.py create --title <description> --intent <description>
--type unknown --operation-id <stable-request-id>`. Pass `--origin <source-key>`
when work comes from a durable source. A distinct action gets a new request
ID; an uncertain retry keeps the original ID. Use the returned `work_id` for
later actions.
- **Start:** `work.py start <WORK-ID> --operation-id <stable-request-id>`.
- **Complete:** `work.py complete <WORK-ID> --operation-id <stable-request-id>`.
Queued work already performed can be recorded complete directly. Do not
invent a start event. This records local progress; checks remain unknown
until their actual evidence is assessed.
- **Reopen:** `work.py reopen <WORK-ID> --operation-id <stable-request-id>`.
For native projects that explicitly configure `work.py transition-map-configure`,
these same start, complete and reopen calls save their configured issue and
single-select Project intent, or a specific waiting reason, in the same local
work transaction. The transition makes no GitHub request. An absent or disabled
map leaves ordinary lifecycle behavior available. Read `work.py get <WORK-ID>`
or `work.py view <WORK-ID>` for separate local progress, check, delivery and
tracker states. `work.py transition-map-get` shows whether the selected native
project opted in; configure once with IDs discovered from the existing provider
and Project tools. Never infer an option ID from its display label.
When explicitly asked to transmit mapped targets, use `work.py sync-mapped
<WORK-ID> [--pull-number N]`. This may send the bound issue state and the one
configured Project field; it reports each target separately. The configured
provider's after-merge timing applies to both mapped targets, even through a
lower-level sync command. Existing manually staged Project effects retain their
explicit sync-now behavior. Disabling the map pauses mapped sends and does not
undo remote changes. Reconcile an uncertain send before trying the latest
desired state. A human may change a Project field between its read and update;
report that race instead of claiming remote compare-and-set.
For a create, bind the caller's description and stable request ID as separate
variables after resolving the installed helper and interpreter from the card.
Pass each value as a literal argument from the intended worktree. A distinct
intent may be bound separately when its wording differs from the title.
### PowerShell create invocation
```powershell
$caCreateArgs = @('create', '--title', $caDescription, '--intent', $caDescription, '--type', 'unknown', '--operation-id', $caRequestId)
& $caPython -B $caHelper @caCreateArgs
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
```
### POSIX create invocation
```sh
"$ca_python" -B "$ca_helper" create --title "$ca_description" --intent "$ca_description" --type unknown --operation-id "$ca_request_id"
```
The facade reads the selected revision for an ordinary update and applies the
owner's exact change check. When a caller already holds the preimage, pass
`--expected-revision` and `--expected-model-sha256` together for native work,
or `--expected-model-sha256` with the returned board hash for legacy work.
Keep the same request ID and preimage after an uncertain result. Native work
returns its journaled result on an exact retry. A legacy update refuses a
stale preimage, including one already applied; inspect the selected row before
acting again. Do not overwrite a changed item by minting a fresh request ID.
For a historical board row that cannot be selected through a stable `WORK-ID`,
including an originless row with an existing dotted ID,
`hooks/taskwrite.py` remains an explicit compatibility or repair path. Inspect
the exact row and use its dotted ID, or the unique title for an ID-less row,
with the documented selector and board lock; do not teach best-effort title
matching as the normal /task route. Direct
board edits remain invalid.
## Related owners
- Harvest promotes selected follow-ups through the current work owner.
- `/ca:standup` owns archival and preserves undated historical rows. Native
items use `work.py`; legacy rows stay with `taskwrite.py` for that selected
archive.
- Work lifecycle changes ride their associated work commit through
`commit-gate` under ADR-0008. A separate `chore(board)` PR for an ordinary
transition is the anti-pattern; it can claim progress before the work lands.
## Hard gate
- Never hand-edit the legacy board or a native work model.
- Never write two work owners for one action or silently adopt a board.
- Preserve the selected identity, real host stop, exact change check, and
original request ID on an uncertain retry.
- Do not equate local completion with passed checks, remote sync, or delivery.

View in repo