/manage-schemas

name: manage-schemas
description: "Creates, views, edits, deletes, and validates note schemas for the MCP Task Orchestrator in .taskorchestrator/config.yaml — the templates that define which notes agents must fill at each workflow phase. Also recommends schema designs from a library of workflow patterns (autonomous coding loops, spec-driven teams, research pipelines, content production, support triage, data pipelines, incident response, document review) — use this skill whenever the user describes a workflow they want tracked or gated, even without the word 'schema': what schema should I use, help me design schemas, recommend gates for X, set up schemas for my team/workflow/pipeline. Also manages the actor_authentication config block: set actor authentication policy, configure degraded mode, show actor_authentication config, set degradedModePolicy to reject, what's the current degraded mode policy. Use when user says: create schema, show schemas, edit schema, delete schema, validate config, what schemas exist, add a note to schema, remove note from schema, or configure gates."
argument-hint: "[optional: action + schema name, workflow description, or 'actor_authentication', e.g. 'view bug-fix', 'create research-spike', 'recommend schemas for support triage', 'validate', 'set degradedModePolicy reject']"

Manage Schemas — Note Schema Lifecycle

Create, view, edit, delete, and validate note schemas in `.taskorchestrator/config.yaml`. Schemas define which notes agents must fill at each workflow phase before advancing items.

---

Step 1 — Determine Intent

Classify from `$ARGUMENTS` and conversation context before making any tool calls.

| Signal words | Action | |---|---| | "create", "build", "new", "add schema", "define", "set up" | CREATE | | "recommend", "advise", "design", "what schema should I use", "help me choose", a described workflow with no schema name | CREATE (advisor path) | | "show", "view", "list", "what schemas", "display" | VIEW | | "edit", "modify", "change", "update", "add note to", "remove note from" | EDIT | | "delete", "remove schema", "drop" | DELETE | | "validate", "check", "verify", "lint" | VALIDATE |

If `$ARGUMENTS` contains both an action and a schema name (e.g., "view bug-fix"), extract both. If intent cannot be determined, ask via `AskUserQuestion` with options: Create, View / Validate, Edit, Delete.

> Validate is grouped with View — both are read-only operations on the config file.

---

Step 2 — Config Bootstrap

The target file is the path on the SessionStart context's `Config:` line (project or personal scope) when there is one, otherwise `.taskorchestrator/config.yaml`. In personal scope that is the user-level file, so an edit applies to every directory that has no project config of its own. Check if the target file exists by reading it.

**If the file does not exist:**

• For **VIEW** or **VALIDATE**: report "No schemas configured — `.taskorchestrator/config.yaml` does not exist." and stop.
• For **CREATE**, **EDIT**, or **DELETE**: create the `.taskorchestrator/` directory if missing, then create `config.yaml` with an empty `work_item_schemas:` key:

  work_item_schemas:

**If the file exists:** Read and parse it. Proceed to Step 3.

> **Note:** `project:` is a recognized top-level key alongside `work_item_schemas`, `traits`, `resources`, and `actor_authentication` — it anchors this repo to a project root item and is read only by other skills and the plugin hooks (`quick-start`, `/task-orchestrator:init`, `/adopt-project-scope`), never edited by this skill. Do not treat it as unknown, and never drop or rewrite it — every write operation in Step 3 (CREATE/EDIT/DELETE) must carry it through unchanged. See `references/config-format.md` → Project Scoping for its fields. (`resources:` is the optional shared-resource registry — see `references/config-format.md` → "Resources (Trait Dimension)"; it must be preserved the same way, as must the hook-read `orchestration:`, `retrospective:`, and `actor_attribution:` blocks.)

---

Step 3 — Route to Operation

CREATE — Build a New Schema

Three entry paths: a pattern-driven **advisor** (the user describes their workflow; classify it against `references/workflow-patterns.md` and recommend a configuration with per-gate rationale), starter **templates**, and from-scratch **Q&A**. All three converge on the same customize → write → smoke-test machinery. When the user described a workflow rather than naming a schema, go straight to the advisor path.

For detailed workflow, see `references/create-workflow.md` in this skill folder.

VIEW — Display Existing Schemas

Read `.taskorchestrator/config.yaml` and display schemas in a summary table:

◆ Note Schemas — .taskorchestrator/config.yaml

| Schema Type | Lifecycle | Queue Notes | Work Notes | Review Notes | Total |
|---|---|---|---|---|---|
| feature-implementation | auto | 1 (1 req) | 2 (2 req) | 1 (1 req) | 4 |
| bug-fix | auto | 1 (1 req) | 2 (2 req) | 1 (1 req) | 4 |

If the user specified a schema name, show that schema's full detail: each note with key, role, required, description, guidance, and skill (if set). Also show the schema's lifecycle mode and default_traits (if any).

If the config has a `traits:` section, show a separate traits summary table:

◆ Traits

| Trait | Notes | Skills | Dispatch |
|---|---|---|---|
| needs-security-review | security-assessment (review, req) | security-review | — |
| needs-migration-review | migration-assessment (queue, req) | migration-review | — |
| delegated | delegation-metadata (work, opt) | — | work: implementer, review: reviewer (effort high) |

The `Dispatch` column summarizes the trait's `dispatch:` map (if any) as `phase: agent` pairs, each with `(effort <level>)` appended when that phase's profile sets one (e.g. `review: reviewer (effort high)`); a `model`-only or `effort`-only phase profile (no `agent`) shows as `phase: (model <name>)` / `phase: (effort <level>)`;