tint_me 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 32acd1788229fa045285ea19649c993b0b4f9e59758ae92ec9a0eee630b58544
+  data.tar.gz: 89cfff7bc922b2fcbf876263b2a2b8dccf8762663bf15777e0b877f127d57553
+SHA512:
+  metadata.gz: 118fa5cf809036f4169c0b7e0832fa4a90c14d92298db7f3afac16bb70bd7855200f8bed0b600369c3163a1a1a2f7d7d91c619a265a3720b030020207aeeea67
+  data.tar.gz: dc3e91e45584ed1c353bc28cf8d095af7a429ed0873d5aa88ea4ed2cf5e289c1e3259ac3ef24806d2147a0d2451f31dd313a3b6da4cc2aaf511cd4f538558cfe

data/.rubocop_todo.yml

@@ -0,0 +1,7 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config --no-exclude-limit --no-offense-counts --no-auto-gen-timestamp`
+# using RuboCop version 1.80.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.

data/.serena/project.yml

@@ -0,0 +1,68 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: ruby
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "tint_me"

data/.simplecov

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+SimpleCov.start do
+  # Coverage output directory
+  coverage_dir "coverage"
+
+  # Minimum coverage threshold
+  minimum_coverage 90
+
+  # Exclude files from coverage
+  add_filter "/spec/"
+  add_filter "/vendor/"
+  add_filter "/bin/"
+  add_filter "lib/tint_me/version.rb"
+
+  # Group coverage by directory
+  add_group "Main", "lib/tint_me"
+
+  # Coverage formats
+  formatter SimpleCov::Formatter::MultiFormatter.new([
+                                                       SimpleCov::Formatter::HTMLFormatter,
+                                                       SimpleCov::Formatter::SimpleFormatter
+                                                     ])
+end

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir docs/api
+--markup markdown
+--markup-provider redcarpet
+--readme README.md
+--title "TIntMe! API Documentation"
+lib/**/*.rb

data/AGENTS.md

@@ -0,0 +1,60 @@
+# Repository Guidelines
+
+> **Note**: This file is also accessible via the `CLAUDE.md` symlink for AI agent compatibility.
+
+> **Important**: This document references other documentation files. Please also read:
+> - `docs/agents/rubocop.md` - RuboCop fix guidelines for AI agents
+> - `docs/agents/git-pr.md` - Git commit and pull request guidelines
+> - `docs/agents/languages.md` - Language usage guidelines for communication and code
+> - Any other documents referenced inline below
+
+## Project Structure & Module Organization
+- `lib/tint_me`: Core library. Entry point is `lib/tint_me.rb`; code is namespaced under `TIntMe` (autoloaded via Zeitwerk).
+- `spec`: RSpec tests. Mirror library paths (e.g., `spec/tint_me/style_spec.rb`).
+- `docs/api`: Generated YARD documentation. Do not edit by hand; use `rake doc`.
+- `benchmark/*`: Performance experiments and notes.
+- `bin`: Development helpers (`bin/setup`, `bin/console`).
+
+## Build, Test, and Development Commands
+- `bundle install`: Install dependencies (use a supported Ruby; see policy below and `mise.toml`).
+- `rake`: Default task; runs `spec` and `rubocop`.
+- `rake spec`: Run the test suite.
+- `rubocop` or `rake rubocop`: Lint and style checks.
+- `rake doc`: Build YARD docs into `docs/api`.
+- `bin/console`: IRB with the gem loaded for quick experiments.
+- `docquet regenerate-todo`: Regenerate `.rubocop_todo.yml` after lint updates; include with related code fixes.
+
+## Communication & Languages
+See `docs/agents/languages.md` for detailed language usage guidelines covering:
+- AI/user chat communication languages
+- Source code and documentation language requirements  
+- Issues/PRs language preferences
+- Context-appropriate language switching
+
+## Coding Style & Naming Conventions
+- Ruby 3.x compatible; 2-space indent, `# frozen_string_literal: true` headers.
+- Follow RuboCop rules (`.rubocop.yml`); fix offenses before committing.
+- Files and specs use snake_case; specs live under `spec/tint_me/*_spec.rb`.
+- Public API is under `TIntMe`; avoid monkey patching. Prefer immutable, composable objects (e.g., `Style` and `>>`).
+- RuboCop fixes: When addressing lints, follow `docs/agents/rubocop.md` (safe autocorrect first; targeted unsafe only as needed).
+
+## Testing Guidelines
+- Framework: RSpec with `spec_helper` and SimpleCov. Maintain ≥ 90% coverage.
+- Name/spec files to mirror library paths; keep examples focused and readable.
+- Run `rake spec` locally; ensure `.rspec_status` is clean.
+
+## Commit & Pull Request Guidelines
+- Title format: Must start with a GitHub `:emoji:` code followed by a space, then an imperative subject. Example: `:zap: Optimize Style#call path`.
+- No raw emoji: Use `:emoji:` codes only (commit hook rejects Unicode emoji).
+- Exceptions: `fixup!` / `squash!` are allowed by hooks.
+- Merge commits: Auto-prefixed with `:inbox_tray:` by the prepare-commit-msg hook.
+- Commit body: English, explaining motivation, approach, and trade-offs.
+- Include rationale and, when useful, before/after snippets or benchmarks.
+- Link issues (e.g., `Fixes #123`) and update README/CHANGELOG when user-facing behavior changes.
+- PRs must pass `rake` (tests + lint), include tests for changes, and keep API docs current (`rake doc` when needed).
+
+## Security & Configuration Tips
+- Supported Ruby: latest patch of the newest three minor series (e.g., 3.4.x / 3.3.x / 3.2.x). Develop locally on the oldest of these.
+- Version management: Use `mise`; the repo’s `mise.toml` sets the default to the oldest supported series. Examples: `mise use -g ruby@3.2`, `mise run -e ruby@3.3 rake spec`.
+- Keep runtime dependencies minimal; prefer standard library where possible.
+- No network access is expected at runtime; avoid introducing it without discussion.

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+## [Unreleased]
+
+## [1.0.0] - 2025-09-09
+
+### Added
+- Core Style class with immutable data structure using Data.define (extracted from Fasti gem)
+- Support for foreground/background colors (named colors, hex values)
+- Text effects: bold, faint, italic, underline (including double), overline, blink, hide, inverse
+- Style composition with >> operator for layering styles
+- Bold/faint mutual exclusion handling in composition
+- TIntMe[] shortcut method for convenient style creation
+- Style#call and Style#[] methods for applying styles to text
+- Native ANSI SGR implementation with comprehensive color and effect support
+- Zeitwerk autoloader with custom inflection rules for TIntMe
+- Comprehensive test suite with 100% code coverage
+- SimpleCov integration for coverage reporting
+- YARD documentation generation with redcarpet markdown support
+- RuboCop configuration with systematic violation resolution
+- Rake tasks for testing, linting, and documentation generation
+
+### Development
+- Complete project setup with proper gem structure
+- Git configuration with appropriate .gitignore patterns
+- Bundler gem tasks integration
+- RSpec test framework with progress format output
+- Development dependencies: RuboCop, YARD, SimpleCov
+- Continuous integration ready configuration
+- Comprehensive AI agent guidelines for Git/PR operations and language usage
+- Performance guidelines for style composition optimization

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 OZAWA Sakuro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# :lipstick: TIntMe! :nail_care:
+
+A Ruby library for terminal text styling with ANSI colors and effects. TIntMe! provides an elegant and composable API for applying colors, text decorations, and formatting to terminal output.
+
+## Features
+
+- **Rich Color Support**: Foreground and background colors with support for standard colors and hex values
+- **Text Effects**: Bold, faint, italic, underline (including double), overline, blink, inverse, and concealed text
+- **Style Composition**: Combine multiple styles using the `>>` operator for layered styling
+- **Type Safety**: Comprehensive argument validation using dry-schema and dry-types
+- **Immutable Design**: All style operations return new instances, making them safe for concurrent use
+- **Zeitwerk Integration**: Automatic loading with proper module organization
+- **Comprehensive API**: Both explicit `Style.new` and convenient `TIntMe[]` shortcut syntax
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tint_me"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install tint_me
+```
+
+## Usage
+
+### Basic Styling
+
+```ruby
+require 'tint_me'
+
+# Create a style
+red_style = TIntMe::Style.new(foreground: :red)
+puts red_style.call("Hello World")
+
+# Using the shortcut syntax
+blue_style = TIntMe[foreground: :blue, bold: true]
+puts blue_style["Hello World"]
+```
+
+### Color Options
+
+```ruby
+# Standard colors
+TIntMe[foreground: :red]
+TIntMe[background: :yellow]
+
+# Hex colors (with or without #)
+TIntMe[foreground: "#FF0000"]
+TIntMe[background: "#00FF00"]
+TIntMe[foreground: "FF0000"]
+```
+
+### Text Effects
+
+```ruby
+# Individual effects
+TIntMe[bold: true]
+TIntMe[faint: true]          # Faint/dim text
+TIntMe[italic: true]
+TIntMe[underline: true]
+TIntMe[underline: :double]   # Double underline
+TIntMe[overline: true]       # Overline decoration
+TIntMe[blink: true]          # Blinking text
+TIntMe[inverse: true]        # Reverse colors
+TIntMe[conceal: true]        # Hidden/concealed text
+
+# Multiple effects
+TIntMe[foreground: :green, bold: true, underline: true]
+```
+
+### Style Composition
+
+```ruby
+# Base styling
+base = TIntMe[foreground: :blue]
+emphasis = TIntMe[bold: true, underline: true]
+
+# Combine styles (right-hand style takes precedence)
+combined = base >> emphasis
+puts combined.call("Styled text")
+
+# Chain multiple compositions
+final = base >> emphasis >> TIntMe[background: :white]
+```
+
+#### ⚡ Performance Considerations
+
+**TIntMe is optimized for reusable styles** through SGR sequence pre-computation. The composition operator (`>>`) should be used thoughtfully:
+
+```ruby
+# ✅ RECOMMENDED: Pre-compose and reuse
+ERROR_STYLE = TIntMe[foreground: :red] >> TIntMe[bold: true]
+ERROR_STYLE.call("Error message")  # Fast: ~4.8M operations/sec
+
+# ❌ AVOID: Runtime composition  
+(TIntMe[foreground: :red] >> TIntMe[bold: true]).call("Error")  # Slow: ~0.01M ops/sec
+```
+
+**Key Guidelines:**
+- **Use `>>` for initialization**: Create composed styles once and reuse them
+- **Avoid runtime composition**: Don't chain `>>` operators inside loops or frequently-called methods
+- **For one-time styling**: Consider alternatives like `Paint` gem for better dynamic performance
+- **Each `>>` operation**: Creates new Style instances and recalculates SGR sequences
+
+**Performance Comparison:**
+- Pre-computed styles: **~4.8M operations/sec** (fastest)
+- Runtime composition: **~0.01M operations/sec** (246x slower)
+- Direct Style.new: **~0.03M operations/sec** (71x slower)
+
+#### 🎯 When to Use TIntMe vs Alternatives
+
+**TIntMe excels at:**
+```ruby
+# Terminal UI frameworks with predefined styles
+UI_STYLES = {
+  error:   TIntMe[foreground: :red] >> TIntMe[bold: true],
+  success: TIntMe[foreground: :green] >> TIntMe[bold: true],
+  info:    TIntMe[foreground: :blue] >> TIntMe[italic: true]
+}
+
+def show_error(msg)
+  puts UI_STYLES[:error].call(msg)  # Extremely fast: ~4.8M ops/sec
+end
+```
+
+**Consider alternatives for:**
+```ruby
+# Dynamic styling (use Paint gem instead)
+texts.each { |text| Paint[text, :red, :bold] }  # ~2M ops/sec
+
+# One-time styling with readable syntax (use Rainbow gem)
+puts Rainbow("Success").green.bold  # ~0.5M ops/sec
+
+# Avoid with TIntMe - creates unnecessary overhead
+texts.each { |text| (red >> bold).call(text) }  # Only ~0.01M ops/sec
+```
+
+**Design Philosophy:**
+TIntMe is intentionally optimized for the **"define once, use many"** pattern through SGR sequence pre-computation at initialization time. The performance characteristics guide you toward the most efficient usage patterns, where a small set of predefined styles serves many styling operations.
+
+### Method Aliases
+
+```ruby
+style = TIntMe[foreground: :red, bold: true]
+
+# All of these are equivalent
+puts style.call("Hello")
+puts style["Hello"]
+puts style.("Hello")  # Callable syntax
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sakuro/tint_me.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASING.md

@@ -0,0 +1,202 @@
+# Releasing
+
+This document describes the release process for the tint_me gem, which is fully automated through GitHub Actions workflows.
+
+## Overview
+
+The release process consists of three automated workflows:
+
+1. **Release Preparation** - Creates a release branch with version updates
+2. **Release Validation** - Validates the release branch on PR creation
+3. **Release Publish** - Publishes the gem after PR merge
+
+## Prerequisites
+
+Before initiating a release, ensure:
+
+- [ ] All desired features and fixes are merged to `main`
+- [ ] CI is passing on `main` branch
+- [ ] `CHANGELOG.md` has entries under `## [Unreleased]` section
+- [ ] `RUBYGEMS_API_KEY` secret is configured in repository settings
+
+## Release Process
+
+### Step 1: Initiate Release
+
+1. Go to the [Actions tab](../../actions) in the GitHub repository
+2. Select "Release Preparation" workflow
+3. Click "Run workflow"
+4. Enter the version number (e.g., `1.0.0`)
+5. Click "Run workflow"
+
+The workflow will automatically:
+- Create a new branch `release-v{version}`
+- Update `lib/tint_me/version.rb` with the new version
+- Update `CHANGELOG.md`:
+  - Replace `## [Unreleased]` with `## [{version}] - {date}`
+  - Add a new `## [Unreleased]` section for future changes
+- Create a git tag `v{version}` on the release branch
+- Push the branch and tag to GitHub
+- Create a Pull Request to `main`
+
+### Step 2: Review and Merge
+
+Once the PR is created, the Release Validation workflow automatically:
+- Validates version format (must be `x.y.z`)
+- Verifies version consistency between branch name and `version.rb`
+- Checks that the git tag doesn't already exist (or can be updated)
+- Confirms the version isn't already published on RubyGems
+- Verifies `RUBYGEMS_API_KEY` secret is configured
+- Validates `CHANGELOG.md` has an entry for this version
+
+**Note**: Quality checks (tests and RuboCop) are handled by the CI workflow to avoid duplication.
+
+**Important**: If you push additional commits to the release PR (e.g., bug fixes, workflow updates, documentation changes):
+- The validation workflow automatically moves the release tag to the latest commit
+- This ensures the tag always points to the final reviewed code
+- No manual intervention required
+- All changes will be included in the final release
+
+If all checks pass, merge the PR.
+
+### Step 3: Automatic Publishing
+
+After the PR is merged, the Release Publish workflow automatically:
+- Checks out the exact git tag created on the release branch
+- Builds the gem from the tagged commit
+- Publishes the gem to RubyGems
+- Creates a GitHub Release with:
+  - Release notes extracted from `CHANGELOG.md`
+  - The built gem file as an attachment
+- Cleans up the release branch
+
+## Workflow Architecture
+
+### Key Design Decisions
+
+#### Tag-Based Deployment
+
+The release workflow uses a **tag-based deployment strategy** to ensure the released gem contains exactly the code that was reviewed and approved in the release PR, without any subsequent changes from `main`.
+
+```mermaid
+graph LR
+    A[main branch] -->|Create release branch| B[release-v1.0.0]
+    B -->|Update version & tag| C[Tagged: v1.0.0]
+    B -->|Create PR| D[Pull Request]
+    A -->|Other PRs merged| E[main with new commits]
+    D -->|Merge PR| E
+    C -->|Checkout tag| F[Build & Publish gem]
+    F -->|Contains only| G[Code from release branch]
+```
+
+#### Automatic Tag Movement
+
+When additional commits are pushed to a release PR, the tag automatically moves to the latest commit:
+
+```mermaid
+graph LR
+    A[Initial commit] -->|Tag v1.0.0| B[Tagged commit]
+    B -->|Fix typo| C[New commit]
+    C -->|Auto-move tag| D[Tag v1.0.0 on latest]
+    D -->|Final review| E[Ready to merge]
+```
+
+This ensures:
+- The tag always points to the final reviewed code
+- No manual tag management required
+- The published gem matches exactly what was approved
+
+## Manual Release (Emergency Only)
+
+If automation fails, you can release manually using our tag-based strategy:
+
+```bash
+# 1. Create release branch
+git checkout -b release-v1.0.0
+
+# 2. Update version
+vim lib/tint_me/version.rb
+
+# 3. Update CHANGELOG (move content from [Unreleased] to [1.0.0])
+vim CHANGELOG.md
+
+# 4. Commit changes and create tag
+git add -A
+git commit -m ":bookmark: Release v1.0.0"
+git tag -a v1.0.0 -m "Release v1.0.0"
+
+# 5. Push release branch and tag
+git push origin release-v1.0.0
+git push origin v1.0.0
+
+# 6. Create PR and merge after review
+gh pr create --title "Release v1.0.0" --body "Release v1.0.0"
+# (Review and merge PR)
+
+# 7. Checkout the tag and build gem
+git checkout v1.0.0
+bundle exec rake build
+
+# 8. Push to RubyGems
+gem push pkg/tint_me-1.0.0.gem
+
+# 9. Create GitHub release
+gh release create v1.0.0 --title "tint_me v1.0.0" --generate-notes pkg/tint_me-1.0.0.gem
+```
+
+## Troubleshooting
+
+### Release Validation Fails
+
+**Version already exists on RubyGems**
+- Solution: Increment the version number and try again
+
+**RUBYGEMS_API_KEY not configured**
+1. Generate an API key at https://rubygems.org/profile/edit
+2. Go to repository Settings → Secrets and variables → Actions
+3. Add new secret: `RUBYGEMS_API_KEY` with your API key
+
+**Tests or RuboCop failing**
+- These are checked by the CI workflow, not in release validation
+- Fix the issues on the release branch or `main` as appropriate
+- Release validation focuses on version consistency and format
+
+### Release Publish Fails
+
+**Tag not found**
+- The release preparation workflow may have failed to create the tag
+- Check if the tag exists: `git tag | grep v1.0.0`
+- If missing, the release validation workflow will recreate it on PR updates
+- For manual fix: create tag on release branch with `git tag -a v1.0.0 -m "Release v1.0.0"`
+
+**Gem push fails**
+- Verify RubyGems API key is valid
+- Check if you have push permissions for the gem
+- Ensure the version doesn't already exist on RubyGems
+
+## Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions  
+- **PATCH** version for backwards-compatible bug fixes
+
+Examples:
+- `0.1.0` → `0.1.1`: Bug fixes only
+- `0.1.1` → `0.2.0`: New features added
+- `0.2.0` → `1.0.0`: Breaking changes or stable release
+
+## Workflow Files
+
+The release automation is implemented in:
+
+- `.github/workflows/release-preparation.yml` - Creates release branch and PR
+- `.github/workflows/release-validation.yml` - Validates release PR
+- `.github/workflows/release-publish.yml` - Publishes gem after merge
+
+## Security Notes
+
+- The `RUBYGEMS_API_KEY` secret is only accessible to workflows running on the default branch
+- Release branches are automatically deleted after successful release
+- All releases are tagged for audit trail and rollback capability

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new(:doc)
+
+require "rake/clean"
+CLEAN.include("coverage", ".yardoc", "docs/api", ".rspec_status")
+CLOBBER.include("pkg")
+
+task default: %i[spec rubocop]

data/benchmark/2025-09-08-style-caching-optimization/01_baseline_results.txt

@@ -0,0 +1,39 @@
+BASELINE BENCHMARK RESULTS (Before Optimization)
+=================================================
+Date: 2025-09-08
+
+## Performance Summary
+
+### Style Application (operations/second)
+- Simple style: ~766k ops/s (1.3μs per call)
+- Complex style: ~437k ops/s (2.3μs per call)  
+- Hex color style: ~266k ops/s (3.8μs per call)
+
+### Repeated Application (1000x)
+- Simple style: 781 ops/s (1.28ms total)
+- Complex style: 433 ops/s (2.31ms total)
+- Hex style: 265 ops/s (3.78ms total)
+
+### Memory Usage
+- Simple style creation: 5.8KB, 52 objects
+- Complex style creation: 6.6KB, 66 objects
+- Simple style application (first): 45KB, 466 objects
+- Complex style application (subsequent): 1.1KB, 14 objects
+
+### Object Allocations (100 applications)
+- Simple style: 703 objects
+- Complex style: 1203 objects
+
+## Key Observations
+
+1. **Performance overhead**: Each call recalculates SGR sequences
+2. **Object allocations**: Significant allocations on every call
+3. **Hex colors slower**: RGB conversion adds ~45% overhead
+4. **Complex styles slower**: More parameters = more processing
+
+## Expected Improvements with Caching
+
+- Reduced object allocations per call
+- Consistent performance regardless of style complexity
+- Minimal overhead for repeated applications
+- Trade-off: Slightly higher memory per Style instance