workflow-schema-tuning

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)

When the AI consistently picks the wrong node type, look here in priority order:

1. ai-editing-skill-template.md step 4 — strongest pull. A line like "use built-in sub-agents by default" overrides every other signal in the schema. Keep this neutral.
2. nodeTypes.<type>.description — the AI's first impression of what each node means. Keep terse, contrastive, role-focused.
3. nodeTypes.<type>.aiGenerationGuidance — when present, this is read closely. Audit for stale "default" framings or anti-patterns that no longer apply.
4. examples[] — the AI learns strongly from examples. If every example uses one node type, expect that node to dominate output.
5. Top-level constraints (connections.overview.forbidden, exportValidationRules, postGenerationChecklist) — these can encode false constraints (e.g., "no cycles allowed" when the runtime allows them, since the runtime is an AI that uses judgment, not a deterministic executor). Removing false constraints is itself a valid improvement.

Workflow for making changes

1. Diagnose: identify the symptom (wrong node type chosen, false constraint cited in AI's reasoning, etc.).
2. Locate the bias: walk the audit checklist above. Look for a single source pulling the AI in the wrong direction before adding new content.
3. Minimal edit: prefer removing biased text or fixing one description over adding new sections.
4. Regenerate TOON: npm run generate:toon.
5. Validate: npm run check && npm run build.
6. Test: npm run debug launches a fresh Extension Development Host. Trigger the AI editor with a node-type-agnostic prompt (no hints like "use a sub-agent for X") and inspect the generated workflow.
7. Iterate: if the minimal change is insufficient, add the smallest additional signal — not a guidance section.

Important constraints

• The framework is multi-agent (Claude Code, Codex, "other"). Schema text must be agent-agnostic. Avoid Claude-specific phrasing like "isolated Claude session" — use "isolated AI agent session" or "isolated sub-agent."
• The runtime is an AI agent making judgments, not a deterministic program. Constraints that make sense in code (no cycles, no infinite loops) often do not apply here. Verify before transcribing programming-style constraints.
• After generate:toon, confirm the change took effect by grepping the relevant string in workflow-schema.toon. The MCP delivers TOON, not JSON.

Commit conventions for schema changes

Per the project's conventional commit policy:

• Description fixes / bias removal → improvement: (patch bump)
• Build/tooling-only changes → chore: (no release)
• Keep subjects ≤50 chars, body 3–5 bullets, "what changed" only
• Split unrelated concerns into separate commits to make diffs reviewable