comfy-draftsman: Instructions file for Codex

AGENTS.md — comfy-draftsman

A local-first MCP server that drafts, organizes, validates, and runs ComfyUI workflows. Delivers clean, labeled, annotated UI-format graphs that humans can read — computed layout, colored stage groups, titled nodes, green-highlighted knobs, and generated guidance notes. Python ≥3.11, hatchling build, httpx + websockets + mcp stack.

Deep reference: docs/ARCHITECTURE.md (read it before engine/graph/validation changes)

Current state

Last verified: 2026-10-23

• Status: in development; v0.25.0 (src/comfy_draftsman/__init__.py is the single source of truth for the version). CI green. Published to PyPI as comfy-draftsman via Trusted Publishing (.github/workflows/release.yml); a v* tag push publishes and cuts the GitHub Release - see README -> "Publishing a release".
• Works: the full draft → organize → validate → run → save loop against a live ComfyUI instance; schema 0.4 and 1.0 graphs including subgraph flatten/rebuild; V3 dynamic combos, autogrow inputs and match types round-tripping through the API's dotted-key form; organize_workflow's labeled stage groups, knob cards and guidance notes; workflow import straight from ComfyUI's browser (list_workflows + import_workflow(name=…)); the per-family knowledge floor plus a persistent learned overlay written by record_learning; to_api bypass routing that mirrors the frontend's; organize_workflow staging that uses graph position (switches, primitives, MODEL patches, i2i preprocessing) with row-wrapped bands.
• In progress: nothing half-built - each round lands complete. 0.25.0 adds the fibo2, flux3_klein, minimax_h3 and anima families, a spectral color-stripe banding score (checked on real MOSS SFT renders), above-native-resolution and hidden-troubleshooting lints, headless fresh LoRA Manager loaders (text and loras kept in sync), off-step values accepted at edit time, unwrapped text/JSON outputs, record_learning shape hints, and sweep sampling_s and crop guide. 0.24.0 adds the moss_image family with a family-avoid-node lint, guards record_learning shapes, maps imported LoRA Manager widgets by their saved names, makes organize text plain (no emoji), refreshes object_info on edits naming an unlisted model, and gives sweeps fractional crops, per-crop sheets and cached-run marking. 0.23.0 fixes upload cache refresh, partial-edit reporting and template findings, adds sweep output relocation/reuse hints and sampling-size lint. 0.22.0 fixes a LoRA Manager feedback round: JS-widget inputs added as widget-backed slots, stale link slots repaired on import, collapsed-node overlap lint, disconnect/set_color/group bounding ops, and organize guidance that keeps hand-arranged layouts. CHANGELOG.md records older rounds and what was deliberately not changed.
• Known gaps / next steps: confirmation dialogs fall back to the explicit confirm flag on the 2026-07-28 MCP protocol (no back-channel for ctx.elicit; pre-2026 handshakes still get the dialog); misaligned pack nodes are reported, not realigned, so they can't run headlessly; no confirmation popup appears in the Claude Code VS Code extension (verified 2026-10-11 on 0.21.0); gates take the ask-in-chat fallback, and overwrite proceeds; add_node treats a custom type nothing outputs as a JS widget, so a real socket whose producer pack is missing gets a widget marker too; some families carry no VRAM data and correctly stay silent; acceleration variants match the UNet filename only, not lora_name; COMFY_DYNAMICSLOT_V3 is classified but never exercised (no live instance declares one - do not implement it speculatively); widget-backed custom-JS inputs stay a deliberate loud stop rather than a silently-wrong emit (the LM Lora Loader is the one pack resolved by name); flux3_klein, minimax_h3 and anima floors come from public sources and have not been rendered locally. All written up in full under docs/ARCHITECTURE.md -> "Remaining TODOs".
• Deep docs: docs/ARCHITECTURE.md (module map, data flow, subgraph mechanics, hard-won gotchas, open TODOs), docs/PERMISSIONS.md (which tools are read-only), CHANGELOG.md.