Task Workflow

Task workflow

WORK/TASKS.json is the canonical task ledger. Agent 0 maintains it through the CLI, which regenerates the Markdown work views after each successful change.

Statuses

Status	View	Meaning
todo	TODO.md	Accepted work waiting to start
in_progress	WORKING-ON.md	Work has started and has a concrete next action
blocked	BLOCKED.md	An explicit dependency or decision prevents progress
needs_review	REVIEW.md	Results are ready for acceptance review
done	DONE.md	Evidence has been recorded and reviewed
cancelled	CANCELLED.md	Work was intentionally stopped, with a retained reason

Create and start work

The examples below assume an adopted project with a fresh task ledger. Use the actual ID returned by task-add when work already exists.

bash .SYSTEMX/SYSTEMX.sh task-add \
  --title 'Verify the selected behavior' \
  --owner agent.0 \
  --acceptance 'The affected behavior has reproducible verification evidence' \
  --scope 'tests/' \
  --next 'Inspect the existing regression test'

bash .SYSTEMX/SYSTEMX.sh task-set TASK-001 \
  --status in_progress \
  --next 'Run the focused regression check'

Each task has a stable ID, owner, acceptance criteria, dependency list, timestamps, and transition history. Add --milestone M-001 after declaring the milestone in the master plan. Repeat --scope, --acceptance, or --depends-on for multiple entries. Owners must exist in the agent registry.

Submit evidence and accept completion

Run the relevant checks using the project's real tools, then record their actual command, revision, environment, result, and report location:

bash .SYSTEMX/SYSTEMX.sh task-set TASK-001 \
  --status needs_review \
  --evidence 'Replace with the actual command, revision, result, and report path'

The evidence string above is a placeholder, not proof. After reviewing real evidence against the task's acceptance criteria, Agent 0 or the project owner records acceptance:

bash .SYSTEMX/SYSTEMX.sh task-set TASK-001 \
  --status done \
  --reviewer agent.0

The CLI requires needs_review, nonempty evidence, and reviewer agent.0 or user before completion. It validates those fields; it does not authenticate the reviewer or independently rerun the cited checks. Failed review returns the task to in_progress or records an actual blocker.

Dependencies and blockers

Add a dependent task with --depends-on TASK-001. Every dependency must exist and be done before dependent work enters in_progress, needs_review, or done. Cycles are rejected.

To record a blocker on an open task:

bash .SYSTEMX/SYSTEMX.sh task-set TASK-002 \
  --status blocked \
  --blocker 'Waiting for the approved fixture from its owner' \
  --next 'Ask the owner for the fixture reference'

Use a blocker for a real condition preventing progress. A difficult task alone does not require a blocked state.

Allowed transitions

From	Allowed next states
todo	in_progress, blocked, cancelled
in_progress	todo, blocked, needs_review, cancelled
blocked	todo, in_progress, cancelled
needs_review	in_progress, blocked, done, cancelled
done	todo
cancelled	todo

Open tasks can also receive notes or field updates without changing state. Cancellation needs --note with a reason. Terminal tasks must reopen to todo before editing. Reopening clears the current evidence/reviewer fields while retaining the previous completion evidence in history. Reopen dependent work first if it would otherwise rely on an unfinished prerequisite.

Inspect and recover

bash .SYSTEMX/SYSTEMX.sh status
bash .SYSTEMX/SYSTEMX.sh task-show TASK-001

status summarizes recorded work; task-show includes the full history. Neither command reports live process state.

After a reviewed manual ledger edit or resolved Git merge:

bash .SYSTEMX/SYSTEMX.sh refresh-work
bash .SYSTEMX/SYSTEMX.sh validate

Preserve coherent transition history when editing records manually. Do not edit the six generated status views or CURRENT.md independently. See Operations and troubleshooting for lock recovery.

Task state, event history, and review are different records

When enabled, Agent X records meaningful occurrences and due items, Agent Y tracks one task's external CLI/GitHub handoff, and Agent Z assesses the fixed policy at a completion boundary or on request. Their records support the canonical task ledger; they do not change statuses automatically. An Agent Y job or draft PR does not make a task done or authorize merge. Agent 0/user still reviews before done. Use Daily workflow for a task and the one-shot guide for phased projects.

Mirror external task lists without duplicating authority

The optional ROOT task delta maps actual IDE/harness items and cloud/bot items to existing tasks. The mapping is many-to-many and preserves observed raw/normalized state, source revision, time, and evidence. A provider's completed label is execution evidence for review; it cannot accept a canonical task. Unmapped, stale, unknown, or unavailable observations remain explicit. Read back the external surface before recording a fresh observation; ROOT supplies local records and a read-only delta, rather than a continuous connector or automatic status writer.