mudguard

mudguard

Autonomous, independently-verified architecture deepening — the headless counterpart of the now-interactive architecture skills.

mudguard is a Claude Code skill: an orchestration + verification layer that runs the deep-module / deletion-test methodology over your codebase — the whole thing or a chosen part — headlessly, delta-aware (skips already-filed/shipped seams), with an independent propose/verify pass on every candidate, and files the survivors as ready-to-grab vertical-slice issues under .scratch/. It keeps your architecture from silting up with shallow, duplicated seams.

The engine is interchangeable; the layer is the value. The durable part is mudguard's layer — inlined methodology + propose/verify + delta-awareness + ADR closure. How the loop runs is a swappable driver: by default mudguard drives the sweep itself via short sub-agents (no external engine); for a hands-off loop, plug in ralph, Claude Code's native /loop, or Codex — see DRIVERS.md.

Requires

• Claude Code.
• A loop driver is optional — the default drives via sub-agents and needs none. For a hands-off loop: ralph (the reference driver), the native /loop, or Codex. See DRIVERS.md.

Install

With the skills CLI (recommended) — run from your project root:

npx skills add Aijo24/mudguard

Installs to .claude/skills/mudguard/, so you invoke it as /mudguard. This is the install path tracked by skills.sh.

As a Claude Code plugin — if you want /plugin version tracking + updates:

/plugin marketplace add Aijo24/mudguard
/plugin install mudguard@aijo24

Plugin-installed skills are namespaced by the plugin, so you invoke this one as /mudguard:mudguard (vs the plain /mudguard from every other path). The trade-off buys you /plugin update and marketplace discoverability.

Fallback: npx installer — for setups without the skills CLI or plugin support:

npx mudguard            # → ./.claude/skills/mudguard
npx mudguard --global   # → ~/.claude/skills/ (all projects)
npx github:Aijo24/mudguard   # straight from GitHub, no npm account needed

Manual — copy the skill folder yourself:

cp -R skills/mudguard <your-repo>/.claude/skills/

Reload the session so the skill is picked up, then invoke /mudguard (or /mudguard:mudguard if you went the plugin route).

Use

/mudguard (or /mudguard <path-or-subsystem> to skip the scope question) — it:

1. resolves the scope — the whole codebase or a chosen part (a subsystem / package / directory); asks only if ambiguous, defaults to the whole codebase unattended,
2. forks a mudguard/* worktree off your remote default branch (so it sees shipped refactors and won't re-find them) — or resumes an interrupted sweep from its per-area checkpoints,
3. sweeps for deepening candidates (analysis-only, delta-aware) — robustly, via one sub-agent per area with a one-retry policy,
4. verifies every candidate independently — replays the evidence, re-argues the deletion test, dedupes seams across areas; unverifiable candidates are dropped, not filed,
5. writes vertical-slice issues + a per-area PRD under .scratch/, lint-checked against the issue template, committing per area.

Nothing is pushed — you review the issues before merging or implementing.

See SKILL.md for the full pipeline + guardrails, DRIVERS.md for running it on ralph / native /loop / Codex, and EXTENDING.md for the optional, project-specific implement & deploy phases.

Configure for your project

The skill uses generic placeholders — adapt:

• your remote default branch (e.g. main),
• your area split (subsystems / packages / directories — one loop iteration each),
• your driver (sub-agents by default; ralph / /loop / Codex for a hands-off loop — see DRIVERS.md),
• your gates (typecheck / test / lint) for the optional implement phase,
• your decision record — a CONTEXT.md and/or ADR log of decisions the sweep must not re-propose (no record yet? Matt Pocock's domain-modeling skill writes one inline; until you have one the guardrail is a no-op).

Keep infrastructure (servers, SSH, secrets, domains, deploy commands) out of the skill — those live in your own project.

How it works