Find before creating
Call orient with {} and follow the task map and its task-authoring contract. Then call task_list with a bounded filter, for example:
{"text":"<distinctive job wording>","limit":20}Read each likely match with task_get using {"id":"<returned task id>"}. A redacted or unavailable result is not a complete read. Use the returned canonical task rather than copying its title into a new file.
Create through the allocator
If there is no existing task and creation is authorised, call task_create. Obtain the prefix and project from the Mind's task contract; do not invent a complete task id.
{"prefix":"<permitted allocator prefix>","project":"<permitted project>","title":"<specific outcome>","status":"backlog","finish_gates":["<task id that must be done first>"]}finish_gates lists the ids of other tasks that must be done before this one can be done. It is not a place for a written completion condition: an entry that is not a task id can never be satisfied, and the task then cannot be closed. Put the acceptance condition in the task body, or create a separate task for it and list that task's id.
Read the returned result and its minted id. If the response is lost, reconcile task_list and the creation result before creating again.
Update under current ownership
For an agent that will own the work, follow the session and claim procedure. Retain the current session id and returned claim generation. Call task_get immediately before a body or checklist replacement.
{"id":"<task id>","claim_context":{"<task id>":{"session_id":"<current session id>","generation":1}},"expected_content":"<entire exact content from the latest task_get>","body":"<updated Markdown body, without frontmatter>"}Replace generation 1 with the actual returned generation. A checklist update also supplies expected_checklist exactly matching the current checklist when one exists. Preserve unrelated fields and body content.
Verify the lifecycle result
Use supported states: backlog, active, in-progress, blocked, review, done, cancelled. A transition can use task_transition with id, status and current claim_context. Do not pass a top-level session; in a task update it is the task's own session field, not the claim check.
A task moves forward one step at a time: backlog, active, in-progress, review, done. Skipping a step or moving back is refused with forward_only. The other allowed moves are active or in-progress to blocked, blocked back to active or in-progress, any state except cancelled to cancelled, and done back to active. cancelled is final.
Setting done is refused unless the task body has a ## Verification section containing a bullet that starts Result: or Evidence: with a real value, for example - **Evidence:** the saved brief and its checked sources. It is also refused while any task listed in finish_gates, or any child task, is not yet done (inv2_verification, inv2_finish_gates, inv2_children). Read the task again and report its actual saved state.
On stale content or claim refusal, read the task and ownership again. Do not replay the old update or approve a held task proposal under an obsolete generation.
Related
Practical guides for people and agents