malkuthro-ComfyUI-Koolook/AGENTS.md

ComfyUI-Koolook Codex Instructions

Required Project Context

Read CLAUDE.md before making substantive changes. It contains the project-specific workflow, dev-sync rules, release rules, and sidebar maintenance notes.

Test Environment Bootstrap

Use scripts\bootstrap_test_env.ps1 (Windows) or bash scripts/bootstrap_test_env.sh (POSIX) to create .venv and install test deps. Never install into system Python. Full rule in CLAUDE.md § Hard rules.

External Repository Boundary

If a user request appears to involve files, workflows, repositories, or publishing targets that are not present in this repository, stop and confirm the exact target before acting. Dictation typos and shorthand are common; do not infer a sibling repository or revive old local workflows from broad filesystem search results without explicit user confirmation.

Disk Safety Boundary

Never delete, move, rename, or edit files outside this repository. External paths may be read only when the user explicitly provides them for inspection or copying into the repository. Any destructive or modifying action outside the repo is forbidden; stop and ask the user to perform it manually instead.

Ambiguity Safety Boundary

If an instruction is unclear, contradictory, unusually destructive, or seems to conflict with the user's broader intent, do not execute it literally. Stop, explain the ambiguity in plain language, and ask for confirmation before acting. This is especially important for filesystem operations, sync targets, workflow paths, and anything outside the repository.

Review Session Default

When running a PR review for this repository, approve by default if the review finds no actionable concerns that need to be flagged. If the review finds blockers, risks, missing validation, or anything that needs maintainer judgment, flag those items clearly to the user instead of approving silently.

Visual QA Is Mandatory For UI Work

For any change that affects rendered UI, guide pages, screenshots, CSS/layout, onboarding docs, or browser-visible behavior:

1. Do not rely on CSS coordinates, source inspection, or user screenshots alone.
2. Open the changed page/app in a browser-rendered environment that Codex can screenshot.
3. If a file:// guide page is blocked by browser tooling, serve the repo over local HTTP instead, for example: python3 -m http.server <port> from the repo root, then open http://127.0.0.1:<port>/....
4. Take a rendered screenshot after the change and inspect the actual visual result before committing or pushing.
5. If visual verification is blocked, say that clearly and do not present the UI change as ready unless the user explicitly waives visual QA.

This is especially important for overlays, icon highlights, responsive layout, text fitting, and visual guide pages.