Schema Workflow

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.