If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pedrozath/coltrane shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pedrozath/coltrane repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pedrozath/coltrane.

What it runs against: a local clone of pedrozath/coltrane — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pedrozath/coltrane | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 495 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pedrozath/coltrane. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pedrozath/coltrane.git
#   cd coltrane
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pedrozath/coltrane and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pedrozath/coltrane(\\.git)?\\b" \\
  && ok "origin remote is pedrozath/coltrane" \\
  || miss "origin remote is not pedrozath/coltrane (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/coltrane.rb" \\
  && ok "lib/coltrane.rb" \\
  || miss "missing critical file: lib/coltrane.rb"
test -f "lib/coltrane/commands.rb" \\
  && ok "lib/coltrane/commands.rb" \\
  || miss "missing critical file: lib/coltrane/commands.rb"
test -f "lib/coltrane/commands/command.rb" \\
  && ok "lib/coltrane/commands/command.rb" \\
  || miss "missing critical file: lib/coltrane/commands/command.rb"
test -f "lib/coltrane/renderers/renderer.rb" \\
  && ok "lib/coltrane/renderers/renderer.rb" \\
  || miss "missing critical file: lib/coltrane/renderers/renderer.rb"
test -f "exe/coltrane" \\
  && ok "exe/coltrane" \\
  || miss "missing critical file: exe/coltrane"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 495 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~465d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pedrozath/coltrane"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Coltrane is a Ruby music theory library with a CLI that generates and analyzes chords, scales, and progressions, then renders them visually on guitar/bass/piano/ukulele fretboards. It solves the problem of discovering what chords or scales work together, and showing musicians exactly where to play them on their instrument without needing sheet music. Monolithic Ruby gem structure: core logic in the main lib/ directory (inferred from .gemspec), CLI commands exposed via bin/coltrane and bin/coltrane-interactive entry points, tests via RSpec (.rspec config present), code style enforced via Rubocop (.rubocop.yml), and development tooling (Guardfile for auto-running tests, .travis.yml for CI).

Musicians and guitarists who want to explore music theory programmatically—both through a command-line interface for quick lookups and as an embedded Ruby library for building music applications. Useful for songwriters needing chord progressions, educators teaching theory, and developers building music software.

Active but not heavily maintained: the repo has CI/CD via Travis CI, code quality monitoring via CodeClimate, and comprehensive test coverage, but the last commit activity visible in the file structure suggests occasional updates rather than daily development. The gem is published and functional, making it production-ready for its niche use case, though it's not a high-velocity project.

Single maintainer (pedrozath) is a moderate risk. The dependency tree appears heavy (bundler config, many bin/ executables suggest numerous gems). No recent activity data provided, so staleness risk is unclear. Breaking changes in music theory definitions are unlikely, but gem dependency updates could cause issues if not regularly maintained. Recommend checking CHANGELOG.md and GitHub Issues for activity recency.

No specific PR or milestone data visible in the file list. The presence of CHANGELOG.md and recent Ruby version pins (.ruby-version, .tool-versions) suggest maintenance occurs, but specific feature work is not evident from the static file structure alone. Check GitHub Issues and Pull Requests for active development.

git clone https://github.com/pedrozath/coltrane.git
cd coltrane
bundle install
bin/coltrane --help

Or run the interactive REPL: bin/coltrane-interactive. For library use, add gem 'coltrane' to your Gemfile and bundle install.

Daily commands: CLI: bin/coltrane show chord chord:CM7 chord_representation:Guitar or bin/coltrane find scale by chords chords:E6/9-BM. Interactive REPL: bin/coltrane-interactive. Development tests: bundle exec rspec. Code checks: bundle exec rubocop.

• lib/coltrane.rb — Main entry point and gem loader that exposes all music theory functionality.
• lib/coltrane/commands.rb — Command dispatcher that routes CLI and programmatic requests to appropriate handlers.
• lib/coltrane/commands/command.rb — Base command class that all music theory queries inherit from—defines execution pattern.
• lib/coltrane/renderers/renderer.rb — Abstract renderer interface; all output formatters (text, guitar, piano) extend this.
• exe/coltrane — CLI entry point that parses arguments and executes commands for interactive/batch usage.
• lib/coltrane/representation.rb — Core abstraction for instrument-specific chord/note representations (guitar, piano, bass).

• Music Theory Engine (lib/coltrane/*.rb) (Pure Ruby) — Computes chords, scales, progressions, and their relationships using music theory rules
  • Failure mode: Invalid query results if pitch/interval calculations are wrong; mitigated by extensive test suite
• Representation Mapper (lib/coltrane/representation.rb) (Pure Ruby) — Converts abstract note sets into instrument-specific fingerings and positions
  • Failure mode: Incorrect fingering diagrams if note-to-position mapping is miscalibrated per instrument
• Text Renderer (lib/coltrane/renderers/) (String manipulation, terminal control codes) — Formats query results into human-readable terminal output with ASCII art
  • Failure mode: Garbled or unreadable output if terminal width assumptions are violated
• Command Dispatcher (lib/coltrane/commands.rb) (Ruby reflection/routing) — Routes CLI invocations and programmatic queries to appropriate command handlers
  • Failure mode: Command not found or incorrect command invoked if routing is misconfigured
• CLI Entry Point (exe/coltrane) (Argument parsing (likely Thor), ARGV handling) — Parses command-line arguments and invokes the command dispatcher
  • Failure mode: Argument parsing errors or help text mismatches if CLI schema diverges from dispatcher

• CLI arguments → undefined — undefined

Add a new music theory query command

1. Create a new command class inheriting from Command in lib/coltrane/commands/ (lib/coltrane/commands/your_new_command.rb)
2. Implement #build method returning the result object (chord, scale, or collection) (lib/coltrane/commands/command.rb)
3. Register the command in the dispatcher or auto-loader referenced by lib/coltrane/commands.rb (lib/coltrane/commands.rb)
4. Create a drawer class in lib/coltrane/renderers/text_renderer/ if custom output formatting is needed (lib/coltrane/renderers/text_renderer/base_drawer.rb)

Add support for a new instrument representation

1. Create a new drawer class for the instrument in lib/coltrane/renderers/text_renderer/ (lib/coltrane/renderers/text_renderer/representation_guitar_chord_drawer.rb)
2. Extend the representation logic to map notes to the instrument's fingerboard/keyboard (lib/coltrane/representation.rb)
3. Register the new drawer in the text renderer dispatcher (lib/coltrane/renderers/text_renderer.rb)
4. Test with commands that output instrument representations (e.g., get_chords_from_scale) (lib/coltrane/commands/get_chords_from_scale.rb)

Add a new chord progression type

1. Define progression template data (chord names and intervals) as needed by the theory engine (lib/coltrane/commands/get_chords_from_progression.rb)
2. Create or extend a command like get_chords_from_notable_progression to handle the new type (lib/coltrane/commands/get_chords_from_notable_progression.rb)
3. Add output rendering via the existing text_renderer drawers (lib/coltrane/renderers/text_renderer/theory_progression_drawer.rb)
4. Update available_notable_progressions to expose the new progression (lib/coltrane/commands/available_notable_progressions.rb)

• Ruby — Expressive DSL syntax suitable for music theory domain, fast prototyping and CLI tooling
• Text-based rendering (no graphics library) — Minimal dependencies; terminal output is portable, scriptable, and works in CI/CD environments
• Command pattern (lib/coltrane/commands/command.rb) — Decouples query logic from presentation; enables both CLI and programmatic API with shared business logic
• Representation abstraction — Single query (e.g., 'chords in scale') can render on guitar, piano, bass, ukelele without duplicating theory

• Pure ASCII/text rendering instead of SVG or graphic output

  • Why: Simplifies distribution and eliminates graphics library dependencies
  • Consequence: Guitar chord diagrams and piano layouts are text-based and less visually refined; limits graphical detail

• Single-threaded, blocking command execution

  • Why: Simpler state management for CLI tool; music theory queries are typically sub-second
  • Consequence: No concurrent queries; long-running operations (e.g., exhaustive progression search) block the CLI

• Representation as a separate abstraction from theory objects

  • Why: Theory (chords, scales) remain instrument-agnostic; rendering is pluggable
  • Consequence: Two-step pipeline (query → map to instrument) adds modest latency and code duplication per instrument

• MIDI synthesis or audio playback
• Real-time performance or live instrument interaction
• GUI or graphical score notation
• Network API or cloud deployment
• Machine learning-based chord recognition
• Non-Western music systems or microtonal tuning

No obvious environment variables or external service dependencies visible. Ruby version constraints may apply (.ruby-version exists), so ensure local Ruby matches the pinned version. The bin/ directory is full of bundler-managed executables—do not edit directly, always use bundle exec <command>. Music theory conventions in the library (e.g., note naming, chord naming schemes) may assume Western 12-tone equal temperament; extending to other tuning systems would require significant rework.

• Chord voicing and inversion — Coltrane renders chords on different instruments by computing inversions and voicings; understanding how the same chord can be played in multiple ways across a fretboard is core to the library's value
• Scale modes and modal interchange — The library finds scales containing specific chords and progressions; knowing how Dorian, Phrygian, and other modes relate is essential for understanding scale search results
• Chromatic and diatonic pitch relationships — Coltrane calculates which notes belong to which chords/scales using interval distances in semitones; this is fundamental to all note-matching logic
• Fretboard topology and string tuning — Different instruments have different string counts and tunings; the library must handle Guitar (6-string E-A-D-G-B-E), Bass (4-string), Ukulele (4-string reentrant), and Piano (chromatic layout) topologies differently
• Chord progressions and functional harmony — Coltrane recommends next chords in a progression (Jazz, Blues, Pop styles); understanding why CM7 → Dm7 works requires knowing harmonic function and voice leading principles
• Ruby DSL patterns and metaprogramming — As a library, Coltrane likely uses method_missing, define_method, or class_eval to provide a fluent API for chord/scale building; understanding Ruby metaprogramming is key to modifying the API
• Set theory and note enharmonic equivalence — C# and Db are the same pitch but different note names; Coltrane must handle enharmonic spelling for accurate scale/chord identification and display

• jgoerzen/music21 — Python music theory library with similar goals (chords, scales, progressions); useful reference for algorithm design if porting features
• tonaljs/tonal — JavaScript music theory library with similar API surface (scale/chord generation); demonstrates how to structure music theory abstractions in a different language
• ciconia/musictheory.js — Another JavaScript music theory implementation; useful for comparing note/chord representation patterns
• ruby-music-dsl/ruby-music — Related Ruby music gem for composition/MIDI generation; potential integration point for Coltrane users who want to generate MIDI from theory outputs
• rails/rails — Coltrane is Ruby but not Rails-based; relevant for any junior unfamiliar with non-Rails Ruby gem architecture

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Migrate from Travis CI to GitHub Actions

The repo uses .travis.yml which is outdated. Travis CI has become less popular in the open source community. GitHub Actions is free, faster, and better integrated with GitHub. This would modernize the CI/CD pipeline and ensure the build status badge reflects current testing.

• [ ] Create .github/workflows/tests.yml with Ruby test matrix (2.6+, 3.0+, 3.1+)
• [ ] Add linting step using RuboCop (bin/rubocop exists in repo)
• [ ] Remove or deprecate .travis.yml file
• [ ] Update README.md badge from Travis to GitHub Actions
• [ ] Test locally with act tool to validate workflow

Complete the truncated README 'Features' section and add API documentation

The README's Features section ends abruptly with 'F' (incomplete). Additionally, there's no API documentation for the library portion—only CLI usage is shown. New contributors need clear examples of how to use Coltrane as a library via require 'coltrane'.

• [ ] Complete the Features list in README.md (reference lib/coltrane.rb to understand what's available)
• [ ] Add 'Library Usage' section with code examples for: note operations, scale queries, chord finding
• [ ] Create CONTRIBUTING.md with development setup (bin/setup already exists)
• [ ] Add API documentation for main classes in lib/coltrane/ (suggest YARD documentation format)
• [ ] Link to generated docs from README

Add comprehensive RSpec test suite for lib/coltrane core modules

.rspec config exists but test coverage is low (per CodeClimate badge). The lib/coltrane directory likely contains untested music theory calculations (notes, scales, chords, progressions). Adding focused unit tests would improve maintainability and help new contributors understand the codebase.

• [ ] Identify core classes in lib/coltrane/ (likely: Note, Scale, Chord, ChordProgression based on CLI features)
• [ ] Create spec/coltrane/note_spec.rb with tests for note creation, transposition, enharmonic equivalents
• [ ] Create spec/coltrane/scale_spec.rb with tests for scale generation and note membership
• [ ] Create spec/coltrane/chord_spec.rb with tests for chord building and voicings
• [ ] Run bundle exec rspec --cov and aim for >80% coverage on core logic

• Add visual fretboard representations for 5-string bass in lib/coltrane/representations/ or equivalent; currently only guitar/ukulele/piano are mentioned in the README, bass support is incomplete.
• Write integration tests in spec/ for the full CLI flow (e.g., end-to-end test calling coltrane find chord by notes notes:C-E-G and validating output format); RSpec config exists but test coverage for CLI output parsing is likely thin.
• Document the music theory calculation algorithm for chord voicing and fretboard positioning in a doc/ or ARCHITECTURE.md file; new contributors cannot easily understand how to add new instruments without reading the source.

The Coltrane music theory library has a moderate security posture. Primary concerns include: (1) unnecessary gem binaries in version control increasing attack surface, particularly debugging tools like pry and byebug; (2) potential input validation gaps in the CLI command processing; and (3) dependency management best practices. The project appears to be a utility library without direct database or network exposure, which reduces some risk categories. No obvious hardcoded credentials were detected in the file listing. Recommendations focus on cleaning up the bin directory, implementing robust input validation for CLI tools, and establishing regular dependency scanning practices.

• High · Multiple Gem Binaries in Repository Root — bin/ directory (multiple files including bin/pry, bin/byebug, bin/rescue, etc.). The /bin directory contains numerous executable scripts from bundled gems (guard, pry, bundler, etc.). This increases the attack surface and could allow arbitrary code execution if an attacker compromises gem dependencies or modifies these binaries. The presence of debugging tools like 'pry', 'byebug', and 'rescue' in production could also enable unauthorized access. Fix: Remove or exclude unnecessary gem binaries from version control. Add 'bin/' to .gitignore and rely on bundle exec to run commands. Ensure debugging tools are only available in development/test environments.
• Medium · Interactive CLI Tool Without Input Validation Indicators — lib/coltrane/commands/ directory, bin/coltrane, bin/coltrane-interactive. The codebase includes an interactive CLI tool (bin/coltrane-interactive) and command-line interface for processing user input. Without visible input validation patterns in the file structure, there is a risk of injection attacks if user input is not properly sanitized before processing. Fix: Implement comprehensive input validation and sanitization for all CLI inputs. Use allowlists for musical note/chord input. Validate and escape any user input before processing or displaying.
• Medium · Potential Dependency Version Lock Issues — Gemfile.lock, coltrane.gemspec. Gemfile.lock exists but the actual dependency versions and security status cannot be fully assessed from provided context. Outdated gems could contain known vulnerabilities. Fix: Regularly run 'bundle audit' to check for known vulnerabilities in dependencies. Update gems frequently and pin to secure versions. Consider using automated dependency scanning in CI/CD pipeline.
• Low · Test Coverage Configuration Exposed — README.md. CodeClimate badge and test coverage metrics are publicly displayed, potentially revealing information about code quality and test gaps that could be exploited. Fix: While not a critical issue, consider limiting exposure of detailed metrics. Ensure test coverage includes security-critical code paths.
• Low · Travis CI Configuration Present — .travis.yml. The .travis.yml file suggests CI/CD pipeline configuration. If this file contains secrets or exposes build details, it could be a security concern. Fix: Audit .travis.yml to ensure no secrets, API keys, or credentials are hardcoded. Use encrypted environment variables for sensitive data. Ensure build logs do not expose sensitive information.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.