ComfyUI

This is the ComfyUI router for Story-Film Skills.

Start

1. Read ../../references/COMFYUI_MANAGED_RUNTIME.md.
2. Read ../../references/COMFYUI_OPERATIONS.md.
3. Read ../../references/COMFYUI_SECURITY.md.
4. Identify the requested control surface and scope.
5. Read only the specialist skill needed next.

Route

• primary Pi live control, official MCP discovery, nodes, models, lifecycle, jobs, outputs, and assets: comfyui-mcp
• inspect server, nodes, models, features, resources, or existing workflows: comfyui-discover
• inspect, validate, edit, or prepare workflow JSON: comfyui-workflow
• submit, wait, queue, cancel, free memory, or collect a run: comfyui-run
• upload inputs or download generated outputs: comfyui-assets
• official CLI workspace and lifecycle operations behind the managed runtime: comfyui-cli
• managed comfy-api-proxy or another approved Comfy API v2 endpoint: comfyui-api-v2
• diagnose missing nodes, models, invalid prompts, execution failures, or VRAM problems: comfyui-troubleshoot
• compile and run a deterministic multi-job generation batch that cannot call an LLM: comfyui-offline-batch
• hand GPU/RAM ownership from a local LLM to ComfyUI and back without model calls during generation: resource-safe-generation

Rules

• In Pi, use the native story_comfy tool as the primary live ComfyUI control surface. Start with action=server-info.
• story_comfy has precedence over shell/filesystem discovery for ComfyUI installation/location, live server state, installed models, model search, nodes, and workflows.
• Do not use Bash, find, ls, which, locate, direct comfy-cli discovery commands, guessed personal paths, home-directory scans, model-folder scans, raw config-file inspection, or one-off HTTP clients to discover those facts.
• Before deciding a model is missing, use action=model-inventory, then action=model-search when a filtered search is needed. For workflow discovery use action=workflow-catalog; it catalogs only the extension's comfyui_workflows/ tree. Use action=node-search/action=node-info for live nodes.
• Use action=search-tools only when the exact allowed non-gallery comfy-mcp verb is unknown. Story-Film filters template-gallery tools and template cross-references out of LLM-facing MCP discovery. An empty or failed MCP tool-name search is not permission to fall back to Bash; the native story_comfy inventory/catalog/node actions remain the first fallback.
• A failed guessed path, missing guessed directory, empty checkpoints directory, or empty filesystem search is never evidence that ComfyUI or a model is absent.
• Story-Film automatically bootstraps its separate official control environment. The managed comfy-mcp process is private stdio behind story_comfy, not a server registered in Pi's generic mcp tool. Generic mcp status may therefore show 0/0; use story_comfy action=mcp-status for Story-Film MCP health.
• Do not ask the user to install or configure comfy-cli, comfy-mcp, comfy-api-proxy, or a generic MCP extension.
• Managed bootstrap never installs ComfyUI, models, or custom nodes. The user supplies ComfyUI and their model collection.
• Discover live capabilities before naming executable nodes or model files.
• For normal workflow selection, catalog only Story-Film's comfyui_workflows/ directory. Never scan project workflow/default folders, ComfyUI userdata, arbitrary external paths, or template catalogs. To add another existing workflow, copy its JSON into comfyui_workflows/custom/<task>/<model>/.
• If the user explicitly asks Story-Film to create a new workflow, route to comfyui-workflow and use bounded live-schema authoring. Workflow creation remains supported; extension-only discovery must not be interpreted as a ban on authoring new graphs.
• A Story-Film prompt adapter name describes prompt grammar only. It never proves that a same-named ComfyUI node, API node, checkpoint, or runtime exists.
• ComfyUI-Pi-Agent and a separately configured Pi MCP server are not prerequisites.
• Third-party custom-node installation, model downloads, ComfyUI version changes, broad updates, and paid partner execution require explicit user approval.
• Keep credentials out of workflows and project files.
• For long generations, submit asynchronously and keep the prompt ID.
• The bundled native HTTP controller remains a deterministic fallback/internal path; do not replace the managed tool with ad hoc curl, urllib, requests, or raw prompt loops.