Add AGENTS.md

This commit is contained in:
Greg Shuflin committed 2025-09-29 01:36:29 -07:00
1 parent 2be31a59e8
commit ccce25f050
1 file changed
+85
+85
View File
@@ -0,0 +1,85 @@
## AGENTS.md — Project Guidance for AI/Cursor Agents (Aug 2025)
This file is the authoritative context for AI assistants working on this repository.
### Project Overview
Modern Rust, cross‑platform GUI utility for viewing and batch‑renaming image files. Must support animated GIF playback.
### Primary Objectives
- Fast, smooth image viewing (jpeg, png, webp, gif), including animated GIFs with correct timing/looping.
- Ergonomic single and batch renaming with live preview and conflict detection.
- Native, first‑class support on Linux, macOS, and Windows.
### Explicit Non‑Goals (current)
- Network features (sync/telemetry) unless explicitly enabled.
- Heavy image editing. Lightweight transforms (rotate/flip) are acceptable.
## Tech & Build
- Language: Rust (stable)
- GUI: Native desktop (see `src/main.rs`)
- OS targets: Linux, macOS, Windows
- Build: Cargo
Commands:
- Build: `cargo build`
- Release: `cargo build --release`
- Run: `cargo run -- <args>`
### Planned CLI
- `image-viewer [PATH]` — open target folder or image
- `--recursive` — include subdirectories
- `--readonly` — disable rename operations
## Operating Principles for Agents
1. Keep the UI responsive. Offload I/O, decoding, and directory scans off the main/UI thread.
2. Prefer incremental/lazy loading for large directories (10k+ files). Avoid blocking operations.
3. Renames must be safe by default: dry‑run and preview before commit; use atomic file moves when supported.
4. Memory‑wise: reuse decoders/thumbnails; avoid loading full‑resolution frames unless necessary.
5. Platform quirks matter: case sensitivity, path length, invalid characters differ by OS. Call these out in PRs.
6. Logging: human‑friendly messages in UI; verbose logs only with a flag.
7. Privacy: no network I/O by default; any remote call must be opt‑in and documented.
## Tasks You May Autonomously Perform
- Add/extend modules for image loading, GIF playback, directory scanning, and rename planning/execution.
- Improve responsiveness via async/workers; remove blocking calls from event handlers.
- Add tests for rename plans, conflict detection, and animated GIF timing.
- Introduce keyboard shortcuts and accessible UI affordances.
## Constraints & Success Criteria
- Large folders (≥10k files) remain navigable; no main‑thread stalls over ~16ms per frame.
- Animated GIF playback honors per‑frame delays and loops.
- Rename plans are conflict‑free and reversible if any step fails.
- `clippy` and `rustfmt` clean; avoid unsafe unless justified.
## Module Sketch (evolving)
- `src/main.rs` — entry point, bootstrap, arg parsing
- `src/ui/` — views, components, global/local state
- `src/image/` — loaders, decoders, metadata, GIF playback
- `src/rename/` — planning, validation, execution, rollback
- `src/fs/` — directory scanning, platform specifics
## Testing Guidance
- Unit tests: filename normalization/sanitization, conflict graphs, atomic move fallbacks.
- Snapshot tests: rename plans for representative sample directories.
- Integration: CLI flags, basic viewer flows, GIF timing (coarse validation acceptable).
## Acceptance Criteria Template
- Functionality: expected behavior + edge cases.
- Performance: bounds for N files in a directory and scroll/thumbnail latency.
- UX: keyboard shortcuts, focus management, error surfaces.
- Tests: unit/integration assertions you added or updated.
## Safeguards for Renaming
- Always compute a dry‑run plan with a full before→after mapping.
- Detect and surface collisions, cycles, and cross‑device moves.
- Use temporary names/atomic swaps where needed; ensure rollback on partial failure.
## Decision Log (append newest first)
- [2025-09-29] Adopted `AGENTS.md` as the canonical AI guidance; supersedes `CONTEXT.md`.
## Quickstart Prompts for Agents
- "Add a rename preview dialog with conflict highlights and confirm/cancel."
- "Move directory scanning to a background worker and stream results to the UI."
- "Implement animated GIF playback with correct frame timing and loop count."