AGENTS.md - Development Guide

🎯 Project Overview

This project is a RubyGem managed with the kettle-rb toolchain.

Minimum Supported Ruby: See the gemspec required_ruby_version constraint.
Local Development Ruby: See mise.toml for the version used in local development (typically the latest stable Ruby).

Modular Gemfile Architecture

Gemfiles are split into modular components under gemfiles/modular/. Each component handles a specific concern (coverage, style, debug, etc.). The main Gemfile loads these modular components via eval_gemfile.
Gemfiles in the project, including modular ones, can utilize a *_local.gemfile counterpart pattern enabled via an ENV flag. This uses nomono to load sibling gems in the same workspace.

⚠️ AI Agent Terminal Limitations

Use `mise` for Project Environment

CRITICAL: The canonical project environment lives in mise.toml, with local overrides in .env.local loaded via dotenvy.

⚠️ Watch for trust prompts: After editing mise.toml or .env.local, mise may require trust to be refreshed before commands can load the project environment. Until that trust step is handled, commands can appear hung or produce no output, which can look like terminal access is broken.

Recovery rule: If a mise exec command goes silent or appears hung, assume mise trust is the first thing to check. Recover by running:

mise trust -C /path/to/project
mise exec -C /path/to/project -- bundle exec kettle-test

Do this before spending time on unrelated debugging; in this workspace pattern, silent mise commands are usually a trust problem first.

✅ CORRECT — Run self-contained commands with mise exec:

mise exec -C /path/to/project -- bundle exec kettle-test

✅ CORRECT — If you need shell syntax first, load the environment in the same command:

eval "$(mise env -C /path/to/project -s bash)" && bundle exec kettle-test

❌ WRONG — Do not rely on a previous command changing directories:

cd /path/to/project
bundle exec rspec

❌ WRONG — A chained cd does not give directory-change hooks time to update the environment:

cd /path/to/project && bundle exec rspec

Prefer Internal Tools Over Terminal

✅ PREFERRED — Use internal tools:

grep_search instead of grep command
file_search instead of find command
read_file instead of cat command
list_dir instead of ls command
replace_string_in_file or create_file instead of sed / manual editing

❌ AVOID when possible:

run_in_terminal for information gathering

Only use terminal for:

Running tests (bundle exec kettle-test)
Installing dependencies (bundle install)
Simple commands that do not require much shell escaping
Running scripts (prefer writing a script over a complicated command with shell escaping)

When you do run tests, keep the full output visible so you can inspect failures completely.

🏗️ Architecture

Toolchain Dependencies

This gem is part of the kettle-rb ecosystem. Key development tools:

Tool	Purpose
`kettle-dev`	Development dependency: Rake tasks, release tooling, CI helpers
`kettle-test`	Test infrastructure: RSpec helpers, stubbed_env, timecop
`kettle-jem`	Template management and gem scaffolding

Executables (from kettle-dev)

Executable	Purpose
`kettle-release`	Full gem release workflow
`kettle-pre-release`	Pre-release validation
`kettle-changelog`	Changelog generation
`kettle-dvcs`	DVCS (git) workflow automation
`kettle-commit-msg`	Commit message validation
`kettle-check-eof`	EOF newline validation

📁 Project Structure

lib/
├── <gem_namespace>/           # Main library code
│   └── version.rb             # Version constant (managed by kettle-release)
spec/
├── fixtures/                  # Test fixture files (NOT auto-loaded)
├── support/
│   ├── classes/               # Helper classes for specs
│   └── shared_contexts/       # Shared RSpec contexts
├── spec_helper.rb             # RSpec configuration (loaded by .rspec)
gemfiles/
├── modular/                   # Modular Gemfile components
│   ├── coverage.gemfile       # SimpleCov dependencies
│   ├── debug.gemfile          # Debugging tools
│   ├── documentation.gemfile  # YARD/documentation
│   ├── optional.gemfile       # Optional dependencies
│   ├── rspec.gemfile          # RSpec testing
│   ├── style.gemfile          # RuboCop/linting
│   └── x_std_libs.gemfile     # Extracted stdlib gems
├── ruby_*.gemfile             # Per-Ruby-version Appraisal Gemfiles
└── Appraisal.root.gemfile     # Root Gemfile for Appraisal builds
.git-hooks/
├── commit-msg                 # Commit message validation hook
├── prepare-commit-msg         # Commit message preparation
├── commit-subjects-goalie.txt # Commit subject prefix filters
└── footer-template.erb.txt    # Commit footer ERB template

🔧 Development Workflows

Running Commands

Always make commands self-contained. Use mise exec -C /home/pboling/src/kettle-rb/prism-merge -- ... so the command gets the project environment in the same invocation.
If the command is complicated write a script in local tmp/ and then run the script.

Running Tests

Always run specs via kettle-test (provided by kettle-test). It runs bundle exec rspec,
captures all output to tmp/kettle-test/rspec-TIMESTAMP.log, and prints a structured highlight block:
timing, seed, pass/fail count, failing examples, and SimpleCov coverage percentages.

Full suite:

mise exec -C /path/to/project -- bundle exec kettle-test

For single file, targeted, or partial spec runs the coverage threshold must be disabled.
Use the K_SOUP_COV_MIN_HARD=false environment variable to disable hard failure:

mise exec -C /path/to/project -- env K_SOUP_COV_MIN_HARD=false bundle exec kettle-test spec/path/to/spec.rb

Template Management (kettle-jem)

Run the kettle-jem templater to sync project files with the latest template:

# Standard run (quiet, non-interactive — the default)
mise exec -C /path/to/project -- bundle exec rake kettle:jem:install

# Verbose output (see per-file detail)
mise exec -C /path/to/project -- env KETTLE_JEM_VERBOSE=true bundle exec rake kettle:jem:install

# Interactive mode (prompt before each change)
mise exec -C /path/to/project -- bundle exec rake kettle:jem:install force=false

Current defaults (no flags needed):

quiet=true — only phase summary lines shown; use --verbose or KETTLE_JEM_VERBOSE=true to opt out
force=true — non-interactive; use --interactive or force=false to opt out
allowed=true — env file changes auto-accepted; set allowed=false to require review

Building & Installing Locally

To test local code changes across sibling repos, rebuild and reinstall the gem:

cd /path/to/gem && rm -rf *.gem && SKIP_GEM_SIGNING=true gem build *.gemspec && gem install --force *.gem

SKIP_GEM_SIGNING=true bypasses the PEM passphrase prompt for signed gemspecs.
--force overwrites the currently installed version.
Always rebuild and reinstall before verifying cross-repo behaviour.

Coverage Reports

mise exec -C /path/to/project -- bin/rake coverage
mise exec -C /path/to/project -- bin/kettle-soup-cover -d

Key ENV variables (set in mise.toml, with local overrides in .env.local):

K_SOUP_COV_DO=true – Enable coverage
K_SOUP_COV_MIN_LINE – Line coverage threshold
K_SOUP_COV_MIN_BRANCH – Branch coverage threshold
K_SOUP_COV_MIN_HARD=true – Fail if thresholds not met

Code Quality

mise exec -C /path/to/project -- bundle exec rake reek
mise exec -C /path/to/project -- bundle exec rubocop-gradual

Releasing

bin/kettle-pre-release    # Validate everything before release
bin/kettle-release        # Full release workflow

📝 Project Conventions

Freeze Block Preservation

Template updates preserve custom code wrapped in freeze blocks:

# kettle-jem:freeze
# ... custom code preserved across template runs ...
# kettle-jem:unfreeze

Modular Gemfile Architecture

Forward Compatibility with `**options`

CRITICAL: All constructors and public API methods that accept keyword arguments MUST include **options as the final parameter for forward compatibility.

🧪 Testing Patterns

Test Infrastructure

Uses kettle-test for RSpec helpers (stubbed_env, block_is_expected, silent_stream, timecop)
Uses Dir.mktmpdir for isolated filesystem tests
Spec helper is loaded by .rspec — never add require "spec_helper" to spec files

Environment Variable Helpers

before do
  stub_env("MY_ENV_VAR" => "value")
end

before do
  hide_env("HOME", "USER")
end

Dependency Tags

Use dependency tags to conditionally skip tests when optional dependencies are not available:

RSpec.describe SomeClass, :prism_merge do
  # Skipped if prism-merge is not available
end

🚫 Common Pitfalls

NEVER pipe test output through head/tail — Run tests without truncation so you can inspect the full output.
README.md is mostly auto-generated by kettle-jem — Only the following sections may be edited by hand or by agents:
- ## 🌻 Synopsis
- ## ⚙️ Configuration
- ## 🔧 Basic Usage
All other sections (badges, installation, FLOSS funding, security, contributing, versioning, license, etc.) are managed by the kettle-jem template and will be overwritten on the next templating run. Do not edit them.

AGENTS.md - Development Guide

🎯 Project Overview

Modular Gemfile Architecture

⚠️ AI Agent Terminal Limitations

Use mise for Project Environment

Prefer Internal Tools Over Terminal

🏗️ Architecture

Toolchain Dependencies

Executables (from kettle-dev)

📁 Project Structure

🔧 Development Workflows

Running Commands

Running Tests

Template Management (kettle-jem)

Building & Installing Locally

Coverage Reports

Code Quality

Releasing

📝 Project Conventions

Freeze Block Preservation

Modular Gemfile Architecture

Forward Compatibility with **options

🧪 Testing Patterns

Test Infrastructure

Environment Variable Helpers

Dependency Tags

🚫 Common Pitfalls

Use `mise` for Project Environment

Forward Compatibility with `**options`