AGENTS.md

Project Identity

Project Name: ratatui_ruby-tea

Description: Part of the RatatuiRuby ecosystem.

1. Standards

STRICT REQUIREMENTS

• Every file MUST begin with an SPDX-compliant header. Use LGPL-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.

• Pre-commit: Use bundle exec 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 bundle exec agent_rake (provided by the ratatui_ruby-devtools gem) for running tests, linting, or checking compilation.

• Usage:

  • Runs default task (compile + test + lint): bundle exec agent_rake

  • Runs specific task: bundle exec agent_rake test:ruby (for example)

• Setup: bin/setup must handle Bundler dependencies.

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

Tea-Specific Vocabulary

• BANNED WORD: “component” — Reserved for Kit.

• Avoid “widget” for Tea units — “Widget” refers to Engine/Ratatui render primitives. In Tea, call them bags.

• Bag: A module containing Model, INITIAL, UPDATE, and VIEW constants. Bags compose: parent bags delegate to child bags.

• Use “model”, “update”, “view” for the MVU pattern. Use “message” (not “msg”) and “command” (not “cmd”).

Ruby Standards

• Use Data.define for all value objects (Ruby 3.2+).

• Define types in .rbs files. Don’t use untyped just because it’s easy; be comprehensive and accurate.

• Every public Ruby class/method must be documented for humans in RDoc.

2. 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.

• Format:

  • Format: Use Conventional Commits.

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

    • DON’T list the files changed or the edits made in the body.

    • DON’T use markdown syntax (no backticks, no bolding, no lists, no links).

3. Definition of Done (DoD)

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

1. Production Ready: RBS types are complete and accurate (no untyped), errors are handled with good DX, documentation follows guidelines, high code quality (no “pre-existing debt” excuses).

2. Default Rake Task Passes: Run bundle exec agent_rake (no args). Confirm it passes with ZERO errors or warnings.

3. You will save time if you run bundle exec agent_rake rubocop:autocorrect first.

4. If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.

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

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

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

8. 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.