Schema Workflow

---
name: schema-workflow
description: "Internal, hook-triggered: drives a schema-typed MCP item through its gate-enforced phases, filling required notes."
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:

| 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

**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 (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). 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.