Schema Workflow

Drive any schema-tagged MCP work item through its gate-enforced lifecycle. This skill is schema-driven — it reads note requirements and authoring guidance from the item's tag schema at runtime, never hardcoding what notes should contain.

When this skill applies: Any item whose type field matches a schema defined in work_item_schemas: in .taskorchestrator/config.yaml, or whose tags match a schema in note_schemas: (legacy). Items without a matching type or tags advance freely (no gates).

Entry Point

Start by loading the item's context:

get_context(itemId="<uuid>")

The response tells you everything needed to proceed:

| Field | What it means | |-------|--------------| | currentRole | Which phase the item is in (queue, work, review, terminal) | | canAdvance | Whether the gate is satisfied for the next start trigger | | missing | Required notes not yet filled for the current phase | | expectedNotes | All notes defined by the schema, with exists and filled status (keys-only — no description/guidance/skill) | | guidanceKey | Key of the first unfilled required note with guidance; resolve its text via query_items(operation="schema", itemId=...) | | noteSchema | The full schema definition matching the item's tags |

If currentRole is terminal, the item is already complete — nothing to do.

If noteSchema is null or empty, no schema matches the item. This means either:

.taskorchestrator/config.yaml doesn't exist or has no work_item_schemas or note_schemas section
The item's type field doesn't match any configured schema key in work_item_schemas
The item's tags don't match any configured schema key in note_schemas (legacy fallback)
No default schema exists as a fallback

Inform the user: "No schema found for this item's type/tags. Use /manage-schemas to configure gate workflows." The item can still advance freely — this is non-blocking, but gate enforcement won't apply.

Phase Progression Loop

Each phase follows the same pattern: fill required notes, then advance.

Step 1 — Identify missing notes

From get_context, check the missing array. These are the required notes that must be filled before the gate allows advancement.

If missing is empty and canAdvance is true, skip to Step 3.

Step 2 — Fill notes using guidanceKey

For each missing note, guidanceKey names the note with authoring guidance; resolve its text via query_items(operation="schema", itemId=...) and follow it.

manage_notes(
  operation="upsert",
  notes=[{
    itemId: "<uuid>",
    key: "<note-key>",
    role: "<note-role>",
    body: "<content following the resolved guidance>"
  }]
)

Keep the body distilled prose; route verbatim artifacts (test output, diffs, logs) through bodyFromFile instead of pasting them inline.

How guidanceKey works:

get_context returns guidanceKey (a note key) for the first unfilled required note
After filling that note, call get_context again to get the key for the next one
Resolve the key's guidance text via query_items(operation="schema", itemId=...)
If guidanceKey is null, no unfilled required note has guidance — use the note's description (also from the schema op) as a general guide

Skill-assisted note filling:

If the get_context response includes skillPointer (a non-null string), invoke that skill via the Skill tool before filling the note
The skill provides a structured evaluation workflow — follow its steps, then use the output to fill the note
skillPointer is derived from the first unfilled required note's skill field in the schema
If skillPointer is null, use the resolved guidanceKey text as the authoring guide
description/guidance/skill are not in expectedNotes (keys-only) — fetch them via query_items(operation="schema", itemId=...)

Batch filling: If you already know the content for multiple notes (e.g., from a completed plan or implementation), fill them all in one manage_notes call. You only need to re-check get_context between notes when you need the next guidanceKey for authoring direction.

Step 3 — Advance to the next phase

advance_item(transitions=[{ itemId: "<uuid>", trigger: "start" }])

The response confirms the transition:

| Field | Check | |-------|-------| | applied | Must be true — if false, the gate rejected (notes still missing) | | newRole | Phase you moved to (previousRole is omitted from success results) | | expectedNotes | Notes required for the new phase (fill these next) | | unblockedItems | Other items that were waiting on this one |

If the gate rejects: The response lists which notes are missing. Fill them (Step 2), then retry. Do not call get_context first — advance_item already told you what's needed.

If the response instead has applied: false with errorCode: "resource_unavailable" (errorKind: "transient"): this is NOT a note-gate rejection — do not fill more notes and do not retry the same call. A shared resource this item declares via a resources: trait is currently held by another item entering WORK. Report the contended contendedResources key(s) (and retryAfterMs if present) back to the orchestrator/user rather than spin-retrying; see /status-progression → "resource_unavailable" for the full recovery pattern.

Step 4 — Repeat or finish

After advancing, check whether the new phase has its own required notes:

If expectedNotes in the advance response shows unfilled required notes → loop back to Step 2
If newRole is terminal → the item is complete
Otherwise, continue work in the new phase and fill notes as progress is made

Phase-Specific Guidance

The schema defines which notes belong to which phase. Common patterns:

| Phase | Typical purpose | When notes get filled | |-------|----------------|----------------------| | queue | Requirements, design, reproduction steps | During planning, before implementation starts | | work | Implementation notes, test results, fix summaries | During or after implementation | | review | Deploy notes, verification results | After implementation, during validation |

The actual note keys and content requirements vary per schema — always check expectedNotes rather than assuming specific keys exist.

Orchestrator vs Subagent Responsibility

Protocol auto-injection is agent-type gated. The subagent-start hook injects the Agent-Owned-Phase Protocol only when the dispatched subagent's agent_type resolves to implementer or reviewer (bare, or plugin-qualified like task-orchestrator:implementer) — see current/docs/integration-guides/plugin-skills-hooks.md → "Execution modes". Dispatching any other agent type (general-purpose, Explore, Plan, a project-local research agent, etc.) for a work/review phase gets NO auto-injected protocol. When dispatch.agent is unset (see the dispatch-profile note below), prefer dispatching the phase owner explicitly as task-orchestrator:implementer (work) / task-orchestrator:reviewer (review) so the protocol is injected automatically; if a different agent type is genuinely required, include the Agent-Owned-Phase Protocol text directly in that dispatch's prompt instead of relying on injection. The hook is also silent for the entire duration of a headless ralph iteration (TASK_ORCHESTRATOR_MODE=headless-iteration), which never dispatches subagents in the first place.

Orchestrator (this skill's primary user):

Fills queue-phase notes (requirements, design) during planning
Dispatches implementation agents with the item UUID
When dispatching the phase owner (implementer on work, reviewer on review), reads the profile for the phase being dispatched INTO — advance_item's dispatch for newRole once the transition is already made, or query_items(operation="schema", itemId=...) → dispatch.<phase> when the agent will enter the phase itself (agent-owned-phase protocol, item still in queue at dispatch; get_context only returns the CURRENT role's profile, the wrong one in that case) — and honors it: subagent_type = dispatch.agent when set, and ALWAYS still passes model explicitly (dispatch.model if set, else its own model policy) regardless of whether agent is set, since effort has no Agent-tool parameter and is advisory unless agent names a definition carrying that effort
After implementation agents return, advances the item via advance_item(start) and inspects newRole:
- If review: dispatches review agents or performs inline review
- If terminal: item completed through a lightweight lifecycle (no review-phase notes in schema)
Performs the final terminal transition (review→terminal) after the review verdict
Uses this skill for queue-phase note filling and terminal advancement

Implementation agents (agent-owned-phase model):

Receive the full phase-aware protocol automatically via the subagent-start hook
Call advance_item(start) once to enter work phase (queue→work)
Fill work-phase notes using the JIT progression loop (guidanceKey + skillPointer)
Return to the orchestrator — do NOT call advance_item again
The orchestrator advances the item to the next phase and handles all further routing

Review agents (dispatched into an item already in review):

Receive the subagent-start hook, which tells them to call advance_item(start)
Since the item is already in review, advance_item returns applied: false — this is expected
The hook's fallback applies: call get_context(itemId=...) to get guidance instead
Fill review-phase notes (e.g., review-checklist), report verdict, return
Do NOT call advance_item again — the orchestrator handles the terminal transition

Key invariant: Agents own phase entry (one advance_item(start) call to enter their assigned phase). When a run plan assigns several seats to one phase (run-wave), only that phase's entry seat makes this call; in-phase seats (test author, declarations extractor) and read-only seats never call advance_item; the orchestrator owns every later transition. The orchestrator owns all phase-to-phase transitions — advancing the item, inspecting the schema to determine the next phase (review or terminal), and dispatching phase-appropriate agents. Review agents fill review-phase notes and return — they do not advance items.

Creating a New Schema Item

When creating a new item with a schema, set the type field to the schema key:

manage_items(
  operation="create",
  items=[{ title: "...", type: "<schema-key>", priority: "medium" }]
)

The type field is the primary schema selector — it maps directly to a key in work_item_schemas:. Tags can still be used for additional categorization and as a legacy schema fallback, but type takes precedence.

Check expectedNotes in the response — it lists all notes the schema requires across all phases. Begin filling queue-phase notes immediately, then follow the progression loop above.

Error Recovery

Gate rejection: advance_item returns applied: false with the missing note keys. Fill them and retry — no need for a separate get_context call.

Resource-lease contention: advance_item returns applied: false with errorCode: "resource_unavailable" and errorKind: "transient" instead of missing notes — distinct from a gate rejection. Do not fill notes in response to this; it means another item currently holds a resource this item's traits declare. Wait (retryAfterMs is a hint) or work a different item; never spin-retry the same advance_item call.

Wrong phase notes: If you try to upsert a note with a role that doesn't match the item's current role, the note is still created (notes are not phase-locked), but it won't satisfy a gate for a different phase. Always match the note's role to the schema definition.

Blocked items: If advance_item fails because the item is blocked by a dependency, resolve the blocking item first. Use get_blocked_items or query_dependencies to diagnose.

No schema match: Items whose type doesn't match any schema in work_item_schemas and whose tags don't match any schema in note_schemas have no gate enforcement. advance_item will succeed without notes. This is by design — only typed or tagged items require structured note workflows.