Article Or Announcement

Use this skill for outward-facing writing that is not core README maintenance.

Rules

• Keep technical claims aligned with the current README and implementation.
• Avoid promising model hosting, weights, or platform support that this repo does not provide.
• For English replies, keep wording natural and concise; do not over-explain the internal development process.
• For Hugging Face / ModelScope / article drafts, distinguish this custom node from downstream models such as Wan/VACE.

Source Material

• README.md
• README_ja.md
• docs/adr/
• example_workflows/

ComfyUI Node Change

Use this skill for changes under nodes/ or __init__.py that affect node behavior or ComfyUI schema.

Read First

• AGENTS.md
• Relevant docs/requirements/*.md
• Relevant docs/adr/*.md
• Existing Classic and Flow implementations if the change touches shared behavior

Rules

• Preserve graph compatibility unless the user explicitly approves a break.
• Keep node_id, socket names, socket order, defaults, categories, and metadata stable when possible.
• Prefer shared helpers only when both Classic and Flow genuinely use the same behavior.
• Keep ComfyUI imports at the node boundary where possible. Pure math and parsing helpers should remain testable without a ComfyUI runtime.
• Validate inputs early and return clear errors or safe fallback output.

Checks

Run:

python3 scripts/validate_repo.py

When a ComfyUI environment is available, also load the node in ComfyUI and exercise at least one small workflow.

Dependency Audit

Use this skill when investigating runtime dependencies or environment drift.

Focus Areas

• Direct imports in nodes/ and __init__.py.
• Declared dependencies in pyproject.toml.
• What ComfyUI itself installs versus what this package must declare.
• Difference between standard OpenCV and contrib OpenCV.
• Shared venv accidents: a package may import locally because another custom node installed it, not because this repo declared it.

OpenCV Notes

• cv2.DISOpticalFlow may exist in standard OpenCV builds.
• cv2.optflow is part of OpenCV contrib/extra modules in common Python wheels.
• TV-L1 fallback should not assume cv2.optflow exists.

Useful Commands

python3 -m pip show opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless kornia
python3 -c "import cv2; print(cv2.__version__, cv2.__file__, hasattr(cv2, 'DISOpticalFlow'), hasattr(cv2, 'optflow'))"
python3 scripts/validate_repo.py

Docs Sync

Use this skill when behavior, schema, dependencies, workflow samples, or release metadata changes.

What To Sync

• README.md and README_ja.md should describe the same public behavior.
• docs/requirements/ should state the intended behavior and acceptance criteria.
• docs/adr/ should record significant design decisions, especially compatibility or fallback changes.
• pyproject.toml version/dependencies should match release and runtime behavior.

Rules

• Keep README concise and user-facing.
• Put implementation rationale in ADRs, not the README.
• Do not document fallback behavior that the code does not actually implement.
• Keep local workflow links valid.

Checks

python3 scripts/validate_repo.py

PR Readiness Check

Use this skill right before commit/push/PR creation, especially after adding new files, validation scripts, nodes, docs, or workflows.

Checklist

1. Inspect branch and file state:

git status -sb
git diff --stat
git diff --cached --stat
git ls-files --others --exclude-standard

2. Verify new files are intentionally included.

• If code imports a new module, confirm the module is tracked or staged.
• If validation references a new script, confirm the script is tracked or staged.
• Do not rely on git diff alone; it does not show untracked files.

3. Check staged scope before commit.

git diff --cached --name-only

• Stage explicit paths when the worktree is mixed.
• Do not use broad staging if unrelated user changes are present.

4. Run validation in the environment that has runtime dependencies.

python3 scripts/validate_repo.py
python3 -m compileall nodes scripts

If plain python3 lacks declared runtime dependencies such as OpenCV, also run the checks with the available ComfyUI venv and report the environment difference.

5. Before opening a PR:

• Confirm the PR title has no [codex], [claude], or similar tool label.
• Link related issues without closing them unless the user explicitly asks: use Related: #N, not Fixes #N / Closes #N.
• Confirm the pushed branch contains the latest local commit.

When Reporting

Mention:

• branch and latest commit
• whether untracked files remain
• validation commands and results
• any skipped review finding and why

Release Check

Use this skill before release-oriented work.

Checklist

• Confirm pyproject.toml version.
• Confirm runtime dependencies are declared.
• Confirm README / README_ja reflect current behavior.
• Confirm example_workflows/*.json parse and reference current node ids.
• Confirm .github/workflows/publish_action.yml still publishes only intended changes.
• Run python3 scripts/validate_repo.py.
• If creating a PR, do not prefix the title with [codex], [claude], or any other tool label.

Notes

This repo currently publishes to Comfy Registry when pyproject.toml changes on main, or via manual workflow dispatch.

Stabilizer Backend Change

Use this skill for work on feature tracking, dense optical flow, DIS/TV-L1, transform fitting, smoothing, crop handling, or fallback behavior.

Context

• Classic estimates sparse feature motion with OpenCV GFTT/LK.
• Flow normally uses OpenCV DIS optical flow.
• cv2.optflow is not available in standard OpenCV wheels; TV-L1 requires contrib OpenCV or an equivalent available API.
• Existing sample workflows use the Flow node.

Rules

• Do not assume cv2 or cv2.optflow exists unless declared and checked.
• If a stronger backend is unavailable, prefer safe fallback: perspective -> similarity -> translation -> identity.
• Keep fallback metadata auditable (flow_backend, applied transform mode, confidence/residual data where available).
• Preserve deterministic behavior for identical frames and inputs.
• Avoid GPU-only dependencies; this node is CPU-oriented.

Useful Checks

python3 scripts/validate_repo.py
python3 -c "import cv2; print(cv2.__version__, hasattr(cv2, 'DISOpticalFlow'), hasattr(cv2, 'optflow'))"

If using a ComfyUI venv, run the cv2 check inside that venv too.

Workflow Update

Use this skill for example_workflows/*.json and README workflow links.

Rules

• Keep workflow JSON valid and formatted as ComfyUI can load it.
• Preserve sample intent: VACE/outpainting examples should demonstrate using padding_mask from the stabilizer.
• Check that workflows reference current node ids: video_stabilizer_classic and/or video_stabilizer_flow.
• Avoid embedding local machine paths unless they are already part of the sample and the user intentionally wants them preserved.
• Update README and README_ja links when sample filenames change.

Checks

python3 scripts/check_workflows.py
python3 scripts/validate_repo.py