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/sonic-pi-net/sonic-pi 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.

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 5 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{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 sonic-pi-net/sonic-pi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sonic-pi-net/sonic-pi.

What it runs against: a local clone of sonic-pi-net/sonic-pi — 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 sonic-pi-net/sonic-pi | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sonic-pi-net/sonic-pi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sonic-pi-net/sonic-pi.git
#   cd sonic-pi
#
# 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 sonic-pi-net/sonic-pi and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "app/CMakeLists.txt" \\
  && ok "app/CMakeLists.txt" \\
  || miss "missing critical file: app/CMakeLists.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "SYNTH_DESIGN.md" \\
  && ok "SYNTH_DESIGN.md" \\
  || miss "missing critical file: SYNTH_DESIGN.md"
test -f "BUILD-LINUX.md" \\
  && ok "BUILD-LINUX.md" \\
  || miss "missing critical file: BUILD-LINUX.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/sonic-pi-net/sonic-pi"
  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).

A software project. See architecture tab.

Developers.

See activity metrics.

Standard open source risks apply.

Check recent commits.

Check README for instructions.

• app/CMakeLists.txt — Root build configuration for the entire application; defines how the C++ codebase is compiled and linked across platforms.
• README.md — Project mission and overview; essential for understanding Sonic Pi's purpose as a live-coding musical instrument.
• CONTRIBUTING.md — Contribution guidelines and workflow; must-read for all developers before submitting changes.
• SYNTH_DESIGN.md — Core synthesizer architecture and audio engine design; foundational for understanding sound generation.
• BUILD-LINUX.md — Linux build instructions and platform-specific dependencies; critical for cross-platform development setup.
• .github/workflows/build.yml — CI/CD pipeline configuration; defines automated testing and build requirements for all commits.
• CHANGELOG.md — Version history and breaking changes; essential for understanding feature evolution and compatibility.

• CMake Build System (CMake 3.x, C++17) — Cross-platform compilation orchestration; detects OS, sets compiler flags, manages dependencies
  • Failure mode: Build fails on unsupported OS or missing audio libraries; cryptic compiler errors if CMakeLists.txt misconfigured
• Audio Engine (C++) (C++, JACK/PulseAudio/CoreAudio/WASAPI, lock-free queues) — Real-time synth scheduling, voice allocation, envelope generation, audio buffer management
  • Failure mode: Audio dropout, clicks/pops, CPU overload if voice count exceeds hardware capacity
• Synthesizer (C++) (C++, signal processing (DSP)) — Sound generation: oscillators, filters, ADSR envelopes, per-voice state management
  • Failure mode: Aliasing artifacts if sample rate not handled correctly; envelope clicks if attack/release too sharp
• Ruby/User-Facing Layer (inferred) (Ruby, REPL) — Live-coding interface for musical expressions; translates user commands to audio engine events
  • Failure mode: Script execution halts if syntax error; jitter in timing if Ruby GC pauses coincide with audio callbacks
• Test Suite (Catch2) (C++, Catch2) — Validates audio engine correctness, synth voice behavior, edge cases
  • Failure mode: Test suite failure reveals regression; missing tests allow subtle bugs (e.g., envelope state leaks)

• User script (Ruby) → undefined — undefined

Add a New Synth Voice

1. Review existing synthesizer architecture in SYNTH_DESIGN.md to understand voice generation pipeline (SYNTH_DESIGN.md)
2. Implement C++ synth class in app source directory (check BUILD-LINUX.md for header locations) (app/CMakeLists.txt)
3. Register new voice in audio engine initialization code (app/CMakeLists.txt)
4. Add unit tests in app/api-tests following Catch2 conventions (app/api-tests/CMakeLists.txt)
5. Document synth parameters and ADSR envelopes in SYNTH_DESIGN.md (SYNTH_DESIGN.md)

Add Support for a New Platform

1. Create new BUILD-PLATFORM.md with toolchain requirements and dependencies specific to target OS (BUILD-LINUX.md)
2. Update app/CMakeLists.txt to detect platform and apply conditional compilation flags (app/CMakeLists.txt)
3. Add GitHub Actions workflow in .github/workflows for CI/CD on new platform (.github/workflows/build.yml)
4. Update CONTRIBUTING.md with platform-specific developer notes (CONTRIBUTING.md)

Fix a Bug or Add a Test Case

1. Write new test in app/api-tests using Catch2 TEST_CASE macro following existing patterns (app/api-tests/CMakeLists.txt)
2. Implement fix in relevant source file referenced by app/CMakeLists.txt (app/CMakeLists.txt)
3. Run full test suite locally using instructions in TESTING.md (TESTING.md)
4. Document change in CHANGELOG.md with version and impact (CHANGELOG.md)

• C++ — High-performance real-time audio synthesis requires low-latency, efficient code execution with direct memory control
• CMake — Cross-platform build system enabling compilation on Linux, macOS, Windows, and Raspberry Pi with unified configuration
• Catch2 — Header-only C++ testing framework suitable for fast unit testing of audio engine components without runtime overhead
• Ruby (inferred) — Live-coding scripting language for user-facing music programming interface, separate from low-level audio synthesis

• Separate Ruby frontend from C++ audio engine

  • Why: Allows user-friendly scripting language while maintaining real-time audio performance
  • Consequence: Increased architectural complexity with IPC/messaging layer between interpreter and synthesis engine

• Raspberry Pi & ARM64 support as first-class citizens

  • Why: Makes Sonic Pi accessible to educational users with limited hardware budgets
  • Consequence: Must optimize for lower CPU/memory, constrains audio buffer sizes and polyphony

• Open-source (implied by LICENSE.md and CONTRIBUTING.md)

  • Why: Enables community contribution and educational transparency
  • Consequence: Requires careful governance of breaking changes and API stability

• Not a DAW (Digital Audio Workstation) — focused on live performance, not studio production/mixing
• Does not support MIDI file import/export as primary workflow
• Not a general-purpose programming language — domain-specific for musical expression
• Does not provide low-latency timing guarantees below ~20ms (OS-dependent)

Standard debugging applies.

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.

Add comprehensive API tests for Sonic Pi's C++ audio engine

The repo has a Catch2 test framework already set up at app/api-tests/ with vendor files, but the actual test suite appears sparse. Given that Sonic Pi is a live coding music environment, robust C++ API tests for the audio engine, synth parameters, and real-time scheduling are critical. This ensures audio quality and reliability across platforms (Linux, Mac, Windows, Raspberry Pi, ARM64).

• [ ] Review existing tests in app/api-tests/ directory structure
• [ ] Create test suites for core audio engine APIs (referenced in SYNTH_DESIGN.md)
• [ ] Add tests for real-time synth parameter updates and OSC message handling
• [ ] Add tests for cross-platform audio initialization and buffer management
• [ ] Integrate tests into .github/workflows/build.yml for all supported platforms

Create platform-specific build verification workflows in GitHub Actions

The repo has 6 platform-specific BUILD files (BUILD-LINUX.md, BUILD-MAC.md, BUILD-RASPBERRY-PI.md, BUILD-WINDOWS.md, BUILD-WINDOWS-ARM64.md, ARM64-BUILD-IMPROVEMENTS.md) but the .github/workflows/build.yml is minimal. Adding matrix workflows that actually execute these build scripts on their respective platforms will prevent platform-specific regressions and validate the detailed build documentation.

• [ ] Audit current .github/workflows/build.yml for missing platform targets
• [ ] Add macOS ARM64 (M1/M2) runner to build.yml (referenced in Catch2 workflows but not main build)
• [ ] Add Windows ARM64 build workflow (BUILD-WINDOWS-ARM64.md exists but untested in CI)
• [ ] Add Raspberry Pi cross-compilation verification (via Docker or appropriate runner)
• [ ] Add matrix strategy to test each BUILD-*.md guide with appropriate dependencies

Implement translation validation and workflow automation in CI

The repo has TRANSLATION.md and TRANSLATION-WORKFLOW.md documentation files indicating an active translation system, but there's no CI check to validate translation files (missing keys, formatting issues, or merge conflicts in translation diffs). This prevents translation regressions and makes it easier for translators to contribute.

• [ ] Create a GitHub Action workflow that validates translation file formats (likely YAML/JSON in app/ directory)
• [ ] Add a check to ensure no translation keys are missing compared to the base language file
• [ ] Add a linting step that validates translation file syntax before merge
• [ ] Document the validation process in TRANSLATION-WORKFLOW.md with specific file paths
• [ ] Set up automatic comment on PRs showing translation coverage for changed files

Check the issue tracker.

The Sonic Pi codebase demonstrates reasonable security practices with clear project structure and established build processes. The primary concerns are around dependency management (vendored libraries requiring manual updates), lack of explicit security documentation, and absence of visible security hardening measures in the build pipeline. No critical vulnerabilities or hardcoded secrets were identified in the file structure provided. The project would benefit from implementing a formal security policy, automating dependency updates, and documenting security controls in the CI/CD pipeline.

• Medium · Vendored Third-Party Dependencies — app/api-tests/vendor/Catch2-3.8.0/. The codebase includes vendored copies of third-party libraries (e.g., Catch2-3.8.0) directly in the repository. While this ensures reproducibility, it increases the maintenance burden for security patches and may lead to outdated vulnerable versions being shipped. Fix: Consider using a package manager (CMake FetchContent, vcpkg, Conan) to manage dependencies with automatic update notifications. At minimum, establish a regular patching schedule for vendored dependencies and document the versions pinned.
• Low · Potential Exposure of Development Configuration Files — .vscode/settings.json. .vscode settings and other development configuration files are committed to version control. While not inherently dangerous, they may reveal development practices or tool configurations that could aid attackers. Fix: Add development tool configuration files (.vscode, .idea, etc.) to .gitignore. Use shared configuration templates in documentation instead.
• Low · Limited Visibility into Build Configuration Security — Build configuration files (BUILD-*.md, CMakeLists.txt, .github/workflows/). Multiple build configuration files exist (BUILD-LINUX.md, BUILD-WINDOWS.md, etc.) but the repository structure does not provide clear evidence of security hardening flags, signed builds, or supply chain protections in the build pipeline. Fix: Document security measures in the build process: compiler security flags, signed artifacts, build reproducibility verification, and dependency pinning. Review GitHub Actions workflows for secure practices (secrets management, least privilege).
• Low · No Visible Security Policy or Vulnerability Disclosure — Repository root. The repository does not show a visible SECURITY.md file at the root level defining responsible disclosure procedures, though one exists in the Catch2 vendor directory. This may make it difficult for security researchers to report vulnerabilities. Fix: Create a SECURITY.md file at the root of the repository documenting: vulnerability reporting procedures, supported versions for security patches, and response timelines.

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.