Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (85 loc) · 4.66 KB

AGENTS.md

File metadata and controls

108 lines (85 loc) · 4.66 KB
Raw

AGENTS.md

Onboarding notes for anyone (human or automated agent) making changes to comfy-cli — a Python/Typer CLI for installing and running ComfyUI. This is a quick-start; see CONTRIBUTING.md for the fuller development and contribution guide.

Setup

Requires Python >= 3.10 (CI targets 3.10, the minimum supported version). Install the package with its dev extras in editable mode:

pip install -e '.[dev]'

This pulls in the runtime dependencies plus the dev toolchain (ruff, pytest, pytest-cov, pre-commit, jsonschema).

Verify your changes

Before opening a PR, run the same three checks CI enforces:

ruff check .            # lint
ruff format --check .   # formatting (CI runs `ruff format --diff`)
pytest                  # unit tests

All three must pass. Keep changes formatted with ruff format and imports sorted (ruff's isort rules are enabled) so the format check stays green.

pre-commit

The repo ships a pre-commit config that runs ruff (lint

  • format) and a few file hygiene hooks on every commit. Install it once so commits are auto-checked:
pre-commit install

Branching

The default branch is main — branch off main and open PRs against it.

Gotcha: a local checkout may already sit on a working branch (e.g. agent-cli), not main. Don't assume the current branch is the base. Create your branch (or worktree) off origin/main explicitly:

git fetch origin
git switch -c my-feature origin/main
# or, without disturbing the current checkout:
git worktree add ../comfy-cli-my-feature -b my-feature origin/main

Conventions

  • Use typer for command/argument handling and rich for console output.
  • New commands are registered in comfy_cli/cmdline.py; subcommands live under comfy_cli/command/<name>/. See CONTRIBUTING.md for the boilerplate.
  • End-to-end tests are disabled by default; enable them with TEST_E2E=true pytest tests/e2e/ (see docs/TESTING-e2e.md).

Architecture Decision Records

Architectural decisions live in docs/adr/. Code changes must be consistent with accepted ADRs. Proposed ADRs express design direction and should be treated as guidance during review. See .agents/checks/adr-compliance.md for the automated review rules.

Comfy repositories standardize the ADR behavior: canonical records, identifier and status semantics, review expectations, and supersession history should mean the same thing everywhere. Each repository implements validation and CI with its native toolchain. In this Python repository that means scripts/check_adrs.py, pytest, pre-commit, and GitHub Actions; do not copy a TypeScript validator merely to make the implementation identical to another repository.

Write an ADR when a decision establishes a durable boundary, invariant, data ownership rule, compatibility contract, or dependency choice. Keep transient implementation details in the PR instead. Capture the context, alternatives, tradeoffs, and consequences that a future maintainer cannot infer from code. Start from docs/adr/TEMPLATE.md. Its Context, Decision, Alternatives considered, What we reject, Consequences, Validation, and Revisit triggers sections are recommended review guidance, not a schema enforced by the validator; concise records may adapt them when that makes the decision clearer. Relate an ADR to earlier records with Builds on, Refines, Amends, or Supersedes and state what remains true. An Accepted decision remains binding until its replacement is also Accepted; a Proposed replacement is review context, not permission to contradict it.

The validator tests are this repository's native replay of the shared conformance cases: exact status values, real calendar dates, full-identifier collisions, companion ownership, and direct/reference-style supersession links. A workflow run is not itself proof that the ADR check is configured as a required merge gate.

ADR files are named <DOMAIN>[-<SUBDOMAIN>]-<NNNN>-descriptive-title.md: use at most two broad-to-narrow tags, with the owning subsystem first, followed by the next unused four-digit sequence number. Each ADR opens with # ADR-<IDENTIFIER>: Title, a Date: YYYY-MM-DD line, and a ## Status section whose value is Proposed, Accepted, Rejected, Deprecated, or Superseded. Run python scripts/check_adrs.py; CI and pre-commit enforce the filename, metadata, identifier uniqueness, companion-directory naming, non-legacy references, and ADR-link integrity. There is deliberately no manually maintained index; list docs/adr/ to discover records.