task command
Add, select, start, complete, or reopen local work through its owning store.
/ca:task$ca-task/ca-taskAvailability is read from each shipped host catalog. Preview-only commands are marked on the page.
At a glance
Section titled “At a glance”- 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.
What it does
Section titled “What it does”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>listpages through the listing until the item is found or the listing ends. The selected item is then read by its returnedWORK-ID. If nothing matches, or the selection is ambiguous, the command stops and reports it.addcreates new work from your description with the typeunknownand returns itsWORK-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,doneandreopentake the returnedWORK-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.donerecords 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.
Archiving and historical rows
Section titled “Archiving and historical rows”/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.
Example
Section titled “Example”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.| Gate | When | Effect |
|---|---|---|
| one owner, no hand edits | any add, start, done or reopen | the 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 |
Related
Section titled “Related”Route context
Section titled “Route context”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
Section titled “Source”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 andlegacy projects. It selects the current owner, gives new work a stable `WORK-ID`,and performs one semantic action through that owner. Existing boards staylegacy until an explicit adoption. Do not create a board beside native work orwrite both owners. A mixed or unsafe store is a refusal to report, not a reasonto 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 interpreterfrom the intended project worktree. Keep caller text in literal arguments; donot 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 andsingle-select Project intent, or a specific waiting reason, in the same localwork transaction. The transition makes no GitHub request. An absent or disabledmap leaves ordinary lifecycle behavior available. Read `work.py get <WORK-ID>`or `work.py view <WORK-ID>` for separate local progress, check, delivery andtracker states. `work.py transition-map-get` shows whether the selected nativeproject opted in; configure once with IDs discovered from the existing providerand 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 oneconfigured Project field; it reports each target separately. The configuredprovider's after-merge timing applies to both mapped targets, even through alower-level sync command. Existing manually staged Project effects retain theirexplicit sync-now behavior. Disabling the map pauses mapped sends and does notundo remote changes. Reconcile an uncertain send before trying the latestdesired 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 separatevariables after resolving the installed helper and interpreter from the card.Pass each value as a literal argument from the intended worktree. A distinctintent 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 @caCreateArgsif ($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 theowner'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 workreturns its journaled result on an exact retry. A legacy update refuses astale preimage, including one already applied; inspect the selected row beforeacting 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. Inspectthe 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 titlematching as the normal /task route. Directboard 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.