bug-hunt

Files (7)

• SKILL.md
• exclude_enforce.sh · scripts/
• git_safety_scan.sh · scripts/
• hunt.sh · scripts/
• prewarm_ubs.sh · scripts/
• test_exclude_files_enforcement.sh · tests/
• test_git_safety_scan.sh · tests/

SKILL.md (first lines)

# /bug-hunt — Autonomous Multi-Phase Bug Hunting

Run a pluggable engine (Codex, Gemini, or Claude) through a structured 3-phase
bug hunting routine against the current working directory. Each phase runs N
iterations (default 3). A rolling hunt journal accumulates across iterations via
Agent Mail threads, so each engine run builds on what previous runs discovered.

## Arguments

```
/bug-hunt                              # full run: 3 phases x 3 iterations (9 total)
/bug-hunt --engine gemini              # use Gemini CLI instead of Codex
/bug-hunt --engine claude              # use Claude Code subagent (worktree isolation)
/bug-hunt --iterations 5               # 5 iterations per phase (15 total)
/bug-hunt --phase 2                    # run only phase 2 (review others' code)
/bug-hunt --phase 1 --iterations 2     # 2 iterations of phase 1 only
/bug-hunt --dry-run                    # print prompts without executing
/bug-hunt --no-mail                    # skip Agent Mail (solo mode, local journal only)
```

## Phases

| # | Name | Focus |
|---|------|-------|
| 1 | **Explore & Fix** | Randomly explore code files, trace execution flows, find and fix bugs |
| 2 | **Review Others** | Review code written by other agents, deep root-cause analysis |
| 3 | **Self-Review** | Fresh-eyes review of all code just written/modified |

## Workflow

### 1. Parse Arguments

Extract from `$ARGUMENTS`:
- `--engine <codex|gemini|claude>` (default: codex)
- `--iterations N` (default: 3)
- `--phase N` (1, 2, or 3 — omit to run all phases)
- `--dry-run` flag
- `--model <model>` (default: engine-specific — codex=gpt-5.4, gemini=default)
- `--no-mail` flag (skip Agent Mail)

### 2. Register & Create Hunt Thread

Unless `--no-mail` is set:

1. Call `macro_start_session` with:
   - `human_key`: current working directory path
   - `program`: `claude-code`
   - `model`: your model name
   - `task_description`: `"bug-hunt: <phases> x <iterations> iterations"`

   **Save the response.** Hold `agent.name` and `registration_token` for the
   entire session — needed to deregister cleanly in step 5.

2. **Set open contact policy** so broadcasts don't fail as new agents register:
   - Call `set_contact_policy` with `policy: "open"` (or `auto_accept: true`)
   - This prevents the contact-approval explosion seen in long sessions

3. Check inbox. Acknowledge pending messages. Note active agents and their
   file reservations.

4. **Check for prior hunt history**: Call `search_messages` with
   `query="bug AND hunt"`, `ranking="recency"`, and `limit=20` to find past
   hunt threads. Include a 1-line summary of prior findings in the first engine
   prompt.

5. Create a hunt thread ID: `bug-hunt-YYYY-MM-DD-HHMM`

6. Announce the hunt via `send_message`:
   - thread_id: the hunt thread ID
   - subject: prefix with `[bug-hunt]`
   - body: phases, iteration count, target directory, any prior-hunt context

**Agent Mail isolation**: Only this Claude Code session registers with Agent
Mail. Engine sub-processes do NOT register — they have no MCP access. All
Agent Mail communication flows through the orchestrating Claude Code session.

### 3. Build Context

Before running phases, gather context for the engine:
- Read `AGENTS.md` to extract rules the engine must follow
- Record `start_sha=$(git rev-parse HEAD)` — needed for the pristine-tree
  falsification in step 4c
- Note the current git branch and recent commits
- If Agent Mail is active, note file reservations and prepend
  "DO NOT MODIFY these files: ..." to engine prompts
- **Pre-flight concurrency gate before dispatch**. The shared helper blocks
  if active host-wide `codex exec` + `gemini -p` processes are already at
  the cap (default `2`, override with `SWARM_MAX_CONCURRENT` or
  `hunt.sh --max-concurrent N`). If the check refuses, stop before phase
  dispatch so dry-run and real runs fail the same way.
- **Record quality-gate baseline** — identify the project's test command
  (from AGENTS.md / README / `package.json` / `pyproject.toml`) and run it
  once. Persist the failing-test IDs and pass/fail counts to a per-session
  baseline file:
  ```bash
  TEST_BASELINE="$(mktemp -t bug-hunt-baseline.XXXXXX)"
  # run project test command, capture failing-test IDs + pass/fail counts to $TEST_BASELINE
  ```
  A file (not just conversation context) because the orchestrator may be
  compacted between iterations and lose in-context memory. You will diff
  every post-iteration run against this file. If the project has no test
  suite, write `NO_TEST_SUITE` to `$TEST_BASELINE` and fall back to
  comparing `git status` + manual smoke checks.

  Bug-hunt expects deltas — some baseline-failing tests SHOULD flip to
  passing (that's the point). The regression rule is one-directional:
  baseline-passing → now-failing is a regression; baseline-failing →
  now-passing is good. Tests the engine skipped or deleted are a judgment
  call: "the bug was in the test" is sometimes true but usually suspicious.

**Git safety block** (appended verbatim to every engine prompt in every phase — handled
in `hunt.sh` alongside the feature-creep guard):

```
Git safety — NON-NEGOTIABLE:
- DO NOT run git commit --amend under any circumstances.
- DO NOT run git revert, git reset, git rebase, or git cherry-pick.
- DO NOT force-push or git push --force-with-lease.
- If you need to fix something, create a NEW commit on top of HEAD.

From thunter009/skills, MIT.

More from thunter009/skills