Create and edit a task

Create a task with enough context for a person or 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. Choose Task type: Coding agent (the default) or Person. The type cannot be changed after creation.
3. 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.
4. In the metadata panel, choose one active Plan or Unplanned, choose an optional Sprint and Milestone when enabled, then set Mass for Coding agent work or Weight for Person work, labels, and dependencies where known.
5. Select Create task. The task is created in Backlog without starting work.

If you already have the complete details in a configured repository, alterac-ai task create "Task details" --title "Short title" creates an immediate Coding agent Backlog task. Add --type person to create a Person task. Add Mass (Coding agent) or Weight (Person, with --type person), labels, dependencies, an active Plan, an available Sprint or Milestone, 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 on a Coding agent task, or Weight with --weight on a Person task, the complete label or dependency sets with repeated --label or --dependency, Plan membership with --plan, current Sprint membership with --sprint, current Milestone membership with --milestone, and assignment with --assignee. Clear those metadata fields with --clear-mass or --clear-weight, --clear-labels, --clear-dependencies, --clear-plan, --clear-sprint, --clear-milestone, or --clear-assignee. See Update a task for complete syntax and examples.

Sprint and Milestone CLI membership are independent of each other and Plan membership. Planned assignment needs no classification; membership or actual estimate changes affecting Current planning history require an explicit Correction or Scope change, with Team Lead authority for Correction. The Sprint estimate-history requirement remains when Sprints are disabled, while Sprint assignment, clearing, and filtering are unavailable. Disabled Milestones reject CLI membership, filtering, and Milestone classification; a CLI estimate edit affecting retained Started Milestone history waits for re-enablement. See Assign a Sprint and classify later changes for commands and recovery. See Assign a Milestone and classify later changes for independent Milestone choices, evidence requirements, and retained Complete history. Browser task forms support independent Sprint and Milestone membership as described below.

Use the metadata panel to set or update Plan membership, Mass or Weight, labels, and dependencies. Coding-agent tasks use Mass; Person tasks use Weight. 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.

When Milestones are enabled in Project Settings, choose one existing Planned or Current Milestone, or No Milestone. A task can belong to at most one current Milestone. Changing it leaves Plan and Sprint membership unchanged and does not start or complete work. Complete Milestones are historical records and cannot receive new current members. The browser label Current corresponds to the API/JSON state Started.

Adding, removing, or moving membership affecting a Current Milestone opens a change-intent dialog. Choose Scope change to change scope from now. Choose Correction to repair the opening membership and Size plan; this requires a Team Lead or organization owner/admin. A Correction may include a task created after Start while keeping its real creation, state, and completion times. Before the task existed, its completed contribution is zero; genuinely unknown earlier task states remain unavailable. Choose Apply intent, then save the task. Moving between Current Milestones asks for the source and destination intent separately. Changing Mass or Weight asks for intent when you save; choose Continue saving to complete the save. An estimate edit that also affects a Current Sprint asks for its own intent. Cancel or Escape leaves your form values in place without applying the dialog choices; saving asks again for any missing intent. These changes save together; a stale version or unauthorized intent leaves the task unchanged. Refresh to load the latest records before retrying.

Task metadata shows the current Milestone, or No Milestone. Select View Milestone change history beside the Milestone heading on task details or the edit page to inspect its changes and retained participation. After a Milestone completes, current membership clears and unfinished tasks return to Backlog; its history keeps the captured outcome at completion. Later edits to the live task do not replace that outcome. Disabling Milestones hides its selector, detail metadata, and filter while retaining membership and history. Saving estimate edits affecting retained Current history still opens a neutral Planning history change dialog.

Managers can also manage one task at a time on the Milestone page, inspect retained outcomes, and correct captured estimates through Milestone history. Guarded reopening restores the latest completion's original membership only when its evidence remains safe; tasks keep their current states and further work still needs the normal queue or start action.

Team Leads can also manage one task at a time from the Sprint page, including moves from another Planned Sprint and authorized Corrections to retained Complete history.

When Sprints are enabled in Project Settings, choose No Sprint or one same-project Planned or Current Sprint in the metadata panel. A Planned Sprint can hold future work before it opens; see the current Sprint lifecycle actions. Complete Sprints are historical and cannot receive new current members. Sprint membership is independent of the task's Plan and Milestone; changing it does not queue, start, assign, or complete the task.

Moving out of or into a Current Sprint, or changing the Mass or Weight of its current task, requires a change intent for each affected Current Sprint. The Classify Sprint changes dialog opens when a membership change needs intent, or when you save an estimate change. Choose Scope change to apply the membership or estimate change from now. A Team Lead, organization owner, or organization admin can choose Correction to repair the opening membership and Size plan, including a task created after Start. Its real creation, state, and completion times stay unchanged. Before the task existed, its completed contribution is zero; genuinely unknown earlier task states remain unavailable instead of being guessed. You must choose explicitly; saving cannot infer intent. A move and estimate edit are saved together, and a stale Sprint version rejects the save with guidance to reload the page before retrying.

Task metadata shows only the current Sprint, or No Sprint. Select View Sprint change history beside the Sprint heading on task details or the edit page to inspect changes and previous participation. Historical links remain available after unfinished work returns to Backlog at Sprint completion. Opening a historical record does not reattach the task or change its lifecycle; you can choose a Planned or Current Sprint for its next work.

Disabling Sprints hides their selector, task links, list metadata, and filters while retaining membership and history. An estimate change that affects retained Current planning history still opens a neutral Planning history change dialog when you save. Ordinary members can choose Scope change; Corrections require Team Lead authority. Re-enabling restores the same Sprint membership and history. This task-metadata workflow is available in the browser; the CLI reference lists the scheduling options currently supported by the CLI.

The Sprint change history and Milestone change history dialogs use the same controls. Open one from View Sprint change history or View Milestone change history beside its task-metadata heading. Each dialog shows only that task's participation and changes. If it has participated in several records, use Sprint history or Milestone history to search by number or title and select the record to inspect.

Changes appear newest recorded first in pages of ten. Each collapsed row shows a short description and when it was recorded, down to seconds. Use Search Sprint changes or Search Milestone changes to find changes or dates, and Change kind to narrow the list. Expand a row for before/after membership and Size, who made the change, and revision details. Effective time means when the change applies to the history; recorded time means when it was saved. Times use the current organization time zone, even for an older record. Changing the zone changes the displayed clock time without rewriting the saved moment.

Milestone changes also show captured task states and the task work-run source when available. For a Complete Milestone, history shows the task's saved final outcome, or explains that it left before completion. Later live-task changes do not replace those facts.

Use the page arrows, or enter a Page number and press Enter to jump directly to older changes. Clear filters restores the full list after an empty search. The record selector, search, filter, page controls, and Close stay visible while the change list scrolls. Choose Close or press Escape to return focus to the history action. If history cannot load, use Retry; a failed read does not mean there are no changes.

Set Mass (for Coding-agent tasks) 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 it empty when the expected review effort is unknown.

Set Weight (for Person tasks) to communicate how difficult the work is to complete, not how long it takes. For example, a straightforward investigation might take an hour but be straightforward, while a complex refactor might take a week with multiple technical decisions.

Both fields use the stored task size value, which the Tasks list shows in its Mass/Weight column. The CLI calls this field Mass on Coding agent tasks, using --mass or --clear-mass, and Weight on Person tasks, using --weight or --clear-weight.

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 for a coding agent or started by a person, 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. Task type is read-only. The State menu offers every Person state (Backlog, In progress, Reviewing, and Done) whatever the task’s current state. Choosing In progress, Reviewing, or Done opens the matching Start work, submit, return, or completion confirmation. From Backlog, choosing Reviewing starts the work and submits it for review in one step, so it asks for the latest changes; choosing Done starts and completes the work without review. From Done, choosing In progress or Reviewing reopens the work for the current assignee; reopening for review asks for the latest changes. Choosing Backlog ends incomplete Person work without submitting or completing it; its history remains available. Your metadata saves first, then the matching confirmation collects the required lifecycle evidence. 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.

To stop pursuing a task while preserving its history, use the warning-colored Close button beside Delete on the edit page. Person tasks also support Close; closing active Person work keeps unfinished history without submitting or completing it. Confirming Close saves your other edits immediately and returns to task details. Close is not available on the read-only task or review page. To reopen a Closed task, use Reopen on its edit page or review history; task details do not offer Reopen. On the edit page, confirming Reopen saves your other edits immediately and returns to task details, the same as Close. See Close or reopen superseded work.

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 a Coding agent task or start work on a Person task when it is ready.