Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (79 loc) · 4.31 KB

AGENTS.md

File metadata and controls

92 lines (79 loc) · 4.31 KB
Raw

AGENTS.md

This file is the operating map for agents working in this repo. Keep product framing in README.md, durable architecture in docs/, and usage guidance in skills/termviz/SKILL.md.

Source Map

  • src/bin/termviz.rs and src/bin/tvz.rs: binary entrypoints.
  • src/cli.rs: CLI dispatch and command behavior.
  • src/profile.rs: input profile detection and option resolution.
  • src/input/: input sniffing and loading.
  • src/asset/: raster/SVG asset metadata and decoding boundaries.
  • src/plot/: plot parsing, model, stream, table, and histogram logic.
  • src/render/: terminal rendering and protocol backends.
  • src/viewer/: interactive viewer behavior.
  • src/viewer/plot/: plot viewer state, atlas/cache, events, hover, and chrome.
  • src/tui.rs and src/tui/: TUI shell and chrome/frame rendering.
  • docs/INDEX.md: maintainer navigation.
  • docs/architecture.md: module boundaries and product constraints.
  • docs/testing.md: test organization and PTY/protocol coverage.
  • docs/visual-verification.md: recording and contact-sheet workflow.
  • docs/releasing.md: release and packaging process.
  • skills/termviz/SKILL.md: concise agent-facing usage guide.

Engineering Invariants

  • Keep termviz viewer-first and terminal-first.
  • Keep stdout valid and scriptable; hide terminal escape sequences behind TTY detection or explicit flags.
  • Do not decode or render whole large assets just to draw the first screen.
  • Prefer metadata-first loading, tile readback, bounded plot windows, temporary files, and explicit preloading.
  • Keep image decoding separate from terminal rendering.
  • Keep plot data parsing separate from plot scene/raster rendering.
  • Add terminal protocols as backend implementations, not product branches.
  • If whole-file parsing or whole-image decoding is required, make that tradeoff explicit in CLI help or docs.

Task Routing

  • Unknown task: read README.md, docs/INDEX.md, then the matching doc below.
  • Architecture, module boundaries, terminal protocols, plot model, or asset loading: read docs/architecture.md.
  • TUI rendering, screenshots, recordings, or visual demos: read docs/visual-verification.md.
  • Test organization, protocol coverage, selector behavior, or PTY smoke: read docs/testing.md.
  • Release, packaging, crates.io, npm, GitHub Releases, or version tags: read docs/releasing.md.
  • User-facing usage, install steps, CLI flags, or export behavior: check skills/termviz/SKILL.md as well as README.md.

Verification

  • Run cargo fmt.
  • Run cargo test.
  • Run cargo clippy --all-targets -- -D warnings when Clippy is available.
  • After implementing a user-facing command or viewer behavior, run the exact command path, or the closest faithful fixture command, before reporting completion.
  • For TUI changes, run the built CLI under a real PTY such as script and verify draw, resize, scroll, and quit behavior.
  • For visual TUI or block-rendering changes, create PTY recording artifacts with scripts/record-pty-demo.sh, inspect keyframes or contact-sheet.png, and keep the path in the handoff.
  • For Kitty or pixel-protocol visual changes, create real emulator recording artifacts with scripts/record-emulator-demo.sh, inspect frames or contact-sheet.png, and keep the path in the handoff.
  • For terminal protocol changes, verify protocol output does not appear on redirected stdout unless explicitly requested.
  • For protocol renderer or viewer changes, cover every explicit protocol at the appropriate test layer; keep auto tests focused on selector behavior.
  • For large-file behavior, add or update benchmark scripts before claiming the implementation is bounded.

Docs Update Rules

  • CLI flags, install steps, or user-visible behavior: update README.md.
  • User-facing usage patterns: update skills/termviz/SKILL.md.
  • Architecture, module boundary, protocol, or artifact policy: update docs/architecture.md.
  • Test strategy or coverage requirements: update docs/testing.md.
  • Visual verification workflow: update docs/visual-verification.md.
  • Release, packaging, or artifact policy: update docs/releasing.md.
  • User-facing behavior, packaging, or release process: update CHANGELOG.md.

Commit Rules

  • Use Conventional Commits with a body.
  • Keep release notes current before tagging.
  • Do not revert unrelated user changes.