ratatui_ruby-devtools 0.1.0

data/lib/ratatui_ruby/devtools/tasks/license.rake

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+namespace :license do
+  namespace :headers do
+    desc "Ensure markdown files have correct CC-BY-SA-4.0 headers"
+    task :md, [:files] do |_t, args|
+      files = args[:files] || ""
+      ruby "tasks/license/headers_md.rb #{files}"
+    end
+
+    desc "Ensure Ruby files have correct AGPL-3.0-or-later headers"
+    task :rb, [:files] do |_t, args|
+      files = args[:files] || ""
+      ruby "tasks/license/headers_rb.rb #{files}"
+    end
+
+    desc "Ensure all files have correct license headers"
+    task :all do
+      Rake::Task["license:headers:md"].invoke
+      Rake::Task["license:headers:rb"].invoke
+    end
+  end
+
+  namespace :snippets do
+    desc "Add MIT-0 SPDX snippet headers to markdown fenced code blocks"
+    task :md, [:files] do |_t, args|
+      files = args[:files] || ""
+      ruby "tasks/license/snippets_md.rb #{files}"
+    end
+
+    desc "Add MIT-0 SPDX snippet headers to RDoc code examples in Ruby files"
+    task :rdoc, [:files] do |_t, args|
+      files = args[:files] || "lib/"
+      ruby "tasks/license/snippets_rdoc.rb #{files}"
+    end
+
+    desc "Add MIT-0 SPDX snippet headers to all code examples"
+    task :all do
+      Rake::Task["license:snippets:md"].invoke
+      Rake::Task["license:snippets:rdoc"].invoke
+    end
+  end
+
+  desc "Run all license tasks (headers + snippets)"
+  task all: ["headers:all", "snippets:all"]
+
+  desc "Run license tasks on changed files only (staged + unstaged)"
+  task :new do
+    # Get changed .md and .rb files (staged and unstaged)
+    changed_md = `git diff --name-only --diff-filter=ACMR HEAD -- '*.md' 2>/dev/null`.split("\n")
+    staged_md = `git diff --name-only --cached --diff-filter=ACMR -- '*.md' 2>/dev/null`.split("\n")
+    changed_rb = `git diff --name-only --diff-filter=ACMR HEAD -- '*.rb' 2>/dev/null`.split("\n")
+    staged_rb = `git diff --name-only --cached --diff-filter=ACMR -- '*.rb' 2>/dev/null`.split("\n")
+
+    # Also get untracked new files
+    untracked = `git ls-files --others --exclude-standard`.split("\n")
+    untracked_md = untracked.select { |f| f.end_with?(".md") }
+    untracked_rb = untracked.select { |f| f.end_with?(".rb") }
+
+    md_files = (changed_md + staged_md + untracked_md).uniq.join(" ")
+    rb_files = (changed_rb + staged_rb + untracked_rb).uniq
+
+    # Filter rb files to only lib/
+    lib_rb_files = rb_files.select { |f| f.start_with?("lib/") }.join(" ")
+
+    if md_files.empty? && lib_rb_files.empty?
+      puts "No changed .md or lib/*.rb files to process"
+    else
+      unless md_files.empty?
+        puts "Processing #{md_files.split.count} changed .md file(s)..."
+        Rake::Task["license:headers:md"].invoke(md_files)
+        Rake::Task["license:headers:md"].reenable
+        Rake::Task["license:snippets:md"].invoke(md_files)
+        Rake::Task["license:snippets:md"].reenable
+      end
+
+      unless lib_rb_files.empty?
+        puts "Processing #{lib_rb_files.split.count} changed lib/*.rb file(s)..."
+        Rake::Task["license:headers:rb"].invoke(lib_rb_files)
+        Rake::Task["license:headers:rb"].reenable
+        Rake::Task["license:snippets:rdoc"].invoke(lib_rb_files)
+        Rake::Task["license:snippets:rdoc"].reenable
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/lint.rake

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "rubocop/rake_task"
+require "rubycritic/rake_task"
+require "inch/rake"
+
+RuboCop::RakeTask.new
+
+# Run rubycritic in a shell to prevent it from exiting the rake process
+task :rubycritic do
+  paths = []
+  paths << "exe" if Dir.exist?("exe")
+  paths << "lib" if Dir.exist?("lib")
+  paths << "sig" if Dir.exist?("sig")
+  sh "bundle exec rubycritic --no-browser #{paths.join(' ')}" unless paths.empty?
+end
+
+Inch::Rake::Suggest.new("doc:suggest", "exe/**/*.rb", "lib/**/*.rb", "sig/**/*.rbs") do |suggest|
+  suggest.args << ""
+end
+
+namespace :lint do
+  task :safe_rdoc_coverage do
+    if Rake::Task.task_defined?("rdoc:coverage")
+      sh "bundle exec rake rdoc:coverage"
+    else
+      puts "rdoc:coverage task not defined, skipping"
+    end
+  end
+
+  # Build dynamic task lists based on what's available
+  docs_tasks = %w[rubycritic reuse:lint]
+  docs_tasks.unshift("autodoc") if Rake::Task.task_defined?("autodoc")
+  docs_tasks << "safe_rdoc_coverage" if Rake::Task.task_defined?("rdoc:coverage")
+
+  code_tasks = %w[rubocop rubycritic]
+  code_tasks += %w[cargo:fmt cargo:clippy cargo:test] if Dir.exist?("ext")
+
+  task docs: docs_tasks
+  task code: code_tasks
+  task licenses: %w[reuse:lint]
+  task all: %w[docs code licenses]
+
+  namespace :fix do
+    desc "Auto-fix RuboCop offenses (most aggressive)"
+    task :rubocop do
+      sh "bundle exec rubocop --autocorrect-all"
+    end
+
+    if Dir.exist?("ext")
+      desc "Auto-fix Clippy warnings (most aggressive: --fix --allow-dirty --allow-staged)"
+      task :clippy do
+        ext_dirs = Dir.glob("ext/*").select { |d| File.directory?(d) && File.exist?("#{d}/Cargo.toml") }
+        ext_dirs.each do |dir|
+          sh "cd #{dir} && cargo clippy --fix --allow-dirty --allow-staged"
+        end
+      end
+    end
+
+    desc "Add SPDX headers and normalize Ruby file structure"
+    task reuse: %w[reuse:fix reuse:normalize_ruby]
+
+    # Build dynamic fix:all task
+    fix_all_tasks = %w[lint:fix:rubocop lint:fix:reuse]
+    fix_all_tasks.insert(1, "lint:fix:clippy") if Dir.exist?("ext")
+
+    desc "Run all auto-fix tasks"
+    task all: fix_all_tasks
+  end
+end
+
+desc "Run all lint auto-fix tasks"
+task("lint:fix") { Rake::Task["lint:fix:all"].invoke }
+
+# Aliases for convenience
+task "rubocop:autocorrect_all" => "lint:fix:rubocop"
+
+desc "Run all lint tasks"
+task(:lint) { Rake::Task["lint:all"].invoke }

data/lib/ratatui_ruby/devtools/tasks/rdoc_config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Configuration for RDoc documentation generation.
+#
+# RDoc generates API documentation from source files. Configuring which files
+# to include requires glob patterns. Large files slow generation. Verification
+# examples clutter the output.
+#
+# This module defines the file list, size limits, and main page. Use it to
+# configure RDoc::Task consistently across ecosystem gems.
+module RDocConfig
+  # Maximum file size to include in documentation. Files larger than this are
+  # skipped to avoid performance issues. 100KB handles most source files while
+  # excluding chat logs and similar large artifacts.
+  MAX_FILE_SIZE = 100_000
+
+  # Files to include in RDoc generation.
+  #
+  # Includes markdown docs, readme files, library source, and executables.
+  # Excludes large files and verification examples.
+  RDOC_FILES = Dir.glob(%w[
+    doc/**/*.md
+    examples/**/*.md
+    *.md
+    *.rdoc
+    lib/**/*.rb
+    exe/**/*
+  ]).reject { |f|
+    # Skip large files
+    if File.size(f) > MAX_FILE_SIZE
+      warn "RDoc: skipping #{f} (#{File.size(f) / 1024}KB > #{MAX_FILE_SIZE / 1024}KB limit)"
+      next true
+    end
+    # Skip verification examples (internal testing, not user-facing)
+    f.start_with?("examples/verify_")
+  }.freeze
+
+  # The main page for RDoc output.
+  MAIN = "README.md"
+end

data/lib/ratatui_ruby/devtools/tasks/resources/build.yml.erb

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - git
+artifacts:
+  - ratatui_ruby/pkg/<%= gem_filename %>
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
+      . ~/.buildenv
+      export CI="true"
+      cd ratatui_ruby
+      sed -i 's/ruby = .*/ruby = "<%= ruby_version %>"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:<%= bundler_version %>
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+      mise x -- bundle exec rake compile
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Testing Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

data/lib/ratatui_ruby/devtools/tasks/resources/rubies.yml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+- "3.2"
+- "3.3"
+- "3.4"
+- "4.0.0"

data/lib/ratatui_ruby/devtools/tasks/reuse.rake

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+namespace :reuse do
+  desc "Run the REUSE Tool to confirm REUSE compliance"
+  task :lint do
+    sh "reuse lint"
+  end
+
+  desc "Add SPDX headers to files missing them (per AGENTS.md standards)"
+  task :fix do
+    copyright = ENV.fetch("REUSE_COPYRIGHT", "Kerrick Long <me@kerricklong.com>")
+
+    # Code files: AGPL-3.0-or-later
+    code_extensions = %w[rb rs rake gemspec rbs toml yml yaml json lock].freeze
+    code_license = ENV.fetch("REUSE_CODE_LICENSE", "AGPL-3.0-or-later")
+
+    # Documentation files: CC-BY-SA-4.0
+    doc_extensions = %w[md txt].freeze
+    doc_license = ENV.fetch("REUSE_DOC_LICENSE", "CC-BY-SA-4.0")
+
+    # Find files missing headers (listed after "no copyright and licensing" message)
+    puts "Checking for files missing REUSE headers..."
+    output = `reuse lint 2>&1`
+    in_missing_section = false
+    missing_files = output.lines.filter_map do |line|
+      in_missing_section = true if line.include?("no copyright and licensing")
+      in_missing_section = false if line.start_with?("# ") && !line.include?("copyright")
+      next unless in_missing_section
+
+      line.match(/^\* (.+)/)&.[](1)
+    end
+
+    if missing_files.empty?
+      puts "All files have REUSE headers!"
+    else
+      missing_files.each do |file|
+        ext = File.extname(file).delete(".")
+        license = if code_extensions.include?(ext)
+          code_license
+        elsif doc_extensions.include?(ext)
+          doc_license
+        else
+          puts "  Skipping #{file} (unknown extension: .#{ext})"
+          next
+        end
+
+        puts "  Annotating #{file} with #{license}"
+        sh "reuse annotate --license #{license} --copyright '#{copyright}' --skip-existing '#{file}'", verbose: false
+      end
+    end
+  end
+
+  desc "Normalize Ruby files: frozen_string_literal at top, SPDX in #--/#++ block"
+  task :normalize_ruby do
+    ruby_extensions = %w[rb rake gemspec].freeze
+    ruby_files = Dir.glob("**/*.{#{ruby_extensions.join(',')}}")
+      .reject { |f| f.start_with?("vendor/", "tmp/", ".") }
+
+    fixed_count = 0
+    ruby_files.each do |file|
+      content = File.read(file)
+      original = content.dup
+
+      # Skip if no SPDX header
+      next unless content.match?(/# SPDX-/)
+
+      # Extract components
+      frozen = content.match?(/^# frozen_string_literal: true/)
+      spdx_match = content.match(/(# SPDX-FileCopyrightText:[^\n]+\n(?:#[^\n]*\n)*# SPDX-License-Identifier:[^\n]+\n)/m)
+      next unless spdx_match
+
+      spdx_block = spdx_match[1]
+
+      # Remove existing frozen_string_literal and SPDX block (and any #--/#++)
+      cleaned = content
+        .sub(/^# frozen_string_literal: true\n+/, "")
+        .sub(/^#--\s*\n/, "")
+        .sub(spdx_block, "")
+        .sub(/^#\+\+\s*\n/, "")
+        .sub(/\A\n+/, "") # Remove leading blank lines
+
+      # Rebuild file in correct order: frozen, blank, #--, SPDX, #++, rest
+      new_content = ""
+      new_content += "# frozen_string_literal: true\n\n" if frozen
+      new_content += "#--\n#{spdx_block}#++\n\n"
+      new_content += cleaned.sub(/\A\n+/, "") # Ensure no double blank lines
+
+      next unless new_content != original
+
+      File.write(file, new_content)
+      puts "  Normalized #{file}"
+      fixed_count += 1
+    end
+
+    puts fixed_count.zero? ? "All Ruby files properly normalized!" : "Fixed #{fixed_count} files."
+  end
+end
+
+task(:reuse) { Rake::Task["reuse:lint"].invoke }

data/lib/ratatui_ruby/devtools/tasks/sourcehut.rake

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+desc "Generate SourceHut build manifests from template"
+task sourcehut: "sourcehut:build"
+
+namespace :sourcehut do
+  desc "Build SourceHut manifests"
+  task build: "sourcehut:build:manifest"
+
+  namespace :build do
+    desc "Generate SourceHut build manifests from template"
+    task :manifest do
+      require "erb"
+      require "yaml"
+
+      gem_name = RatatuiRuby::Devtools.gem_name
+      gemspec_file = RatatuiRuby::Devtools.gemspec_file
+      version_file = RatatuiRuby::Devtools.version_file
+
+      # Detect if this is a Rust extension gem
+      has_rust = File.exist?("ext/#{gem_name}/Cargo.toml") ||
+        File.exist?("ext/#{gem_name.tr('-', '_')}/Cargo.toml")
+
+      spec = Gem::Specification.load(gemspec_file)
+
+      # Read version directly from file to ensure we get the latest version
+      # even if it was just bumped in the same Rake execution
+      version_content = File.read(version_file)
+      version = version_content.match(/VERSION = "(.+?)"/)[1]
+
+      gem_filename = "#{spec.name}-#{version}.gem"
+
+      rubies = YAML.load_file("tasks/resources/rubies.yml")
+
+      bundler_version = File.read("Gemfile.lock").match(/BUNDLED WITH\n\s+([\d.]+)/)[1]
+
+      template = File.read("tasks/resources/build.yml.erb")
+      erb = ERB.new(template, trim_mode: "-")
+
+      FileUtils.mkdir_p ".builds"
+
+      # Remove old generated files to ensure a clean state
+      Dir.glob(".builds/*.yml").each { |f| File.delete(f) }
+
+      rubies.each do |ruby_version|
+        filename = ".builds/ruby-#{ruby_version}.yml"
+        puts "Generating #{filename}..."
+        content = erb.result_with_hash(gem_name:, has_rust:, ruby_version:, gem_filename:, bundler_version:)
+        File.write(filename, content)
+      end
+    end
+  end
+
+  desc "Update stable branch to match release and set as default"
+  task :update_stable do
+    version_file = RatatuiRuby::Devtools.version_file
+
+    # Read version to determine tag
+    version_content = File.read(version_file)
+    version = version_content.match(/VERSION = "(.+?)"/)[1]
+    tag_name = "v#{version}"
+
+    # Verify that the version file matches the actual git tag
+    # This prevents updating stable to the wrong version if the release failed
+    latest_tag = `git describe --tags --abbrev=0`.strip
+    if latest_tag != tag_name
+      abort "Fatal: Version mismatch! '#{version_file}' says #{tag_name}, " \
+        "but the latest git tag is #{latest_tag}."
+    end
+
+    puts "Updating stable branch to point to #{tag_name}..."
+    # Resolve the tag to a commit hash (peel annotated tags)
+    # This renders a commit SHA that can be pushed to a branch head
+    commit_sha = `git rev-parse #{tag_name}^{}`.strip
+
+    # Update local stable branch to match
+    sh "git branch -f stable #{commit_sha}"
+
+    # Push the commit to remote stable branch
+    # This creates 'stable' if it doesn't exist, or fast-forwards it.
+    sh "git push origin #{commit_sha}:stable"
+  end
+end
+
+if Rake::Task.task_defined?("release")
+  Rake::Task["release"].enhance do
+    Rake::Task["sourcehut:update_stable"].invoke
+  end
+end

data/lib/ratatui_ruby/devtools/tasks/test.rake

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Minitest task for pure Ruby gems.
+#
+# Consumer gems need test running. This provides a simple Minitest::TestTask
+# that discovers tests in the standard locations. Gems with Rust extensions
+# should define their own test task that includes cargo:test.
+
+require "minitest/test_task"
+
+Minitest::TestTask.create(:test) do |t|
+  t.test_globs = ["test/**/*_test.rb", "test/**/test_*.rb"]
+end

data/lib/ratatui_ruby/devtools/templates/.builds/ruby.yml.erb

@@ -0,0 +1,47 @@
+# REUSE-IgnoreStart
+# SPDX-FileCopyrightText: <%= Time.now.year %> <%= copyright_holder %>
+# SPDX-License-Identifier: <%= license %>
+# REUSE-IgnoreEnd
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - git
+sources:
+  - https://git.sr.ht/~kerrick/<%= gem_name %>
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+      . ~/.buildenv
+      export CI="true"
+      cd <%= gem_name %>
+      sed -i 's/ruby = .*/ruby = "<%= ruby_version %>"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+  - test: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Testing Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Linting Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake lint

data/lib/ratatui_ruby/devtools/templates/.gitignore.erb

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+**/.idea/
+**/.DS_Store
+/.bundle/
+/.yardoc/
+/_yardoc/
+/coverage/
+/pkg/
+/spec/reports/
+/tmp/
+<%- if has_rust -%>
+/ext/<%= gem_name %>/target/
+*.bundle
+*.dylib
+*.so
+<%- end -%>

data/lib/ratatui_ruby/devtools/templates/.pre-commit-config.yaml.erb

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2020 Free Software Foundation Europe e.V.
+# SPDX-License-Identifier: CC0-1.0
+repos:
+  - repo: local
+    hooks:
+      -   id: bundle-check
+          name: Check Gemfile.lock
+          entry: bundle check
+          language: system
+          files: (Gemfile|Gemfile\.lock|<%= gem_name %>\.gemspec)
+          pass_filenames: false
+      -   id: rake
+          name: rake
+          entry: bundle exec rake
+          language: system
+          pass_filenames: false

data/lib/ratatui_ruby/devtools/templates/.rubocop.yml.erb

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+inherit_from:
+  - ./vendor/goodcop/base.yml
+
+AllCops:
+  TargetRubyVersion: "3.2"

data/lib/ratatui_ruby/devtools/templates/AGENTS.md.erb

@@ -0,0 +1,65 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# AGENTS.md
+
+## Project Identity
+
+Project Name: <%= gem_name %>
+
+Description: Part of the RatatuiRuby ecosystem.
+
+## 1. Standards
+
+### STRICT REQUIREMENTS
+
+- Every file MUST begin with an SPDX-compliant header. Use `<%= license %>` 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 `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 `agent_rake`** (provided by the `ratatui_ruby-devtools` gem) for running tests, linting, or checking compilation.
+  - **Usage:**
+    - Runs default task (compile + test + lint): `agent_rake`
+    - Runs specific task: `agent_rake test:ruby` (for example)
+- **Setup:** `bin/setup` must handle Bundler dependencies.
+- **Git:** ALWAYS set `PAGER=cat` with `git`. **THIS IS CRITICAL!**
+
+### 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](https://www.conventionalcommits.org/).
+    - 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:
+
+1. **Default Rake Task Passes:** Run `agent_rake` (no args). Confirm it passes with ZERO errors.
+2. **Documentation Updated:** If public APIs changed, update relevant docs.
+3. **Changelog Updated:** If public APIs changed, update CHANGELOG.md's **Unreleased** section.
+4. **Commit Message Suggested:** Include a suggested commit message block.
+
+### Type Conventions
+
+- `lib/`, `ext/`, `sig/`: Use `feat`, `fix`, `refactor`, `perf` as appropriate.
+- `bin/`, `tasks/`, `.builds/`, CI/CD: Use `chore` for tooling internal to developing this gem. Use `feat`/`fix` for user-facing executables or changes that affect downstream users.
+- `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`.
+

data/lib/ratatui_ruby/devtools/templates/CHANGELOG.md.erb

@@ -0,0 +1,18 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased]
+
+### Added
+
+- Initial release of <%= gem_name %>