@codexstar/bug-hunter 3.0.0

package/modes/local-sequential.md

@@ -0,0 +1,143 @@
+# Local-Sequential Mode (no subagents — default fallback)
+
+Run all pipeline phases in the main agent's own context window. This is the **most common execution mode** — most agent runtimes will land here because subagent dispatch requires specific tooling that isn't always available.
+
+This is NOT a degraded mode. The skill is designed to work fully here.
+
+## How It Works
+
+You (the orchestrating agent) play each role yourself, sequentially. Between phases you **write outputs to files** so later phases can reference them without holding everything in working memory.
+
+All state files go in `.bug-hunter/` relative to the working directory.
+
+## Phase A: Recon (map the codebase)
+
+**Check for triage data first.** The orchestrator runs `triage.cjs` in Step 1 and writes `.bug-hunter/triage.json`. If this file exists, triage has already:
+- Discovered and classified all source files (domains + riskMap)
+- Computed FILE_BUDGET from actual file sizes
+- Built a priority-ordered scanOrder for Hunters
+- Determined the execution strategy
+
+1. Read `SKILL_DIR/prompts/recon.md` with the Read tool — do NOT act from memory.
+
+2. **If `.bug-hunter/triage.json` exists:**
+   - Read it. Use `triage.riskMap` as the initial risk map (skip file discovery + classification).
+   - Use `triage.fileBudget` as FILE_BUDGET (skip computation).
+   - Use `triage.scanOrder` as the file order for Phase B.
+   - Recon's remaining job: read 3-5 key files from CRITICAL domains to identify **tech stack** (framework, auth mechanism, database, key dependencies) and **trust boundary patterns** (how routes are defined, how auth middleware is applied, etc.).
+   - If git is available, check recently changed files with `git log`.
+   - Write your Recon output to `.bug-hunter/recon.md` — include the tech stack, patterns, and the triage-provided risk map.
+
+3. **If `.bug-hunter/triage.json` does NOT exist** (fallback — Recon called directly):
+   - Execute the full Recon instructions: discover files, classify, compute FILE_BUDGET.
+   - Use search tools (`rg`, `grep`, or manual Read) to find trust boundaries.
+   - Measure file sizes to compute FILE_BUDGET (default: 40 if measurement fails).
+   - Write complete output to `.bug-hunter/recon.md`.
+
+4. Parse your output: extract the risk map, FILE_BUDGET, tech stack, and scan order. You will use these in all subsequent phases.
+
+**If Recon fails or you cannot complete it:** Skip Recon. Set FILE_BUDGET=40. Use triage's scanOrder if available, otherwise use a flat file list ordered by directory depth. Continue to Phase B.
+
+## Phase B: Hunter (deep scan for bugs)
+
+1. Read `SKILL_DIR/prompts/hunter.md` with the Read tool.
+2. Read `SKILL_DIR/prompts/doc-lookup.md` with the Read tool.
+3. **Switch mindset**: you are now a Bug Hunter. Your ONLY job is to find behavioral bugs.
+4. Execute the Hunter instructions yourself:
+   - Read files in risk-map order: CRITICAL → HIGH → MEDIUM.
+   - For each file, use the Read tool. Do NOT rely on memory from earlier phases.
+   - Apply the mandatory security checklist sweep (Phase 3 in hunter.md) on every CRITICAL and HIGH file.
+   - Track which files you actually read — be honest about coverage.
+   - For each bug found, record it in the exact BUG-N format specified in hunter.md.
+5. Write your complete findings to `.bug-hunter/findings.md`.
+
+**Context management:** If you notice earlier files becoming hazy in your memory:
+- STOP expanding to new files.
+- Record your honest coverage in FILES SCANNED / FILES SKIPPED.
+- Complete the current file thoroughly rather than skimming more files.
+- The pipeline will handle partial coverage via gap-fill or `--loop` mode.
+
+**Chunked execution (when files > FILE_BUDGET):**
+
+If the Recon risk map contains more files than FILE_BUDGET, do NOT try to read them all in one pass. Instead:
+
+1. Initialize state:
+   ```bash
+   node "$SKILL_DIR/scripts/bug-hunter-state.cjs" init ".bug-hunter/state.json" "local-sequential" ".bug-hunter/source-files.json" 30
+   ```
+2. For each chunk:
+   a. Get next chunk:
+      ```bash
+      node "$SKILL_DIR/scripts/bug-hunter-state.cjs" next-chunk ".bug-hunter/state.json"
+      ```
+   b. Mark in-progress:
+      ```bash
+      node "$SKILL_DIR/scripts/bug-hunter-state.cjs" mark-chunk ".bug-hunter/state.json" "<chunk-id>" in_progress
+      ```
+   c. Run the Hunter scan on this chunk's files only.
+   d. Write chunk findings to `.bug-hunter/chunk-<id>-findings.json`.
+   e. Record findings in state:
+      ```bash
+      node "$SKILL_DIR/scripts/bug-hunter-state.cjs" record-findings ".bug-hunter/state.json" ".bug-hunter/chunk-<id>-findings.json" "local-sequential"
+      ```
+   f. Mark done:
+      ```bash
+      node "$SKILL_DIR/scripts/bug-hunter-state.cjs" mark-chunk ".bug-hunter/state.json" "<chunk-id>" done
+      ```
+3. After all chunks: merge findings from `.bug-hunter/state.json` into `.bug-hunter/findings.md`.
+
+**Gap-fill:** After scanning, compare FILES SCANNED against the risk map. If any CRITICAL or HIGH files are in FILES SKIPPED, read them now and append any new findings. If you truly cannot read them (context exhaustion), leave them in FILES SKIPPED.
+
+If TOTAL FINDINGS: 0, skip Phases C and D. Go directly to Step 7 (Final Report) in SKILL.md.
+
+## Phase C: Skeptic (challenge your own findings)
+
+1. Read `SKILL_DIR/prompts/skeptic.md` with the Read tool.
+2. Read `SKILL_DIR/prompts/doc-lookup.md` with the Read tool.
+3. **Switch mindset completely**: you are now the Skeptic. Your job is to DISPROVE false positives. Forget the pride of finding them — you want to kill weak claims.
+4. Read `.bug-hunter/findings.md` to get the findings list.
+5. For EACH finding:
+   - Re-read the actual code at the reported file and line with the Read tool. This is MANDATORY — do not evaluate from memory.
+   - Read all cross-referenced files.
+   - Mentally trace the runtime trigger: does the code actually behave the way the Hunter claimed?
+   - Check framework/middleware protections the Hunter may have missed.
+   - Apply the risk calculation: `EV = (confidence% × points) - ((100 - confidence%) × 2 × points)`. Only DISPROVE when EV is positive (confidence > 67%).
+   - For Critical bugs: need >67% confidence AND all cross-references read.
+6. Write your complete Skeptic output to `.bug-hunter/skeptic.md` in the format from skeptic.md.
+
+**Important:** When switching from Hunter to Skeptic, genuinely try to disprove your own findings. The point of this phase is adversarial review. If you cannot genuinely argue against a finding, ACCEPT it and move on — do not waste time rubber-stamping.
+
+## Phase D: Referee (final verdicts)
+
+1. Read `SKILL_DIR/prompts/referee.md` with the Read tool.
+2. **Switch mindset**: you are the impartial Referee. You trust neither the Hunter nor the Skeptic.
+3. Read both `.bug-hunter/findings.md` and `.bug-hunter/skeptic.md`.
+4. For each finding:
+   - **Tier 1 (all Critical + top 15 by severity):** Re-read the actual code yourself a THIRD time using the Read tool. Construct the runtime trigger independently. Make your own judgment.
+   - **Tier 2 (remaining):** Evaluate evidence quality. Whose code quotes are more specific? Whose runtime trigger is more concrete?
+5. Make final REAL BUG / NOT A BUG verdicts with severity calibration.
+6. Write the final Referee report to `.bug-hunter/referee.md`.
+7. Proceed to Step 7 (Final Report) in SKILL.md.
+
+## State Files Summary
+
+After a complete local-sequential run, these files should exist:
+
+| File | Phase | Content |
+|------|-------|---------|
+| `.bug-hunter/recon.md` | A | Risk map, file metrics, tech stack |
+| `.bug-hunter/findings.md` | B | All Hunter findings in BUG-N format |
+| `.bug-hunter/skeptic.md` | C | Skeptic challenges and decisions |
+| `.bug-hunter/referee.md` | D | Final verdicts and confirmed bugs |
+| `.bug-hunter/state.json` | B (chunked) | Chunk progress, findings ledger |
+| `.bug-hunter/source-files.json` | A | Source file list (for state init) |
+
+## Coverage Enforcement
+
+After Phase D, check coverage:
+
+- If all CRITICAL and HIGH files were scanned: proceed to Final Report.
+- If any CRITICAL/HIGH files were skipped:
+  - If `--loop` mode: the ralph-loop will iterate and cover them next.
+  - If not `--loop`: include a coverage WARNING in the Final Report and recommend `--loop`.
+- Do NOT claim "full coverage" or "audit complete" unless every CRITICAL and HIGH file was actually read with the Read tool and has status DONE.

package/modes/loop.md

@@ -0,0 +1,125 @@
+# Ralph-Loop Mode (`--loop`)
+
+When `--loop` is present, the bug-hunter wraps itself in a ralph-loop that keeps iterating until the audit achieves full coverage. This is for thorough, autonomous audits where you want every file examined.
+
+## CRITICAL: Starting the ralph-loop
+
+**You MUST call the `ralph_start` tool to begin the loop.** Without this call, the loop will not iterate.
+
+When `LOOP_MODE=true` is set (from `--loop` flag), before running the first pipeline iteration:
+
+1. Build the task content from the TODO.md template below.
+2. Call the `ralph_start` tool:
+
+```
+ralph_start({
+  name: "bug-hunter-audit",
+  taskContent: <the TODO.md content below>,
+  maxIterations: 10
+})
+```
+
+3. The ralph-loop system will then drive iteration. Each iteration:
+   - You receive the task prompt with the current checklist state.
+   - You execute one iteration of the bug-hunt pipeline (steps below).
+   - You update `.bug-hunter/coverage.md` with results.
+   - If ALL CRITICAL/HIGH files are DONE → output `<promise>COMPLETE</promise>` to end the loop.
+   - Otherwise → call `ralph_done` to proceed to the next iteration.
+
+**Do NOT manually loop or re-invoke yourself.** The ralph-loop system handles iteration automatically after you call `ralph_start`.
+
+## How it works
+
+1. **First iteration**: Run the normal pipeline (Recon → Hunters → Skeptics → Referee). At the end, write a coverage report to `.bug-hunter/coverage.md` using the machine-parseable format below.
+
+2. **Coverage check**: After each iteration, evaluate:
+   - If ALL CRITICAL and HIGH files show status DONE → output `<promise>COMPLETE</promise>` → loop ends
+   - If any CRITICAL/HIGH files are SKIPPED or PARTIAL → call `ralph_done` → loop continues
+   - If only MEDIUM files remain uncovered → output `<promise>COMPLETE</promise>` (MEDIUM gaps are acceptable)
+
+3. **Subsequent iterations**: Each new iteration reads `.bug-hunter/coverage.md` to see what's already been done, then runs the pipeline ONLY on uncovered files. New findings are appended to the cumulative bug list.
+
+## Coverage file format (machine-parseable)
+
+**`.bug-hunter/coverage.md`:**
+```markdown
+# Bug Hunt Coverage
+SCHEMA_VERSION: 2
+
+## Meta
+ITERATION: [N]
+STATUS: [IN_PROGRESS | COMPLETE]
+TOTAL_BUGS_FOUND: [N]
+TIMESTAMP: [ISO 8601]
+CHECKSUM: [line_count of Files section]|[line_count of Bugs section]
+
+## Files
+<!-- One line per file. Format: TIER|PATH|STATUS|ITERATION_SCANNED|BUGS_FOUND -->
+<!-- STATUS: DONE | PARTIAL | SKIPPED -->
+<!-- BUGS_FOUND: comma-separated BUG-IDs, or NONE -->
+CRITICAL|src/auth/login.ts|DONE|1|BUG-3,BUG-7
+CRITICAL|src/auth/middleware.ts|DONE|1|NONE
+HIGH|src/api/users.ts|DONE|1|BUG-12
+HIGH|src/api/payments.ts|SKIPPED|0|
+MEDIUM|src/utils/format.ts|SKIPPED|0|
+TEST|src/auth/login.test.ts|CONTEXT|1|
+
+## Bugs
+<!-- One line per confirmed bug. Format: BUG-ID|SEVERITY|FILE|LINES|ONE_LINE_DESCRIPTION -->
+BUG-3|Critical|src/auth/login.ts|45-52|JWT token not validated before use
+BUG-7|Medium|src/auth/login.ts|89|Password comparison uses timing-unsafe equality
+BUG-12|Low|src/api/users.ts|120-125|Missing null check on optional profile field
+```
+
+## TODO.md task content for ralph_start
+
+Use this as the `taskContent` parameter when calling `ralph_start`:
+
+**For `--loop` (scan only):**
+```markdown
+# Bug Hunt Audit
+
+## Coverage Tasks
+- [ ] All CRITICAL files scanned
+- [ ] All HIGH files scanned
+- [ ] Findings verified through Skeptic+Referee pipeline
+
+## Completion
+- [ ] ALL_TASKS_COMPLETE
+
+## Instructions
+1. Read .bug-hunter/coverage.md for previous iteration state
+2. Parse the Files table — collect all lines where STATUS is not DONE and TIER is CRITICAL or HIGH
+3. Run bug-hunter pipeline on those files only
+4. Update coverage file: change STATUS to DONE, add BUG-IDs
+5. Output <promise>COMPLETE</promise> when all CRITICAL/HIGH files are DONE
+6. Otherwise call ralph_done to continue to the next iteration
+```
+
+## Coverage file validation
+
+At the start of each iteration, validate the coverage file:
+1. Check `SCHEMA_VERSION: 2` exists on line 2 — if missing, this is a v1 file; migrate by adding the header
+2. Parse the CHECKSUM field: `[file_lines]|[bug_lines]` — count actual lines in Files and Bugs sections
+3. If counts don't match the checksum, the file may be corrupted. Warn: "Coverage file checksum mismatch (expected X|Y, got A|B). Re-scanning affected files." Then set any files with mismatched data to STATUS=PARTIAL for re-scan.
+4. If the file fails to parse entirely (malformed lines, missing sections), rename it to `.bug-hunter/coverage.md.bak` and start fresh. Warn user.
+
+Update the CHECKSUM every time you write to the coverage file.
+
+## Iteration behavior
+
+Each iteration after the first:
+1. Read `.bug-hunter/coverage.md` — parse the Files table
+2. Collect all lines where STATUS != DONE and TIER is CRITICAL or HIGH
+3. If none remain → output `<promise>COMPLETE</promise>` (this ends the ralph-loop)
+4. Otherwise, run the pipeline on remaining files only (use small/parallel mode based on count)
+5. Update the coverage file: set STATUS to DONE for scanned files, append new bugs to the Bugs section
+6. Increment ITERATION counter
+7. Call `ralph_done` to proceed to the next iteration
+
+## Safety
+
+- Max 10 iterations by default (set via `ralph_start({ maxIterations: 10 })`)
+- Each iteration only scans NEW files — no re-scanning already-DONE files
+- User can stop anytime with ESC or `/ralph-stop`
+- All state is in `.bug-hunter/coverage.md` — fully resumable, machine-parseable

package/modes/parallel.md

@@ -0,0 +1,113 @@
+# Parallel Mode (11–FILE_BUDGET files) — sequential-first hybrid
+
+This mode handles medium-sized scan targets. The deep Hunter scans all files sequentially.
+An optional read-only dual-lens **scout pass** can run in parallel to provide hints.
+All phases are dispatched using the `AGENT_BACKEND` selected during SKILL preflight.
+
+---
+
+## Triage Integration
+
+Before any phase, check for `.bug-hunter/triage.json` (written by Step 1). If present:
+- Use `triage.riskMap` as the risk map — skip Recon's file classification.
+- Use `triage.scanOrder` as the Hunter's file order.
+- Use `triage.fileBudget` as FILE_BUDGET.
+- Recon becomes an enrichment pass: identify tech stack and trust boundary patterns only.
+
+---
+
+## Step 4: Run Recon
+
+Dispatch Recon using the standard dispatch pattern (see `_dispatch.md`, role=`recon`).
+
+**If triage data exists**, tell Recon to use the triage risk map and only identify tech stack + patterns. Pass the triage JSON path as phase-specific context.
+
+**If no triage data**, Recon does full file discovery and classification.
+
+After Recon completes, read `.bug-hunter/recon.md` to extract the risk map, tech stack, and FILE_BUDGET.
+
+Report architecture summary to user.
+
+---
+
+## Step 5: Optional read-only dual-lens scout pass (safe parallel)
+
+**This step is optional** — skip it if the codebase is straightforward or if `AGENT_BACKEND = "local-sequential"`.
+
+Launch two scout Hunters in parallel on CRITICAL+HIGH files only:
+
+1. Generate payloads:
+   ```
+   node "$SKILL_DIR/scripts/payload-guard.cjs" generate triage-hunter ".bug-hunter/payloads/scout-hunter-a.json"
+   node "$SKILL_DIR/scripts/payload-guard.cjs" generate triage-hunter ".bug-hunter/payloads/scout-hunter-b.json"
+   ```
+2. Fill payloads: Scout-A = security lens, Scout-B = logic lens. Both scan the same CRITICAL+HIGH files.
+3. Validate both payloads.
+4. Dispatch in parallel:
+   ```
+   subagent({ tasks: [
+       { agent: "scout-hunter-security", task: "<security scout template>", output: ".bug-hunter/scout-a.md" },
+       { agent: "scout-hunter-logic", task: "<logic scout template>", output: ".bug-hunter/scout-b.md" }
+   ]})
+   ```
+5. Wait for both. Merge scout shortlists into hints for the deep Hunter.
+
+**Scout pass rules:**
+- Scouts are READ-ONLY — they never modify files or state.
+- If either scout dispatch fails, disable scout pass and continue to Step 5-deep without hints.
+- Scout findings alone are NOT the final result — they only inform the deep scan.
+
+---
+
+## Step 5-deep: Run Deep Hunter
+
+Dispatch Hunter using the standard dispatch pattern (see `_dispatch.md`, role=`hunter`).
+
+Pass to the Hunter:
+- File list in risk-map order. If triage exists, use `triage.scanOrder`.
+- Risk map from Recon (or triage).
+- Tech stack from Recon.
+- If scout hints exist (from Step 5), use them to prioritize certain code sections, but scan all files regardless.
+- `doc-lookup.md` contents as phase-specific context.
+
+After completion, read `.bug-hunter/findings.md`.
+
+**Merge scout + deep findings:** If scout pass ran, compare scout findings with deep Hunter findings. Promote any scout-only findings (bugs the deep Hunter missed) into the findings list for Skeptic review.
+
+If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in SKILL.md.
+
+---
+
+## Step 5-verify: Gap-fill check
+
+Same as small mode: compare FILES SCANNED vs risk map, re-scan any missed CRITICAL/HIGH files.
+
+---
+
+## Step 6: Run Skeptic
+
+Dispatch Skeptic using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
+
+For parallel mode, you may split into two Skeptics by directory if findings span multiple services:
+- Skeptic-A: bugs in service/directory A
+- Skeptic-B: bugs in service/directory B
+
+Pass to each Skeptic only the bugs in their assigned scope. After completion, merge results.
+
+If only one service/directory: use a single Skeptic.
+
+---
+
+## Step 7: Run Referee
+
+Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
+
+Pass the merged Hunter findings + Skeptic challenges.
+
+After completion, read `.bug-hunter/referee.md`.
+
+---
+
+## After Step 7
+
+Proceed to **Step 7** (Final Report) in SKILL.md.

package/modes/scaled.md

@@ -0,0 +1,76 @@
+# Scaled Mode (FILE_BUDGET×2+1 to FILE_BUDGET×3 files) — state-driven sequential
+
+This mode handles large targets requiring 3+ chunks with full resume state.
+All phases are dispatched using the `AGENT_BACKEND` selected during SKILL preflight.
+
+---
+
+## Triage Integration
+
+Before any phase, check for `.bug-hunter/triage.json` (written by Step 1). If present:
+- Use `triage.riskMap` as the risk map — skip Recon's file classification.
+- Use `triage.scanOrder` as the chunk-building source (files already priority-ordered).
+- Use `triage.fileBudget` as FILE_BUDGET and chunk size cap.
+- Use `triage.domains` for service-aware partitioning if available.
+- Recon becomes an enrichment pass: identify tech stack and trust boundary patterns only.
+
+---
+
+## Step 4: Run Recon
+
+Dispatch Recon using the standard dispatch pattern (see `_dispatch.md`, role=`recon`).
+
+Same as Extended mode: Recon enriches triage data with tech stack and patterns. If no triage, Recon does full discovery.
+
+---
+
+## Step 5: Run Chunked Hunters with Resume State
+
+### 5a. Build chunks and initialize state
+
+Same as Extended mode. Partition from `triage.scanOrder` or risk map. Initialize state:
+```bash
+node "$SKILL_DIR/scripts/bug-hunter-state.cjs" init ".bug-hunter/state.json" "scaled" ".bug-hunter/source-files.json" 30
+```
+
+### 5b. Execute chunks with hash-based skip filtering
+
+Before each chunk, apply skip filtering to avoid re-scanning files already processed (handles resume after interruption):
+```bash
+node "$SKILL_DIR/scripts/bug-hunter-state.cjs" hash-filter ".bug-hunter/state.json" ".bug-hunter/chunk-<id>-files.json"
+```
+
+For each chunk: dispatch Hunter, record findings, mark done — same pattern as Extended mode.
+
+### 5c. Cross-chunk consistency
+
+After all chunks complete:
+1. Merge findings from state into `.bug-hunter/findings.md`.
+2. Run consistency check: look for duplicate BUG-IDs across chunks and conflicting claims on the same file/line.
+3. Resolve conflicts: keep the finding with the stronger evidence.
+
+If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in SKILL.md.
+
+---
+
+## Step 6: Run Skeptic(s)
+
+Dispatch 1-2 Skeptics by directory using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
+
+Split bugs by directory/service for focused scope. Merge results.
+
+---
+
+## Step 7: Run Referee
+
+Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
+
+Pass merged Hunter findings + Skeptic challenges.
+
+---
+
+## After Step 7
+
+Proceed to **Step 7** (Final Report) in SKILL.md.
+
+If `--loop` was specified and coverage is incomplete, the ralph-loop will iterate to cover remaining files.

package/modes/single-file.md

@@ -0,0 +1,38 @@
+# Single-File Mode (1 file)
+
+All phases are dispatched using `AGENT_BACKEND` selected during SKILL preflight.
+Recon is skipped — a single file doesn't need codebase mapping.
+
+---
+
+## Step 4: Run Hunter
+
+Dispatch Hunter using the standard dispatch pattern (see `_dispatch.md`, role=`hunter`).
+
+Pass the single file path as the file list. No risk map needed — the file is implicitly CRITICAL.
+
+For `local-sequential`: read the prompt file and scan the single file yourself.
+
+After completion, read `.bug-hunter/findings.md`.
+
+If TOTAL FINDINGS: 0, go to Step 7 (Final Report) in SKILL.md.
+
+---
+
+## Step 5: Run Skeptic
+
+Dispatch Skeptic using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
+
+Inject the Hunter's findings.
+
+After completion, read `.bug-hunter/skeptic.md`.
+
+---
+
+## Step 6: Run Referee
+
+Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
+
+Inject Hunter + Skeptic reports.
+
+After completion, read `.bug-hunter/referee.md`. Go to Step 7 (Final Report) in SKILL.md.

package/modes/small.md

@@ -0,0 +1,86 @@
+# Small Mode (2–10 files)
+
+This mode handles small scan targets where all files fit in a single pass.
+All phases are dispatched using the `AGENT_BACKEND` selected during SKILL preflight.
+
+---
+
+## Triage Integration
+
+Before any phase, check for `.bug-hunter/triage.json` (written by Step 1). If present:
+- Use `triage.riskMap` as the risk map — skip Recon's file classification.
+- Use `triage.scanOrder` as the Hunter's file order.
+- Recon becomes an enrichment pass: identify tech stack and trust boundary patterns only.
+
+---
+
+## Step 4: Run Recon
+
+Dispatch Recon using the standard dispatch pattern (see `_dispatch.md`, role=`recon`).
+
+**If triage data exists**, tell Recon to use the triage risk map and only identify tech stack + patterns. Pass the triage JSON path as phase-specific context.
+
+**If no triage data**, Recon does full file discovery and classification.
+
+After Recon completes, read `.bug-hunter/recon.md` to extract the risk map and tech stack.
+
+Report architecture summary to user.
+
+---
+
+## Step 5: Run Hunter
+
+Dispatch Hunter using the standard dispatch pattern (see `_dispatch.md`, role=`hunter`).
+
+Pass to the Hunter:
+- File list in risk-map order (CRITICAL → HIGH → MEDIUM). If triage exists, use `triage.scanOrder`.
+- Risk map from Recon (or triage).
+- Tech stack from Recon.
+- `doc-lookup.md` contents as phase-specific context.
+
+After completion, read `.bug-hunter/findings.md`.
+
+If TOTAL FINDINGS: 0, skip Skeptic and Referee. Go to Step 7 (Final Report) in SKILL.md.
+
+---
+
+## Step 5-verify: Gap-fill check
+
+Compare the Hunter's FILES SCANNED list against the risk map.
+
+If any CRITICAL or HIGH files appear in FILES SKIPPED:
+
+**local-sequential:** Read the missed files yourself now and scan them for bugs. Append new findings to `.bug-hunter/findings.md`.
+
+**subagent/teams:** Launch a second Hunter on ONLY the missed files using the standard dispatch pattern. Merge gap findings into `.bug-hunter/findings.md`.
+
+---
+
+## Step 6: Run Skeptic
+
+Dispatch Skeptic using the standard dispatch pattern (see `_dispatch.md`, role=`skeptic`).
+
+Pass to the Skeptic:
+- Hunter findings from `.bug-hunter/findings.md` (compact format: bugId, severity, file, lines, claim, evidence, runtimeTrigger).
+- Tech stack from Recon.
+- `doc-lookup.md` contents as phase-specific context.
+
+After completion, read `.bug-hunter/skeptic.md`.
+
+---
+
+## Step 7: Run Referee
+
+Dispatch Referee using the standard dispatch pattern (see `_dispatch.md`, role=`referee`).
+
+Pass to the Referee:
+- Hunter findings from `.bug-hunter/findings.md`.
+- Skeptic challenges from `.bug-hunter/skeptic.md`.
+
+After completion, read `.bug-hunter/referee.md`.
+
+---
+
+## After Step 7
+
+Proceed to **Step 7** (Final Report) in SKILL.md. The Referee output in `.bug-hunter/referee.md` provides the confirmed bugs table, dismissed findings, and coverage stats needed for the final report.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@codexstar/bug-hunter",
+  "version": "3.0.0",
+  "description": "Adversarial AI bug hunter — multi-agent pipeline finds security vulnerabilities, logic errors, and runtime bugs, then fixes them autonomously. Works with Claude Code, Cursor, Codex CLI, Copilot, Kiro, and more.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "bug-hunter": "bin/bug-hunter"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "skill",
+    "bug-hunter",
+    "security",
+    "vulnerability",
+    "code-review",
+    "auto-fix",
+    "claude-code",
+    "cursor",
+    "codex",
+    "copilot",
+    "kiro",
+    "multi-agent",
+    "adversarial",
+    "static-analysis"
+  ],
+  "files": [
+    "bin/",
+    "scripts/",
+    "prompts/",
+    "templates/",
+    "modes/",
+    "evals/",
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codexstar69/bug-hunter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/codexstar69/bug-hunter/issues"
+  },
+  "homepage": "https://github.com/codexstar69/bug-hunter#readme",
+  "scripts": {
+    "test": "node --test scripts/tests/*.test.cjs",
+    "doctor": "node bin/bug-hunter doctor",
+    "postinstall": "node -e \"console.log('\\n  Run: bug-hunter install    to set up the skill\\n  Run: bug-hunter doctor     to check your environment\\n')\""
+  }
+}