From 3fcffad8c47121fc9f3ed8d69d778b05d6bc7c7d Mon Sep 17 00:00:00 2001 From: JawlessEel <113311129+JawlessEel@users.noreply.github.com> Date: Sat, 11 Apr 2026 15:04:49 -0500 Subject: [PATCH] Add AGENTS and prompt guidance files Introduce repository guidance and reusable prompt templates. Adds AGENTS.md with repo-local environment, command, file-safety, git, validation, and ComfyUI-specific rules. Adds PROMPT_BUG_FIX.md, PROMPT_INSPECTION.md, PROMPT_NODE_REPAIR.md, and PROMPT_PACKAGE_INSTALL.md providing focused workflows for bug fixes, repository inspection, custom node repair, and package installation audits that enforce using the repo venv, PowerShell commands, minimal safe changes, and explicit validation/reporting. --- AGENTS.md | 114 ++++++++++++++++++++++++++++++++++++++ PROMPT_BUG_FIX.md | 16 ++++++ PROMPT_INSPECTION.md | 14 +++++ PROMPT_NODE_REPAIR.md | 15 +++++ PROMPT_PACKAGE_INSTALL.md | 16 ++++++ 5 files changed, 175 insertions(+) create mode 100644 AGENTS.md create mode 100644 PROMPT_BUG_FIX.md create mode 100644 PROMPT_INSPECTION.md create mode 100644 PROMPT_NODE_REPAIR.md create mode 100644 PROMPT_PACKAGE_INSTALL.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..a7ccb29fe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,114 @@ +# AGENTS.md + +## Scope + +These instructions apply to the entire repository unless a deeper AGENTS.md overrides them. + +## Project context + +This is a standard Git-based ComfyUI repository on Windows. + +Repository root: +`C:\AI_PROJECTS\ComfyUI` + +Primary Python environment: +`C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe` + +Primary shell: +Windows PowerShell + +## Core working rules + +- Preserve existing functionality unless the user explicitly asks for redesign or removal. +- Do not remove features, nodes, scripts, launchers, or config behavior unless explicitly told. +- Fix root causes instead of patching symptoms where practical. +- Reuse and improve existing logic instead of duplicating it. +- Do not invent files, APIs, packages, results, or test outcomes. +- Do not claim something was tested unless you actually ran the test or command. +- Keep changes tightly scoped to the user’s request. +- Stay focused on the current task. Do not perform unrelated cleanup or refactors. +- Prefer additive, reversible changes. + +## Environment rules + +- Always use the repo-local Python interpreter: + `C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe` +- Never use a global Python, Conda environment, Windows Store Python, or some other interpreter unless the user explicitly asks. +- When installing packages, use: + `C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m pip ...` +- Do not use bare `pip` commands. +- Assume the repo-local venv is the source of truth unless the user says otherwise. + +## Command rules + +When giving commands or running commands: + +- Use Windows PowerShell syntax. +- Always state the working directory first. +- Prefer exact commands over summaries. +- Prefer commands that are safe to copy/paste. + +## File safety rules + +- Do not modify files outside this repository unless the user explicitly asks. +- Do not edit anything inside `venv\Lib\site-packages` unless the user explicitly asks for a local hotfix there. +- Do not delete models, outputs, checkpoints, LoRAs, embeddings, or user assets unless explicitly asked. +- Be careful with files under: + - `models\` + - `custom_nodes\` + - `user\` + - launch scripts + - config files +- Before changing behavior in `custom_nodes`, inspect that node’s current imports, dependencies, and startup assumptions. + +## Git rules + +If modifying files: + +- Work on the current branch unless the user explicitly asks for a new one. +- Do not rewrite history. +- Do not amend existing commits unless the user explicitly asks. +- Do not create commits unless the user asks for a commit. +- Show `git status` after making changes when relevant. + +## Validation rules + +After code changes, run the smallest relevant validation that actually checks the change. + +Preferred validation commands: + +- Python syntax check for a file: + `C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -m py_compile ` +- Package import check: + `C:\AI_PROJECTS\ComfyUI\venv\Scripts\python.exe -c "import ; print('ok')"` +- If the change affects startup or node imports, use the repo-local environment and validate with the relevant launch command or targeted import path when practical. +- If a full startup test is too heavy, say so clearly and run the best targeted validation available. + +## Reporting rules + +In responses: + +- State exactly which files were changed. +- State exactly which commands were run. +- State exactly what was verified and what was not verified. +- If something is risky, incomplete, or untested, say that plainly. +- Do not hide uncertainty. + +## ComfyUI-specific guidance + +- Treat startup logs as important evidence. +- When debugging node import failures, identify whether the problem is: + 1. missing package + 2. wrong package version + 3. broken path/import + 4. incompatible ComfyUI/custom-node API change + 5. GPU/CUDA/Torch mismatch +- For package fixes, prefer minimal changes over large dependency churn. +- If a custom node shells out to `pip`, prefer replacing that with interpreter-safe commands using `python -m pip` when asked to fix it. +- Be cautious about torch, CUDA, TensorRT, xformers, flash-attn, triton, sageattention, and custom kernel packages because version mismatches can destabilize the whole stack. + +## Instruction priority + +- Follow direct user instructions first. +- Then follow deeper nested AGENTS.md files if present. +- Then follow this root AGENTS.md. diff --git a/PROMPT_BUG_FIX.md b/PROMPT_BUG_FIX.md new file mode 100644 index 000000000..9bf401141 --- /dev/null +++ b/PROMPT_BUG_FIX.md @@ -0,0 +1,16 @@ +Read AGENTS.md and follow it exactly. + +Task: +Investigate and fix the specific issue I describe below with the smallest safe change possible. + +Requirements: + +- Stay within scope. +- Use the repo-local venv only. +- Do not use bare pip. +- Do not refactor unrelated code. +- Do not remove features. +- After changes, run the smallest relevant validation commands and report exact results. + +Issue: +[paste the bug here] diff --git a/PROMPT_INSPECTION.md b/PROMPT_INSPECTION.md new file mode 100644 index 000000000..79d0786e9 --- /dev/null +++ b/PROMPT_INSPECTION.md @@ -0,0 +1,14 @@ +Read AGENTS.md and inspect this repository before making changes. + +Task: +Summarize: + +1. the repo-local Python interpreter path, +2. the safest validation commands for this repo, +3. any risky directories or files, +4. whether there are additional AGENTS.md files, +5. the exact steps you would take for a small code fix without making any changes yet. + +Do not modify files. +Do not install packages. +Do not make a commit. diff --git a/PROMPT_NODE_REPAIR.md b/PROMPT_NODE_REPAIR.md new file mode 100644 index 000000000..e3b74be3f --- /dev/null +++ b/PROMPT_NODE_REPAIR.md @@ -0,0 +1,15 @@ +Read AGENTS.md and follow it exactly. + +Task: +Diagnose this custom node problem and fix only the direct cause. + +Requirements: + +- Limit changes to the relevant custom node and direct supporting files only. +- Do not change unrelated custom nodes. +- Do not upgrade broad dependency sets unless absolutely necessary. +- Use startup logs as evidence. +- Report exact files changed and exact commands run. + +Problem: +[paste startup error or traceback] diff --git a/PROMPT_PACKAGE_INSTALL.md b/PROMPT_PACKAGE_INSTALL.md new file mode 100644 index 000000000..d85ae45e2 --- /dev/null +++ b/PROMPT_PACKAGE_INSTALL.md @@ -0,0 +1,16 @@ +Read AGENTS.md and follow it exactly. + +Task: +Audit this repo for the safest way to install or repair the package(s) needed for [feature or node name]. + +Requirements: + +- Use only the repo-local interpreter. +- Prefer python -m pip commands. +- Do not install anything until you explain: + 1. what package is needed, + 2. why it is needed, + 3. what version risk exists, + 4. what command you recommend. + +Then wait for my approval before making package changes.