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/thoughtbot/suspenders 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 the board

• Last commit 1d ago
• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 75% 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 thoughtbot/suspenders repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/thoughtbot/suspenders.

What it runs against: a local clone of thoughtbot/suspenders — 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 thoughtbot/suspenders | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "thoughtbot/suspenders(\\.git)?\\b" \\
  && ok "origin remote is thoughtbot/suspenders" \\
  || miss "origin remote is not thoughtbot/suspenders (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

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

Suspenders is a Rails application template generator that bootstraps new Rails projects with thoughtbot's standard defaults (PostgreSQL, RSpec, Sidekiq, Redis, GitHub Actions CI) and is optimized for single-command deployment to Heroku. It wraps rails new with pre-configured gems, initializers, Procfile configuration, and test infrastructure to eliminate boilerplate setup. CLI-driven gem: exe/suspenders entry point calls lib/suspenders/cli.rb which orchestrates lib/templates/ directory containing template.rb and pre-built Rails structure (app/, config/initializers/, lib/tasks/, spec/support/). The template applies these files to a new Rails app via Rails' built-in templating system.

Rails developers at thoughtbot and other teams who need to scaffold new production-ready Rails applications quickly with sensible defaults, particularly those deploying to Heroku who want PostgreSQL + Sidekiq + RSpec pre-configured.

Production-ready and actively maintained. The project has CI workflows (GitHub Actions in .github/workflows/main.yml), a release process (RELEASING.md), security scanning, and enforces code standards (.standard.yml). Presence of Gemfile.lock, NEWS.md versioning history, and structured issue/PR templates indicate mature project governance.

Low risk for a template generator. Risks are primarily: (1) Rails version coupling—Suspenders requires the latest Rails version, so breaking Rails releases could require rapid updates; (2) Heroku-specific assumptions in Procfile/config that may diverge from user needs; (3) dependency freshness—Redis and PostgreSQL versions specified in README may drift. Single-maintainer risk is mitigated by thoughtbot's institutional backing.

Active maintenance visible from GitHub workflows (dynamic-readme.yml, dynamic-security.yml, stale.yml) that auto-update documentation and manage issues. FEATURES.md and GOALS.md suggest ongoing feature refinement. Workflows in .github/workflows/main.yml indicate CI validation on each commit.

gem install suspenders
gem update rails
suspenders new my_app
cd my_app
gh secret set RAILS_MASTER_KEY "$(cat config/master.key)"

Daily commands: This is a generator, not a runnable app. To test locally: bin/setup installs dependencies, bin/qa runs quality checks (linting via Standard, tests via RSpec on lib/templates/spec/). To generate a test app: exe/suspenders new test_app.

• lib/suspenders/cli.rb: Entry point for the suspenders command that parses options and invokes Rails' template system
• lib/templates/Procfile: Defines Heroku process types (web, worker) for production deployment
• lib/templates/Procfile.dev: Local development process file for running Rails, Sidekiq, and other services via Foreman
• lib/templates/config/initializers/sidekiq.rb: Configures Sidekiq background job processor with Redis integration
• lib/templates/spec/support/: Pre-configured RSpec helpers (action_mailer, factory_bot, shoulda_matchers, i18n, driver) that all generated apps inherit
• .github/workflows/main.yml: CI/CD pipeline validating the template generation and running tests on commits
• FEATURES.md: Public documentation of what this template adds to a Rails app—essential reference for users
• Gemfile: Development dependencies for testing and maintaining Suspenders itself (not the generated app)

To add new defaults: modify lib/templates/ structure (Rails files under app/, config/, lib/, spec/). To change template behavior: edit the unnamed template.rb file in lib/templates/ (mentioned in README but path not explicit in file list—likely lib/templates/template.rb). To update CLI: edit lib/suspenders/cli.rb. Add new gems to the template's Gemfile injections.

Critical hidden trap: The README states 'require_master_key' is enabled in generated apps, requiring users to manually set RAILS_MASTER_KEY as a GitHub secret and Heroku config var—this is non-obvious and will fail CI/deploys silently if skipped. Second trap: Suspenders mandates the latest Rails version (stated in Prerequisites); using an older Rails version will fail template application. Third trap: Generated apps depend on Redis and PostgreSQL addons on Heroku; heroku addons:create commands in README are mandatory, not optional. Fourth trap: The template skips --solid (Rails 8 Solid ecosystem) in favor of Sidekiq; users unfamiliar with this choice may be confused by missing Solid Queue.

• Rails Application Templates — Suspenders' entire mechanism—it uses Rails' built-in template system (template.rb scripts) to inject code into new apps; understanding this is essential to modifying or extending the generator
• Heroku Procfile Process Model — Suspenders generates Procfile and Procfile.dev to define web server and worker processes; this is specific to Heroku deployment and non-portable to other hosts
• RSpec Testing Framework — Suspenders skips Rails' default Minitest in favor of RSpec; generated apps have RSpec-specific support helpers (lib/templates/spec/support/) that require RSpec knowledge
• Sidekiq Background Job Processing — Redis-backed background job processor configured by default in Suspenders apps; critical for async work and explicitly chosen over Rails 8 Solid Queue
• Rails Master Key & Encrypted Credentials — Suspenders enables require_master_key, meaning all generated apps use Rails' encrypted credentials system; users must manage config/master.key as a secret
• GitHub Actions CI/CD Workflows — Suspenders generates apps with GitHub Actions workflows (.github/workflows/) for automated testing; the generator itself validates via these workflows
• Ruby Gem Packaging & Distribution — Suspenders itself is distributed as a Ruby gem (installed via gem install suspenders); understanding gem structure (lib/, exe/, Gemfile, .gemspec) is needed to contribute to the generator itself

• rails/rails — Core Rails framework that Suspenders wraps; Suspenders depends on latest Rails version and uses its template system
• thoughtbot/dotfiles — thoughtbot's shared environment config (referenced in README for PostgreSQL preference rationale); complementary to Suspenders for full dev setup
• thoughtbot/refactoring-rails — Companion thoughtbot project providing refactoring patterns for Rails apps—natural next step after scaffolding with Suspenders
• jeremyevans/roda — Lightweight Rails alternative; relevant context for understanding why Suspenders chose Rails over microframeworks for thoughtbot projects
• sidekiq/sidekiq — Background job framework pre-configured in all Suspenders-generated apps via lib/templates/config/initializers/sidekiq.rb

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 integration tests for CLI template generation

The repo has lib/suspenders/cli.rb which handles the core template generation logic, but spec/suspenders_spec.rb appears minimal. There are no tests verifying that generated Rails apps include all expected files from lib/templates/. This is critical since the entire value proposition depends on correct template scaffolding. Tests should verify template files are copied, ERB templates are rendered correctly, and optional features generate expected outputs.

• [ ] Expand spec/suspenders_spec.rb with tests that invoke CLI and verify template files exist in output
• [ ] Add tests for each template directory: lib/templates/config/initializers/, lib/templates/app/views/, lib/templates/spec/support/
• [ ] Add tests verifying Procfile, Procfile.dev, and web.rb are correctly generated
• [ ] Add tests for conditional template logic (e.g., Sidekiq configuration inclusion based on flags)

Document template customization points in CONTRIBUTING.md

CONTRIBUTING.md exists but likely doesn't explain how to add new template files, modify existing ones, or test template changes locally. New contributors can't easily understand the flow: edit lib/templates/ → test with bin/setup → PR. This blocks contributions to core features like new initializers or view partials.

• [ ] Add 'Working with Templates' section to CONTRIBUTING.md explaining the lib/templates/ directory structure
• [ ] Document how to add a new template file (e.g., new initializer) and test it locally
• [ ] Add example: 'To add a new config initializer, create lib/templates/config/initializers/my_feature.rb, then run suspenders new test_app to verify'
• [ ] Reference the exe/suspenders entry point and explain how templates are copied into generated apps

Add Ruby version validation test in spec/suspenders_spec.rb

The repo specifies .ruby-version and requires the latest Rails, which implies a minimum Ruby version. However, there's no test verifying that the CLI rejects or warns users with outdated Ruby versions before attempting to generate a template. This is a critical UX issue since failures will occur mid-generation rather than upfront.

• [ ] Add test to spec/suspenders_spec.rb that mocks RUBY_VERSION and verifies CLI validates it
• [ ] Update lib/suspenders/cli.rb to check Ruby version and raise SystemExit with helpful error message if too old
• [ ] Add test verifying the error message mentions the required Ruby version and where to find .ruby-version
• [ ] Update README.md Prerequisites section to explicitly state minimum Ruby version required

• Add test coverage for the Sidekiq initializer template (lib/templates/config/initializers/sidekiq.rb) by creating a spec file that validates configuration injection into generated apps
• Document the exact path and content of the generated template.rb file currently referenced in README but missing from the file list—add this to FEATURES.md with inline examples of Gemfile mutations
• Create a GitHub Actions workflow that validates Suspenders-generated apps can boot without errors, catching regressions in template structure or gem compatibility on each commit

The Suspenders Rails template project demonstrates reasonable security practices with existing vulnerability disclosure policy, CI/CD pipeline, and code quality tools. However, the analysis is limited by missing dependency file contents. Primary concerns are: (1) inability to verify dependency security status without Gemfile.lock content, (2) lack of security-specific guidance in generated templates, and (3) minimal technical security documentation. The project would benefit from automated dependency scanning visibility, enhanced security documentation in the template itself, and explicit secure coding practice guidelines for maintainers and users.

• Medium · Incomplete Dependency Analysis — Gemfile.lock. No Gemfile.lock content provided for analysis. Unable to verify if dependencies have known security vulnerabilities. This is critical for a Rails template project that generates new applications. Fix: Provide Gemfile.lock content for analysis. Implement automated dependency scanning using tools like Bundler Audit or Dependabot in CI/CD pipeline (already configured in .github/workflows). Regularly update dependencies and monitor for CVEs.
• Low · Missing CODEOWNERS File Details — CODEOWNERS. CODEOWNERS file exists but content not provided. Unable to verify security review requirements for code changes. Fix: Ensure CODEOWNERS file designates security-sensitive paths (e.g., config/, lib/suspenders/) to require approval from security-conscious maintainers.
• Low · Potential Development Seeder in Templates — lib/templates/lib/development/seeder.rb. lib/templates/lib/development/seeder.rb file exists. Development-only code in templates could accidentally be used in production if not properly guarded. Fix: Verify that development seeder files are only loaded in development/test environments. Add guards like 'if Rails.env.development?' and ensure proper documentation.
• Low · Security Documentation Present but Minimal — SECURITY.md. SECURITY.md exists with responsible disclosure guidance, which is positive. However, it refers to external URL and lacks specific technical security guidelines for template users. Fix: Enhance SECURITY.md with security best practices for applications generated from this template, such as: environment variable management, secret handling, SQL injection prevention, XSS mitigation, etc.
• Low · No Evidence of Input Validation Documentation — FEATURES.md, GOALS.md, CONTRIBUTING.md. As a Rails template generator, no visible documentation on secure coding practices for generated applications regarding input validation and sanitization. Fix: Add security guidelines to CONTRIBUTING.md and template documentation covering Rails security best practices (strong parameters, Rails helpers for XSS prevention, query parameterization).

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.