SnapFX: Instructions file for Codex

AI Agent Definitions

These instructions are shared for all AI agents working on this workspace.

Core Workflow

• Always add or update unit tests for new behavior, bug fixes, or refactors.
• For bug fixes, first add or update a test that reproduces the issue and verify it fails before implementing the fix.
• Exception: if a bug is only reproducible via user interaction and cannot be automated yet, document manual reproduction/verification steps and add or improve logging so the failure path is observable.
• Always run unit tests after code changes when possible (./gradlew test).
• Always review STATUS.md, DONE.md, and ROADMAP.md after changes and update each file only when the change is relevant to that file's scope (STATUS = current state/open issues, DONE = completed milestones/capabilities, ROADMAP = planned/proposed work).
• Keep CHANGELOG.md up to date for release-visible changes (Unreleased during development, grouped by tags for releases).
• Update other *.md files if the change affects their content or accuracy.
• Keep changes scoped and avoid unrelated edits.
• After successful changes, prepare a small, focused commit (stage relevant files and propose a commit message).
• Always git add new files when preparing a commit.
• Before creating a commit, always show the proposed commit message to the user and get confirmation.
• Commit-message focus rule: for feature commits, describe the delivered user-visible/technical feature scope (not temporary sprint/phase labels), and do not list intermediate bug fixes encountered during feature development unless the commit is primarily a bug-fix commit.
• Keep commits minimally mixed: one logical topic/fix per commit; avoid bundling unrelated changes.
• Default to one commit per fix/feature so changes stay clearly separated and release notes remain precise.
• For fix commits, use a multi-line commit message body with at least one explanation line per fix.
• Use git-cliff-compatible commit prefixes in the subject line (feat:, fix:, docs:, test:, refactor:, perf:, ci:, build:, chore:); domain prefixes like floating:, dnd:, ui:, demo: are also allowed when they map to cliff groups.
• If a fixed collaboration rule is agreed with the user, add it to this AGENTS.md immediately.
• Treat AGENTS.md as the source of truth for all persistent collaboration rules in this workspace.
• API-to-settings parity rule: every SnapFX API function must be represented in the MainDemo Settings tab to keep manual verification accessible.
• Design-decision documentation rule: every significant design/architecture decision must be documented in JavaDoc (API/algorithm intent), in ARCHITECTURE.md (system behavior), and as an ADR file under docs/adr/.
• JavaDoc completeness rule: for every new or changed public/protected API element (class, method, enum constant, public field), add/update full JavaDoc immediately in the same change (@param, @return, @throws where applicable), run ./gradlew :snapfx-core:javadoc --rerun-tasks, and do not defer missing JavaDoc cleanup to later follow-up work.
• As soon as a focused, sensible commit is ready, proactively show the proposed commit message without waiting for the user to ask.
• If MainDemo visuals change (layout, window composition, look and feel, styling, icons, controls), always run ./scripts/update-main-demo-preview.ps1 and include the updated docs/images/main-demo.png.
• Versioning is controlled by gradle-jgitver in build.gradle.kts; do not reintroduce custom version calculators in the build script.
• Use tag-driven releases (vX.Y.Z) as the only release source of truth; do not create tags per commit.
• Maintainability-refactor tagging rule: when roughly half of the planned pre-v1.0.0 maintainability refactor scope is fully completed, create tag v0.7.0; when that refactor scope is fully completed, move project/release baseline to v0.8.0.
• Naming/package convention rule: except for SnapFX and BuildInfo, framework classes should use the Dock prefix; extracted/refactored implementation types must be placed in thematic packages (for example org.snapfx.shortcuts) instead of a catch-all org.snapfx.internal.snapfx, and related types for one concern should stay co-located in that thematic package.
• Utility packaging rule: place extracted classes in org.snapfx.util only when they are true cross-domain utilities; otherwise keep them in the most fitting thematic package for their concern.
• Branch workflow policy: while base implementation is ongoing, work directly on main; once develop exists, integrate features into develop and cut release tags from main after merge.
• Pre-release compatibility policy: until the first public Maven release, prefer best technical fixes over backward compatibility; breaking API changes are acceptable when they improve correctness/maintainability. After the first Maven release, public API compatibility becomes mandatory unless explicitly planned as a breaking release.
• Status documentation consistency rule: in STATUS.md, DONE.md, and ROADMAP.md, status bullets must always include a status icon prefix (✅, 🚧, 📋, 💡, ❌, ⚠️), never plain - Added/Updated/Completed/....
• Change-history rule: STATUS.md should stay current-state focused; versioned historical details belong in CHANGELOG.md.
• Status/DONE readability rule: keep STATUS.md as a concise current-state snapshot (no changelog/commit-style bullet history), keep DONE.md at milestone level only, and keep per-test-case breakdowns/count churn out of both files (details belong in CI output, test reports, or CHANGELOG.md when release-relevant).
• Refactor-progress documentation rule: during ongoing multi-step refactor tracks, do not log each implementation slice in STATUS.md or ROADMAP.md; keep both files high-level and update them at milestone/phase boundaries or when the tracked refactor scope is completed.
• Changelog style rule: write CHANGELOG.md entries in concise release-note style (grouped outcomes), not as step-by-step internal worklog/task-sequencing bullets.
• Changelog category rule: structure Unreleased (and new release sections going forward) using git-cliff-style categories in this order (include applicable sections only): Features, Fixes, UI and Interaction, Refactoring, Tests, Documentation, Build and Tooling, Other Changes.
• Changelog scope rule: do not add AGENTS.md-only collaboration/workflow rule changes to CHANGELOG.md; keep those developer-internal rule updates out of release notes.
• Markdown encoding rule: preserve UTF-8 and avoid shell text-rewrite commands that can alter Unicode; prefer apply_patch for markdown edits.
• Temporary-file rule: markdown files matching *_temp.md are local working notes only, must not be committed, and must not be referenced from repository status/history docs.
• Diff minimization rule: for all file changes, prefer minimal targeted edits and avoid full-file rewrites when smaller diffs are sufficient; only rewrite entire files when explicitly requested or technically required.
• Logic deduplication rule: when new behavior overlaps existing behavior (for example restore/fallback flows), reuse or extract the existing implementation path instead of re-implementing parallel logic.
• Unicode escape readability rule: when icon constants use \u... notation in code, add an inline comment showing the rendered icon.