jpicklyk/task-orchestrator/schema-workflow

Schema Workflow

Drive a work item through its gate-enforced lifecycle. The skill is schema-driven: note requirements and authoring guidance are read from the item's resolved schema at runtime, never assumed. Shapes are in `_generated/call-shapes.md`; ids below are 8-hex shorts (a full UUID is also accepted). Read every answer through the envelope: ok, then data.results[0] (ok or error) and data.summary {ok, failed}. When a write element fails, the call-level error is only partial_failure (no detail, no fix): read code, kind (retry class), detail and fix from data.results[0].error. A read (select) call reports its failure in the call-level error.

Applies to any item whose type resolves to a schema under its pin (config effective lists the declared types). An item whose type resolves to no schema is schema-free and advances without gates.

Director mode. In director mode (the session state entered by /task-orchestrator:director, or the hardened director agent) a director never drives an item through its phases: hand it to the run's coordinator (SendMessage) or to ONE background Agent (run_in_background: true, model set). A background agent dispatched by a director is not in director mode: it runs the steps below.

Entry point

{"tool": "items_read", "select": "context", "args": {"itemId": "4b7d0e19"}}

• item.role of terminal: nothing to do. blocked: use /status-progression; for a pending decision follow its decisions rule (answer first, resume only when resumable).
• Schema-free: the schema read answers {schemaFree: true}. Tell the user "No schema for this item's type; use /manage-schemas to configure gates". The item still advances freely.
• Lifecycle-free (role absent): never advanced; its notes are optional. Any advance trigger fails invalid_transition with fromRole: none.

Resolve authoring text (guidance, description, skill) for the notes:

{"tool": "items_read", "select": "schema", "args": {"itemId": "4b7d0e19", "fields": ["guidance"]}}

Phase progression loop

Each phase: fill the required notes, then advance.

Step 1 - Find the missing notes

Read gateStatus.missing. If it is empty and canAdvance is true, go to Step 3.

Step 2 - Fill the notes

For the note named by guidanceKey, follow its resolved guidance; if skillPointer is set, invoke that skill first and use its output. If guidanceKey is absent, use the note's description. Write the body as distilled prose; route verbatim artifacts (test output, diffs, logs) through bodyFromFile.

{"tool": "notes_write", "op": "upsert", "args": {"itemId": "4b7d0e19", "key": "implementation-notes", "role": "work", "body": "Added the retry policy; one deviation, see below."}}

When you already know several bodies, send them in one notes_write call (an upsert element each). Re-read context only when you need the next guidanceKey. A note whose role differs from the schema's role fails schema_violation. A schema_pinned_conflict means the item's pin lacks a key the current config requires: repin it (items_write repin), then retry.

Step 3 - Advance

{"tool": "advance", "op": "transition", "args": {"itemId": "4b7d0e19", "trigger": "start"}}

Read data.results[0]:

A failed transition is ok: false with call-level partial_failure; the reason is data.results[0].error.code:

• gate_blocked: data.results[0].error.detail.missing[] names the notes still unfilled. Fill them (Step 2) and retry; no need to re-read first. Also read detail.violations[].gate in that same error: missing and violations may both be present, and a review-pending or independence violation is not cleared by filling notes.
• resource_unavailable (data.results[0].error.kind: transient): not a note gate. Another item holds a resource this item's traits declare. Do not fill notes and do not spin-retry; report data.results[0].error.detail.resources[] and data.results[0].error.retryAfterMs and see /status-progression.
• dependency_unmet: a blocker is unfinished; diagnose with /dependency-manager.
• not_claim_holder: someone else holds the claim; only the holder can transition.
• seat_forbidden: the item is a member of an open or paused run whose schema declares seats, and your caller is not allowed that trigger (detail.allowedSeats lists who is; it always starts with coordinator). If you are the run's coordinator, resend with the run's coordinator token as top-level seatToken; otherwise leave the transition to the run. Never retry it token-less.
• run_paused: a start under a token of a run that is paused on its budget or attempt limit. Read detail.pauseReason and detail.pauseDecisionId; stop and never retry. A director or human answers the decision.
• invalid_transition: read detail.fromRole and detail.allowed; the trigger is not valid from that role.

Step 4 - Repeat or finish

If expectedNotes lists unfilled required notes, go back to Step 2. If newRole is terminal the item is complete. Otherwise keep working and fill notes as progress is made.

Phase-specific guidance

Keys vary per schema; take them from schema[], never from assumption.

Orchestrator and subagent responsibility

Protocol injection is agent-type gated. The subagent-start hook injects the Agent-Owned-Phase Protocol only when the dispatched agent_type resolves to implementer or reviewer (bare or plugin-qualified, for example task-orchestrator:implementer). Any other agent type gets no injected protocol: dispatch the phase owner as task-orchestrator:implementer or task-orchestrator:reviewer, or paste the protocol text into the prompt. The hook is also silent for a headless ralph iteration (TASK_ORCHESTRATOR_MODE=headless-iteration).

Orchestrator:

• fills queue notes during planning and dispatches with the item id;
• reads the profile for the phase being dispatched INTO: the dispatch of the advance result once the transition is made, or items_read schema (dispatch, dispatchBySeat) when the agent will enter the phase itself; items_read context returns only the current role's profile. Pass subagent_type = dispatch.agent when set, and always pass model explicitly;
• after agents return, advances with start and checks newRole: review means dispatch reviewers or review inline, terminal means a schema without review notes;
• performs the review-to-terminal transition after the verdict.

Implementer (entry seat): the seat the schema marks enters calls start once to enter work, fills work notes with the loop above, returns, and never calls advance again.

Reviewer and other non-entry seats: a reviewer is dispatched into an item already in review. It must NOT call start (from review that lands terminal). It reads items_read context, fills the review notes, reports the verdict and returns. Test authors, extractors and read-only seats never call advance.

Invariant: only an entry seat moves its item, and only into its own phase; the orchestrator owns every other transition.

Item in an open run. On a member of an open or paused run whose schema declares seats, the orchestrator's advance, notes_write and items_write carry the run's coordinator token as top-level seatToken. With it only orchestrator-seat note keys are writable; other seat-owned keys answer note_owned_by_other. See current/docs/config-reference.md ("Seat transitions"). Find the membership by listing the root's runs, then reading each run's frontier (a non-terminal member is in ready, inFlight or waiting):

{"tool": "runs_read", "select": "list", "args": {"rootId": "ce064d2c", "status": "open"}}

{"tool": "runs_read", "select": "frontier", "args": {"runId": "7c41e0a2"}}

Repeat the list with status: "paused"; one status per call.

Pre-dispatch recipe: a seat at a parent

Before dispatching a seat (a feature reviewer, a closing step) at a parent, read the parent and branch on its role:

{"tool": "items_read", "select": "context", "args": {"itemId": "98d452e9"}}

Never dispatch a reviewer at a work-role parent. Note that the terminal cascade from the last child into a review-role parent is suppressed (cascades[] shows applied: false, review-pending), so a review parent needs an explicit complete, or its review and then start.

Creating a schema item

Set type to a declared schema key (config effective types; a wrong one fails schema_violation with data.results[0].error.detail.availableTypes):

{"tool": "items_write", "op": "create", "args": {"title": "Add retry layer", "type": "feature-task", "priority": "medium", "traits": ["needs-docs-accuracy-review"]}}

The answer is {ok, id, version}; read items_read schema for the notes and start filling queue notes, then follow the loop. See /create-item for anchoring.

Error recovery