- Run the installer:
npx @loopskills/claude-skills-
Pick which skills and supporting agents to install. Everything goes into
~/.claude/— nothing else is touched. -
Open Claude Code and type
/loop-planor/loop-debug.
That's it. You're ready to go.
This package is also a native Pi package. From this repository (or after publishing), install it with:
pi install /Users/you/path/to/claude-loop-plan
# or: pi install npm:@loopskills/claude-skillsPi loads the platform-safe skills loop-plan, loop-debug, and loop-audit from skills/pi/. They use Pi's subagent orchestration, work with OpenAI models selected by Pi, store plans under .pi/plans/, and gate all writes on explicit approval. The original Claude Code installer remains available via npx @loopskills/claude-skills.
I built these skills to fix the most common failure modes I see when using Claude Code for real engineering work.
"Give me six hours to chop down a tree and I will spend the first four sharpening the axe."
Abraham Lincoln
The Problem. You describe a feature. Claude Code starts writing immediately. Three hundred lines in — sometimes five hundred — you realize the architecture is wrong. The wrong abstraction was chosen. An existing pattern wasn't followed. A critical edge case was missed. Reversing course now is expensive.
This isn't Claude's fault. It's doing what you asked. The problem is the workflow: describe → code. There's no research phase. No verification that Claude actually understood the codebase before touching it.
The Fix is to use /loop-plan. Before writing a single line, it:
- Explores your codebase with parallel read-only agents — finding similar features, mapping upstream consumers, discovering existing tests
- Asks only the questions that can't be answered by reading the code
- Searches the web with today's date — not training-data assumptions from eighteen months ago
- Writes a plan with test specs per task, ADRs for architecture decisions, and an orchestration design
Then it loops. You review the plan, ask for more research, add questions, or say "ship it." Only then does Claude start coding.
"No-one knows exactly what they want."
David Thomas & Andrew Hunt, The Pragmatic Programmer
The Problem. When something is unclear, Claude fills in the gap. Sometimes it guesses right. Often it doesn't — and the guess is buried 200 lines deep in an implementation before you see it. By then, reversing the assumption is a real cost.
The instinct is to ask the user for everything upfront. But that's the other failure mode: twenty clarifying questions before any work begins, most of which Claude could have answered by just reading the codebase.
The Fix is Phase 2 of /loop-plan. After exploring the codebase, Claude asks only the decisions that genuinely can't be inferred — longevity of the feature, consistency model, persistence strategy. Everything else it figures out from the code. The result is 2–3 targeted questions instead of twenty generic ones.
"It's not a bug — it's an undocumented feature."
Unknown, but lived by everyone who's shipped a fix that came back
The Problem. You describe a bug. Claude patches the symptom. Tests pass. You ship it. Three months later the same root cause manifests differently — a slightly different code path, a new caller, a different input shape. The fix never addressed why it broke, only that it broke.
Or worse: the "fix" didn't actually fix the bug at all. It just moved the failure somewhere less visible.
The Fix is to use /loop-debug. The first thing it does — before any investigation — is write a regression test that reproduces the failure. This test must fail (RED) before the fix, and pass (GREEN) after. No exceptions.
Only then does Claude investigate root cause. It plans a minimal fix (T-fix) and a prevention design (T0b) — tests and structural changes that make the bug class harder to reintroduce. At Standard intensity, it also runs mutation testing to verify the test suite actually got stronger after the fix, not weaker.
"Measurement is the first step that leads to control and eventually to improvement."
H. James Harrington
The Problem. Tasks complete. The summary says "done." But did the goal actually get achieved? Task-completion and goal-achievement are not the same thing. A plan can have all tasks marked green while the user's original outcome remains unmet — a missing integration, a wired-but-never-called feature, an acceptance criterion answered correctly on paper but never tested in the real codebase.
The failure is subtle: Claude is genuinely trying to help. The summary is honest about what tasks were done. The gap is that no one verified the outcome independently, adversarially, starting from "not achieved" as the default hypothesis.
The Fix is the loop-verifier agent. It is read-only, adversarial, and intentionally distrustful of narration. At each stage gate, it:
- Reads the
must_havescontract — observable truths, required artifacts, key wiring links — derived from your original goal - Runs a 4-level check on every artifact: exists → substantive (not a stub) → wired → real data flows through it
- Runs behavioral probes that execute the actual code against the acceptance criteria
- Returns
passed,gaps_found, orhuman_needed— never "probably fine"
The execution probes are the hard gate. A file can exist. A function can be imported. A test can pass. None of that is sufficient — the agent must observe the behavior you originally asked for. completion_state = "shipped" is blocked until the verifier says passed.
"A test that always passes is worse than no test — it creates false confidence."
Common wisdom in the mutation testing community
The Problem. Claude Code writes tests as part of the implementation. Those tests pass. But were they written to prove the behavior, or to fit the implementation? If the same agent writes both the code and the tests, the tests inherit the implementation's assumptions. They validate the code that was written, not the behavior that was required. A tautological test (expected = sut(input); assert result == expected) is green by construction — it can never fail, and it proves nothing.
This isn't unique to AI. It's a well-known failure mode in human-written TDD when the "test first" contract isn't enforced. With AI, the failure mode is faster and more consistent: the tests are always structurally sound and always passing, which makes them harder to identify as hollow.
The Fix is the test-writer agent — a separate agent whose only job is to write failing tests before any implementation exists. It:
- Reads the
Test behaviors:spec, not the implementation - Computes expected values independently (by hand, not by calling the SUT)
- Proves each test RED before returning the file paths
- Refuses to touch any production or source file — if asked, it replies
BLOCKED
The orchestrator hash-locks the test files after test-writer returns. The implementer that runs next cannot modify them. Two static analyzers (detect-test-gaming, detect-tautological-tests) scan the implementation for gaming patterns — hardcoded returns for test inputs, SUT-as-oracle, stack inspection — and HARD-BLOCK on a match. The chain: separate author → locked tests → implementation → gaming scan → mutation proof.
/loop-plan— 7-phase iterative planner: explores codebase → clarifies decisions → researches current patterns → writes plan → loops until you say "ship it" → executes with review gates
/loop-debug— 7-phase debugger: regression test written before investigation → root-cause analysis → fix pattern research → minimal fix + prevention design → intensity-gated execution with mutation testing
The installer optionally adds 42 agents across 8 groups. The skills use these at runtime — you pick which groups to install. Full reference: docs/agents.md.
Universal — used across all stacks:
loop-verifier— goal-backward adversarial verifier (stage gates + terminal acceptance)test-writer— separate TDD test author, separation-of-duties anti-cheating controlspec-reviewer— verifies implementation matches the plan spec (Phase 7 gate)code-quality-reviewer— 11-dimension code quality review (Phase 7 gate)research-agent— 5-step methodology research with date verification (Phase 3)test-runner— test suite execution + mutation testing (Phase 7)second-opinion— cross-model Codex review, requiresOPENAI_API_KEY(Phase 6)security-reviewer— auth/injection/secrets auditsrp-godclass-auditor— God-class + LCOM4 cohesion detectordry-duplication-auditor— Rule-of-Three duplication gatecomplexity-long-method-auditor— cyclomatic + cognitive complexitydip-dependency-direction-auditor— import cycles + layer violationsnaming-conventions-auditor— naming smell detectorcomment-quality-auditor— comment hygiene (WHAT vs WHY)yagni-premature-abstraction-auditor— speculative-generality detectorchar-test-coverage-auditor— pre-refactor characterization test coverage gateadr-completeness-auditor— MADR 4.0.0 schema completeness
Android / KMP:
android-kmp-explorer— Android/KMP/Compose codebase exploration (Phase 1)android-coroutine-scope-leak-auditor— GlobalScope/viewModelScope leak detectorandroid-fgs-compliance-auditor— FGS Android 14/15 complianceandroid-r8-proguard-auditor— R8/ProGuard AGP 9 keep-rule auditandroid-baseline-profile-checklister— Baseline Profile setup completeness
iOS / macOS / KMP interop:
swiftui-explorer— iOS/SwiftUI codebase exploration (Phase 1)ios-appstore-preflight-auditor— PrivacyInfo + Required Reason API preflightios-codable-edge-auditor— Codable semantic edge casesios-coredata-migration-auditor— Core Data migration eligibilitykmp-bridging-topology-auditor— KMP source-set topology auditkmp-swift-interop-readiness-auditor— SKIE / Swift Export readinessmacos-entitlements-distribution-auditor— entitlement/sandbox consistencymacos-notarization-preflight-auditor— notarytool CI pre-flightmacos-appkit-swiftui-interop-auditor— NSViewRepresentable seam audit
Architecture:
compose-architect— Jetpack Compose UI architecture + MVVM designdatalayer-architect— KMP data layer: repos, Ktor, Room, Koin
React / Next.js:
react-nextjs-explorer— React/Next.js/TypeScript codebase exploration (Phase 1)react-hooks-misuse-auditor— stale closures, missing deps, conditional hooksnextjs-rsc-boundary-auditor— RSC vs client boundaries, data-fetch waterfalls
TypeScript / Node.js:
typescript-strict-mode-auditor—anycreep, unsafe casts,@ts-ignoreusagenodejs-async-safety-auditor— unhandled rejections, blocking event loop
Python:
python-async-correctness-auditor— blocking calls in async context, asyncio pitfallsdjango-fastapi-safety-auditor— migration safety, cascade risks, N+1 queries
Vue / Nuxt:
vue-reactivity-pitfalls-auditor— destructured state loss, watch cleanup, computed SEnuxt-ssr-hydration-auditor— SSR/CSR hydration mismatches, server-guard misuse
| 📖 loop-plan guide | Phase-by-phase reference, tips, example sessions |
| 🐛 loop-debug guide | Regression-test contract, intensity levels, workflow |
| 🤖 Agents reference | What each agent does and when it runs |
| ⚙️ CLI reference | All flags, sub-commands, environment variables |
| 🔧 How it works | File layout, update mechanism, architecture |
| 📝 Changelog | Version history |
Every release ships checksums.txt with SHA-256 digests of all installed files:
cd $(npm root -g)/@loopskills/claude-skills
sha256sum -c checksums.txtOr download checksums.txt from the GitHub release and verify the files in ~/.claude/ directly.
The installer has no postinstall hook — nothing runs automatically on npm install. It only writes to ~/.claude/, requires no elevated privileges, and shows every file write before it happens. See SECURITY.md.
git clone https://github.com/tech1ee/claude-loop-plan
cd claude-loop-plan
npm install && npm run build && npm testSee CONTRIBUTING.md for setup, CI gates, and the release process.