Workflow Schema Tuning

The schema (resources/workflow-schema.json) is the primary spec delivered to the AI editor at runtime via the get_workflow_schema MCP tool. It is not a runtime validator, the runtime barely validates anything. Whatever the schema says, the AI believes. Treat schema edits as prompt engineering, not type definitions.

Core principle: align direction, do not prescribe rules

AI agents already know how to choose between node types intuitively (e.g., when to delegate to a sub-agent vs. handle in-context). The fix for bad output is almost never "add more rules", it is "remove what is biasing the AI in the wrong direction."

Defaults:

• Prefer minimal description text that states each node's positional role (立ち位置). Example: "A step executed by the main orchestrating agent" vs. "A step executed by an isolated sub-agent." The contrast does the work.
• Avoid aiGenerationGuidance lists of "when to use / when not to use / anti-patterns." They treat the AI as a rules engine, bloat tokens, and fail on unanticipated cases.
• Test minimal first. Only add guidance after a concrete failure where the minimal change is provably insufficient.

Anti-pattern: writing detailed upgradeToSubAgentWhen / stayInPromptWhen lists. If you find yourself writing 3+ bullets explaining when to use a node, the description itself is probably wrong.

Schema architecture

File	Role	Editable?
resources/workflow-schema.json	Single source of truth	YES
resources/workflow-schema.toon	Token-efficient format consumed by AI via MCP	NO, auto-generated
resources/ai-editing-skill-template.md	Skill template loaded at AI editor launch	YES
scripts/generate-toon-schema.ts	TOON generator	YES (rare)

After editing .json, regenerate .toon:

npm run generate:toon

The full build (npm run build) does this automatically as the first step.

Where biases hide (audit checklist)