ba39cb3658
* refactor(nodes): drop keyframe_batch alias from Easy Image Batch The keyframe_batch input was a deprecated alias of keyframes_insert, added in 0.4.1 during PR #246 review to keep pre-rename workflows loading. The old name only ever existed in unreleased dev builds before the rename, so no published workflow depends on it and the alias only cluttered the node with a second IMAGE input. Remove the input, its parameter, and the alias-routing fallback; the node now exposes a single keyframes_insert insert input. Tests and the behavior spec updated; CHANGELOG notes the removal under [Unreleased]. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(policy): make backward compatibility opt-in for Koolook nodes Invert the default: backward compatibility is no longer a standing constraint for Koolook-created nodes (the root k_*.py custom nodes). By default, make the cleanest change — rename/drop/reorder IDs, inputs, and outputs freely, no deprecation aliases or _v2 suffixes. Compatibility with saved workflows is only preserved when the maintainer explicitly says "check backward compatibility". Forks are explicitly excluded: anything under forks/ (including the Koolook-original nodes exposed via SKIP_VERSION_SUFFIX) keeps full back-compat discipline by default, no request needed. The __koolook_vX_Y_Z collision suffix always applies. Scoped across the binding instruction files and skills: CLAUDE.md, copilot-instructions, node-versioning.md, versioning.md, and the preflight-release / add-external-fork / tdd skills. The preflight workflows check is reframed as a drift detector for Koolook IDs and a hard back-compat gate for fork IDs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: clarify keyframe_batch alias removal * fix: retain keyframe_batch compatibility alias --------- Co-authored-by: AI Machine <ai.machine@x.baconcph.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Maintainer docs
Project-internal procedures. If you're cutting a release, forking a node, hitting the Comfy Registry API, or debugging CI — read these first.
These are docs for humans doing the work. The corresponding agent
workflows for Claude Code live in ../../.claude/skills/
and should be kept in sync with these prose docs.
Contents
| File | What it covers |
|---|---|
conventions.md |
Cross-cutting project conventions that don't fit any single topic doc — currently the Mermaid-for-diagrams rule. Add new cross-cutting rules here as they accrete. |
releasing.md |
Canonical step-by-step release procedure: branch → PR → publish-validate → squash-merge → tag → GitHub Release. Anti-patterns to avoid. The per-release tickbox mirror is .github/ISSUE_TEMPLATE/release_checklist.md. |
registry-api.md |
The Comfy Registry's undocumented version-management endpoints (deprecate, delete, query) reverse-engineered while cleaning up v0.1.0–0.1.5. Includes ready-to-paste curl commands and an optional GitHub Actions workflow YAML for codified version management. |
dependency-security.md |
Dependency CVE protocol: the locked test set as the review surface, local/CI pip-audit gates, relocking, and weekly scheduled audit response. |
published-setup-loop.md |
Architecture overview / entry point for the publish → run loop: the plain-terms loop, a technical map (frontend JS → Koolook routes → ComfyUI engine), and the contract/schema requirements. Read this first, then follow the links. |
published-setups.md |
Published workflow setup schema, server-side storage boundary, sidebar publish flow, and catalog API contract for external frontends. |
published-setup-external-ui-contract.md |
Product/design contract for how ComfyUI publish nodes expose controls and result fields to an external frontend. |
published-setup-full-circle-plan.md |
Remaining implementation plan for the full authoring → publish → exported setup/API → external runner loop. |
external-frontend-job-submitter-brief.md |
Handoff brief for an AI or developer session building the real external frontend job submitter. |
external-frontend-kit.md |
Complete file/dependency/fixture checklist for another AI session building the production external frontend. |
node-versioning.md |
Hard-won rules for changing INPUT_TYPES / RETURN_TYPES / class names without breaking saved user workflows. The five rules + the suffix-version pattern (MyNode → MyNodeV2) + the alias-then-deprecate migration path. |
curated-sidebar.md |
The Kforge Labs sidebar starter-preset workflow. How to customize the bundled web/starter_preset.json shipped to fresh users (Snapshot → Load → starter). Storage keys, library directory resolution, reset procedure. |
workflows-sidebar.md |
The "Workflows" section of the same sidebar. Save canvas / save selection / directories / archive on collision / load with named tab. Storage shape, action semantics, reset procedure. |
dev-iteration-loop.md |
The fast iteration pattern we used to build the sidebar — the dev-sync loop, agent trigger phrases (go, dev-sync, paste-JSON), what survives across re-syncs vs what doesn't, push/publish gates. Read this when returning to UI work after a break. |
comfyui-server-api-testing.md |
How to give an AI session access to a running ComfyUI server, submit API-format prompts, poll /history, keep outputs safe, and document real server-side validation in PRs. |
Read this first if you're confused about version numbers:
../reference/versioning.mdexplains the three independent version axes in this codebase (pack version, fork wrapper version, upstream pinned commit) and which skill/doc owns each one. Worth a one-time read before starting any version-bump work.
Companion agent skills
Skill (in .claude/skills/) |
Mirrors this doc |
|---|---|
license-pre-check |
Runs before any third-party fork; refuses to proceed on incompatible licenses. The principles also apply when a human is doing it manually. |
add-external-fork |
The forks/ workflow — clone outside MAIN, register in forks_manifest.yaml, namespace the IDs. Phase 0 calls license-pre-check. |
docs-sync |
Find-and-replace a version tag (or any string token) across docs, code constants, and manifests in one controlled pass. Used during fork wrapper version bumps. |
preflight-release |
Runs the release-gate checks from tools/preflight_release.py — static AST node-ID extraction, VAE wrapper rank/type dispatch roundtrip, and workflow-fixture stability. The ComfyUI-Manager extension-node-map drift check remains available as an explicit advisory check (--check manager-meta) but does not block releases because Manager metadata is maintained independently. Run before opening any release PR — releasing.md step 1. |
menu-comfy |
Lists all project skills with one-liners — quick inventory when you can't remember what's available. Distinct from the global /menu skill so the two don't collide. |