taletorrent/AGENTS.md

Sample AGENTS.md file

General agent workflow.

During one run in Plan mode, any part of the program on any scope can be discussed. During one run in Build mode, scope of no more than one commit should be covered. On the scope of commit, see "Git instructions" below.

Dev environment

• Use uv to manage python versions and packages.
  • uv add [package list] to add packages
  • uv run [file] to run programs.
• Do not ever use pip and python directly. Every time virtual environment isolation is broken, a kitten is thrown into a blender.
• Use ruff to check for lint and formatting.
• Use basedpyright.

Configuration

• Do not ever use environment variables to manage settings of the software you are developing.
  • To manage credentials, use the system credential manager.
  • To manage software configuration, use configuration files.
    • Note, that this excludes all forms of .env files, or other types of workarounds for using environment variables.
  • To let users temporarily disable features without modifying the configuration files, use command line parameters.
  • This rule only applies to software you are writing. That is, if an external tool requires managing environment variables, you are allowed to use them.

Code style conventions

Prefer snake case, unless directly inconsistent with external tools' code style.

Prefer descriptive but short names, that express their purpose that is not directly obvious from the code. For example, if your code contains a variable that represents a SD image generation pipeline:

• Naming it p is too short and ambiguous, and is considered prohibited practice.
• Naming it pipe or pipeline is useful to indicate the type of the variable (since python is a weakly typed language), but will likely result in confusion when multiple pipelines are present in code. Also, it is likely that it's usage in code will immediately indicate that it is a pipeline. This is considered a bad practice. (Note: it is considered a good practice to make use of python typing when type is ambiguous, or needs to be enforced).
• Naming it sd_pipeline is good to indicate type and specify that it uses Stable Diffusion, which is likely not obvious. However, due to the abundance of either actual or potential future usages of SD pipelines for purposes other than image generation (e.g. upscaling), this naming is ambiguous and does not provide sufficient information to the developer reading the code. This is considered undesirable practice.
• Naming it img_gen_pipeline is great to establish the purpose of the object, that likely isn't immediately inferable from it's usage. Although it does not disclose the type, it is likely obvious that image generator uses SD. This is considered good practice.

Writing comments is generally to be avoided, unless the code itself isn't expressive enough to convey the purpose for it's existence. YOU SHOULD NEVER WRITE COMMENTS THAT DESCRIBE WHAT CODE DOES, OR HOW IT WORKS.

Code architecture conventions

• Procedural programming is encouraged.
• Domain Driven Design is encouraged.
• All architectural decisions should be discussed with a human developer before implementation.

Git instructions

• Every commit should:
  • Be logically atomic code change (that is, the one that cannot be separated in smaller steps).
  • Contain brief description of the purpose of the change.
  • Be formatted with ruff.
  • There is no requirement for code correctness on commit level.
• Every PR should:
  • Provide a complete working feature/fix.
  • Should pass all checks with ruff.
  • Should pass all checks with basedpyright.
    • The only exceptions are expressions that:
      • Are valid, due to quirks of used libraries/tools.
      • When fixed, sacrifice code readability and/or conciseness.
  • Should pass all tests, if present.