Create and edit a task

Create a task with enough context for a coding agent to complete useful work and for a reviewer to make a good decision, then keep its metadata current as the work changes. Create one task immediately from the task list or with alterac-ai task create. Use Task Builder when multiple or related tasks need to be developed and reviewed before publication.

1. Open your project's task list and select Create task.
2. Enter a short, specific Task title and write Task details in Markdown. State the intended outcome, relevant paths or context, acceptance checks, and explicit exclusions. Clear task details help an AI agent complete the intended work without filling in important gaps.
3. In the metadata panel, choose one active Plan or Unplanned, then set Mass, labels, and dependencies where known. Completing this information when you create the task makes it easier to find, claim, and queue later.
4. Select Create task. The task is created in Backlog.

If you already have the complete details in a configured repository, alterac-ai task create "Task details" --title "Short title" creates the same immediate Backlog task. Add Mass, labels, dependencies, an active Plan, or an eligible assignee with the command options described in the CLI reference. It does not queue work.

Task details identify the person who created the task. When that person needed alterac.ai platform-support access to create it, the creator metadata also shows Created by a support admin. Tasks created through ordinary project access do not show that note.

For an existing published task, alterac-ai task update <taskNumber> --title "Replacement title" changes only the title and preserves omitted content and metadata. Replace Markdown inline or with --file. Replace Mass with --mass, the complete label or dependency sets with repeated --label or --dependency, Plan membership with --plan, and assignment with --assignee. Clear those metadata fields with --clear-mass, --clear-labels, --clear-dependencies, --clear-plan, or --clear-assignee. See Update a task for complete syntax and examples.

Use the metadata panel to set or update Plan membership, Mass, labels, and dependencies. On an existing task, use Edit to select a project member as the assignee, reassign a task, or unassign it. When you are an eligible project member viewing an unassigned task, select the highlighted Assign to me link beside Unassigned to claim it without editing the task. Only effective members of the project can be assigned.

A task belongs to at most one Plan. Choose an active Plan to group the task, or choose Unplanned to remove membership. Archived Plans do not appear as new choices, but a task that already belongs to one keeps its numbered Plan link and shows the archived membership while you edit. You can leave that membership unchanged, move the task to an active Plan, or choose Unplanned. Moving a task changes only its Plan membership.

Set Mass to communicate how difficult the completed work will be to review, not how long implementation may take. For example, a focused documentation update may be quick to read and verify, while a feature might require checking out a branch, setting up services, running frontend and backend checks, and completing manual verification. Leave Mass empty when the expected review effort is unknown.

Labels are available from the project and any inherited organization labels. A task can have one label from a scoped label group, so selecting another label in that group replaces the prior one. Use the project label-management surface to create or change the available labels.

Dependencies identify tasks that should be completed first. A dependent task can still be queued, but the application asks you to acknowledge incomplete direct dependencies. See Organize tasks for how dependencies affect task lists.

Open a task and select Edit, change the content or metadata, then select Save changes. If your edit changes a Backlog task to Queued, choose a coding agent in the queue dialog before the state changes.

The generic CLI update command does not change workflow state. It preserves task comments, reviews, work runs, completion facts, and Task Builder provenance. Queue work and handle review or execution completion through their purpose-built workflows.

Use Delete only for a published task that should no longer exist. You can also run alterac-ai task delete <taskNumber> and confirm the exact number and title, or use the explicit --yes option for a deliberate asynchronous-agent invocation. Deletion happens immediately, follows the server's current relationship and history rules, and cannot be restored. Removing a Task Builder draft through your local AI tool changes an unpublished Building session rather than deleting published project work.

Next, queue the task when it is ready for coding-agent work.