AGENTS.md

Project Identity

Project Name: ratatui_ruby

Description: A high-performance Ruby wrapper for the Ratatui TUI library.

Architecture:

• Frontend (Ruby): Pure Data objects (Ruby 3.2+) used in Frames and/or defining the View Tree. Immediate mode.

• Backend (Rust): A generic renderer using ratatui and magnus that traverses the Ruby Data tree and renders to the terminal buffer.

Stability & Compatibility

• Project Status: Pre-1.0.

• User Base: First external users (as of 2026-01-03).

• Breaking Changes: Backward compatibility is NOT YET a priority. Since there are few external users, you are encouraged to refactor APIs for better ergonomics and performance even if it breaks existing code. This will when we ship v1.0.0.

• Requirement: All breaking changes MUST be explicitly documented in the CHANGELOG.md’s Unreleased section to ensure transparency as the project evolves toward 1.0. Migration guides MUST be included in doc/ when we release a new minor version.

1. Standards

STRICT REQUIREMENTS

• Every file MUST begin with an SPDX-compliant header. Use AGPL-3.0-or-later for code; CC-BY-SA-4.0 for documentation. reuse annotate can help you generate the header. For Ruby files, wrap SPDX comments in – / ++ to hide them from RDoc output.

• Every line of Ruby MUST be covered by tests that would stand up to mutation testing.

• Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code “doesn’t crash” is insufficient and unacceptable.

• Prefer snapshot tests (assert_snapshots, plural) over manual buffer_content assertions for UI widgets. Snapshots are self-documenting and easier to maintain.

• For UI widgets, use with_test_terminal and snapshot assertions to verify terminal buffer content.

• Every line of Rust MUST be covered by tests that would stand up to mutation testing.

• Tests must be meaningful; simply verifying that code “doesn’t crash” or “compiles” is insufficient and unacceptable.

• Each widget implementation must have a tests module with unit tests verifying basic rendering.

• Pre-commit: Use bin/agent_rake to ensure commit-readiness. See Tools for detailed instructions.

• Git Pager: ALWAYS set PAGER=cat for ALL git commands (e.g., PAGER=cat git diff). This is mandatory.

Tools

• NEVER run bundle exec rake directly. NEVER run bundle exec ruby -Ilib:test ... directly.

• ALWAYS use bin/agent_rake for running tests, linting, or checking compilation.

• Usage:

  • Runs default task (compile + test + lint): bin/agent_rake

  • Runs specific task: bin/agent_rake test:ruby (for example)

• Snapshot Testing: When tests fail due to intentional behavior changes (not bugs), update snapshots:

• Command: UPDATE_SNAPSHOTS=1 bin/agent_rake test:ruby

• This regenerates all snapshot/*{txt,ansi} files to match current output

• When to use: After modifying widget rendering, changing default values, or updating UI behavior

• When NOT to use: For actual test failures that indicate bugs in your code

• After updating, verify the changes make sense by reviewing the diff of .snapshot files

• Setup: bin/setup must handle both Bundler and Cargo dependencies.

• Git: ALWAYS set PAGER=cat with git, git, etc.. THIS IS CRITICAL!

• Rake: Our rake tasks use git ls-files, so errors happen when you move or delete files. In this case, ask the user to stage changes for you.

Ruby Standards

• Use Data.define for all value objects (UI Nodes). (Prefer class Foo < Data.define() over Foo = Data.define() do).

• Define types in .rbs files. Don’t use untyped just because it’s easy; be comprehensive and accurate. Do not include initialize in .rbs files; use self.new for constructors instead.

• Every public Ruby class/method must be documented for humans in RDoc (preferred)–not YARD–or markdown files (fallback), and must have *.rbs types defined.

• Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.

• Rust-backed methods: For methods implemented in Rust (magnus bindings), use RDoc directives instead of empty method bodies. Use ## followed by :method:, :call-seq:, and prose. End with (Native method implemented in Rust). See lib/ratatui_ruby.rb for examples.

• Refer to docs/contributors/design/ruby_frontend.md for detailed design philosophy regarding the Immediate Mode paradigm including Data-Driven UI and Frames.

Rust Standards

• Crate Type: cdylib.

• Bindings: Use magnus.

• Platform: Support macOS (Apple Silicon), Linux, and Windows.

• Refer to docs/contributors/design/rust_backend.md for detailed implementation guidelines, module structure, and rendering logic.

2. Directory Structure Convention

The project follows a standard Gem layout with an ext/ directory for Rust code and examples/ for example application-level code.

3. Configuration & Tooling

Development Environment

• Scripting Preference: Simple sed or shell one-liners are fine. When a one-off script grows to multiple lines of logic, prefer a temporary rake task or ruby -e '...' over a multi-line shell script in a string. Ruby’s File.read/File.write, Dir.glob, and regex handle complex transformations more cleanly.

Documentation

• The doc/ folder contains source markdown files that are included in RDoc output.

• Documentation should separate “User Guide” (Ruby API for TUI developers) from “Contributor Guide” (Ruby/Rust/Magnus internals).

• Files within doc/contributors/ are for library developers.

• Files within doc/ outside of conttributors/ are for application developers and users of this RubyGEm.

• Style Guide: You MUST follow the Documentation Style Guide. This dictates the Alexandrian/Zinsser prose style and strict RDoc formatting required for all public API documentation.

• DON’T write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate. DO use RDoc and rustdoc for documentation.

4. Committing

• Who commits: DON’T stage (DON’T git add) unless explicitly instructed. DON’T commit unless explicitly instructed. DO suggest a commit message when you finish, even if not instructed..

• When: Before reporting the task as complete to the user, suggest the commit message.

• What: Consider not what you remember, but EVERYTHING in the git diff and git diff --cached.

• Format:

  • Format: Use Conventional Commits.

  • Body: Explanation if necessary (wrap at 72 chars).

    • Explain why this is the implementation, as opposed to other possible implementations.

    • Skip the body entirely if it’s rote, a duplication of the diff, or otherwise unhelpful.

    • DON’T list the files changed or the edits made in the body. Don’t provide a bulleted list of changes. Use prose to explain the problem and the solution.

    • DON’T use markdown syntax (no backticks, no bolding, no lists, no links). The commit message must be plain text.

• Type conventions by directory:

  • lib/, ext/, sig/: Use feat, fix, refactor, perf as appropriate.

  • bin/, tasks/, .builds/, CI/CD: Always chore (internal tooling).

  • examples/: Always docs (documentation by example).

  • test/: Use test for new/changed tests, or match the type of the code being tested.

  • doc/: Always docs.

5. Changelog

• Follow Semantic Versioning

• Follow the Keep a Changelog specification.

• What belongs in CHANGELOG: Only changes that affect application developers or higher-level library developers who use or depend on ratatui_ruby:

  • New public APIs or widget parameters

  • Backwards-incompatible type signature changes, or behavioral additions to type signature changes

  • Observable behavior changes (rendering, styling, layout)

  • Deprecations and removals

  • Breaking changes

• What does NOT belong in CHANGELOG: Internal or non-behavioral changes that don’t affect downstream users:

  • Test additions or improvements

  • Documentation updates, RDoc fixes, markdown clarifications

  • Refactors of internal code

  • New or modified example code

  • Internal tooling, CI/CD, or build configuration changes

  • Code style or linting changes

  • Performance improvements that affect applications

• Changelogs should be useful to downstream developers (both app and library developers), not simple restatements of diffs or commit messages.

• The Unreleased section MUST be considered “since the last git tag”. Therefore, if a change was done in one commit and undone in another (both since the last tag), the second commit should remove its changelog entry.

• Location: New entries ALWAYS go in ## [Unreleased]. Never edit past version sections (e.g., ## [0.4.0])—those are frozen history.

6. Definition of Done (DoD)

Before considering a task complete and returning control to the user, you MUST ensure:

1. Default Rake Task Passes: Run bin/agent_rake (no args). Confirm it passes with ZERO errors or warnings.

2. You will save time if you run bin/agent_rake rubocop:autocorrect first.

3. If you think the build is looking for deleted files, it is not. Instead, explain to the user why staging is needed and use the run_command tool with git add -A so they get a Run button with context.

4. Documentation Updated: If public APIs or observable behavior changed, update relevant RDoc, rustdoc, doc/ files, README.md, and/or ratatui_ruby-wiki files.

5. Changelog Updated: If public APIs, observable behavior, or gemspec dependencies have changed, update CHANGELOG.md’s Unreleased section.

6. Commit Message Suggested: You MUST ensure the final message to the user includes a suggested commit message block. This is NOT optional.

7. You MUST also check git log -n1 to see the current standard AI footer (“Generated with” and “Co-Authored-By”) and include it in your suggested message.