version: "1.0.1" name: schema-workflow description: "Guides an MCP work item through its schema-defined lifecycle — filling required notes using guidancePointer and advancing through gate-enforced phases. Internal skill triggered by hooks and output styles during orchestration workflows. Use when an item has schema tags and needs to progress through queue, work, review, or terminal phases with note gates." user-invocable: false

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 guidancePointer

For each missing note, the schema provides authoring guidance via guidancePointer. This is the schema author's instruction for what the note should contain — follow it.

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

How guidancePointer works:

• get_context returns guidancePointer for the first unfilled required note
• After filling that note, call get_context again to get the pointer for the next one
• The pointer comes from the guidance field in .taskorchestrator/config.yaml
• If guidancePointer is null, the note has no specific authoring instructions — use the

note's description field 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 guidancePointer as the authoring guide (current behavior)
• The skill field is also visible per-entry in expectedNotes for batch operations

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 guidancePointer 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.

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

Orchestrator (this skill's primary user):

• Fills queue-phase notes (requirements, design) during planning
• Dispatches implementation agents with the item UUID
• 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 (guidancePointer + 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). 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.

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.