useful-loops

useful-loops

A Claude Code plugin for autonomous, iterative codebase improvement. Runs gap analysis, test coverage, security audits, beta-readiness audits, service health audits, funnel audits, plan refinement, document refinement, plan-to-plan alignment, mockup generation, and prototype building in loops that find issues, fix them, PR, pass CI, merge, and repeat.

Designed to work with the Ralph Loop plugin for automated iteration.

Install

claude plugin marketplace add neonwatty/useful-loops
claude plugin install useful-loops@useful-loops

Also install the Ralph Loop plugin if you want looping:

claude plugin install ralph-loop

Commands

Single Iteration (run once)

Command	Description
/useful-loops:gap-analysis <repo-url>	Compare this app against a reference app, fix gaps
/useful-loops:test-coverage [threshold]	Find untested files, write tests (default: 80%)
/useful-loops:security-audit	Audit 1-2 OWASP categories, fix findings
/useful-loops:beta-audit	Holistic beta-readiness review across 5 dimensions
/useful-loops:service-audit	Audit Vercel, Supabase, PostHog, Sentry, GitHub for issues
/useful-loops:funnel-audit	Audit one top-of-funnel marketing category, fix issues
/useful-loops:plan-to-plan <source> <target>	Align a derived plan against its source plan
/useful-loops:mockup-from-plan <plan> <mockup-dir>	Build/refine an HTML mockup from a plan document
/useful-loops:prototype-from-mockup <mockup-dir> <app-dir>	Build/refine an app prototype from an HTML mockup

Looped (requires ralph-loop plugin)

Command	Description
/useful-loops:gap-loop <repo-url> [--max N]	Loop gap analysis until no gaps remain
/useful-loops:test-loop [threshold] [--max N]	Loop test coverage until threshold met
/useful-loops:security-loop [--max N]	Loop security audit until all categories clean
/useful-loops:beta-audit-loop [--max N]	Loop beta audit until no HIGH/MEDIUM code findings
/useful-loops:service-audit-loop [--max N]	Loop service audit until no CRITICAL/HIGH findings
/useful-loops:funnel-loop	Guide for running funnel audit iterations (interactive, not automated)
/useful-loops:plan-to-plan-loop <source> <target> [--max N]	Loop plan-to-plan until target fully covers source
/useful-loops:mockup-from-plan-loop <plan> <mockup-dir> [--max N]	Loop mockup-from-plan until mockup matches plan
/useful-loops:prototype-from-mockup-loop <mockup-dir> <app-dir> [--max N]	Loop prototype-from-mockup until prototype matches mockup

Default max iterations: 10.

Self-Contained (single iteration, no Ralph Loop dependency)

Command	Description
/useful-loops:plan-refine "<PROMPT>" <PLAN>	Refine a plan document or directory using a prompt-driven analysis
/useful-loops:doc-refine "<PROMPT>" <DOC_FILE>	Refine a document using a prompt-driven analysis
/useful-loops:plan-refine-loop "<PROMPT>" <PLAN> [--max N]	Loop plan-refine until no improvements found (requires ralph-loop)
/useful-loops:doc-refine-loop "<PROMPT>" <DOC_FILE> [--max N]	Loop doc-refine until no improvements found (requires ralph-loop)

How It Works

Each skill follows an 8-phase lifecycle per iteration:

1. Setup — checkout main, create iteration branch, read tracking file
2. Analyze — domain-specific analysis (compare repos, find untested files, audit security)
3. Fix — prioritize and fix HIGH/MEDIUM issues (cap ~12 files per iteration)
4. Validate — run lint, typecheck, tests
5. Track — append results to tracking file in docs/plans/
6. Ship — commit, push, create PR
7. CI & Merge — poll CI, fix failures, squash-merge when green
8. Signal — exit normally (more work to do) or emit completion promise (done)

When run in a Ralph Loop, the same prompt is fed back after each iteration. Claude sees its previous work via the tracking files and git history, focusing on uncovered ground each time.

Tracking Files

Each skill maintains a tracking file in docs/plans/: