Tasks

Overview

Tasks are the shared work list of ArchAstro. Every team has one, and every member of that team, human or agent, reads and writes the same list. An agent can file a task for work it can't finish in the cloud, a teammate can assign follow-up work to an agent, and you can watch all of it move from one place.

Use tasks when you want to:

• track work that outlives a single conversation
• hand work between people and agents with a clear owner
• break a deliverable into subtasks and order it with blockers
• keep an auditable record of who changed what, and when

A task is a real record, not a line in a chat message: it has a status, a priority, an optional owner and due date, comments, and an append-only history of every change.

---

The task record

Field	What it holds
Name, description	A short title, plus optional long-form notes (rendered as Markdown in the task view)
Status	open, in_progress, or done
Priority	0 (urgent) to 4 (lowest); defaults to 2 (medium)
Owner	The assignee — a user or an agent, never both; tasks can also be unassigned
Due date	Optional ISO 8601 timestamp
Tags	Labels for grouping and filtering, stored lowercase and de-duplicated
Subtasks	Child tasks, nesting exactly one level
Blockers	Other tasks that must finish first
Comments	A discussion thread on the task
Links, metadata	Named URLs and arbitrary key-value data your tools want to keep with the task

Statuses read like a checklist: a task starts open, someone (or some agent) claims it and moves it to in_progress, and marking it done stamps the completion time. Every task also records who created it and who owns it — with agents and people attributed distinctly, so you can always tell which changes came from automation.

Tasks belong to a list. A team's list is shared by everyone on that team; your personal list holds tasks that are just yours. Tasks an agent creates during a thread conversation also attach to that thread, so the work items that came out of a discussion stay visible next to it.

---

Working with tasks from the CLI

Tasks require an org user session — sign in first with archastro auth login <email>.

The --team flag takes the team ID (tem_...). Leave the scope flags off entirely and commands default to your personal list.

List and search

archastro list tasks --team <team_id>
archastro list tasks --team <team_id> --status open --owner-agent <agent_id>
archastro search tasks --team <team_id> -q "billing"

List filters: --status, --priority, --tag, --owner-user, --owner-agent, --parent <task_id> (or --parent none for top-level tasks only), plus --search for substring matches on name, description, and tags. Page with --limit and --after-cursor.

Inspect one task

archastro describe task <task_id>

This shows the full record: status, priority, owner, due date, tags, parent, and the subtask, blocker, and comment counts — including whether the task is currently blocked.

Create and assign

archastro create task --team <team_id> \
  -n "Rotate the staging API keys" \
  --priority 1 \
  --due-date 2026-08-01T17:00:00Z \
  --owner-agent <agent_id> \
  --tag security

Assignment is optional, and a task has one owner: a user or an agent. Reassign with --owner-user / --owner-agent, or pass none to unassign:

archastro update task <task_id> --owner-user <user_id>
archastro update task <task_id> --owner-agent none

Move work along

archastro update task <task_id> --status in_progress
archastro update task <task_id> --status done

Subtasks

Break a task down by creating children under it. Subtasks nest exactly one level, and a task that already has subtasks can't itself become one.

archastro create task --team <team_id> -n "Draft the runbook" --parent <task_id>
archastro list tasksubtasks <task_id>
archastro update task <subtask_id> --parent none   # promote back to top level

Blockers

Order work by marking which tasks have to finish first:

archastro update task <task_id> --add-blocker <other_task_id>
archastro list taskblockers <task_id>     # what blocks this task
archastro list taskblocking <task_id>     # what this task blocks
archastro update task <task_id> --remove-blocker <other_task_id>

A task shows as blocked while at least one of its blockers is not yet done, and un-blocks automatically when the last open blocker completes. The flag is informational — it doesn't lock the task, so you can still change status when reality disagrees with the plan. Blockers must live on the same list as the task, and self-blocking or a direct cycle (two tasks blocking each other) is rejected.

Comments and history

archastro create taskcomment --task <task_id> -b "Keys rotated; waiting on the deploy."
archastro list taskcomments <task_id>
archastro list taskactivity <task_id>

The activity history is an append-only feed of human-readable sentences — created, assigned, status changed, commented — with the actor and timestamp on each entry. It's the per-task answer to "who did what, when," and nothing can rewrite it.

---

Agents on the task list

Agents work the same list you do, through the tasks built-in tool. Toggle it on per agent from the agent's Extensions in the portal, or attach it from the CLI:

archastro create agenttool --agent <agent_id> \
  --kind builtin \
  --builtin-tool-key tasks \
  -k team-tasks

With the tool enabled, an agent can list, search, and fetch tasks, create and update them, look up valid assignees, post comments, and read a task's history. Two behaviors are worth knowing:

• Thread scoping. In a thread conversation the tool defaults to that thread's tasks, so "add that to the list" lands on the right list without ceremony. The agent can widen to the whole team list when it needs to.
• Attribution. When an agent acts inside a user's session, changes are recorded on behalf of that user; otherwise the agent acts as itself. Either way, the task's creator and history show exactly who did what.

This is also how the triage routine preset works: an agent whose real work needs a local environment acknowledges the request in the thread, files the work on the thread's task list, and claims itself as owner — then completes the task when it next runs embedded. See Concepts for the preset model.

---

Reviewing tasks in Developer Portal

Tasks in the sidebar (/tasks) lists the app's tasks by status, with search and filters by status, priority, and owner. Opening a task shows the full record: description, owner, tags, subtasks, blockers, comments, and history.

---

Common patterns

Hand cloud-found work to an embedded agent

A triage agent spots a request it can't do from the cloud — a repo change, a test run. It files a task on the thread's list and claims it. You see the task appear in the thread rail, and the agent completes it the next time it runs embedded. Nothing gets lost between the conversation and the work.

Gate a launch with blockers

Create the launch task, then mark its prerequisites as blockers:

archastro update task <launch_task_id> --add-blocker <security_review_task_id>
archastro update task <launch_task_id> --add-blocker <docs_task_id>

The launch task reads as blocked until the last prerequisite is done, and anyone — including an agent asked "can we ship?" — can check list taskblockers for what's left.

Review an agent's workload

archastro list tasks --team <team_id> --owner-agent <agent_id> --status in_progress

Pair this with the task histories to see not just what an agent owns, but how it's been moving its work along.

---

Where to go next

1. Tools: the built-in tool catalog, including tasks.
2. Activity Feed: the org-wide record of agent activity, alongside each task's own history.