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/guides 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 — Missing license — unclear to depend on

• Last commit 1w ago
• 38+ active contributors
• Distributed ownership (top contributor 9% of recent commits)
• CI configured
• Tests present
• ⚠ No license — legally unclear to depend on

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

What it runs against: a local clone of thoughtbot/guides — 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/guides | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

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

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

# 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 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/guides"
  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).

thoughtbot/guides is a curated style guide repository documenting programming conventions, best practices, and collaboration protocols across Ruby, Swift, JavaScript/TypeScript, and other languages. It provides opinionated guidance on code organization, naming, testing, code review, accessibility, and security—designed to enforce consistency across teams at thoughtbot and the open-source community. Flat, category-driven structure: top-level folders for each language/protocol (ruby/, swift/, javascript-typescript/, code-review/, etc.), each containing a README.md with the actual guide. CI/CD configured in .github/workflows/ with linting (markdownlint-cli2) and code review automation. A _template/ directory provides structure for new guides.

Software engineers, tech leads, and open-source contributors at thoughtbot and beyond who need prescriptive guidance on writing consistent, maintainable code across multiple languages (Ruby, Swift, JavaScript) and ensuring team alignment on collaboration practices like code review and product review.

Highly mature and actively maintained. The repo has structured guides across 20+ language and framework categories, enforced linting via Hound CI (.hound.yml), and Git workflows managed with Lefthook. It is backed by thoughtbot's institutional weight and clearly supports long-term use, though it's a documentation project rather than executable software.

Minimal risk for users. The repo has only two dependencies (markdownlint-cli2 and lefthook), both well-established. The main risk is outdated guidance—some guides may lag behind framework evolution (Rails, React versions). No breaking changes affect users since this is documentation. Contribution risk is low given thoughtbot's stewardship and the one-week review policy.

Active maintenance with Markdown linting via .markdownlint-cli2.jsonc and Git hooks via lefthook.yml. Recent tooling setup includes .tool-versions for consistency and mise.toml for dependency management. Contributions are governed by the one-week review policy documented in CONTRIBUTING.md.

git clone https://github.com/thoughtbot/guides.git
cd guides
npm install
npm run lint

Daily commands: This is a documentation repository—no server to run. To validate locally: npm run lint checks Markdown syntax against .markdownlint-cli2.jsonc rules. Lefthook (configured in lefthook.yml) can enforce linting on git hooks.

• README.md: Master index documenting all guide categories, high-level principles (consistency, DRY), and language conventions—entry point for all users.
• CONTRIBUTING.md: Defines contribution workflow and the critical one-week review policy that governs all PRs, setting expectations for maintainers and contributors.
• .hound.yml: Configures Hound CI for automated code review on PRs, enforcing style consistency across the guides themselves.
• .markdownlint-cli2.jsonc: Defines Markdown linting rules (npm run lint), ensuring consistent formatting across all guide files.
• ruby/README.md: Largest language guide (5362 LOC); core guide for the Ruby community at thoughtbot with Rails-specific conventions.
• swift/README.md: Second-largest guide (2683 LOC); iOS-focused, documents Swift idioms and best practices for Apple platforms.
• code-review/README.md: Collaboration protocol guide detailing code review process, feedback styles, and team interaction norms.
• _template/: Template structure (_template/README.md, _template/how-to/) for contributors creating new guides; ensures consistency.

Add or edit language-specific guides in <language>/README.md (e.g., ruby/README.md, swift/README.md). Follow the _template/ directory structure for new categories. Use Markdown; validate with npm run lint. For collaboration guides, edit code-review/README.md, open-source/README.md, or product-review/README.md. Submit PRs for review; wait one week per CONTRIBUTING.md.

No hidden traps. Straightforward documentation repo: npm install pulls markdownlint-cli2; npm run lint validates syntax. The one-week review policy is enforced by convention, not automation. No required environment variables, services, or version constraints beyond Node.js for linting tools.

• Style Guide Philosophy: Consistency > Perfection — The core principle stated in the README ('Be consistent. Don't rewrite existing code...') shapes how to read and apply these guides—they prioritize team alignment over purism, affecting PR review tone.
• Semantic Markdown Linting — markdownlint-cli2 enforces structural consistency in the guides themselves (line length, heading hierarchy, link validity); understanding this prevents CI failures on contributions.
• Git Hooks & Lefthook — Lefthook automates pre-commit linting and validation (e.g., running npm run lint before commit); critical for enforcing guide consistency locally before PR submission.
• Code Review as Protocol — code-review/README.md treats code review as a documented team practice with specific feedback styles and psychological safety norms, not just a technical gate.
• Accessibility-First Web Design — accessibility/README.md documents WCAG compliance and inclusive design; understanding this influences HTML, CSS, and Rails view guide recommendations.
• Object-Oriented Design Principles — object-oriented-design/README.md covers SOLID and DRY patterns; foundational to Ruby and Swift guide decisions on class design and inheritance.
• GraphQL Best Practices & Query Optimization — graphql/README.md documents query patterns and server-side best practices; relevant for teams adopting GraphQL alongside Rails or JavaScript backends.

• airbnb/javascript — Equivalent JavaScript/TypeScript style guide; direct alternative for javascript-typescript/ guidance, useful for comparing philosophy and depth.
• ruby/rubocop — RuboCop is the Ruby linter recommended by most Ruby guides and would automate enforcement of ruby/README.md rules; complementary tooling.
• realm/SwiftLint — SwiftLint enforces Swift style rules; directly compatible with swift/README.md guidance for automated linting of iOS projects.
• thoughtbot/factory_bot — thoughtbot's testing library for Rails; implementation of patterns documented in the guides' testing and Rails sections.
• thoughtbot/suspenders — thoughtbot's Rails template project; applies the rails/README.md and ruby/README.md guidance in a production starter template.

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.

Complete the incomplete README.md languages section and add missing Security/Web/Web Performance guides

The README.md has an incomplete 'Languages' section (cuts off at Bash) and references Security, Web, and Web Performance in the Protocols section, but these directories don't exist in the file structure. A new contributor should either: (1) add the missing directories with proper README.md files, or (2) update README.md to remove broken links and complete the languages list. This improves navigation and prevents 404s.

• [ ] Check if security/, web/, and web-performance/ directories should exist by reviewing git history or issues
• [ ] Either create missing guide directories (security/README.md, web/README.md, web-performance/README.md) with initial content structure matching the _template pattern, or remove the broken references from README.md
• [ ] Complete the truncated Languages section in README.md to include all language guides present in the repo (Python, Rails, GraphQL, etc.)
• [ ] Run 'npm run lint' to ensure markdown compliance
• [ ] Verify all internal links in README.md resolve correctly

Add a security/README.md guide with specific secure coding practices

The repo has references to Security in README.md, and rails/ai-rules/rules/security.md exists, indicating security is important. However, there's no security/ directory at the top level. Creating a comprehensive security guide (similar in structure to code-review/, accessibility/) would provide cross-language security practices and centralize security guidelines referenced throughout the repo.

• [ ] Create security/ directory with README.md following the structure of other guides
• [ ] Reference and summarize security best practices from rails/ai-rules/rules/security.md
• [ ] Add sections for common security concerns (authentication, authorization, secrets management, input validation, CORS, etc.) applicable across languages
• [ ] Link from main README.md Protocols section and verify no broken references remain
• [ ] Run markdownlint to ensure consistency with existing guides

Enhance the CI/linting workflow to validate guide consistency and enforce structure compliance

The repo has markdownlint configured but .github/workflows/linting.yml and main.yml exist without visible validation that new guides follow the expected structure (e.g., each guide should have a README.md, optional how-to/ subdirectory structure as shown in _template/). A new contributor could enhance the workflow to validate: (1) each language/guide directory has a README.md, (2) front matter consistency, (3) proper reference linking between guides.

• [ ] Review current .github/workflows/linting.yml to understand existing checks
• [ ] Add a custom linting script (e.g., in a scripts/ directory) that validates: all guide directories contain README.md files, and follows the _template/ structure convention
• [ ] Update linting.yml workflow to run this validation on pull requests
• [ ] Document the validation rules in CONTRIBUTING.md so contributors understand expected structure
• [ ] Test the workflow locally using lefthook.yml (already configured for pre-commit hooks)

• Add concrete code examples to the Swift guide (swift/README.md) for optional binding and guard statements—currently minimal; see how ruby/README.md and javascript-typescript/README.md structure detailed examples.
• Document Bash/Shell best practices in bash/README.md and shell/ (latter missing)—currently minimal guidance; could cover variable scoping, error handling, and shellcheck integration.
• Create a 'Testing with Jest' or 'Testing with RSpec' guide structure under testing-jest/ and testing-rspec/ directories (referenced in main README but files don't exist); add assertion patterns and mock examples.

This repository is a documentation/guides project with minimal security risk. The codebase contains only configuration files, markdown documentation, and sample code snippets. Primary concerns are dependency management (keeping markdownlint-cli2 and lefthook updated) and CI/CD configuration best practices. No hardcoded secrets, injection vulnerabilities, or misconfigured infrastructure were detected. The project follows security best practices by including CODE_OF_CONDUCT.md and CONTRIBUTING.md files. Recommendations focus on proactive dependency scanning and lock file management in build pipelines.

• Low · Outdated markdownlint-cli2 Dependency — package.json. The markdownlint-cli2 dependency is pinned to version ^0.19.0, which may contain known vulnerabilities. While this is a linting tool with limited attack surface, it's still a transitive dependency risk. Fix: Regularly update markdownlint-cli2 to the latest version. Consider using automated dependency scanning tools like Dependabot.
• Low · Outdated lefthook Dependency — package.json. The lefthook devDependency is pinned to ^1.11.3. While lefthook is a Git hook manager with lower attack surface, keeping it updated ensures security patches are applied. Fix: Regularly update lefthook to the latest version and monitor for security advisories.
• Low · Broad Linting Glob Pattern — package.json (scripts.lint). The lint script uses './**/*.md' which will process all markdown files recursively. If user-generated or untrusted content is added, the linter processes it without validation. Fix: Consider restricting the linting scope to trusted directories only. Implement pre-commit hooks to validate file sources before linting.
• Low · No Package Lock File Pinning — .github/workflows/linting.yml and .github/workflows/main.yml. While package-lock.json exists in the file structure, there's no indication of lock file verification in CI/CD workflows. This could allow supply chain attacks via dependency substitution. Fix: Ensure CI/CD workflows use 'npm ci' instead of 'npm install' and commit package-lock.json to enforce dependency pinning.

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.