hacker-bob: Instructions file for Claude Code

Hacker Bob Repo Instructions

This repository is the install source for the Hacker Bob /bob-evaluate Claude Code framework.

If a user asks you to install this framework into a project:

1. Clone this repo locally.
2. Run ./install.sh /absolute/path/to/target/project from the cloned repo.
3. The installer copies the skills, update command shim, agents, rules, hooks, knowledge, bypass tables, MCP runtime, and generated settings. It merges .mcp.json and .claude/settings.json instead of overwriting unrelated config.
4. After install, run Claude Code from the target project and use /bob-evaluate <target> (slash command) or the bob-evaluate skill.

Do not assume this cloned repo is the user's active workspace unless they explicitly want that.

Each installed workspace gets its OWN session root — ~/hacker-bob-sessions-<workspace>-<hash>, derived from the workspace path (stable across re-installs) and written as BOB_SESSIONS_ROOT into that workspace's .mcp.json server env and .claude/settings.json env. Bob elects one engine per session root, so concurrent engines in two workspaces require DISJOINT roots; the root is operator configuration read once at engine boot and frozen there, and no agent or MCP tool can change it. A workspace that was already installed and still has sessions in the shared ~/hacker-bob-sessions/ keeps using it rather than orphaning them — migrate with mv ~/hacker-bob-sessions/<target-domain> ~/hacker-bob-sessions-<workspace>-<hash>/ (the installer prints the exact path) and re-run the installer. Operator caution: disjoint roots make concurrent ENGINES safe, not concurrent evaluations of the SAME target — rate limits, circuit breakers, and request budgets are per-engine, so two engines on one target double the request volume it sees and neither one knows it.

If the user is developing this framework itself and wants to test changes in a local Claude Code workspace:

1. Use ./dev-sync.sh /absolute/path/to/test-workspace from this repo.
2. This script backs up the target .mcp.json and .claude/settings.json, runs the installer, recopies repo-backed MCP files including mcp/tools/*.js, re-merges the dev config, and runs claude mcp list unless --no-health-check is supplied.
3. It is intended for a dedicated local test workspace because it overwrites Bob-owned runtime files after backing up the target MCP/settings files.
4. After dev-sync.sh, fully restart Claude Code in the test workspace, run /mcp, and smoke test bob_http_scan with target_domain: "example.com" against https://example.com.

Maintainer workflow:

• Run npm test before handing off changes. Useful focused commands are npm run test:mcp, npm run test:prompts, npm run test:install, and npm run check:syntax.
• Generated prompt/config surfaces must stay current. Run node scripts/generate-agent-tools.js after role-bundle metadata changes and node scripts/generate-hacker-bob-skill.js after orchestrator/auth bundle changes.
• TOOLS, MCP dispatch, role-bundle permissions, agent tool frontmatter, skill allowed-tools, Claude settings, and scope-hook registration must remain registry-driven.
• Correctness-vocabulary tags (S*, I*, C*, X., Y-P, Y-D*, Y-R*) are registry-driven via mcp/core/invariant-registry.js. Every tag in the tree must resolve to a REGISTRY entry (or the frozen, only-shrinking ALLOWLIST_UNDOCUMENTED backlog), and every entry's enforced_by file:symbol must exist. The collision-prone S/C/I families are matched only in anchored comment form (// I6), so a tag's enforcing anchor MUST be a comment. npm run check:invariant-registry (in test:prompts) is the orphan-check. Adding a tag means adding its entry AND anchoring the tag at the enforcing site.
• Lifecycle hooks enforce contracts only. Evaluator SubagentStop validates the final marker and structured handoff but must not advance pending_wave, evaluation_wave, explored, findings summaries, or phase state.
• Markdown mirrors are human/debug artifacts. Chain evidence is MCP-owned in chain-attempts.jsonl; report.md remains the final human-facing agent-composed (via bob_compose_report) report.
• Audit-graded session paths are MCP-rendered (Y-P13). mcp/core/io/paths.js exports AUDIT_GRADED_PATHS (positive list — report.md, chains.md, evidence-packs.md, grade.md, verification-round mirrors, wave-handoff mirrors, claim-freeze snapshots, and the hash-bound JSONL ledgers) and the isAuditGradedPath(absolutePath, target_domain) predicate. Agents never call the Write tool on these paths; structured composition flows through bob_compose_report (Y-D15b), bob_write_chain_rollup (Y-D15c), bob_amend_report (Y-P13a operator-amendment path), bob_write_evidence_packs, bob_write_grade_verdict, bob_write_verification_round, and bob_write_wave_handoff. Scratch artifacts (subdomains.txt, attack_surface.json, family_seeds.txt, surface-discovery-tools.txt) are explicitly NOT in AUDIT_GRADED_PATHS and remain agent-writable.
• Evaluator briefs must stay bounded: array counts are capped, scalar strings are capped or omitted, and agents should use auth through bob_list_auth_profiles rather than reading secret files directly.