Skip to content

AGENTS.md

Latest commit

 

History

History
121 lines (101 loc) · 4.25 KB

AGENTS.md

File metadata and controls

121 lines (101 loc) · 4.25 KB

AGENTS.md

Purpose

Reusable PureBasic module for loading images through FreeImage.dll and saving the loaded image as PNG or WebP.
Includes a small demo under CompilerIf #PB_Compiler_IsMainFile.

Core Goal

  • keep the module small, readable, and fully working
  • preserve the stable load/save workflow
  • keep the demo useful, but secondary to the module

Current State

  • core module works
  • demo works
  • WebP quality and lossless save work
  • external dependency is required: FreeImage.dll

Key Files

  • Mod_FreeImage_Wrapper_WebP.pbi = main module and demo
  • README.md = project overview and setup
  • THIRD_PARTY.md = FreeImage dependency and license notes

Requirements

  • Target OS: Windows
  • Language: PureBasic
  • External dependency: FreeImage.dll
  • Offline local tool / module
  • No installer required
  • Demo expects FreeImage.dll in the working directory or next to the executable

Project Style

  • module-based PureBasic code
  • practical structure over abstraction
  • single-file module with built-in demo
  • readable event handling
  • minimal public API
  • avoid unnecessary extra files

Code Rules

  • use EnableExplicit
  • preserve DeclareModule / Module structure
  • keep module interface clean
  • use Shared consistently for module-level structures/vars in procedures
  • keep functions focused
  • avoid duplicate helper logic
  • remove unused constants, variables, and declared procedures when safe
  • do not add speculative abstractions

Architecture Notes

Module Structure

  • the reusable code is the module
  • the demo block is only an example and test UI
  • the demo must not define the module architecture

State Model

  • module state is held in shared structures
  • loaded image state and FreeImage API state are persistent inside the module

Demo Boundary

  • code under CompilerIf #PB_Compiler_IsMainFile is demo/test code only
  • demo changes must not break the reusable module API
  • module improvements should be implemented in the module first, not only in the demo

Dependency Rules

  • FreeImage.dll is an external dependency
  • do not bundle third-party binaries into the repository unless explicitly requested
  • document dependency usage clearly in README and THIRD_PARTY
  • do not replace FreeImage with another dependency unless explicitly requested

Debugging Rules

  • isolate the failing step first
  • use short targeted debug output
  • prefer minimal fixes over rewrites
  • remove temporary debug traces after the fix unless still useful for the demo
  • keep error messages concrete

Documentation Rules

  • keep README short and scannable
  • keep THIRD_PARTY.md factual and transparent
  • public module releases should include a small working demo
  • document external dependency setup clearly
  • do not repeat the same information across README and THIRD_PARTY more than necessary

Release Rules

  • keep public releases focused
  • release only working code
  • include README and third-party notice
  • do not publish unfinished refactors as stable versions
  • keep the public API stable unless a change is explicitly intended

Change Policy

  • prefer minimal changes
  • preserve working behavior
  • avoid broad rewrites
  • do not reformat unrelated code during functional edits
  • keep the module usable as a drop-in example

Agent Workflow Rules

  • ALWAYS treat the module as the primary code and the demo as secondary example code.

  • ALWAYS preserve existing project style unless a change is explicitly requested.

  • ALWAYS prefer the smallest correct change over a broad rewrite.

  • ALWAYS verify whether the requested feature already partially exists.

  • DO NOT refactor stable working logic unless explicitly asked.

  • DO NOT move core module logic into the demo block.

  • DO NOT treat the demo block as the reusable API.

  • DO NOT add new dependencies unless clearly necessary.

  • DO NOT silently change file formats, naming conventions, or save behavior.

  • CHECK for existing constants before hardcoding values.

  • CHECK for Shared access to module-level structures/variables inside procedures.

  • CHECK for unused defined variables and unused declared procedures before finalizing changes.

What To Avoid

  • unnecessary rewrites
  • duplicate helper functions
  • over-abstracted architecture
  • demo-only fixes that ignore the module
  • undocumented dependency changes
  • dead code left behind