jpicklyk / schema-workflow

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:

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:

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:

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.