aijo24/ralph-architecture-sweep

This is a plugin (called a "skill") for Claude Code, an AI-powered coding assistant. It adds a command called /ralph-architecture-sweep that scans a codebase and identifies places where the code structure could be improved, then writes those findings as ready-to-use GitHub issues for a developer to review and act on. The skill is built on top of another tool called ralph, which is a loop that drives Claude Code through repeated analysis cycles. Ralph-architecture-sweep directs that loop specifically at architecture quality: it looks for overly shallow modules (code that just passes data along without doing real work), patterns that repeat across many parts of the codebase, and places where related logic is scattered rather than collected into one responsible location. The ideas behind these checks come from John Ousterhout's book on software design, and the skill credits two other open-source projects that first formalized this methodology. When you run the command, it asks you whether to scan the whole codebase or just a specific folder or subsystem. It then creates a separate working copy of your code branched from your main branch, which means it sees the latest shipped changes and will not re-report things you have already fixed. It divides the work into areas and runs one analysis agent per area, with a retry if one fails. After collecting candidates, a separate verification step replays the evidence independently, throwing out anything that does not meet a minimum threshold of supporting evidence. What remains gets written as structured issues under a local .scratch/ folder. Nothing is pushed to GitHub automatically. The developer reviews the generated issues first and decides what to implement. An optional extension phase (documented separately) can chain ralph to start implementing approved issues, but that part requires project-specific configuration and is not included in the base skill. The skill is installed via npx from your project root and picked up automatically by Claude Code. It is MIT-licensed and requires both Claude Code and ralph to already be set up in the target repository.