# Bug Hunter

> AI-powered adversarial bug finding that argues with itself to surface real vulnerabilities — and auto-fixes them safely.

## What It Does

Bug Hunter is an automated adversarial code auditing skill for AI coding agents. It runs a multi-agent pipeline where one agent hunts for bugs, a second tries to disprove them, and a third delivers an independent verdict. Only bugs that survive all three stages appear in your report.

## Key Capabilities

- Zero-token triage: classifies files by risk in <2s before any AI runs
- Adversarial pipeline: Hunter → Skeptic → Referee eliminates false positives
- Security classification: STRIDE threat categories, CWE weakness IDs, CVSS 3.1 scoring
- Documentation verification: checks claims against official library docs via Context Hub + Context7
- Safe auto-fix: git-branched fixes with worktree isolation, canary rollout, test verification, and automatic rollback
- Dependency CVE scanning: lockfile-aware audits for npm, pnpm, yarn, bun (including Bun 1.2+ text-format lockfiles)
- PR review: first-class `--pr` workflow for reviewing current, recent, or numbered PRs
- Enterprise security pack: bundled STRIDE threat modeling, vulnerability validation, and security review skills

## Architecture — Skills-First Design

All pipeline agents are bundled as first-class skills under `skills/`:

| Skill | Purpose |
|-------|---------|
| `skills/hunter/` | Deep behavioral code analysis — finds bugs |
| `skills/skeptic/` | Adversarial reviewer — kills false positives |
| `skills/referee/` | Independent arbiter — delivers final verdicts |
| `skills/fixer/` | Surgical code repair — implements fixes |
| `skills/recon/` | Codebase reconnaissance — maps architecture |
| `skills/doc-lookup/` | Documentation access — Context Hub + Context7 |
| `skills/commit-security-scan/` | PR/commit security review |
| `skills/security-review/` | Full enterprise security audit |
| `skills/threat-model-generation/` | STRIDE threat model generation |
| `skills/vulnerability-validation/` | Exploitability/CVSS validation |

## Usage

```
/bug-hunter src/                   # scan a directory, auto-fix confirmed bugs
/bug-hunter --scan-only src/       # report only, no code changes
/bug-hunter --pr current           # review the current PR
/bug-hunter --pr-security          # PR security review with threat model + CVEs
/bug-hunter --security-review src/ # enterprise security audit
/bug-hunter --threat-model src/    # generate STRIDE threat model
/bug-hunter --deps src/            # include dependency CVE scan
/bug-hunter -b feature-xyz        # scan branch diff vs main
```

## Install

```bash
# npm global install (recommended)
npm install -g @codexstar/bug-hunter && bug-hunter install

# Cross-IDE install via skills.sh
npx skills add codexstar69/bug-hunter

# Git clone
git clone https://github.com/codexstar69/bug-hunter.git ~/.agents/skills/bug-hunter

# Optional: curated doc verification
npm install -g @aisuite/chub
```

Requirements: Node.js 18+. Works with Pi, Claude Code, Codex, Cursor, Windsurf, Kiro, Copilot.

## Documentation

- [README.md](https://github.com/codexstar69/bug-hunter/blob/main/README.md) — full documentation
- [SKILL.md](https://github.com/codexstar69/bug-hunter/blob/main/SKILL.md) — agent integration instructions
- [CHANGELOG.md](https://github.com/codexstar69/bug-hunter/blob/main/CHANGELOG.md) — version history
- [CONTRIBUTING.md](https://github.com/codexstar69/bug-hunter/blob/main/CONTRIBUTING.md) — contribution guide

## License

MIT