@codexstar/bug-hunter 3.0.5 → 3.0.7

package/CHANGELOG.md

@@ -5,7 +5,45 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.0.5] — 2026-03-11
+## [3.0.7] - 2026-03-12
+
+### Highlights
+- **All agents are now first-class skills.** Hunter, Skeptic, Referee, Fixer, Recon, and Doc-Lookup are bundled under `skills/` with proper frontmatter - no more loose prompt files.
+- **Prepublish guard** prevents publishing to npm without committing and pushing to GitHub first.
+- **CI fully green** on both Node 18 and 20 with portable shell detection and explicit branch naming.
+
+### Added
+- `skills/hunter/SKILL.md` - deep behavioral code analysis skill (migrated from `prompts/hunter.md`)
+- `skills/skeptic/SKILL.md` - adversarial code reviewer skill (migrated from `prompts/skeptic.md`)
+- `skills/referee/SKILL.md` - independent final arbiter skill (migrated from `prompts/referee.md`)
+- `skills/fixer/SKILL.md` - surgical code repair skill (migrated from `prompts/fixer.md`)
+- `skills/recon/SKILL.md` - codebase reconnaissance skill (migrated from `prompts/recon.md`)
+- `skills/doc-lookup/SKILL.md` - unified documentation access skill (Context Hub + Context7)
+- `scripts/prepublish-guard.cjs` - blocks `npm publish` when git working tree is dirty or commits are unpushed
+- `prepublishOnly` lifecycle hook in `package.json` enforcing the guard
+
+### Changed
+- `SKILL.md` orchestrator routing table now points to `skills/` instead of `prompts/`
+- `run-bug-hunter.cjs` preflight now validates all 10 bundled skill `SKILL.md` files exist
+- `run-bug-hunter.cjs` uses `process.env.SHELL || '/bin/bash'` instead of hardcoded `/bin/zsh` for CI portability
+- `worktree-harvest.test.cjs` uses `git init --bare -b main` for CI environments where default branch is not `main`
+- `templates/subagent-wrapper.md` references `skills/` paths instead of `prompts/`
+- `skills/README.md` now documents all 10 bundled skills (6 core agents + 4 security skills)
+
+### Fixed
+- All v3.0.5 code changes that were published to npm but never committed to GitHub (21 new files, 19 updated files recovered)
+- `package.json` version synced to match npm-published 3.0.5→3.0.6→3.0.7
+
+## [3.0.6] - 2026-03-12
+
+### Added
+- `scripts/prepublish-guard.cjs` - first version of the publish safety net
+- CI fixes for worktree tests and shell portability
+
+### Fixed
+- Synced all v3.0.5 changes from npm to GitHub (security skills, PR review flow, schemas, images)
+
+## [3.0.5] - 2026-03-11
 
 ### Added
 - `agents/openai.yaml` UI metadata for skill lists and quick-invoke prompts
@@ -17,33 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Highlights
-- PR review is now a first-class workflow with `--pr`, `--pr current`, `--pr recent`, `--pr 123`, `--last-pr`, and `--pr-security`.
-- Bug Hunter now emits both `fix-strategy.json` and `fix-plan.json` before fix execution so remediation stays reviewable and confidence-gated.
-- The enterprise security pack now ships inside the repository under `skills/`, making PR security review and full security audits portable.
-- Fix execution is now safer through schema-validated planning, atomic lock handling, safer worktree cleanup, stash preservation, and shell-safe templating.
-
-### Added
-- GitHub Actions npm publish workflow on release publish or manual dispatch, with version/tag verification before `npm publish`
-- bundled local security skills under `skills/`: `commit-security-scan`, `security-review`, `threat-model-generation`, and `vulnerability-validation`
-- enterprise security entrypoints: `--pr-security`, `--security-review`, and `--validate-security`
-- regression tests and eval coverage for integrated local security-skill routing
-- `schemas/fix-plan.schema.json` plus validation coverage for canonical fix-plan artifacts
-- focused regressions for lock-token ownership, atomic lock acquisition, stale artifact clearing, shell-safe worker paths, failed-chunk fix-plan suppression, managed worktree cleanup, and stash-ref preservation
-
-### Changed
-- portable security capabilities now live inside the repository under `skills/` instead of depending on external machine-specific skill paths
-- package metadata now ships the `skills/` directory for self-contained distribution
-- main Bug Hunter orchestration now routes into the bundled local security skills for PR security review, threat-model generation, enterprise security review, and vulnerability validation
-- fix-lock now uses owner tokens for renew/release, atomic acquisition under contention, and safe recovery from corrupted lock files
-- run-bug-hunter now shell-quotes templated command arguments, clears stale artifacts before retries, validates fix-plan artifacts, and skips fix-plan emission when chunks fail
-- worktree cleanup/status now preserve unrelated directories, preserve stash metadata from defensive harvests, and avoid reporting manifest-only worktrees as dirty
-- current-PR git fallback now diffs against the discovered `origin/<default-branch>` ref when the base branch comes from `origin/HEAD`
-- README now opens with a short “New in This Update” and PR-first quick-start section
-- `llms.txt` and `llms-full.txt` now describe the PR review flow, bundled local security pack, current fix artifacts, and the current regression-test coverage
-- `skills/README.md` now explains how the bundled security skills map into Bug Hunter workflows
-
-## [3.0.4] — 2026-03-11
+## [3.0.4] - 2026-03-11
 
 ### Added
 - `schemas/*.schema.json` versioned contracts for recon, findings, skeptic, referee, coverage, fix-report, plus shared definitions and example findings fixtures
@@ -63,7 +75,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - preflight now checks all shipped structured-output schemas, not just findings
 - structured-output migration now enforces orchestrated outbound validation beyond the local/manual path
 
-## [3.0.1] — 2026-03-11
+## [3.0.1] - 2026-03-11
 
 ### Changed
 - Loop and fix-loop completion now require full queued source-file coverage, not just CRITICAL/HIGH coverage
@@ -71,7 +83,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Loop iteration guidance now scales `maxIterations` from queue size so large audits do not stop early
 - Large-codebase mode now treats LOW domains as part of the default autonomous queue instead of optional skipped work
 
-## [3.0.0] — 2026-03-10
+## [3.0.0] - 2026-03-10
 
 ### Added
 - `package.json` with `@codexstar/bug-hunter` package name
@@ -80,7 +92,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `bug-hunter doctor` checks environment readiness (Node.js, Context Hub, Context7, git)
 - Install via: `npm install -g @codexstar/bug-hunter && bug-hunter install`
 - Compatible with `npx skills add codexstar69/bug-hunter` for Cursor, Windsurf, Copilot, Kiro, and Claude Code
-- `scripts/worktree-harvest.cjs` — manages git worktrees for safe, isolated Fixer execution (6 subcommands: `prepare`, `harvest`, `checkout-fix`, `cleanup`, `cleanup-all`, `status`)
+- `scripts/worktree-harvest.cjs` - manages git worktrees for safe, isolated Fixer execution (6 subcommands: `prepare`, `harvest`, `checkout-fix`, `cleanup`, `cleanup-all`, `status`)
 - 13 new tests in `scripts/tests/worktree-harvest.test.cjs` (full suite: 25/25 passing)
 - 5 new error rows in SKILL.md for worktree failures: prepare, harvest dirty, harvest no-manifest, cleanup, and checkout-fix errors
 
@@ -90,7 +102,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `templates/subagent-wrapper.md` updated with `{WORKTREE_RULES}` variable for Fixer isolation rules
 - SKILL.md Step 5b now shows a visible `⚠️` warning when `chub` is not installed (previously a silent suggestion)
 
-## [2.4.1] — 2026-03-10
+## [2.4.1] - 2026-03-10
 
 ### Fixed
 - `scripts/triage.cjs`: LOW-only repositories promoted into `scanOrder` so script-heavy codebases do not collapse to zero scannable files
@@ -101,28 +113,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - `scripts/tests/run-bug-hunter.test.cjs`: regressions for LOW-only triage, optional `code-index`, `teams` backend selection, and delta-hop expansion
 
-## [2.4.0] — 2026-03-10
+## [2.4.0] - 2026-03-10
 
 ### Added
 - `scripts/doc-lookup.cjs`: hybrid documentation lookup that tries [Context Hub](https://github.com/andrewyng/context-hub) (chub) first for curated, versioned, annotatable docs, then falls back to Context7 API when chub doesn't have the library
-- Requires `@aisuite/chub` installed globally (`npm install -g @aisuite/chub`) — optional but recommended; pipeline works without it via Context7 fallback
+- Requires `@aisuite/chub` installed globally (`npm install -g @aisuite/chub`) - optional but recommended; pipeline works without it via Context7 fallback
 
 ### Changed
 - All agent prompts (hunter, skeptic, fixer, doc-lookup) updated to use `doc-lookup.cjs` as primary with `context7-api.cjs` as explicit fallback
 - Preflight smoke test now checks `doc-lookup.cjs` first, falls back to `context7-api.cjs`
 - `run-bug-hunter.cjs` validates both scripts exist at startup
 
-## [2.3.0] — 2026-03-10
+## [2.3.0] - 2026-03-10
 
 ### Changed
-- `LOOP_MODE=true` is the new default — every `/bug-hunter` invocation iterates until full CRITICAL/HIGH coverage
+- `LOOP_MODE=true` is the new default - every `/bug-hunter` invocation iterates until full CRITICAL/HIGH coverage
 - `--loop` flag still accepted for backwards compatibility (no-op)
 - Updated triage warnings, coverage enforcement, and all documentation to reflect the new default
 
 ### Added
 - `--no-loop` flag to opt out and get single-pass behavior
 
-## [2.2.1] — 2026-03-10
+## [2.2.1] - 2026-03-10
 
 ### Fixed
 - `modes/loop.md`: added explicit `ralph_start` call instructions with correct `taskContent` and `maxIterations` parameters
@@ -131,16 +143,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changed completion signal from `<promise>DONE</promise>` to `<promise>COMPLETE</promise>` (correct ralph-loop API)
 - Each iteration now calls `ralph_done` to proceed instead of relying on a non-existent hook
 
-## [2.2.0] — 2026-03-10
+## [2.2.0] - 2026-03-10
 
 ### Added
 - Rollback timeout guard: `git revert` calls now timeout after 60 seconds; conflicts abort cleanly instead of hanging
 - Dynamic lock TTL: single-writer lock TTL scales with queue size (`max(1800, bugs * 600)`)
 - Lock heartbeat renewal: new `renew` command in `fix-lock.cjs`
-- Fixer context budget: `MAX_BUGS_PER_FIXER = 5` — large fix queues split into sequential batches
+- Fixer context budget: `MAX_BUGS_PER_FIXER = 5` - large fix queues split into sequential batches
 - Cross-file dependency ordering: when `code-index.cjs` is available, fixes are ordered by import graph
 - Flaky test detection: baseline tests run twice; non-deterministic failures excluded from revert decisions
-- Dynamic canary sizing: `max(1, min(3, ceil(eligible * 0.2)))` — canary group scales with queue size
+- Dynamic canary sizing: `max(1, min(3, ceil(eligible * 0.2)))` - canary group scales with queue size
 - Dry-run mode (`--dry-run`): preview planned fixes without editing files
 - Machine-readable fix report: `.bug-hunter/fix-report.json` for CI/CD gating, dashboards, and ticket automation
 - Circuit breaker: if >50% of fix attempts fail/revert (min 3 attempts), remaining fixes are halted
@@ -150,7 +162,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Per-bug revert granularity: clarified one-commit-per-bug as mandatory; reverts target individual bugs, not clusters
 - Post-fix re-scan severity floor: fixer-introduced bugs below MEDIUM severity are logged but don't trigger `FIXER_BUG` status
 
-## [2.1.0] — 2026-03-10
+## [2.1.0] - 2026-03-10
 
 ### Added
 - STRIDE/CWE fields in Hunter findings format, with CWE quick-reference mapping for security categories
@@ -164,14 +176,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - `dep-scan.cjs` lockfile-aware audits (`npm`, `pnpm`, `yarn`, `bun`) and non-zero audit exit handling so vulnerability exits are not misreported as scanner failures
 
-## [2.0.0] — 2026-03-10
+## [2.0.0] - 2026-03-10
 
 ### Changed
-- Triage moved to Step 1 (after arg parse) — was running before target resolved
-- All mode files consume triage JSON — riskMap, scanOrder, fileBudget flow downstream
-- Recon demoted to enrichment — no longer does file classification when triage exists
+- Triage moved to Step 1 (after arg parse) - was running before target resolved
+- All mode files consume triage JSON - riskMap, scanOrder, fileBudget flow downstream
+- Recon demoted to enrichment - no longer does file classification when triage exists
 - Mode files compressed: small 7.3→2.9KB, parallel 7.9→4.2KB, extended 7.1→3.3KB, scaled 7.3→2.7KB
-- Skip-file patterns consolidated — single authoritative list in SKILL.md
+- Skip-file patterns consolidated - single authoritative list in SKILL.md
 - Error handling table updated with correct step references
 - hunter.md: scope rules and security checklist compressed
 - recon.md: output format template and "What to map" sections compressed
@@ -181,23 +193,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - single-file.md: local-sequential backend support added
 
 ### Added
-- `modes/_dispatch.md` — shared dispatch patterns (18 references across modes)
+- `modes/_dispatch.md` - shared dispatch patterns (18 references across modes)
 
 ### Removed
-- Step 7.0 re-audit gate removed — duplicated Referee's work
+- Step 7.0 re-audit gate removed - duplicated Referee's work
 - FIX-PLAN.md deleted (26KB dead planning doc)
 - README.md compressed from 8.5KB to 3.7KB
 - code-index.cjs marked optional
 
-## [1.0.0] — 2026-03-10
+## [1.0.0] - 2026-03-10
 
 ### Added
-- `scripts/triage.cjs` — zero-token pre-recon triage, runs before any LLM agent (<2s for 2,000+ files)
+- `scripts/triage.cjs` - zero-token pre-recon triage, runs before any LLM agent (<2s for 2,000+ files)
 - FILE_BUDGET, strategy, and domain map decided by triage, not Recon
 - Writes `.bug-hunter/triage.json` with strategy, fileBudget, domains, riskMap, scanOrder
 - `local-sequential.md` with full phase-by-phase instructions
 - Subagent wrapper template in `templates/subagent-wrapper.md`
-- Coverage enforcement — partial audits produce explicit warnings
+- Coverage enforcement - partial audits produce explicit warnings
 - Large codebase strategy with domain-first tiered scanning
 
 [Unreleased]: https://github.com/codexstar69/bug-hunter/compare/v3.0.5...HEAD

package/SKILL.md

@@ -182,7 +182,7 @@ Before doing anything else, verify the environment:
    - Fallback probe order: `$HOME/.agents/skills/bug-hunter`, `$HOME/.claude/skills/bug-hunter`, `$HOME/.codex/skills/bug-hunter`.
    - Use this path for ALL Read tool calls and shell commands.
 
-2. **Verify skill files exist**: Run `ls "$SKILL_DIR/prompts/hunter.md"` via Bash. If this fails, stop and tell the user: "Bug Hunter skill files not found. Reinstall the skill and retry."
+2. **Verify skill files exist**: Run `ls "$SKILL_DIR/skills/hunter/SKILL.md"` via Bash. If this fails, stop and tell the user: "Bug Hunter skill files not found. Reinstall the skill and retry."
 
 3. **Node.js available**: Run `node --version` via Bash. If it fails, stop and tell the user: "Node.js is required for doc verification. Please install Node.js to continue."
 
@@ -346,7 +346,7 @@ If `THREAT_MODEL_MODE=true`:
    - If it exists but is >90 days old: warn user ("Threat model is N days old — regenerating"), regenerate.
    - If it doesn't exist: generate it.
 2. To generate:
-   - Read `$SKILL_DIR/prompts/threat-model.md`.
+   - Read `$SKILL_DIR/skills/threat-model-generation/SKILL.md`.
    - Dispatch the threat model generation agent (or execute locally if local-sequential).
    - Input: triage.json (if available) for file structure, or Glob-based discovery.
    - Wait for `.bug-hunter/threat-model.md` to be written.
@@ -388,13 +388,13 @@ If `.bug-hunter/dep-findings.json` exists with REACHABLE findings, include them
 |-------|-----------------|
 | PR security review | `skills/commit-security-scan/SKILL.md` (if `PR_SECURITY_MODE=true` or the user asks for PR-focused security review) |
 | Security review | `skills/security-review/SKILL.md` (if `SECURITY_REVIEW_MODE=true` or the user asks for an enterprise/full security audit) |
-| Threat Model (Step 1b) | `skills/threat-model-generation/SKILL.md` + `prompts/threat-model.md` (only if THREAT_MODEL_MODE=true) |
-| Recon (Step 4) | `prompts/recon.md` (skip for single-file mode) |
-| Hunters (Step 5) | `prompts/hunter.md` + `prompts/doc-lookup.md` + `prompts/examples/hunter-examples.md` |
+| Threat Model (Step 1b) | `skills/threat-model-generation/SKILL.md` (only if THREAT_MODEL_MODE=true) |
+| Recon (Step 4) | `skills/recon/SKILL.md` (skip for single-file mode) |
+| Hunters (Step 5) | `skills/hunter/SKILL.md` + `prompts/examples/hunter-examples.md` |
 | Security validation | `skills/vulnerability-validation/SKILL.md` (if `VALIDATE_SECURITY_MODE=true` or confirmed security findings need exploitability validation) |
-| Skeptics (Step 6) | `prompts/skeptic.md` + `prompts/doc-lookup.md` + `prompts/examples/skeptic-examples.md` |
-| Referee (Step 7) | `prompts/referee.md` |
-| Fixers (Phase 2) | `prompts/fixer.md` + `prompts/doc-lookup.md` (only if FIX_MODE=true) |
+| Skeptics (Step 6) | `skills/skeptic/SKILL.md` + `prompts/examples/skeptic-examples.md` |
+| Referee (Step 7) | `skills/referee/SKILL.md` |
+| Fixers (Phase 2) | `skills/fixer/SKILL.md` (only if FIX_MODE=true) |
 
 **Concrete examples for each backend:**
 
@@ -402,8 +402,8 @@ If `.bug-hunter/dep-findings.json` exists with REACHABLE findings, include them
 
 ```
 # Phase B — launching Hunter yourself
-# 1. Read the prompt file:
-read({ path: "$SKILL_DIR/prompts/hunter.md" })
+# 1. Read the skill file:
+read({ path: "$SKILL_DIR/skills/hunter/SKILL.md" })
 
 # 2. You now have the Hunter's full instructions. Execute them yourself:
 #    - Read each file in risk-map order using the Read tool
@@ -418,8 +418,8 @@ write({ path: ".bug-hunter/findings.json", content: "<your findings json>" })
 
 ```
 # Phase B — launching Hunter via subagent
-# 1. Read the prompt:
-read({ path: "$SKILL_DIR/prompts/hunter.md" })
+# 1. Read the skill:
+read({ path: "$SKILL_DIR/skills/hunter/SKILL.md" })
 # 2. Read the wrapper template:
 read({ path: "$SKILL_DIR/templates/subagent-wrapper.md" })
 # 3. Fill the template with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexstar/bug-hunter",
-  "version": "3.0.5",
+  "version": "3.0.7",
   "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",
   "main": "bin/bug-hunter",
@@ -30,16 +30,16 @@
     "static-analysis"
   ],
   "files": [
-    "agents/",
     "bin/",
     "scripts/",
     "schemas/",
     "prompts/",
     "templates/",
     "modes/",
-    "skills/",
     "evals/",
     "docs/",
+    "agents/",
+    "skills/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -57,6 +57,7 @@
     "access": "public"
   },
   "scripts": {
+    "prepublishOnly": "node scripts/prepublish-guard.cjs",
     "prepack": "node --test scripts/tests/*.test.cjs",
     "test": "node --test scripts/tests/*.test.cjs",
     "doctor": "node bin/bug-hunter doctor",

package/scripts/prepublish-guard.cjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * prepublish-guard.cjs
+ *
+ * Blocks `npm publish` unless:
+ *   1. Git working tree is clean (no uncommitted changes)
+ *   2. Current HEAD is pushed to origin (no unpushed commits)
+ *   3. package.json version matches the git tag (if tag exists)
+ *
+ * This prevents the "published to npm but forgot to commit/push" problem.
+ * Bypass with: SKIP_PREPUBLISH_GUARD=1 npm publish
+ */
+
+const { execSync } = require('child_process');
+
+if (process.env.SKIP_PREPUBLISH_GUARD === '1') {
+  console.log('⚠️  prepublish-guard: SKIPPED (SKIP_PREPUBLISH_GUARD=1)');
+  process.exit(0);
+}
+
+const run = (cmd) => execSync(cmd, { encoding: 'utf8' }).trim();
+
+const errors = [];
+
+// 1. Check for uncommitted changes
+try {
+  const status = run('git status --porcelain');
+  if (status) {
+    errors.push(
+      '❌ Uncommitted changes detected. Commit or stash before publishing.\n' +
+      status.split('\n').map(l => `   ${l}`).join('\n')
+    );
+  }
+} catch {
+  errors.push('❌ Not a git repository or git not available.');
+}
+
+// 2. Check for unpushed commits
+try {
+  const unpushed = run('git log --oneline origin/main..HEAD 2>/dev/null');
+  if (unpushed) {
+    errors.push(
+      '❌ Unpushed commits. Run `git push` before publishing.\n' +
+      unpushed.split('\n').map(l => `   ${l}`).join('\n')
+    );
+  }
+} catch {
+  // If origin/main doesn't exist, skip this check
+}
+
+// 3. Version/tag consistency check
+try {
+  const version = require('../package.json').version;
+  const tagExists = (() => {
+    try { run(`git rev-parse v${version} 2>/dev/null`); return true; } catch { return false; }
+  })();
+  if (tagExists) {
+    const tagCommit = run(`git rev-parse v${version}`);
+    const headCommit = run('git rev-parse HEAD');
+    if (tagCommit !== headCommit) {
+      errors.push(
+        `❌ Tag v${version} exists but points to a different commit.\n` +
+        `   Tag:  ${tagCommit.slice(0, 8)}\n` +
+        `   HEAD: ${headCommit.slice(0, 8)}\n` +
+        `   Bump the version or move the tag.`
+      );
+    }
+  }
+} catch {
+  // Non-fatal
+}
+
+if (errors.length > 0) {
+  console.error('\n🛑 prepublish-guard: publish blocked\n');
+  errors.forEach(e => console.error(e + '\n'));
+  console.error('Bypass with: SKIP_PREPUBLISH_GUARD=1 npm publish\n');
+  process.exit(1);
+}
+
+console.log('✅ prepublish-guard: clean tree, all pushed — safe to publish');

package/scripts/run-bug-hunter.cjs

@@ -132,7 +132,19 @@ function requiredScripts(skillDir) {
     path.join(skillDir, 'schemas', 'fix-plan.schema.json'),
     path.join(skillDir, 'schemas', 'fix-strategy.schema.json'),
     path.join(skillDir, 'schemas', 'recon.schema.json'),
-    path.join(skillDir, 'schemas', 'shared.schema.json')
+    path.join(skillDir, 'schemas', 'shared.schema.json'),
+    // Core agent skills (migrated from prompts/)
+    path.join(skillDir, 'skills', 'hunter', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'skeptic', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'referee', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'fixer', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'recon', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'doc-lookup', 'SKILL.md'),
+    // Security skills
+    path.join(skillDir, 'skills', 'threat-model-generation', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'commit-security-scan', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'security-review', 'SKILL.md'),
+    path.join(skillDir, 'skills', 'vulnerability-validation', 'SKILL.md')
   ];
 }
 
@@ -205,7 +217,8 @@ function sleep(ms) {
 
 function runCommandOnce({ command, timeoutMs }) {
   return new Promise((resolve) => {
-    const child = childProcess.spawn('/bin/zsh', ['-lc', command], {
+    const shell = process.env.SHELL || '/bin/bash';
+    const child = childProcess.spawn(shell, ['-lc', command], {
       stdio: ['ignore', 'pipe', 'pipe']
     });
     let stdout = '';

package/scripts/tests/run-bug-hunter.test.cjs

@@ -68,6 +68,21 @@ test('run-bug-hunter preflight tolerates missing optional code-index helper', ()
     );
   }
 
+  // Copy bundled skill SKILL.md files
+  const skillNames = [
+    'hunter', 'skeptic', 'referee', 'fixer', 'recon', 'doc-lookup',
+    'threat-model-generation', 'commit-security-scan', 'security-review',
+    'vulnerability-validation'
+  ];
+  for (const name of skillNames) {
+    const destDir = path.join(optionalSkillDir, 'skills', name);
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(
+      path.resolve(__dirname, '..', '..', 'skills', name, 'SKILL.md'),
+      path.join(destDir, 'SKILL.md')
+    );
+  }
+
   const result = runJson('node', [
     path.join(scriptsDir, 'run-bug-hunter.cjs'),
     'preflight',

package/scripts/tests/worktree-harvest.test.cjs

@@ -20,7 +20,7 @@ function makeGitFixture() {
   // Bare origin
   const origin = path.join(sandbox, 'origin.git');
   fs.mkdirSync(origin, { recursive: true });
-  execFileSync('git', ['init', '--bare'], { cwd: origin, stdio: 'ignore' });
+  execFileSync('git', ['init', '--bare', '-b', 'main'], { cwd: origin, stdio: 'ignore' });
 
   // Working clone
   const repo = path.join(sandbox, 'repo');

package/skills/README.md

@@ -1,19 +1,44 @@
-# Bundled Local Security Skills
+# Bundled Skills
 
-Bug Hunter ships with a local security pack under `skills/` so the repository stays portable and self-contained.
+Bug Hunter ships with all agent skills under `skills/` so the repository stays portable and self-contained.
 
-Included skills:
-- `commit-security-scan`
-- `security-review`
-- `threat-model-generation`
-- `vulnerability-validation`
+## Core Agent Skills
 
-## How They Connect to Bug Hunter
+These are the primary pipeline agents — migrated from `prompts/` to be first-class skills:
 
-These skills are part of the main Bug Hunter orchestration flow:
-- PR-focused security review routes into `commit-security-scan`
-- `--threat-model` routes into `threat-model-generation`
-- `--security-review` routes into `security-review`
-- `--validate-security` routes into `vulnerability-validation`
+| Skill | Purpose |
+|-------|---------|
+| `hunter/` | Deep behavioral code analysis — finds logic errors, security vulnerabilities, race conditions |
+| `skeptic/` | Adversarial code reviewer — challenges each finding to kill false positives |
+| `referee/` | Independent final arbiter — delivers verdicts with CVSS scoring and PoC generation |
+| `fixer/` | Surgical code repair — implements minimal, precise fixes for verified bugs |
+| `recon/` | Codebase reconnaissance — maps architecture, trust boundaries, and risk priorities |
+| `doc-lookup/` | Unified documentation access — Context Hub (chub) + Context7 API for framework verification |
 
-Bug Hunter remains the top-level orchestrator. These bundled skills provide focused security workflows and operate on Bug Hunter-native artifacts under `.bug-hunter/`.
+## Security Skills
+
+Specialized security workflows that integrate with the main Bug Hunter orchestration:
+
+| Skill | Purpose | Trigger |
+|-------|---------|---------|
+| `commit-security-scan/` | Diff-scoped PR/commit/staged security review | `--pr-security` |
+| `security-review/` | Full security workflow (threat model + code + deps + validation) | `--security-review` |
+| `threat-model-generation/` | STRIDE threat model bootstrap/refresh | `--threat-model` |
+| `vulnerability-validation/` | Exploitability/reachability/CVSS/PoC validation | `--validate-security` |
+
+## How They Connect
+
+Bug Hunter remains the top-level orchestrator (`SKILL.md`). The orchestrator reads agent skills at each pipeline phase:
+
+```
+Recon (skills/recon/)
+  → Hunter (skills/hunter/) + doc-lookup (skills/doc-lookup/)
+    → Skeptic (skills/skeptic/) + doc-lookup
+      → Referee (skills/referee/)
+        → Fix Strategy + Fix Plan
+          → Fixer (skills/fixer/) + doc-lookup
+```
+
+All doc-lookup calls use Context Hub (chub) as the primary documentation source with Context7 API as automatic fallback.
+
+All artifacts are written under `.bug-hunter/` using Bug Hunter-native conventions.

package/skills/doc-lookup/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: doc-lookup
+description: "Unified documentation lookup for Bug Hunter agents. Uses Context Hub (chub) as primary source with Context7 API fallback. Provides verified library/framework documentation to prevent false positives and ensure correct fix patterns."
+---
+
+# Doc Lookup — Verified Documentation Access
+
+## Documentation Lookup (Context Hub + Context7 fallback)
+
+When you need to verify a claim about how a library, framework, or API actually behaves — do NOT guess from training data. Look it up.
+
+### When to use this
+
+- "This framework includes X protection by default" — verify it
+- "This ORM parameterizes queries automatically" — verify it
+- "This function validates input" — verify it
+- "The docs say to do X" — verify it
+- Any claim about library behavior that affects your bug verdict
+
+### How to use it
+
+`SKILL_DIR` is injected by the orchestrator. Use it for all helper script paths.
+
+The lookup script tries **Context Hub (chub)** first for curated, versioned docs, then falls back to **Context7** when chub doesn't have the library.
+
+**Step 1: Search for the library**
+```bash
+node "$SKILL_DIR/scripts/doc-lookup.cjs" search "<library>" "<what you need to know>"
+```
+Example: `node "$SKILL_DIR/scripts/doc-lookup.cjs" search "prisma" "SQL injection parameterized queries"`
+
+This returns results from both sources with a `recommended_source` and `recommended_id`.
+
+**Step 2: Fetch documentation**
+```bash
+node "$SKILL_DIR/scripts/doc-lookup.cjs" get "<library-or-id>" "<specific question>"
+```
+Example: `node "$SKILL_DIR/scripts/doc-lookup.cjs" get "prisma/orm" "are raw queries parameterized by default"`
+
+This fetches curated docs from chub if available, otherwise Context7 documentation snippets with code examples.
+
+**Optional flags:**
+- `--lang js|py` — language variant (for chub docs with multiple languages)
+- `--source chub|context7` — force a specific source
+
+### Rules
+
+- Only look up docs when you have a SPECIFIC claim to verify. Do not speculatively fetch docs for every library in the codebase.
+- One lookup per claim. Don't chain 5 searches — pick the most impactful one.
+- If the API fails or returns nothing useful, say so explicitly: "Could not verify from docs — proceeding based on code analysis."
+- Cite what you found: "Per Express docs: [quote]" or "Prisma docs confirm that $queryRaw uses parameterized queries."