{"id":47636714,"url":"https://github.com/slbug/claude-ruby-grape-rails","last_synced_at":"2026-05-06T08:02:25.428Z","repository":{"id":346230458,"uuid":"1189004895","full_name":"slbug/claude-ruby-grape-rails","owner":"slbug","description":"Claude Code plugin for Ruby, Rails, Grape, PostgreSQL, Redis, and Sidekiq development","archived":false,"fork":false,"pushed_at":"2026-04-18T22:26:19.000Z","size":1323,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-18T22:33:15.461Z","etag":null,"topics":["ai","ai-agent","ai-agents","ai-tools","claude","claude-code","llm","ruby","ruby-on-rails"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slbug.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T21:39:14.000Z","updated_at":"2026-04-18T22:25:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/slbug/claude-ruby-grape-rails","commit_stats":null,"previous_names":["slbug/claude-ruby-grape-rails"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/slbug/claude-ruby-grape-rails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slbug%2Fclaude-ruby-grape-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slbug%2Fclaude-ruby-grape-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slbug%2Fclaude-ruby-grape-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slbug%2Fclaude-ruby-grape-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slbug","download_url":"https://codeload.github.com/slbug/claude-ruby-grape-rails/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slbug%2Fclaude-ruby-grape-rails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32278249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-agents","ai-tools","claude","claude-code","llm","ruby","ruby-on-rails"],"created_at":"2026-04-02T00:16:33.091Z","updated_at":"2026-05-06T08:02:25.420Z","avatar_url":"https://github.com/slbug.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ruby/Rails/Grape Plugin for Claude Code\n\n**Claude Code is great. But it doesn't know that `default_scope` will bite you later, that `t.float` will corrupt your money fields, or that your Sidekiq job isn't idempotent.**\n\nThis plugin does. It coordinates **19 specialist agents** and **53 skills** that plan, implement,\nreview, and verify your Ruby/Rails/Grape code in parallel -- each with domain\nexpertise, fresh context, and enforced [Iron Laws](#iron-laws-non-negotiable-rules)\nthat catch the bugs your tests won't. It is now stack-aware enough to handle\nmixed Active Record + Sequel repos and Packwerk-style modular monoliths\nwithout flattening everything into generic Rails advice.\n\nThe plugin also keeps the runtime path leaner than older builds: read-only\nspecialist agents skip the project `CLAUDE.md` payload via `omitClaudeMd`,\nsession start writes a fast runtime snapshot before a quiet async refresh,\nand active plans keep structured scratchpads for dead ends, decisions, and\nhandoffs.\n\n```bash\n# You describe the feature. The plugin figures out the rest.\n/rb:plan Add real-time comment notifications\n\n# 4 research agents analyze your codebase in parallel.\n# A structured plan lands in .claude/plans/comment-notifications/plan.md\n# Then:\n\n/rb:work .claude/plans/comment-notifications/plan.md\n# Implements task by task. Verification checkpoints at key milestones.\n# Stops on programmatic Iron Law violations and pushes the rest into review-time checks.\n\n/rb:review\n# 4 specialist agents audit in parallel:\n# idioms, security, tests, verification.\n# Deduplicates findings. Flags pre-existing issues separately.\n```\n\nNo prompt engineering. No \"please check for N+1 queries.\" The plugin auto-loads\nthe right domain knowledge based on what files you're editing and enforces rules\nthat prevent the mistakes Ruby developers actually make in production.\n\nHook prerequisites: core hook guardrails expect `bash`, `jq`, `grep`, and\nstandard Unix utilities available on macOS/Linux/WSL such as `head`,\n`readlink`, `awk`, `cksum`, `mktemp`, `sed`, `find`, `cp`, `mv`, `rm`, `tr`,\n`wc`, `cat`, and `mkdir`. If a required dependency is missing, the plugin now\nsurfaces an explicit hook error or warning instead of silently disabling those\nchecks.\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│  💎 Ruby/Rails/Grape Plugin for Claude Code                         │\n│                                                                     │\n│  ┌──────────┬──────────┬──────────┬──────────┬──────────┐           │\n│  │    19    │    53    │   100+   │    14    │    22    │           │\n│  │  Agents  │  Skills  │   Refs   │  Events  │Iron Laws │           │\n│  └──────────┴──────────┴──────────┴──────────┴──────────┘           │\n│                                                                     │\n│  AGENTS                          COMMANDS                           │\n│  ─────────────────────           ──────────────────────────         │\n│  Reviewers (mostly sonnet)       Workflow                           │\n│    ruby-reviewer                   /rb:plan    /rb:work             │\n│    testing-reviewer                /rb:review  /rb:full             │\n│    security-analyzer (opus)        /rb:compound /rb:quick           │\n│    iron-law-judge                  /rb:brief   /rb:triage           │\n│    data-integrity-reviewer                                          │\n│    migration-safety-reviewer                                        │\n│    output-verifier                                                  │\n│                                                                     │\n│  Architecture (sonnet)           Investigation \u0026 Debug              │\n│    rails-architect                 /rb:investigate /rb:trace        │\n│    active-record-schema-designer   /rb:n1-check   /rb:perf          │\n│    rails-patterns-analyst          /rb:constraint-debug             │\n│    ruby-runtime-advisor            /rb:state-audit                  │\n│                                                                     │\n│  Investigation (sonnet)          Analysis \u0026 Review                  │\n│    deep-bug-investigator           /rb:audit    /rb:verify          │\n│    call-tracer                     /rb:techdebt /rb:boundaries      │\n│    dependency-analyzer             /rb:pr-review /rb:challenge      │\n│                                    /rb:research  /rb:document       │\n│                                                                     │\n│  Domain (sonnet)                 Knowledge (auto-loaded)            │\n│    sidekiq-specialist              hotwire-patterns                 │\n│    deployment-validator            active-record-patterns           │\n│    ruby-gem-researcher             ruby-idioms      security        │\n│                                    rails-contexts   sidekiq         │\n│                                    testing   deploy   runtime       │\n│                                                                     │\n│  Mechanical / Extraction (haiku)                                    │\n│    verification-runner                                              │\n│    web-researcher                                                   │\n│                                                                     │\n│  Hooks (plugin-wide, not tied to specific agents)                   │\n│    auto-format · ruby-syntax-check · iron-law-verify                │\n│    security-scan · debug-stmt-detect · error-critic                 │\n│    progress-tracking · db/prod/git                                  │\n│                                                                     │\n│  ───────────────────────────────────────────────────────────        │\n│  22 Iron Laws · Runtime Tooling · plan→work→verify→review→compound  │\n│  github.com/slbug/claude-ruby-grape-rails                           │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\nRuby-ish Edit/Write automation is delegated through\n[rubyish-post-edit.sh](plugins/ruby-grape-rails/hooks/scripts/rubyish-post-edit.sh),\nwhich fans out to Iron Law verification, formatting, syntax, and debug checks\nfor `*.rb`, `*.rake`, `Gemfile`, `Rakefile`, and `config.ru`. Generic safety\nhooks stay separate: the security reminder is now advisory, secret scanning\nstill watches all edits/writes and blocks when coverage cannot be trusted,\nprogress logging runs async, and the plan STOP reminder fires only on\n`Write(*plan.md)`. `block-dangerous-ops.sh` currently blocks four\ncommand families: destructive Rails/Rake DB tasks, Redis flushes, git force\npushes, and production-environment commands.\nDefault secret scanning is targeted per edit or inline payload and now fails\nclosed when the workspace root or scanner cannot be trusted. Strict mode\nbroadens that to recent-change sweeps and also fails closed when that broader\ncoverage cannot be trusted.\n[hooks.json](plugins/ruby-grape-rails/hooks/hooks.json)\nis the current wiring source of truth.\n\n## Installation\n\n### From GitHub (recommended)\n\n```bash\n# In Claude Code, add the marketplace\n/plugin marketplace add slbug/claude-ruby-grape-rails\n\n# Install the plugin\n/plugin install ruby-grape-rails\n```\n\n### From Local Path (for development)\n\n```bash\ngit clone https://github.com/slbug/claude-ruby-grape-rails.git\ncd claude-ruby-grape-rails\n\n# Run these commands from the cloned repo root.\n\n# Option A: Test local working-tree changes directly\nclaude --plugin-dir ./plugins/ruby-grape-rails\n\n# Option B: Validate marketplace install flow\n# Note: marketplace.json now uses git-subdir source, so this installs the\n# published GitHub-backed plugin source, not your uncommitted working tree.\n/plugin marketplace add .\n/plugin install ruby-grape-rails\n```\n\n### Known Limitations\n\n**Supported Environments**: This plugin is validated on macOS, Linux, and WSL.\nNative Windows is not currently supported.\n\n**Marketplace Install \u0026 Agent Permissions**: Marketplace-installed plugin agents\nfollow your session permission policy. If you want specialist agents to run Ruby\nverification commands without repeated prompts, add explicit `permissions.allow`\nrules for the tools they need.\n\n**Workarounds:**\n\n1. Add explicit rules to your project's `.claude/settings.json`:\n\n   ```json\n   {\n     \"permissions\": {\n       \"defaultMode\": \"acceptEdits\",\n       \"allow\": [\n          \"Bash(bundle *)\",\n          \"Bash(rails *)\",\n          \"Bash(rake *)\",\n          \"Bash(mkdir -p **/.claude/**)\",\n          \"Bash(*/bin/manifest-update *)\",\n          \"Grep(*)\",\n          \"Read(*)\",\n          \"Glob(*)\",\n          \"Write(**/.claude/plans/**)\",\n          \"Write(**/.claude/reviews/**)\",\n          \"Write(**/.claude/audit/**)\",\n          \"Write(**/.claude/research/**)\",\n          \"Write(**/.claude/solutions/**)\",\n          \"Write(**/.claude/skill-metrics/**)\",\n          \"Write(**/.claude/investigations/**)\"\n       ]\n     }\n   }\n   ```\n\n   Recursive `**/.claude/\u003cns\u003e/**` globs are required: plugin skills\n   write artifacts under nested per-agent subdirs (e.g.,\n   `.claude/reviews/{agent-slug}/{slug}-{datesuffix}.md`). Shallow\n   `Write(.claude/\u003cns\u003e/*)` globs do not match.\n\n2. Run `/rb:permissions` to scan recent prompts and propose safer\n   `settings.json` allowlists instead of growing them blindly\n3. Run `/update-config` to add the recommended Write rules above to\n   `settings.json` without hand-editing\n4. Use `--plugin-dir` for local development while iterating on the plugin itself\n\n## Configuration\n\nPer-shell environment toggles (no `settings.json` edit required):\n\n| Env var | Default | Effect when set |\n|---------|---------|-----------------|\n| `RUBY_PLUGIN_DISABLE_RULES_INJECTION` | `0` (injection on) | `=1` skips Iron Laws + Advisory Preferences injection on `SessionStart` and `SubagentStart`. Use when the plugin is installed at user scope but the active project is not Ruby/Rails/Grape. |\n| `RUBY_PLUGIN_STRICT_PERMS` | `0` (soft deny) | `=1` makes `block-dangerous-ops.sh` `PermissionRequest` deny include `interrupt: true`, fully stopping Claude rather than just denying the single command. |\n| `RUBY_PLUGIN_HOOK_MODE` | `default` | `=strict` broadens `secret-scan.sh` to recent-change sweeps and fails closed when broader coverage cannot be trusted. |\n| `RUBY_PLUGIN_COMPRESSION_TELEMETRY` | `0` (off) | `=1` opts in to verify-output compression telemetry collection at `${CLAUDE_PLUGIN_DATA}/compression.jsonl`. |\n\nSet per-shell, per-command, or via [direnv](https://direnv.net/) `.envrc`\nfor project-scoped values.\n\n### Recommended Claude Code env vars\n\n| Env var | Effect |\n|---------|--------|\n| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | `=1` enables the `SendMessage` tool. Required for spawn-fanout skills (`/rb:review`, `/rb:plan`, `/rb:brainstorm`, `/rb:investigate`) to resume agents that paused at their `maxTurns` cap. Without it, paused agents become coverage gaps with no recovery path. |\n\n## Getting Started\n\nNew to the plugin? Run the interactive tutorial:\n\n```bash\n/rb:intro\n```\n\nIt walks through the workflow, commands, and features in 8 short sections (~5 min).\nSkip to any section with `/rb:intro --section N`.\n\n## Quick Examples\n\n```bash\n# Just describe what you need — the plugin detects complexity and suggests the right approach\n\u003e Fix the N+1 query in the user dashboard\n\n# Plan a feature with parallel research agents, then execute\n/rb:plan Add email notifications for new comments\n/rb:work .claude/plans/email-notifications/plan.md\n\n# Full autonomous mode — plan, implement, review, capture learnings\n/rb:full Add user profile avatars with S3 upload\n\n# 4-agent parallel code review (idioms, security, tests, verification)\n/rb:review\n\n# Quick implementation — skip ceremony, just code\n/rb:quick Add pagination to the users list\n\n# Structured bug investigation with 4 parallel tracks\n/rb:investigate Timeout errors in the checkout flow\n\n# Project health audit across 5 categories\n/rb:audit\n```\n\nThe plugin auto-loads domain knowledge based on what files you're editing\n(Rails patterns for `*_controller.rb`, Active Record patterns for models, security rules for auth code)\nand enforces [Iron Laws](#iron-laws-non-negotiable-rules) that prevent common Ruby/Rails mistakes.\n\n## How It Works\n\n### The Lifecycle\n\nThe plugin supports an optional **Brainstorm** discovery step before the core **Plan → Work → Verify → Review → Compound** lifecycle. Each phase produces artifacts in a namespaced directory:\n\n```\n/rb:brainstorm (optional) → /rb:plan → /rb:work → /rb:verify → /rb:review → /rb:compound\n                                │           │            │              │              │\n                                ↓           ↓            ↓              ↓              ↓\n                   .claude/plans/{slug}/  (namespace)  (namespace)  (namespace)  .claude/solutions/\n```\n\n- **Plan** -- Research agents analyze your codebase in parallel, then synthesize a structured implementation plan\n- **Work** -- Execute the plan task-by-task with quick verification checks after each change\n- **Verify** -- Prefer the repo's native verify wrapper when present; otherwise run the full direct verification loop before review\n- **Review** -- Four specialist agents audit your code in parallel (idioms, security, tests, static analysis)\n- **Compound** -- Capture what you learned as reusable knowledge for future sessions\n\n### Key Concepts\n\n- **Filesystem is the state machine.** Each phase reads from the previous phase's output. No hidden state.\n- **Plan namespaces.** Each plan owns its implementation-state artifacts in `.claude/plans/{slug}/` -- plan, research, summaries, progress, scratchpad.\n- **Scratchpads are durable workflow memory.** Dead ends, decisions, and\n  handoffs survive long sessions and compaction instead of living only in chat.\n- **Reviews are standalone artifacts.** Reviewer outputs live under `.claude/reviews/`, not inside plan namespaces.\n- **Investigations are standalone artifacts.** `deep-bug-investigator`\n  writes its report to\n  `.claude/investigations/deep-bug-investigator/{slug}-{datesuffix}.md`\n  and returns a ≤300-word chat summary; the file is the real output.\n- **Plan checkboxes track progress.** `[x]` = done, `[ ]` = pending. `/rb:work` finds the first unchecked task and continues.\n- **One plan = one work unit.** Large features get split into multiple plans. Each is self-contained.\n- **Agents are automatic.** The plugin spawns specialist agents behind the scenes. You don't manage them directly.\n- **Specialist agents stay lean.** Reviewers and analyzers set\n  `omitClaudeMd: true` so subagents skip the entire project\n  `CLAUDE.md` payload (including the `/rb:init` stack notes —\n  Iron Laws + Advisory Preferences still arrive on `SubagentStart`\n  via `inject-rules.sh`). They are instructed to write only their\n  own artifacts under `.claude/`, not edit project code.\n- **The stack is detected, not guessed.** `/rb:init` and SessionStart hooks identify Rails/Grape/Sidekiq/Karafka, Active Record vs Sequel, and Packwerk/modular package layouts before giving guidance.\n- **Session start is split into fast sync + async refresh.** You get immediate\n  stack context from the quick snapshot while slower helper-version probes\n  refresh in the background.\n- **Fresh research is reused, not re-bought.** `/rb:plan` checks\n  `.claude/research/` and prior plan research before respawning\n  duplicate topic-research agents.\n- **Workflow continuity is hook-backed.** `PreCompact`, `PostCompact`, and\n  `StopFailure` warn before compaction, log failure context, and surface\n  re-read reminders after compaction or failed stops instead of relying only on\n  chat memory.\n\n### Plan Namespaces\n\nEvery plan gets its own directory with its implementation-state artifacts:\n\n```\n.claude/\n├── plans/{slug}/          # Everything for ONE plan\n│   ├── plan.md            # The plan itself (checkboxes = state)\n│   ├── research/          # Research agent output\n│   ├── progress.md        # Session progress log\n│   └── scratchpad.md      # Structured dead ends, decisions, hypotheses, handoffs\n├── research/              # Reusable cross-plan topic research\n├── reviews/               # Review artifacts (per-agent + consolidated)\n└── solutions/             # Compound knowledge (reusable across plans)\n```\n\nImplementation state stays under one plan namespace; review artifacts stay consistently under `.claude/reviews/`.\n\n## Architecture\n\n### Agent Hierarchy\n\nThe plugin uses 19 leaf agents organized by responsibility. Skill bodies\n(main session) spawn agents in parallel. Models vary by risk: `opus` for\nsecurity-critical (1 agent), `sonnet` for judgment-heavy specialists\n(16 agents), `haiku` for mechanical extraction (2 agents).\n\n```\n                ┌──────────────────────────────────────┐\n                │  Specialists (mixed — 17 agents)     │\n                │  Domain experts; called from skill   │\n                │  bodies (main session) in parallel.  │\n                │  security-analyzer is opus; rest     │\n                │  sonnet.                              │\n                └────────────────┬─────────────────────┘\n                                 │\n       ┌──────────────────┬──────┴───────┬──────────────────────┐\n       ▼                  ▼              ▼                      ▼\n┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐\n│  Reviewers   │  │ Architecture │  │ Investigation│  │   Domain         │\n│              │  │              │  │              │  │                  │\n│ ruby-        │  │ rails-       │  │ deep-bug-    │  │ sidekiq-         │\n│   reviewer   │  │   architect  │  │   investigator│ │   specialist     │\n│ security-    │  │ active-      │  │ call-tracer  │  │ deployment-      │\n│   analyzer   │  │   record-    │  │ dependency-  │  │   validator      │\n│   (opus)     │  │   schema-    │  │   analyzer   │  │ ruby-gem-        │\n│ testing-     │  │   designer   │  │              │  │   researcher     │\n│   reviewer   │  │ rails-       │  │              │  │                  │\n│ iron-law-    │  │   patterns-  │  │              │  │                  │\n│   judge      │  │   analyst    │  │              │  │                  │\n│ data-        │  │ ruby-runtime-│  │              │  │                  │\n│   integrity- │  │   advisor    │  │              │  │                  │\n│   reviewer   │  │              │  │              │  │                  │\n│ migration-   │  │              │  │              │  │                  │\n│   safety-    │  │              │  │              │  │                  │\n│   reviewer   │  │              │  │              │  │                  │\n│ output-      │  │              │  │              │  │                  │\n│   verifier   │  │              │  │              │  │                  │\n└──────────────┘  └──────────────┘  └──────────────┘  └──────────────────┘\n\n       ┌─────────────────────────────────────────────┐\n       │  Mechanical / Extraction (haiku — 2)        │\n       │  verification-runner — verification         │\n       │  web-researcher — web/source extraction     │\n       │  Called from skill bodies as leaf workers.  │\n       └─────────────────────────────────────────────┘\n```\n\n**Specialists** (mostly sonnet, security-analyzer opus) -- Domain experts, judgment-heavy tasks.\n**Mechanical / Extraction** (haiku) -- Compression, verification, web-research extraction (matches dashboard tier name).\n\n### How Planning Works\n\nWhen you run `/rb:plan Add real-time notifications`:\n\n```\n1. `/rb:plan` skill body analyzes your request from main session\n   │\n2. Spawns specialists IN PARALLEL via `Agent(subagent_type:)` calls:\n   ├── rails-patterns-analyst    (always -- scans your codebase)\n   ├── rails-architect           (if service/context changes needed)\n   ├── active-record-schema-designer (if database changes needed)\n   ├── security-analyzer         (if auth/user data involved)\n   ├── sidekiq-specialist        (if background jobs needed)\n   ├── web-researcher            (if unfamiliar technology)\n   └── ... up to 8 agents\n   │\n3. Each agent writes to `.claude/plans/{slug}/research/{topic}.md`\n   │\n4. Skill body reads each research artifact + synthesizes the plan\n   │\n5. Output: `.claude/plans/{slug}/plan.md` with [P1-T1] checkboxes\n```\n\n### How Review Works\n\nWhen you run `/rb:review`:\n\n```\n1. `/rb:review` skill body collects git diff + reviewer list\n   │\n2. `manifest-update prepare-run --skill=rb:review --slug=\u003cslug\u003e\n    --base-ref=\u003cref\u003e --agents=\u003ccsv\u003e` archives any prior manifest +\n   inits a fresh `.claude/reviews/\u003cslug\u003e/RUN-CURRENT.json`\n   (helper computes datesuffix, agent paths, consolidated path,\n   git pins)\n   │\n3. Spawns 4 EXISTING specialist agents in parallel:\n   ├── ruby-reviewer        → Idioms, patterns, error handling\n   ├── security-analyzer    → SQL injection, XSS, auth gaps\n   ├── testing-reviewer     → Test coverage, factory patterns\n   └── verification-runner  → zeitwerk:check, format, test\n   │\n4. Each reviewer writes to `.claude/reviews/{agent-slug}/{review-slug}-{datesuffix}.md`\n   │\n5. Skill body reads each artifact + dedupes + writes consolidated review\n   │\n6. Output: `.claude/reviews/{review-slug}-{datesuffix}.md`\n   Manifest: `.claude/reviews/{review-slug}/RUN-CURRENT.json` (status: complete)\n```\n\n## Usage Guide\n\n### Quick tasks (bug fixes, small changes)\n\nJust describe what you need. The plugin auto-detects complexity and suggests the right approach:\n\n```\n\u003e Fix the N+1 query in the dashboard\n\nClaude: This is a simple fix (score: 2). I'll handle it directly.\n```\n\nOr use `/rb:quick` to skip ceremony:\n\n```\n/rb:quick Add pagination to the users list\n```\n\n### Medium tasks (new features, refactors)\n\nUse `/rb:plan` to create an implementation plan, then `/rb:work` to execute it:\n\n```\n/rb:plan Add email notifications for new comments\n```\n\nThe plugin will:\n\n1. Spawn research agents to analyze your codebase patterns\n2. Show a completeness check (every requirement mapped to a task)\n3. Ask you how to proceed (start implementation, review plan, adjust)\n\nWhen starting implementation, the plugin recommends a **fresh session** for plans with 5+ tasks. The plan file is self-contained, so no context from the planning session is needed:\n\n```\n# In a new Claude Code session:\n/rb:work .claude/plans/email-notifications/plan.md\n```\n\n### Large tasks (new domains, security features)\n\nUse deep research planning:\n\n```\n/rb:plan Add OAuth login with Google and GitHub\n```\n\nThis spawns 4+ parallel research agents, then produces a detailed plan.\nFor security-sensitive features, the plugin will ask clarifying questions\nbefore proceeding. Or use `/rb:full` for fully autonomous development.\n\n### Fixing review issues\n\nAfter implementing, run a review:\n\n```\n/rb:review\n```\n\nFour parallel agents check your code (idioms, tests, security, verification). If blockers are found, the plugin asks whether to replan or fix directly:\n\n```\nReview found 2 blockers:\n1. Missing authorization in controller action -- security risk\n2. N+1 query in list_comments -- performance issue\n\nOptions:\n- Replan fixes (/rb:plan --existing)\n- Fix directly (/rb:work)\n- Handle myself\n```\n\n### Project health checks\n\nRun a comprehensive audit with 5 parallel specialist agents:\n\n```\n/rb:audit                    # Full audit\n/rb:audit --quick            # 2-3 minute pulse check\n/rb:audit --focus=security   # Deep dive single area\n/rb:audit --since HEAD~10    # Audit recent changes only\n```\n\nThe audit scores your project across 5 categories (architecture, performance, security, tests, dependencies) and produces an actionable report.\n\n### Full autonomous mode\n\nFor hands-off development:\n\n```\n/rb:full Add user profile avatars with S3 upload\n```\n\nRuns the complete cycle: plan (with research), work, verify, review,\ncompound. Halts on `/rb:verify --full` gate failure (HALTED_VERIFY_FAILED),\non review verdict `BLOCKED` (HALTED_REVIEW_BLOCKED) or `REQUIRES CHANGES`\n(HALTED_REVIEW_REQUIRES_CHANGES), or on missing/unparsable consolidated\nreview (HALTED_REVIEW_UNKNOWN); user decides next step.\n\n## Workflow Tips\n\n### Context management\n\n- `/rb:plan` creates a **self-contained plan file** with all implementation details\n- For 5+ task plans, start `/rb:work` in a **fresh session** to maximize context space\n- For small plans (2-4 tasks), continuing in the same session is fine\n\n### Resuming work\n\nPlan checkboxes are the state. If a session ends mid-work:\n\n```\n# Just run /rb:work on the same plan -- it finds the first [ ] and continues\n/rb:work .claude/plans/my-feature/plan.md\n```\n\n### Splitting large features\n\nWhen a feature has 10+ tasks across different domains, the plugin offers to split into multiple plan files:\n\n```\nCreated 3 plans (14 total tasks):\n1. .claude/plans/auth/plan.md (5 tasks -- login, register, reset)\n2. .claude/plans/profiles/plan.md (4 tasks -- avatar, bio, settings)\n3. .claude/plans/admin/plan.md (5 tasks -- dashboard, roles)\n\nRecommended order: 1 -\u003e 2 -\u003e 3\n```\n\nExecute each plan separately with `/rb:work`.\n\n### Learning from mistakes\n\nAfter fixing a bug or receiving a correction:\n\n```\n/rb:learn Fixed N+1 query -- always preload associations in service objects\n```\n\nThis updates the plugin's knowledge base so the same mistake is prevented in future sessions.\n\n## Iron Laws (Non-Negotiable Rules)\n\n\u003c!-- IRON_LAWS_START --\u003e\n\n\u003c!-- GENERATED FROM iron-laws.yml — DO NOT EDIT --\u003e\n\nThe plugin enforces **22 Iron Laws** that prevent common, costly mistakes:\n\n| Category | Count | Laws |\n|----------|-------|------|\n| Active Record | 7 | Use decimal for money, never float; Use parameterized queries, never SQL interpolation; Use includes/preload to prevent N+1 queries; In Active Record code, use after_commit when enqueueing jobs; Wrap multi-step operations in transactions; Never bypass validations in normal code; Never use default_scope |\n| Sidekiq | 4 | Jobs must be idempotent (safe to retry); Job args must be JSON-safe only; Never pass ORM objects to jobs — pass IDs; Always enqueue jobs after commit using the active ORM |\n| Security | 4 | Never use Ruby eval with user input; Authorize explicitly in every action; Never use html_safe/raw on untrusted content; Never concatenate SQL strings |\n| Ruby | 3 | Always pair method_missing with respond_to_missing?; Always supervise background processes; Only rescue StandardError, never Exception |\n| Hotwire/Turbo | 2 | Pre-compute all data before Turbo Stream broadcast; Use turbo_frame_tag for partial page updates |\n| Verification \u0026 Discipline | 2 | Always run tests and show results before claiming done; Only change what the user asked for — no drive-by improvements |\n\n### Enforcement\n\n- **Programmatic**: 6 programmatic detectors checked automatically on targeted Ruby-ish edits\n- **Behavioral**: All 22 Iron Laws + 6 Advisory Preferences injected on `SessionStart` (main session) and `SubagentStart` (every spawned subagent)\n- **Review-time**: Full audit during `/rb:review`\n\nSee [full registry](plugins/ruby-grape-rails/skills/iron-laws/references/canonical-registry.md) for details.\n\n\u003c!-- IRON_LAWS_END --\u003e\n\n## Commands Reference\n\n### Workflow\n\n| Command                  | Description                                                  |\n| -----------------------  | ------------------------------------------------------------ |\n| `/rb:full \u003cfeature\u003e`     | Full autonomous cycle (plan, work, verify, review, compound) |\n| `/rb:brainstorm \u003ctopic\u003e` | Adaptive requirements gathering before planning              |\n| `/rb:plan \u003cinput\u003e`       | Create implementation plan with specialist agents            |\n| `/rb:plan --existing`    | Enhance existing plan with deeper research                   |\n| `/rb:work \u003cplan-file\u003e`   | Execute plan tasks with verification                         |\n| `/rb:review [focus]`     | Multi-agent code review (4 parallel agents)                  |\n| `/rb:compound`           | Capture solved problem as reusable knowledge                 |\n| `/rb:triage`             | Interactive triage of review findings                        |\n| `/rb:document`           | Generate YARD/RDoc, README, ADRs                             |\n| `/rb:learn \u003clesson\u003e`     | Capture lessons learned                                      |\n| `/rb:brief \u003cplan\u003e`       | Interactive plan walkthrough                                 |\n| `/rb:perf`               | Performance analysis with specialist agents                  |\n| `/rb:pr-review`          | Address PR review comments                                   |\n| `/rb:permissions`        | Analyze permission prompts and suggest safe settings entries |\n\n### Utility\n\n| Command                  | Description                                                |\n| ------------------------ | ---------------------------------------------------------- |\n| `/rb:intro`              | Interactive plugin tutorial (8 sections, ~5 min)           |\n| `/rb:init`               | Write project stack notes to CLAUDE.md (rules runtime-injected) |\n| `/rb:quick \u003ctask\u003e`       | Fast implementation, skip ceremony                         |\n| `/rb:investigate \u003cbug\u003e`  | Systematic bug debugging (4 parallel investigation tracks) |\n| `/rb:research \u003ctopic\u003e`   | Research Ruby topics on the web                            |\n| `/rb:verify`             | Prefer project-native verify wrapper, else run full direct verification |\n| `/rb:trace \u003cmethod\u003e`     | Build call trees to trace method flow                      |\n| `/rb:boundaries`         | Analyze Rails service boundaries                           |\n| `/rb:examples`           | Practical examples and pattern walkthroughs                |\n| `/rb:constraint-debug`   | Debug ActiveRecord constraint violations                   |\n| `/rb:compression-report` | Anonymized verify-output compression telemetry report (opt-in via `RUBY_PLUGIN_COMPRESSION_TELEMETRY=1`) |\n| `/rb:provenance-scan`    | Audit `.claude/` provenance sidecars; classifies each via the 4-state trust algorithm and writes a dated Markdown report |\n\n### Analysis\n\n| Command              | Description                                       |\n| -------------------- | ------------------------------------------------- |\n| `/rb:n1-check`       | Detect N+1 query patterns                         |\n| `/rb:state-audit`    | Audit request state, CurrentAttributes, caching   |\n| `/rb:runtime`        | Runtime tooling integration (Tidewave, etc.)      |\n| `/rb:secrets`        | Scan for leaked secrets and API keys              |\n| `/rb:techdebt`       | Find technical debt and refactoring opportunities |\n| `/rb:audit`          | Full project health audit with 5 parallel agents  |\n| `/rb:challenge`      | Rigorous review mode (\"grill me\")                 |\n\n## Agents (19)\n\n| Agent                             | Model  | Memory  | Role                                         |\n| --------------------------------- | ------ | ------- | -------------------------------------------- |\n| **deep-bug-investigator**         | sonnet | --      | 4-track structured bug investigation         |\n| **call-tracer**                   | sonnet | --      | Parallel call tree tracing                   |\n| **security-analyzer**             | opus   | --      | OWASP vulnerability scanning                 |\n| **verification-runner**           | haiku  | --      | zeitwerk:check, format, test                 |\n| **output-verifier**               | sonnet | --      | Provenance checks for research/review claims |\n| **iron-law-judge**                | sonnet | --      | Pattern-based Iron Law detection             |\n| **dependency-analyzer**           | sonnet | --      | Module dependency \u0026 dead code analysis       |\n| **ruby-gem-researcher**           | sonnet | --      | RubyGems library evaluation                  |\n| **rails-architect**               | sonnet | --      | Service structure, Hotwire/Turbo patterns    |\n| **active-record-schema-designer** | sonnet | --      | Migrations, data models, query patterns      |\n| **rails-patterns-analyst**        | sonnet | --      | Codebase pattern discovery                   |\n| **ruby-reviewer**                 | sonnet | --      | Code idioms, patterns, conventions           |\n| **testing-reviewer**              | sonnet | --      | RSpec, Minitest, factory patterns            |\n| **sidekiq-specialist**            | sonnet | --      | Job idempotency, error handling              |\n| **ruby-runtime-advisor**          | sonnet | --      | Performance, memory, concurrency             |\n| **deployment-validator**          | sonnet | --      | Docker, Kubernetes, Fly.io config            |\n| **web-researcher**                | haiku  | --      | Tiered-source docs and GitHub research       |\n| **data-integrity-reviewer**       | sonnet | --      | Data consistency and constraint validation   |\n| **migration-safety-reviewer**     | sonnet | --      | Migration safety and rollback review         |\n\nAfter the orchestrator cleanup, no shipped agent uses `memory: project`.\nThe field remains supported as a future extension for pattern-analyst\nagents that need cross-session continuity.\n\n## Reference Skills (Auto-Loaded)\n\nThese load automatically based on file context -- no commands needed:\n\n| Skill                     | Triggers On                                      |\n| ------------------------- | ------------------------------------------------ |\n| `ruby-idioms`             | Any `.rb` file                                   |\n| `rails-contexts`          | Context modules, router, controllers, services   |\n| `hotwire-patterns`        | Views, Turbo frames, Stimulus controllers        |\n| `active-record-patterns`  | Models, migrations, queries, associations        |\n| `testing`                 | `*_spec.rb`, `*_test.rb`, factories              |\n| `sidekiq`                 | Sidekiq jobs, workers, queue config              |\n| `security`                | Auth, sessions, CSRF/CSP, input validation       |\n| `deploy`                  | Dockerfile, fly.toml, production config          |\n| `runtime-integration`     | Runtime debugging, live process inspection       |\n| `intent-detection`        | First message routing to /rb: commands           |\n| `compound-docs`           | Solution documentation lookups                   |\n\n## Runtime Tooling Integration\n\nThe plugin integrates with [Tidewave Rails](https://github.com/tidewave-ai/tidewave_rails) for runtime debugging and introspection:\n\n```bash\n# Install Tidewave in your Rails app\nbundle add tidewave --group development\n\n# Runtime commands use Tidewave MCP tools\n/rb:runtime execute \"User.count\"           # Execute Ruby in Rails context\n/rb:runtime query \"SELECT * FROM users\"    # Execute SQL\n/rb:runtime docs \"ActiveRecord::QueryMethods\"  # Fetch version-specific docs\n/rb:runtime logs                           # Read application logs\n```\n\n**Note:** Runtime features require Tidewave Rails gem and Tidewave MCP tool access.\n\n## Requirements\n\n- Claude Code CLI\n- Ruby/Rails/Grape project\n- Ruby \u003e= 3.4 — required by plugin runtime hooks and the\n  `compression-stats` end-user CLI under\n  `plugins/ruby-grape-rails/bin/`. Stdlib only; no Bundler gems\n  required at runtime.\n\n### Optional\n\n- **Runtime tooling** (Tidewave) for runtime debugging\n- **ccrider** for contributor-only session analysis (see Contributing)\n\n## Inspired By\n\nThis plugin draws inspiration from two excellent Claude Code plugin ecosystems:\n\n- **[Elixir/Phoenix Plugin](https://github.com/oliver-kriska/claude-elixir-phoenix)** by Oliver Kriska —\n  The primary architectural inspiration. Adopted the agentic workflow philosophy, filesystem-as-state-machine pattern,\n  and the \"Iron Laws\" concept for non-negotiable rules.\n\n- **[Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin)** by Every Inc —\n  Contributed ideas around parallel specialist review orchestration, structured investigation tracks, and solution compounding.\n\nThe goal is to bring the same rigorous, automated quality enforcement to Ruby/Rails/Grape development that these plugins provide for their respective stacks.\n\n## Contributing\n\nPRs welcome! See [CLAUDE.md](CLAUDE.md) for development conventions.\n\n### Development rules\n\n- Skills: keep `SKILL.md` concise and push most detail into `references/`;\n  prefer roughly `100-200` lines for new skills, but allow larger framework or\n  workflow skills when splitting further would make routing or navigation worse\n- Agents: under 300 lines; prefer denylist-only `disallowedTools` for\n  specialists, `tools:` allowlists only for intentionally narrow tool sets\n- Markdown-only edits should pass `npm run lint:markdown`; `npm run lint`\n  runs the full local lint/validation bundle\n\n### Contributor prerequisites\n\nLocal contributor workflows require more than `npm ci` alone:\n\n- `python3` `3.14+` for eval tooling and release checks\n- `ruby` for YAML validation and Ruby maintenance scripts\n- `shellcheck` for `npm run lint`, `make ci`, and local shell pre-commit checks\n- Claude Code CLI for `npm run validate` / `make validate`\n- `jq` for local hook/runtime script validation\n\nPractical bootstrap:\n\n- `npm ci`\n- `npm run doctor`\n\nIf `npm run validate` reports `claude` missing, install it with:\n\n```bash\nnpm install -g @anthropic-ai/claude-code\n```\n\n### Eval workflow\n\nThe canonical contributor eval workflow now lives in\n[`.claude/rules/eval-workflow.md`](.claude/rules/eval-workflow.md)\n(auto-loaded for contributors). Use that file for the full command matrix\nand caveats.\n\nCommon entrypoints:\n\n- `make eval` or `npm run eval` for lint + injection check + changed surfaces\n- `make eval-ci-deterministic` or `npm run eval:ci:deterministic` for the\n  contributor CI gate (deterministic; used by GitHub CI)\n- `make eval-tests` or `npm run eval:test` for the default contributor test\n  path (`unittest` by default for deterministic cross-environment runs)\n- `make eval-behavioral` or `npm run eval:behavioral` for LLM-based trigger\n  routing tests (cache-only, runs offline if cache exists)\n- `make eval-behavioral-verbose` / `npm run eval:behavioral:verbose` — same with\n  verbose cache/score output\n- `make eval-behavioral-fresh` / `npm run eval:behavioral:fresh` — ignore\n  cache, re-run via the default provider (local Ollama `gemma4:26b-a4b-it-q8_0`).\n  The npm script is a composite (`cmd1 \u0026\u0026 cmd2`), so\n  `npm run ... -- --provider haiku`\n  would append to the wrong target; `make` doesn't forward args either.\n  To switch provider prefix with `RUBY_PLUGIN_EVAL_PROVIDER=haiku` or\n  `RUBY_PLUGIN_EVAL_PROVIDER=apfel`; change the default Ollama model with\n  `RUBY_PLUGIN_EVAL_OLLAMA_MODEL=gemma4:latest` (low-RAM fallback,\n  10GB instead of 28GB) or any other Ollama tag; or\n  call the module directly with\n  `python3 -m lab.eval.behavioral_scorer --all --summary --provider haiku`\n- `make eval-behavioral-fresh-verbose` / `npm run eval:behavioral:fresh:verbose`\n  — fresh run with full prompt/response debug output\n- `make eval-ablation` or `npm run eval:ablation` for matcher signal/noise\n  classification (deterministic, no API calls)\n- `make eval-neighbor` or `npm run eval:neighbor` for confusable-pair\n  regression detection on changed skills (requires the active provider —\n  local Ollama `gemma4:26b-a4b-it-q8_0` by default). `make` doesn't forward args;\n  `npm run eval:neighbor -- --provider haiku` does (single-command script).\n  For a cross-wrapper option prefix with `RUBY_PLUGIN_EVAL_PROVIDER=haiku`\n  or `RUBY_PLUGIN_EVAL_PROVIDER=apfel`,\n  or call the module directly with\n  `python3 -m lab.eval.neighbor_regression --changed --provider haiku`\n- `make eval-hygiene` or `npm run eval:hygiene` for trigger corpus\n  contamination scanning\n- contributor eval tooling requires `python3` 3.14+\n\nNotes:\n\n- `--include-untracked` is local-only for changed-mode exploration and is not\n  part of `eval-ci-deterministic`\n- `scripts/check-dynamic-injection.sh` expects git metadata for comparable\n  tracked-file scans and now refuses broad non-git fallback scans\n- local pre-commit checks staged Markdown (markdownlint), JSON validation,\n  and shell syntax + shellcheck lint; CI is broader\n\n### Docs-check and session analytics\n\nContributor-only maintenance tooling under `.claude/` now has two distinct\nroles:\n\n- `/docs-check` validates the plugin against the current cached Claude Code\n  docs and should be treated as a docs-compatibility workflow, not a generic\n  style lint\n- `/cc-changelog` tracks Claude Code releases against plugin surfaces (hooks,\n  agents, skills, config), classifying entries as BREAKING/OPPORTUNITY/RELEVANT\n  FIX/DEPRECATION/INFO with cross-referenced impact; requires `jq` and `curl`\n- `/session-scan`, `/session-deep-dive`, `/session-trends`, and\n  `/skill-monitor` are exploratory analytics workflows for contributors using\n  `ccrider`\n\nPractical guidance:\n\n- prefer `claude plugin validate`, `make eval`, and `/docs-check` before\n  trusting session-derived conclusions\n- when using session analytics, prefer provider-scoped runs such as\n  `--provider claude-code`\n- treat transcript-derived metrics as heuristic triage signals, not release\n  proof\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslbug%2Fclaude-ruby-grape-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslbug%2Fclaude-ruby-grape-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslbug%2Fclaude-ruby-grape-rails/lists"}