Use task and work-run commands

Coding agents use these commands after a person has initialized the repository and queued work. A person can run them too when the workflow calls for it.

alterac-ai task create "Add concise task details." --title "Improve task creation"

This creates one Backlog task immediately; it does not queue work or create a work run. Add --mass or --weight for the chosen type, --exclude-from-metrics, repeated --label or --dependency, --plan, independent --sprint and --milestone, and --assignee when those details are known. Each Current scheduling assignment needs its own explicit classification; Create and manage tasks with the CLI explains the choice and installed-command checks. Use Task Builder when you want to prepare related work or proposed Plans before publishing.

The authoritative Markdown or JSON response includes the persisted type and ordered compatible states. Omit --type for a Coding agent task or pass --type person for a Person task; the type is fixed after creation.

Use task list to choose the exact published task or inspect current members of a Plan, enabled Sprint, or enabled Milestone before issuing a later direct task command. Filtering is inspection only; update published tasks individually with task update.

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 --json

The default Markdown output orders tasks by their project-scoped number and shows the title, persisted type, current state, ordered compatible states, Mass or Weight, metric exclusion, labels, Plan membership, current Sprint and Milestone independently when enabled, dependency status, assignee, and update time. Add --plan <planNumber>, --sprint <sprintNumber>, or --milestone <milestoneNumber> to inspect current members; combine them to require every selected membership. Each target number must be positive and belong to the selected project. An unavailable target returns an error; an available target with no current tasks returns a successful empty result. Complete records retain historical snapshots rather than current members. Use --project <projectId> to inspect another accessible project without changing this repository's configured selection. --json returns the same authoritative task records when another tool needs structured output.

alterac-ai task get <taskNumber>

This read-only command retrieves a project task's complete authoritative content and metadata, including its persisted type and ordered compatible states, before a direct update or deletion. A taskNumber is a positive number scoped to the selected project; it is not a task ID or the exact work-run GUID. Use --project <projectId> to select another accessible project without changing local configuration, or --json for the same structured response. The command does not retrieve comments or review history.

alterac-ai labels

Use --json for structured output or --project <projectId> to inspect another accessible project without changing repository configuration.

alterac-ai task comment <taskNumber> "Decision text"

Use a task number only for this command. File input is safer for multiline Markdown; see the command reference.

alterac-ai work-run get <taskWorkRunId>

Use the exact work-run GUID from the listener-launched command. After implementation, validation, and delivery are complete, submit both required outputs with alterac-ai work-run complete. The full syntax and completion boundary are in the CLI command reference.

Keep the summary within 8,192 characters and the AI hand-off within 16,384. Limits count Unicode code points, including combining marks separately. If completion reports an oversized field, shorten that text or file and retry with the same work-run GUID. The rejected submission leaves the active run and previously stored output unchanged.

If the organization license expires after a work run starts, work-run get and work-run complete remain available for that exact active run so it can reach review safely. Expiration still blocks creating, queueing, starting, recovering, or following up work. Restore the license before beginning another run; the CLI keeps stored authentication when it reports this problem.

The context records why the run was queued, the task's snapshotted type and ordered compatible states, its metric-exclusion choice at start, and, when applicable, the Plan that grouped the task when the run started. Task type, compatible states, Plan details, labels, and the task exclusion choice remain fixed for the run even if live task or Plan metadata changes later. A fresh-start run includes a prominent instruction to begin from the immutable task snapshot and general comments without continuing earlier review feedback or agent output. JSON exposes the same state through type, compatibleStates, executionOrigin, excludeFromMetrics, and the nullable plan value. Person tasks can be created with task create --type person, but their lifecycle transitions use the application’s Start work, submission, and review actions. These CLI work-run commands are for Coding-agent execution.