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.