Bug Hunter

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.