Task and work-run commands

These commands are primarily for coding agents working in a configured repository. They use a task number for a project task and an internal work-run ID for one exact execution.

alterac-ai task create "Add concise task details." --title "Improve task creation" --mass 3 --label backend

Use task create when one implementation-ready task is already clear. It creates the task immediately in Backlog, with optional Mass, labels, direct dependencies, active Plan membership, and an eligible assignee. It does not queue work or create a work run. Use a Markdown file with --file when the task details are multiline.

Pass --exclude-from-metrics to keep the new task visible while excluding it from task-derived reports; omission records it as included. The choice does not change lifecycle or history and current metric results apply it retroactively.

Use Task Builder for related work, many one-off tasks prepared together, or proposed Plans; Plan work with Task Builder explains that review-before-publication path. The CLI command reference has exact syntax, metadata rules, and recovery guidance.

alterac-ai task list
alterac-ai task list --plan 12
alterac-ai task list --json

Use task list to inspect published tasks before issuing a direct task command. It lists the configured project's tasks in task-number order, including task state, Mass, metric exclusion, labels, Plan membership, dependency status, assignee, and update time. Add --plan <planNumber> to inspect the current members of one available Plan. The Plan number must be positive and belongs to the selected project. An unavailable Plan is an error; a valid Plan with no tasks is a successful empty result. Add --project <projectId> to inspect another accessible project without changing this repository's configured selection.

alterac-ai task get <TASK-NUMBER>

Use a positive project-scoped task number to read the task's complete content, metadata, relationships, completion facts, and active-work-run context before directly changing or deleting it. It is read-only and does not retrieve comments or review history. The task number is not the task's stable ID or a work-run ID. Add --json for the equivalent structured response or --project <projectId> to target another accessible project.

alterac-ai task delete <TASK-NUMBER>
alterac-ai task delete <TASK-NUMBER> --yes

The interactive form retrieves the authoritative task, displays its exact number and title, and asks you to confirm. The default is No. Declining or providing no answer leaves the task unchanged and reports the no-op.

Deletion is immediate and cannot be restored. Use --yes only when an asynchronous coding agent or another non-interactive process has deliberately resolved the exact target and must affirm deletion without a prompt. The option does not bypass authorization or server deletion rules, and the command reports success only after the API confirms the task is gone.

This command removes a published project task. To remove an unpublished Task Builder draft before publication, ask your local AI tool to update the Building session instead.

Omitted fields preserve current values, replacement options replace a complete field, and explicit clear options remove that field. At least one change is required.

# Replace required content; title and Markdown cannot be cleared.
alterac-ai task update 168 --title "Add the task update CLI command"
alterac-ai task update 168 --file task-168.md

# Mass: omit to preserve, replace with a value, or clear.
alterac-ai task update 168 --mass 5
alterac-ai task update 168 --clear-mass

# Metric eligibility: omit to preserve, or choose exactly one value.
alterac-ai task update 168 --exclude-from-metrics
alterac-ai task update 168 --include-in-metrics

# Labels: repeated values replace the complete set, or clear the set.
alterac-ai task update 168 --label cli --label priority::medium
alterac-ai task update 168 --clear-labels

# Dependencies: repeated task numbers replace the complete set, or clear the set.
alterac-ai task update 168 --dependency 164 --dependency 167
alterac-ai task update 168 --clear-dependencies

# Plan: replace with one active project Plan number, or clear to Unplanned.
alterac-ai task update 168 --plan 1
alterac-ai task update 168 --clear-plan

# Assignee: replace with one exact eligible member, or clear to Unassigned.
alterac-ai task update 168 --assignee [email protected]
alterac-ai task update 168 --clear-assignee

You may combine independent fields in one invocation. Do not combine a field's replacement and clear options. The command validates every requested reference before writing, returns the complete authoritative task as Markdown or JSON, and reports exact recovery state if coordinated metadata writes partially fail.

Task state is lifecycle data, not generic metadata. task update preserves state, comments, reviews, work runs, completion facts, and Task Builder provenance. Use queue, review, comment, and work-run actions for their owned changes.

Metric eligibility updates use the task version retrieved by the command, so a concurrent stale change is rejected instead of overwriting newer task data. The dashboard exposes the same choice under Edit task. Excluding or including a task refreshes affected reports without changing its state, completion, history, assignment, or visibility.

alterac-ai work-run get <TASK-WORK-RUN-ID>

Use the exact internal identifier provided when the local listener launches the coding agent. The command returns the immutable task snapshot, general comments, and prior review context for that execution.

alterac-ai task comment 12 "Implemented the requested task details."

Coding agents are the default authors of CLI task comments because they record material direction they receive during a work run. A person can also submit a comment with --author person. The command does not change task state. When a person's direction materially changes the original task's scope, acceptance criteria, architecture, expected behavior, risk, or required validation, record what changed and its effect on the work.

alterac-ai work-run complete <TASK-WORK-RUN-ID> --summary "Implemented the task." --hand-off "Completed the requested update. The next agent can begin from the committed branch if follow-up work is requested."

Completion sends the result for that exact work run and moves the task from Agent working to Reviewing. The hand-off describes the completed work and where the agent stopped so a future coding agent can continue if follow-up work is requested. A coding agent includes a review URL only when its normal delivery command returned that exact URL.

See Understand the task workflow for the human-facing lifecycle.