Buggie — Claude Code Skill

A /buggie slash command for Claude Code that runs a full review engagement on your codebase — with a crew. It staffs a team of specialist subagents (security, backend, data, frontend, UX, accessibility, performance, docs, PM) against the parts of your repo that actually exist, runs them in parallel, then has adversarial skeptics try to refute every finding before you ever see it.

Version 3.0.0. Safe by default (it reports; it never edits unless you pass --fix), evidence-gated, and built around one rule: nobody grades their own work.

---

What it is

Buggie is a skill (a .md slash command plus a small set of scanner scripts) for Claude Code. When you run /buggie, Claude stops acting like a helpful assistant and starts acting like a hired reviewer who has been given a few hours with your codebase before a launch. It finds real problems, proves them, ranks them by evidence and impact, and tells you what to do first.

It does not just find bugs. It:

• Maps risk across the codebase, then reads the risky files first
• Tests routes, buttons, and forms in the live running app (read-only by default; it asks before mutating anything)
• Flags architecture and tech-debt that will cause bugs next month
• Runs performance, mobile, and accessibility audits
• Sweeps for UI/UX inconsistencies, missing/broken animations, navigation defects, and "vibe-coded" AI-slop design tells
• Runs an AI-generated-code security checklist (the classes AI ships insecure by default)
• Ends every run with a prioritized debrief: should I be worried, and what do I do first?

---

What is new in v3 — the crew

v2 was deep but single-threaded: one agent ran eight phases in sequence and then graded its own findings. v3 keeps every checklist and changes who runs them.

• A staffed crew, in parallel. 13 specialist subagents live in agents/. The roster is chosen from what your repo actually contains — no data engineer on a repo with no database — and it is printed with a reason per specialist plus an explicit list of who was not staffed, so you know which lens is missing from the result you're reading.
• Adversarial verification. Every non-trivial finding goes to a skeptic that is given the claim and location but not the reporter's reasoning, and is told to prove it wrong. Verdicts are UPHELD / UNDECIDED / REFUTED; refuted findings are logged with the reason rather than silently vanishing. CONFIRMED now means something survived an attack.
• Green baseline first. Before anyone hunts, baseline-green.mjs runs every package's typecheck and tests and prints the real number — "typecheck clean across 11 projects, 1017 tests passing" — recording pre-existing failures so they can never be reported as new findings, and so --fix is judged against that baseline instead of demanding absolute green.
• Parallel fixing. With --fix, confirmed findings are grouped into units with non-overlapping file sets, fixed concurrently, then verified once, centrally.
• Deterministic identity. findings-merge.mjs owns fingerprinting, cross-agent dedupe (two specialists finding the same defect merge into one record marked ×2 agents), baseline reconciliation, and the cross-run diff — so finding IDs stop drifting between runs.
• Read-only by tool grant. Hunter agents have no Edit/Write tools at all. Safe-by-default is enforced by the harness, not by asking nicely.
• --solo for small scopes, --ultra for the full firm (12+ agents, a 3-lens skeptic panel, and a completeness critic that loops until two rounds find nothing left uncovered).

Carried over from v2, unchanged:

• Safe by default. No --fix means no edits, no commits, and no unrestorable changes to your app's state. Fixes are opt-in and run on a branch, one finding per commit.
• Environment guard. Before clicking anything that mutates state, it confirms the target is a throwaway/dev environment. It will not silently fire real emails, charges, or deletes.
• Persistent, honest state. Findings get stable IDs, an accepted/wontfix baseline ledger (so it stops re-reporting things you already decided), a cross-run diff, and regression detection.
• Calibrated severity and no fabricated numbers. Effort and impact are labeled estimates; unknown is allowed instead of an invented figure.
• Anti-"vibe-coded" system. A design-tell catalog and an AI-code security checklist, both backed by deterministic scanners you can gate CI on (see below).
• Deterministic scanners. Dependency-free Node scripts that turn "don't make it look AI-made / don't ship it insecure" into a grep with an exit code.

Full changelog is at the bottom of buggie.md.

---

How to install it

Buggie is three things: the skill file, the agent roster it staffs, and the scripts it calls. All three are required — v3 without agents/ is a skill with nobody to send.

1. Install Claude Code (desktop or CLI).

2. Copy the skill into your commands folder:

   Mac/Linux

   cp buggie.md ~/.claude/commands/buggie.md

   Windows (PowerShell)

   Copy-Item buggie.md "$env:USERPROFILE\.claude\commands\buggie.md"

3. Copy the agent roster into your agents folder — this is the crew:

   Mac/Linux

   mkdir -p ~/.claude/agents && cp agents/*.md ~/.claude/agents/

   Windows (PowerShell)

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\agents" | Out-Null
   Copy-Item agents\*.md "$env:USERPROFILE\.claude\agents\"

4. Copy the scripts to where the skill expects them (~/.claude/buggie/):

   Mac/Linux

   mkdir -p ~/.claude/buggie/scripts ~/.claude/buggie/workflows
   cp scripts/* ~/.claude/buggie/scripts/
   cp workflows/* ~/.claude/buggie/workflows/

   Windows (PowerShell)

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\buggie\scripts" | Out-Null
   New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\buggie\workflows" | Out-Null
   Copy-Item scripts\*   "$env:USERPROFILE\.claude\buggie\scripts\"
   Copy-Item workflows\* "$env:USERPROFILE\.claude\buggie\workflows\"

5. Open a new Claude Code session. /buggie is now available in any project, and the 13 specialists appear in your agent list — they are useful on their own, not only inside a buggie run.

The scripts need Node 18+ (they use no npm packages). Skipping step 4 leaves you with a working skill whose mechanical checks and baseline gate are gone; skipping step 3 leaves you with a skill that has nothing to staff.

The agent files reference ~/.claude/commands/buggie.md by absolute path for their checklists. If you install the skill somewhere else, update that path in agents/*.md.

---

How to use it

/buggie                     # Full review, report only (no edits)
/buggie src/                # Limit the whole run to a path
/buggie --fix               # Enable the fix workflow (branch + per-finding commits)
/buggie --triage            # 5-minute pulse: top risks + health score
/buggie --scan              # Static code analysis only
/buggie --ui                # Live UI/UX + a11y + PM only
/buggie --ux                # UI/UX quality sweep: consistency, motion, navigation, vibe-coded tells
/buggie --arch              # Architecture & tech-debt only
/buggie --perf              # Performance only
/buggie --a11y              # Accessibility & mobile only
/buggie --pm                # Product-manager UX review only
/buggie --security          # Security focus: live probes + STRIDE-lite + the AI-code checklist
/buggie --house-style       # Also apply the author's opinionated UI standards (as proposals)
/buggie --ci                # Headless: no prompts, no fixes, writes a report + exit code
/buggie --pr [N]            # Scope to a PR's changed files
/buggie --staged            # Scope to staged files
/buggie -b <branch>         # Scope to a branch's diff vs the default branch

Crew size and verification:

/buggie --ultra             # The full firm: 12+ specialists, a 3-lens skeptic panel per
                            #   finding, and a completeness critic that loops until two
                            #   rounds find nothing uncovered. Thorough and expensive.
/buggie --solo              # No crew — one agent, sequentially (v2 behaviour). Right for
                            #   a single file, where staffing eight agents is theatre.
/buggie --crew N            # Force the crew size, overriding adaptive staffing
/buggie --no-verify         # Skip the skeptic panel. Faster, and every finding is then
                            #   capped at PROBABLE — the report says verification was skipped.

Safety modifiers (only apply with --fix): --dry-run, --approve, --fix-wide, --yes-unsafe-env.

---

The anti-"vibe-coded" system

Telling a model "don't make it look AI-generated" does not work. It is not an actionable signal. Buggie converts each tell into a mechanical detection and a concrete, brand-anchored cure.

Appendix A — AI-slop design tells

A ranked catalog (AI-purple gradients, permanent dark theme, gradient hero text, neon glow, emoji-as-icons, untouched shadcn/Inter defaults, the centered-hero + three-card skeleton, colored left rails, all-caps eyebrows, filler blocks, placeholder content, generic copy). Each row has a literal grep/computed-style detection and a fix that points at your project's brand, not another default.

The root-cause step comes first: does the project even have a brand anchor (one non-violet brand color, a deliberate type/radius/shadow/theme)? If not, that is the top finding, because every downstream tell flows from its absence.

Appendix B — AI-generated-code security checklist

The vulnerability classes AI ships insecure by default, treated as vulnerable until proven guarded: exposed/misconfigured database (RLS off), secrets in the client bundle or repo, unauthenticated API/mutation routes, client-side-only auth, IDOR, injection/SSRF, insecure uploads, missing rate limits, weak headers/cookies, over-permissive CORS, XSS, and the AI-specific one others miss — hallucinated/typosquat dependencies. The three that actually breach vibe-coded apps (open database, leaked key, open endpoint) are checked first.

Deterministic scanners (CI-gating)

The mechanical half of both appendices runs the same way every time:

node ~/.claude/buggie/scripts/slop-scan.mjs   . [--json]   # design tells    → exit 1 on HIGH tells
node ~/.claude/buggie/scripts/sec-scan.mjs    . [--json]   # security        → exit 1 on CRITICAL
node ~/.claude/buggie/scripts/buggie-scan.mjs . [--json]   # both, combined exit code

The crew's own two mechanical pieces run the same way — they exist because a model improvising them by hand is exactly where a multi-agent run goes wrong:

# Prove and record what already passes, before anyone hunts
node ~/.claude/buggie/scripts/baseline-green.mjs . [--build|--quick]
#   → "typecheck clean across 11 projects, 1017 tests passing"
#   → writes .buggie/baseline-green.json with every PRE-EXISTING failure

# Merge the crew's findings: stable fingerprints, cross-agent dedupe, cross-run diff
node ~/.claude/buggie/scripts/findings-merge.mjs . --in .buggie/run-<stamp> [--json] [--ci]

Drop buggie-scan.mjs into a CI step to block vibe-coded or insecure code from merging. A project-root .buggierc.json { "allow": ["dark-theme","purple"] } suppresses tells your project owns by decision — a genuinely purple brand is not a finding.

Honesty: the scanners are static heuristics. A green run means "no static hits," not "verified clean." The live buggie phases (measured styles, real auth/IDOR probes) are the other half.

---

What it does, phase by phase

The phases are the checklists. In v3 they are assigned to specialists rather than walked end-to-end by one agent — the security engineer runs 1b/1.5c/2.8, the data engineer runs the silent-cap and migration checks, the UX auditor drives 2.7 in a real browser, and so on, all at the same time.

• Phase 0 — Setup & guards. Detect and boot the app, guard against mutating a non-throwaway environment, provision an authenticated session if the app is gated, set up a fix branch if --fix.
• Phase 0f — Green baseline. Run every package's typecheck and tests, print the count, and record pre-existing failures so nobody can report them as new.
• Phase 1 — Code scan. Risk-map, then hunt: security, correctness, error handling, data integrity, silent caps, concurrency. Runs the AI-code security checklist (Appendix B / sec-scan).
• Phase 1c — Adversarial verification. Every non-LOW finding is attacked by a skeptic that never saw the reasoning behind it.
• Phase 1.5 — Architecture & tech debt. Structure smells, production-readiness gaps, migration reversibility, dependency and secret posture (with baseline-suppressed audit noise).
• Phase 2 — Live UI testing. Route discovery, safe interaction exercise, three-pass form testing, above-cap/volume testing (with an honest UNVERIFIED when it cannot seed the data).
• Phase 2.5 — Performance. N+1s, render hot paths, and live metrics measured against a production build (dev-server sizes are never flagged as critical).
• Phase 2.6 — Mobile & accessibility. Touch targets, keyboard order, ARIA, plus contrast, reduced-motion, 200% zoom, and a dark-mode pass.
• Phase 2.7 — UI/UX quality. The vibe-coded tell sweep (Appendix A / slop-scan), visual/component consistency measured against the app's own baseline, motion/animation (missing, broken, reduced-motion), navigation integrity, and implementation defects.
• Phase 2.8 — Security probes. STRIDE-lite trust-boundary model plus live client-validation bypass, IDOR, headers, cookies, and CSRF checks.
• Phase 3 — PM UX review. Core-journey walks, copy clarity, expected-but-missing features.
• Phase 4–5 — Fix & validate (opt-in). Confirmed findings are grouped into units with non-overlapping file sets and fixed in parallel; then one shared verification against the recorded baseline, a regression test per fix, and one commit per finding.
• Phase 6 — Consultant debrief. Always runs. Executive summary, the baseline, the crew that ran and who was not staffed, how many candidates the skeptics killed, rubric-based health grades (with an "insufficient data" grade for anything nobody examined), top-3 risks, a prioritized action plan, and a "what I did not test" assembled from the crew's coverage reports rather than from memory.

---

Safety model

• Report-only by default. Fixes require --fix, run on a branch, commit one finding at a time, and require confirmation for anything touching auth, payments, security, or destructive paths.
• No mutation without consent. Live testing confirms the environment is safe before it clicks anything that changes state.
• The project's standards win. UI rules come from your project's declared standards and existing components. Buggie's own taste is opt-in (--house-style) and proposal-only. It never rewrites intentional design, and never edits your CLAUDE.md on its own.
• Read-only by tool grant. The hunting specialists are defined with no Edit/Write tools at all — the harness enforces it, so "safe by default" does not depend on an agent choosing to behave.
• Refutations are logged, not hidden. A finding killed by a skeptic is written to .buggie/refuted-<date>.json with the reason, so you can argue with the verdict instead of never seeing the finding.

---

Requirements

• Claude Code (desktop or CLI)
• Browser tools for the live phases (the UX, accessibility, and PM specialists drive a real browser)
• Node 18+ for the scripts
• --ultra needs the Workflow tool; every other mode runs on ordinary subagents

---

Credits

The anti-vibe-coded catalogs synthesize public work (credited in-file in buggie.md): the design-tell ranking from vibecoded-design-tells, the brand-anchor/DESIGN.md approach from awesome-design-md and awesome-ai-tools-for-ui; and the security classes from vibe-security, vibe-check, and vibe-coding-checklist. Buggie maps them onto its own phases, severity model, evidence-gating, and the "owned choice vs unowned default" guardrail.

The skill file (buggie.md) is the complete system prompt Claude Code runs when /buggie is invoked. No API calls, no config required beyond placing the files.