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.

Before using scheduling options, check that your installed CLI help includes them. An unknown option is an executable-version issue; a recognized command's disabled-feature error instead needs the Project Settings recovery below.

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 or Weight, labels, direct dependencies, active Plan membership, an available Sprint or Milestone, 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.

The authoritative Markdown or JSON response identifies the persisted task type and its ordered compatible states. Omit --type for a Coding agent task, or pass --type person for work performed by a person. Both types start in Backlog; the type cannot be changed later.

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 --sprint 7
alterac-ai task list --milestone 12
alterac-ai task list --plan 4 --sprint 7 --milestone 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 persisted task type, current state, ordered compatible states, Mass or Weight, metric exclusion, labels, Plan membership, current Sprint and Milestone, dependency status, assignee, and update time. Add --plan <planNumber>, --sprint <sprintNumber>, or --milestone <milestoneNumber> to inspect current members; combined filters require every selected membership. Each number must be positive and belong to the selected project. An unavailable target is an error; a valid target with no current tasks is a successful empty result. Each scheduling filter requires its own feature to be enabled. Complete records retain historical snapshots and do not have current members. 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. The response includes the persisted task type and ordered compatible states. Enabled features expose current Sprint and Milestone identity and lifecycle; Sprint detail also includes planned dates and opening or closing facts. A disabled feature hides its scheduling details independently. Markdown lifecycle labels are Planned, Current, and Complete; JSON preserves the API states Planned, Started, and Complete. 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

# Sprint: replace one current membership, or clear it.
alterac-ai task update 168 --sprint 7
alterac-ai task update 168 --clear-sprint --sprint-change scope-change

# Milestone: replace one current membership, or clear it.
alterac-ai task update 168 --milestone 12
alterac-ai task update 168 --clear-milestone --milestone-change scope-change

# 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, including its persisted type and ordered compatible states, and reports exact recovery state if coordinated metadata writes partially fail.

Task state and type are lifecycle data, not generic metadata. task update preserves both, along with comments, reviews, work runs, completion facts, and Task Builder provenance. Person lifecycle transitions are available in the application; the CLI has no Person start, submission, or review-resolution commands. 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.

Use a positive project-scoped Sprint number with task create --sprint or task update --sprint. An assignment replaces only current Sprint membership; Plan and other metadata remain independent. Omit both --sprint and --clear-sprint on update to preserve membership. A Planned Sprint needs no classification. A Complete Sprint cannot receive a current member, and closing a Sprint clears its current membership rather than carrying tasks into another Sprint.

For a membership change involving a Current Sprint, or an actual Mass or Weight change affecting Current planning history, add --sprint-change correction or --sprint-change scope-change. Choose one classification for the whole Sprint change, including a move out of a Current Sprint and a simultaneous estimate edit. Correction repairs the opening membership and Size plan and requires Team Lead authority, including inherited organization owner or admin authority. It may include a task created later while preserving its real creation, state, and completion times. Scope change records a later scope decision and is available to project members. Setting a missing estimate or clearing an estimate also counts as a change. The option alone does not change a task.

alterac-ai task create "Add task details." --title "Improve search" --sprint 7 --sprint-change scope-change
alterac-ai task update 168 --sprint 8 --mass 5 --sprint-change scope-change
alterac-ai task update 169 --weight 3 --sprint-change correction

If the same edit also affects Current Milestone history, supply --milestone-change correction or --milestone-change scope-change independently. The same edit can be a Correction for one history and a Scope change for the other. Each affected history must have an explicit permitted choice, and all affected histories save together. For example, a Team Lead can run alterac-ai task update 168 --mass 5 --sprint-change correction --milestone-change scope-change when both histories are affected and Milestones are enabled. A disabled Milestone blocks its classification and the whole edit; re-enable Milestones first.

The examples that supply a classification assume the change affects a Current Sprint. Sprint membership, content, dependencies, and all affected estimate histories are validated and saved together. An invalid target, classification, permission, or concurrent change rejects that operation before it can leave partial Sprint history. Separately stored Plan, labels, assignee, or metric choices may still need the recovery described in the command reference.

When Sprints are disabled, assigning, replacing, clearing, and filtering Sprint membership are unavailable; ask a Team Lead to re-enable Sprints in Project Settings. Ordinary task edits remain available. If an estimate edit affects retained Current planning history, it still requires --sprint-change with the same permissions. The command explains the required planning-history choice without exposing the disabled Sprint's details. There are no CLI commands for creating, opening, closing, or repairing historical Sprint records.

Use task create --milestone <milestoneNumber> to assign a new task or task update <taskNumber> --milestone <milestoneNumber> to replace its current Milestone. Use --clear-milestone to clear membership, and omit both options to preserve it. Each positive number belongs to the selected project. Milestone membership is independent of Sprint and Plan membership, and works when Sprints are disabled.

A Planned Milestone needs no classification. Assignment, removal, or a Mass or Weight change affecting a Current Milestone (Started in JSON) requires --milestone-change correction or --milestone-change scope-change. One choice covers the whole Milestone change, including affected source and destination histories and a simultaneous estimate edit. Scope change records later scope and is available to project members. Correction repairs the opening plan and requires Team Lead authority, including for a newly created task. Its actual creation, state, and completion dates remain unchanged. Scope change instead adds work from the time of the change. The classification option alone does not mutate a task.

alterac-ai task create "Add task details." --title "Improve search" --milestone 12
alterac-ai task create "Add task details." --title "Beta follow-up" --milestone 13 --milestone-change scope-change
alterac-ai task update 168 --milestone 13 --mass 5 --milestone-change scope-change
alterac-ai task update 168 --clear-milestone --milestone-change scope-change

The first example assumes a Planned target; classified examples assume a Started target or source. Requested targets, lifecycle, permissions, classifications, and history evidence are checked before task creation and again at the atomic write. Task content, dependencies, membership, and all affected Sprint/Milestone histories save together. An invalid target, insufficient authority, unsupported Correction, or concurrent change leaves that operation unchanged; separately stored metadata uses the recovery described in the command reference.

A Complete Milestone cannot receive live tasks. Completion clears its current membership and retains the final snapshot; later live estimate changes do not rewrite that snapshot. Historical repairs use the explicit history-correction workflow, rather than task update --milestone or ordinary estimate edits.

When Milestones are disabled, assignment, replacement, clearing, filtering, and --milestone-change are rejected with Project Settings guidance. Records and history remain intact. An estimate edit affecting retained Started Milestone history also waits for re-enablement and an explicit classification; the task and all affected histories remain unchanged. Ask a Team Lead to re-enable Milestones before retrying. Other task edits and enabled Sprint workflows remain available.

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, including its type and ordered compatible states, 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.

Retrospective Correction during direct CLI task creation requires a CLI build containing this change. An older installed CLI may reject that choice before contacting the API. Updating only the API/frontend does not update your local CLI. Until a compatible CLI is installed, create the task without that Current target and use the browser to add it as a Correction. Task Builder saved Milestone intent is validated by the deployed API at publication.