How it works
Task lifecycle
How a task moves from draft to done, what each state means, and what marks it complete.
Every Piyaz task moves through a fixed set of states. The state tells you what is true about a task right now and what is allowed to happen next.
States
| Status | Meaning |
|---|---|
draft | Scope is defined. No implementation plan yet. |
planned | The implementation plan is written and every dependency is done. Ready to start. |
in_progress | One person or agent is actively working on it. |
in_review | Work is complete, a PR is open, and it is waiting on human review. |
done | Reviewed, approved, and merged. Terminal. |
cancelled | Abandoned. Reachable from any non-terminal state. Terminal. |
Transitions
drafttoplanned: when the implementation plan is saved.plannedtoin_progress: when someone claims the task before starting work.in_progresstoin_review: when the work is complete and the completion fields are filled.in_reviewtodone: when a human reviews the PR and approves it.- Any non-terminal state to
cancelled: when the scope is dropped or superseded.
A human owns the final step
An agent writes in_review. A human flips in_review to done. Agents never promote their own work to done. The review gate is where a person inspects the PR and decides whether the work ships.
What marks a task complete
Before a task reaches in_review, these fields are filled:
executionRecord: three to five sentences on how the work was built, grounded in real files, commits, or PRs. Not a restatement of the plan.decisions: one line each, recording the choice and why it was made.files: every repo path that changed, or an empty list when no repo files were touched.acceptanceCriteria: each criterion evaluated true or false against the work, with evidence.- The PR link, when the work changed code.
Propagate after every change
A task does not stand alone. After any status change, update the dependency graph: refresh edge notes, add relationships the change revealed, drop relationships that no longer hold, and update downstream descriptions. A change that does not propagate did not happen.