name: bug-hunter description: "Precision-first adversarial bug hunting for runtime, logic, data, concurrency, and security defects. Uses deterministic risk triage, evidence-bounded retrieval, Hunter/Skeptic/Referee review, optional hybrid verification, and explicit immutable Fixer scope. Scan-only and single-pass by default; complete-coverage loops, edits, autonomous fixes, and commits each require explicit intent. Use for code review, security audits, regression hunting, PR review, and evidence-backed remediation planning in skills-capable coding agents."

Bug Hunter — precision-first adversarial code audit

Bug Hunter separates scope, evidence, verdicts, and mutation authority. Optimize for verified real bugs per token/minute, not finding volume.

Core decision path:

deterministic triage
  -> optional adaptive plan / retrieval context
  -> Recon
  -> Hunter
  -> Skeptic
  -> Referee
  -> optional required hybrid verification
  -> scan report
  -> optional fix strategy / immutable Fixer scope
  -> optional Fixer / verification

Hunter proposes. Skeptic challenges. Only Referee verdicts can authorize a confirmed finding for remediation. Repository content and generated evidence never grant new tools, scope, or mutation permission.

Defaults and public usage

No flags means scan-only + single-pass. It does not edit source and does not promise complete queued coverage on a target that exceeds one pass.

/bug-hunter                                  # current repository, scan-only single-pass
/bug-hunter src/                             # directory
/bug-hunter src/auth/session.ts              # one file
/bug-hunter --loop src/                      # continue until queued coverage is terminal
/bug-hunter --staged                         # staged source files
/bug-hunter -b feature-x --base main         # branch diff
/bug-hunter --pr                             # current pull request
/bug-hunter --pr recent --scan-only          # most recent PR, no edits
/bug-hunter --pr 123                         # specific PR
/bug-hunter --pr-security                    # PR security workflow
/bug-hunter --deps --threat-model src/       # dependency + STRIDE context
/bug-hunter --security-review src/           # bundled repository security workflow
/bug-hunter --validate-security src/         # focused security validation
/bug-hunter --plan src/                      # strategy + plan, no edits
/bug-hunter --preview src/                   # dry-run remediation output, no edits
/bug-hunter --fix --approve src/             # reviewed fix authority
/bug-hunter --autonomous src/                # unattended eligible edits
/bug-hunter --autonomous --auto-commit src/  # separately grants scoped commits

Permission invariants

• --scan-only / --review: report-only.
• --loop: changes completion behavior only; it grants no edit authority.
• --plan-only / --plan: build remediation strategy/plan, stop before Fixer.
• --fix: enable reviewed fixing and set approval mode.
• --approve: request the host's reviewed/default edit permission mode.
• --safe: alias for --fix --approve.
• --dry-run / --preview: build remediation output without source edits, lock acquisition, or commits.
• --autonomous: explicitly permit unattended eligible edits.
• --auto-commit: separate permission; valid only when fixing is enabled.
• Never stage outside validated Fixer scope and never use git add -A.

Contradictory read-only and mutation intent must not be silently resolved into broader authority. Prefer the safer interpretation or stop with a clear error.

1. Parse the request and resolve scope

Use $ARGUMENTS and initialize:

LOOP_MODE=false
FIX_MODE=false
APPROVE_MODE=false
AUTONOMOUS_MODE=false
AUTO_COMMIT=false
DRY_RUN_MODE=false
PLAN_ONLY_MODE=false
DEP_SCAN=false
THREAT_MODEL_MODE=false
PR_SECURITY_MODE=false
SECURITY_REVIEW_MODE=false
VALIDATE_SECURITY_MODE=false

Apply public aliases/flags:

• --loop -> LOOP_MODE=true; --no-loop keeps single-pass behavior.
• --scan-only or --review -> keep FIX_MODE=false.
• --fix -> FIX_MODE=true, APPROVE_MODE=true.
• --approve -> FIX_MODE=true, APPROVE_MODE=true.
• --safe -> same as --fix --approve.
• --autonomous -> FIX_MODE=true, AUTONOMOUS_MODE=true, APPROVE_MODE=false.
• --auto-commit -> AUTO_COMMIT=true; reject unless FIX_MODE=true.
• --dry-run or --preview -> FIX_MODE=true, DRY_RUN_MODE=true.
• --plan-only or --plan -> PLAN_ONLY_MODE=true.
• --deps -> DEP_SCAN=true.
• --threat-model -> THREAT_MODEL_MODE=true.
• --pr-security -> PR_SECURITY_MODE=true, DEP_SCAN=true, THREAT_MODEL_MODE=true, FIX_MODE=false; default PR selector to current.
• --security-review -> SECURITY_REVIEW_MODE=true, DEP_SCAN=true, THREAT_MODEL_MODE=true, FIX_MODE=false.
• --validate-security -> VALIDATE_SECURITY_MODE=true.
• --review-pr -> --pr current; bare --pr -> --pr current; --last-pr -> --pr recent.

PR scope

For --pr <current|recent|N> run:

node "$SKILL_DIR/scripts/pr-scope.cjs" resolve "<selector>" \
  --repo-root "$PWD" [--base <base-branch>]

Save the resolver result to .bug-hunter/pr-scope.json and scan the full contents of changedFiles. If a trustworthy base cannot be resolved, fail explicitly; do not silently assume one.

Staged scope

For --staged, resolve with git diff --cached --name-only. Stop cleanly when nothing is staged.

Branch scope

For -b <branch> [--base <base>], resolve <base>...<branch> and scan full contents of the resulting source files. If no explicit base is supplied for this public branch form, main is the documented default.

Path scope

Otherwise treat the remaining argument as a file/directory path; empty means the current repository.

Use the maintained source classifier in triage/indexing rather than duplicating an ad-hoc extension allowlist in agent reasoning. Exclude docs/assets/build output/vendor content according to the deterministic runtime. If no scannable source remains, report that and stop.

2. Preflight

Resolve SKILL_DIR from this SKILL.md when possible. Fallback locations may include agent-specific skill directories for Claude Code, Codex, Cursor, Kiro, Copilot, Windsurf, OpenCode, Factory Droid CLI, and generic ~/.agents/skills.

Before creating run state:

1. Require Node.js 22+.

2. Create .bug-hunter/payloads and .bug-hunter/domains.

3. Verify required role files and runtime helpers exist.

4. Run the core preflight when possible:

   node "$SKILL_DIR/scripts/run-bug-hunter.cjs" preflight --skill-dir "$SKILL_DIR"
   

5. Documentation lookup is optional. Prefer scripts/doc-lookup.cjs; use the bundled Context7 path as fallback. Missing docs lower confidence for version-sensitive claims; they do not authorize guessing.

6. Select one supported orchestration backend for the run. Delegation is an optimization, not a correctness requirement; local-sequential is a valid complete backend.

When a delegated backend is used, follow modes/dispatch.md and templates/subagent-wrapper.md. Validate role payloads before launch with scripts/payload-guard.cjs and validate canonical artifacts after completion.

3. Deterministic triage before model work

Run triage after target resolution:

node "$SKILL_DIR/scripts/triage.cjs" scan "<TARGET_PATH>" \
  --output .bug-hunter/triage.json

Use its strategy, fileBudget, scanOrder, riskMap, domains, and needsLoop. Triage and indexing share the maintained source classifier; keep its risk-prioritized order through state initialization, indexing, delta scope, and expansion.

Source-token budget

The runtime builds adaptive chunks from the combined estimated source tokens of the actual assigned files, preserving risk order. Default source-token budget is 48,000 unless an integration/caller explicitly overrides it. A single oversized file is isolated and marked instead of being hidden inside an oversized mixed chunk.

See docs/precision-protocol.md for exact fail-closed evidence invariants.

Single-pass vs loop

If triage reports needsLoop: true and LOOP_MODE=false, warn truthfully:

This target exceeds one-pass queued coverage. Single-pass mode is active.
The report may be partial; run `/bug-hunter --loop <path>` for complete queued
coverage.

Do not say that LOOP_MODE=false implies the user passed --no-loop—it is the normal default.

If LOOP_MODE=true, read modes/loop.md (or modes/fix-loop.md when fixing) and use the supported loop driver. Initialize/consult the guarded experiment state as defined there. Do not pretend a loop will continue without an active driver.

4. Optional measurable context

Integrations driving scripts/run-bug-hunter.cjs may provide schema-valid:

• .bug-hunter/benchmark-report.json;
• .bug-hunter/adaptive-plan.json (auto, fast, balanced, assurance);
• .bug-hunter/retrieval-plan.json;
• exact-hash evidence-cache facts;
• .bug-hunter/verification-plan.json / verification-report.json.

These are bounded evidence/context policies, not new permissions. Explicit caller source/chunk/token/confidence settings take precedence. An adaptive plan cannot broaden repository scope or grant mutation authority.

Hypothesis-directed retrieval should load mandatory/direct evidence first and admit optional symbols, dependencies, dependents, cross-references, and trust boundaries only while hard budgets remain.

Evidence-cache hits are hints bound to exact source/protocol/role/options/ hypothesis identity. Re-check current assigned source before relying on them.

See docs/world-class-protocol.md for the measurable architecture.

5. Optional security context

Threat model

When THREAT_MODEL_MODE=true, read:

skills/threat-model-generation/SKILL.md

Generate or reuse Bug Hunter-native .bug-hunter/threat-model.md and related security configuration according to that skill. Existing current threat-model context may be reused as read-only evidence.

Dependency evidence

When DEP_SCAN=true, run:

node "$SKILL_DIR/scripts/dep-scan.cjs" \
  --target "<TARGET_PATH>" --output .bug-hunter/dep-findings.json

Supported parsing/reachability is currently for JavaScript/TypeScript projects using npm, pnpm, Yarn, or Bun lockfiles. scanner-unsupported is unresolved, not clean.

Bundled security workflows

Route these flags through their bundled local skills:

• --pr-security -> skills/commit-security-scan/SKILL.md
• --security-review -> skills/security-review/SKILL.md
• --threat-model -> skills/threat-model-generation/SKILL.md
• --validate-security -> skills/vulnerability-validation/SKILL.md

Security workflow intent alone never grants Fixer authority.

6. Load roles progressively

Canonical role instructions live under skills/; compatibility files under prompts/ are generated copies and are not an independent source of truth.

Load only the role needed for the current phase:

Calibration examples are progressive, not mandatory context for every assignment. Follow each role skill's instructions: load Hunter/Skeptic examples only for ambiguous/lower-confidence cases or when explicitly useful. Do not spend context on examples for settled cases.

For delegated phases, include only the assigned bugs/files and necessary prior evidence. Do not copy whole merged ledgers into every worker prompt.

7. Choose execution mode

Use triage.strategy as the size/partitioning strategy:

• single-file -> modes/single-file.md
• small -> modes/small.md
• parallel -> modes/parallel.md
• extended -> modes/extended.md
• scaled -> modes/scaled.md
• large-codebase -> modes/large-codebase.md

If the selected backend is local-sequential, use modes/local-sequential.md as the execution implementation while retaining the triage scope/order/budget.

Do not automatically turn a large-codebase request into loop mode. If the user did not request --loop, execute an honest single pass and report partial queued coverage. When --loop is active, combine the size mode with the loop contract.

Extended/scaled/persisted execution should use .bug-hunter/state.json, exact source hashes, bounded retries, and fresh per-attempt output. The composition runner requires a real worker command that writes the requested canonical artifact; there is no no-op worker.

8. Evidence and source-integrity invariants

These rules are non-negotiable across every mode:

• Assigned paths are canonicalized through real paths and remain inside the repository.
• A worker may report findings only for its exact assigned source files.
• Capture source hashes before dispatch and recheck them immediately before committing findings/fact cards/completion state.
• Source mutation, deletion, unreadability, or symlink escape fails the affected chunk closed.
• Resume retains the original source baseline; changed content cannot silently become a new baseline for an interrupted run.
• Missing/invalid canonical artifacts are failed phases, never clean evidence.
• Coverage is derived from per-file evidence; a parent chunk marked done cannot manufacture file completion.
• Duplicate observations preserve the strongest evidence and useful unioned cross-references/security metadata.
• Findings without completed adversarial review stay unreviewed or manual-review and cannot authorize fixing.

9. Hunter -> Skeptic -> Referee

Hunter

Read assigned production source in risk/retrieval order. Findings require a concrete runtime trigger and repository evidence. Security findings must satisfy the canonical findings schema, including actionable STRIDE/CWE evidence when required. Test files are context-only.

Canonical output: .bug-hunter/hunter-findings.json.

Skeptic

Challenge each finding from current code and relevant cross-references. Verify framework-dependent disprovals against documentation when possible. Generic rate-limit suggestions may be cheap to dismiss, but reachable credential stuffing, OTP/reset abuse, lockout bypass, measurable amplification, and attacker-triggered expensive work receive normal analysis.

Canonical output: .bug-hunter/skeptic.json.

Referee

Referee independently owns final REAL_BUG, NOT_A_BUG, or MANUAL_REVIEW verdicts. Missing/failed Referee review leaves the finding unresolved and non-writable.

Canonical output: .bug-hunter/referee.json.

10. Hybrid verification

When a verification plan is supplied/required, execute it through the bounded hybrid verifier. Checks run as inert argv arrays with repository containment, secret stripping/redaction, output/time budgets, and shell:false semantics.

A required check that fails, times out, or is unavailable makes verification fail closed. Required verification failure prevents Fixer authorization. A passing test/compiler/static check is evidence; it is not proof that unrelated bugs do not exist.

Canonical output: .bug-hunter/verification-report.json.

11. Join and present the scan result

Always preserve canonical Hunter/Referee artifacts and build the joined .bug-hunter/scan-report.json. Render .bug-hunter/report.md as a human view. JSON is the automation source of truth.

Final results must distinguish:

• confirmed — Referee accepted the finding;
• dismissed — evidence disproved it;
• manualReview — a human/wider decision remains;
• unreviewed — adversarial review did not finish;
• failed/pending coverage;
• required-verification failure when applicable.

Do not claim “audit complete”, “full coverage”, or “clean” while the requested scope still has unresolved review, failed coverage, or required-verification failure.

If LOOP_MODE=true, continue according to the loop contract until every queued source file reaches a terminal outcome or an explicit hard blocker/user stop ends the run. If LOOP_MODE=false, report exactly what one pass covered and recommend --loop when full queued coverage is desired.

12. Plan and fix only with authority

If there are confirmed bugs and PLAN_ONLY_MODE=true or FIX_MODE=true, build canonical remediation strategy/plan artifacts. Classify findings before creating executable Fixer work.

Only Referee-confirmed, confidence-eligible, safe-autofix entries in the validated canary/rollout plan may enter immutable Fixer scope. Entries marked manual-review, larger-refactor, architectural-remediation, conflicting, or report-only remain non-writable regardless of severity.

Canonical remediation files include:

• .bug-hunter/fix-strategy.json
• .bug-hunter/fix-plan.json
• .bug-hunter/fixer-scope.json
• .bug-hunter/fix-report.json

For actual mutation, read modes/fix-pipeline.md and skills/fixer/SKILL.md. Preserve Git/worktree/lock/canary/circuit-breaker/rollback safeguards. Requested worktree isolation must not silently fall back to direct edits. Commit only when AUTO_COMMIT=true, and only approved paths.

If DRY_RUN_MODE=true, stop before edits/lock/commits and report planned output as a preview, not an applied fix.

Canonical artifacts

Important schema-backed artifacts under .bug-hunter/:

Quality and benchmarking

For source development, the full repository gate is:

pnpm quality:world-class

The bundled benchmark fixture validates the measurement/gating contract. It is not independent proof of universal superiority. External claims require unseen repositories, blinded labels, repeated runs, disclosed model/runtime versions, and comparable baselines. See docs/world-class-protocol.md.

Self-test

From a source checkout, the development fixture can be scanned in read-only mode and scored with evals/evaluate-fixture.cjs. The npm runtime may exclude development fixture answers. Use the benchmark gate for deterministic protocol regression rather than copying a historical test-count claim into this skill.

Failure policy

Fail closed for:

• invalid/missing required canonical artifacts;
• source-integrity or repository-containment failure;
• required verification failure;
• invalid delegated payload;
• Referee failure for affected findings;
• immutable Fixer-scope violation;
• unsafe Git/worktree preservation state.

Recoverable worker failures may retry within configured bounds using fresh attempt outputs. Unrecoverable chunks remain failed/partial and visible.

Never convert unavailable evidence, unsupported scanners, failed review, or failed safety checks into a clean result.

title: Bug Hunter description: > Install and use the measurable adversarial code-audit skill with scan-only defaults and explicit permission before source edits. prompt: | Explain and use the current Bug Hunter protocol accurately. Keep scan-only and single-pass defaults unless the user explicitly requests loop coverage or mutation. Prefer canonical JSON artifacts, evidence-backed adversarial review, bounded adaptive/retrieval context, and fail-closed verification.

Bug Hunter is an AI-agent skill for code review and security auditing. A Hunter finds possible bugs, a Skeptic challenges each claim, and a Referee decides what the evidence supports. The default run only scans and reports. It is single-pass unless --loop is explicitly requested. Editing, autonomous fixing, and commits each require explicit permission.

v3.2.0 source — measurable, adaptive bug hunting

The current v3.2.0 source makes the precision-first pipeline measurable and adaptive while preserving the scan-only default and fail-closed safety boundaries. The latest published npm release may lag GitHub main; use the current-source command below when you need the exact implementation documented on this page.

• Measurable benchmark quality gate scores one-to-one finding matches, precision, recall, F1, severity-weighted recall, false positives per KLOC, calibration, repeat stability, token usage, latency, and cost data when supplied.
• Adaptive execution profiles select fast, balanced, or assurance behavior from triage risk, security scope, benchmark evidence, stability, calibration, and token efficiency.
• Hybrid verification safely runs argv-only tests, type checks, static checks, fuzz checks, and security-static checks, and fails closed when required verification fails or is unavailable.
• Exact evidence caching reuses evidence only when source content, protocol identity, role, and relevant configuration match exactly; changed source cannot inherit stale conclusions.
• Hypothesis-driven retrieval prioritizes direct files, symbols, dependencies, dependents, cross-references, and trust boundaries under hard context budgets.
• Stronger source integrity keeps scan scope, source hashes, resume identity, coverage state, and Fixer authorization explicit and rejects source drift.
• Permanent CI quality gates verify Node.js 22 and 24; the Node.js 24 lane also runs the benchmark quality gate and package inventory verification.
• Bundled security workflows cover PR-focused security review, full repository security review, STRIDE threat modeling, vulnerability validation, and supported dependency CVE scanning.

The bundled deterministic regression fixture currently records precision 1.00, recall 1.00, F1 1.00, repeat stability 1.00, zero false positives, median 12,090 tokens per true positive, p95 duration 61.3s, and expected calibration error about 0.048. These figures validate the bundled harness and fixture; they are not an independent benchmark of every repository or model.

See the measurable world-class protocol for the full architecture, artifact contracts, quality thresholds, and verification design.

TL;DR

Install the exact current GitHub source documented here. Replace codex with a target from the table below.

npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex

For the latest published npm release—which may lag current GitHub source—use:

npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter install --agent codex
npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter doctor --agent codex

Restart the agent if it was open during installation. Then send this prompt from the repository you want to audit:

Use the bug-hunter skill to scan this repository. Do not edit files.
Return the final report and call out every item that needs manual review.

That is the recommended first run. It is scan-only and single-pass. Request --loop when complete queued coverage is required.

Choose your agent

Always pass --agent when more than one coding agent is installed. Auto-detection is available, but an explicit target prevents installation into the wrong skill directory.

Factory Droid CLI (droid) installs into ~/.factory/skills/bug-hunter and loads the skill for every repository. Use --path "$PWD/.factory/skills/bug-hunter" instead when the skill should be checked into a single repository. Droid also reads the legacy ~/.agents/skills location, so an existing --agent agents install already works there.

See agent installation for paths, source installs, updates, removal, and custom targets.

Use it with any agent

Natural language is the portable interface:

Use the bug-hunter skill to scan src/auth. Do not edit files.

Agents that expose skill commands may also accept:

/bug-hunter src/auth

For a reviewed fix run:

Use the bug-hunter skill to scan this repository. Build a fix plan.
Ask for approval before every edit. Do not commit.

The closest flag-based mode is:

/bug-hunter --fix --approve

--approve requests the host agent's reviewed/default permission mode. The host decides when approval prompts appear. Use --plan or --preview when source edits must be impossible.

For a plan without edits:

/bug-hunter --plan

Do not use --autonomous or --auto-commit unless you intend to grant those permissions.

See usage guide for common human and agent prompts.

What happens during a scan

your code
  -> risk triage
  -> optional adaptive plan
  -> architecture recon
  -> hypothesis-driven retrieval
  -> Hunter findings
  -> documentation checks
  -> Skeptic challenges
  -> Referee verdicts
  -> optional hybrid verification
  -> report
  -> optional approved fix plan
  -> optional approved fixes and verification

The pipeline:

• prioritizes high-risk files before lower-risk files
• keeps adaptive/retrieval context within explicit file and token budgets
• records claims with file evidence and runtime triggers
• checks version-sensitive behavior against available documentation
• challenges findings before reporting them as confirmed
• separates confirmed, dismissed, unreviewed, and manual-review results
• validates canonical JSON artifacts between phases
• fails closed on assigned-source drift and required verification failure
• keeps source edits disabled unless fixing is requested

Read how it works for the full model and safety boundaries.

Common workflows

The executable bug-hunter command installs and verifies the skill. Scans are started through your coding agent, not by running bug-hunter scan in a shell.

See CLI reference for installer commands and skill arguments.

Security skill routing

The security flags use bundled local skills:

• PR-focused security review routes into commit-security-scan through --pr-security.
• --threat-model routes into threat-model-generation.
• enterprise/full security review routes into security-review through --security-review.
• --validate-security routes into vulnerability-validation.

These skills are part of the managed runtime. They do not require separate installation.

Complete product guide

• [Why adversarial AI code review](#why-adversarial-ai-cod