ai-dev-rails

ai-dev-rails

Claude Code is powerful, but without structure it tends to lose context between sessions, skip research, produce plans with unresolved questions, and make changes without verification.

ai-dev-rails breaks complex tasks into focused stages — research, planning, implementation, validation — where each stage produces an artifact that feeds the next one. Instead of cramming everything into a single context window, each step starts with exactly the right context already written down. The result is better code, fewer hallucinations, and a knowledge base that compounds across sessions and team members.

/research_codebase  →  Research document
         ↓
/create_plan        →  Implementation plan with phases and success criteria
         ↓
/implement_plan     →  Code changes + checkboxes marked in plan
         ↓
/validate_plan      →  Validation report (pass/fail per phase)
         ↓
/commit             →  Atomic commits with user approval
         ↓
/describe_pr        →  PR description from plan + changes

(optional, at any point)

/create_handoff     →  Saves context, learnings, and next steps
         ↓
/resume_handoff     →  Reads handoff, validates current state, creates task list

Installation

Add the marketplace and install the plugin:

/plugin marketplace add BootNodeDev/ai-dev-rails
/plugin install ai-dev-rails@ai-dev-rails

After installing, you should:

1. Create the thoughts/ directory structure in your project:

mkdir -p thoughts/shared/{research,plans,tickets,prs,handoffs} thoughts/global

2. Add the thoughts/ gitignore rules to your .gitignore:

thoughts/*
!thoughts/shared/
!thoughts/global/

3. Allow Claude Code to read and write in thoughts/ without prompting — add to your .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read(thoughts/**)",
      "Edit(thoughts/**)",
      "Write(thoughts/**)"
    ]
  }
}

4. Optionally, add a reference to the methodology in your CLAUDE.md so Claude Code is aware of the available commands

What You Get

agents/       6 specialized sub-agents
commands/     17 workflow commands (slash commands)
hooks/        context-saving hooks

Commands Reference

Research

Each research command produces a document describing the codebase as-is (facts, not opinions). The variants differ in where the output goes:

Command	When to use
/research_codebase	You need a persistent research document that the team can reference later. Output is saved to thoughts/shared/research/. Use this when starting work on a ticket that others might pick up.
/research_codebase_nt	You need quick research for yourself in the current session. Output stays in the conversation only, nothing is written to disk. Use this for small tasks or when thoughts/ is not set up yet.
/research_codebase_generic	Same as /research_codebase but with a less opinionated document structure. Use this when the standard template doesn't fit your research needs.

Planning