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 | | "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

Check if .taskorchestrator/config.yaml 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 note_schemas: key:
```
note_schemas:
```

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

Step 3 — Route to Operation

CREATE — Build a New Schema

Interactive Q&A flow that gathers schema requirements, generates YAML, merges into config, and optionally creates a companion lifecycle skill.

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 Tag | Queue Notes | Work Notes | Review Notes | Total |
|---|---|---|---|---|
| feature-implementation | 2 (2 req) | 2 (2 req) | 1 (0 req) | 5 |
| bug-fix | 2 (2 req) | 2 (2 req) | — | 4 |

If the user specified a schema name, show that schema's full detail: each note with key, role, required, description, and guidance.

EDIT — Modify an Existing Schema

Read current config, display the target schema, ask what to change (add note, remove note, toggle required, change description/guidance, rename key), apply changes, write back.

If the target schema is not found in config.yaml, inform the user and offer to CREATE instead.

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

DELETE — Remove a Schema

Read current config, confirm the schema name, warn about orphaned notes on existing items, remove the key, write back.

If the target schema is not found in config.yaml, inform the user and offer to CREATE instead.

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

VALIDATE — Check Config Integrity

Run structural and semantic checks on the config file and report issues with fix suggestions.

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

Step 4 — Report

For write operations (CREATE, EDIT, DELETE):

Show what changed in the config file
Remind: MCP reconnect required (/mcp) for schema changes to take effect — the server caches schemas on first access

For VIEW and VALIDATE: The output from Step 3 is the deliverable — no additional report needed.

Troubleshooting

expectedNotes is empty after creating an item with the schema tag

Cause: MCP server hasn't loaded the updated config file
Solution: Run /mcp in Claude Code to reconnect the server, then retry

Schema key doesn't match — item has no schema applied

Cause: The item's tags field doesn't contain a string matching any note_schemas key
Solution: Verify the item's tags with query_items(operation="get", id="<uuid>"). The first tag matching a schema key wins.

Duplicate schema key in config file

Cause: YAML allows duplicate keys but only the last one is used
Solution: Check for duplicate entries under note_schemas: and merge them

Changes not taking effect after editing config

Cause: The server caches schemas on first access — changes are not hot-reloaded
Solution: Run /mcp to reconnect the MCP server subprocess

Examples

Example 1: View all schemas

User says: "What schemas do I have?"

Read .taskorchestrator/config.yaml
Display summary table with note counts per phase
Offer to show detail for any specific schema

Example 2: Add a required note to an existing schema

User says: "Add a test-plan note to the bug-fix schema"

Read config, find bug-fix schema
Ask: which phase (queue/work/review), required?, description, guidance
Append the new note entry, write config back
Remind: /mcp reconnect needed

Example 3: Validate config after manual editing

User says: "I edited the config by hand — check it"

Read and parse config
Run validation checks (syntax, structure, field rules, duplicates)
Report issues or confirm "Config is valid — N schemas, M total notes"