# GH Token Furnace Harness The GH Token Furnace Harness is an issue-based trust harness for agentic work. Its job is to convert uncertainty into reviewable artifacts without giving agents open-ended product ownership. > Agents may spend many tokens reading, analyzing, testing, comparing, and documenting, but changes must stay minimal, scoped, and reviewable. ## Core Flow Every run follows the same contract: 1. Issue 2. Dedicated branch 3. Required artifacts 4. Tests or verifier output 5. Pull request 6. Human review Agents must not work directly on `main` or `master`. ## Best Token-Burn Jobs Use the harness for work that benefits from deep inspection but has limited mutation risk: - Architecture audit - Test generation for existing behavior - Bug and risk inventory - PR or diff review - Repository consolidation decision - Verifier or CI script creation - Documentation of current reality Avoid broad prompts such as `build the product further`. Prefer concrete contracts such as `read-only architecture audit`, `tests for module X without behavior changes`, or `minimal verifier for repository health`. ## Operating Rules - Work issue-based. - Create or use a dedicated branch. - No changes on `main` or `master`. - No large rewrites. - No new features without explicit issue scope. - No new dependencies without rationale and an alternative considered. - No architecture changes without a decision log. - If uncertain, document instead of improvising. - Stop when scope expansion is detected. - Treat `tower.yaml`, `focus.md`, `decisions.md`, and `runs/` as human-owned operator state unless the issue explicitly scopes them. - Store run artifacts under `artifacts/issue-/`. - Run `bash scripts/verify.sh` before opening a PR and after each scoped change set. ## Required End Artifacts Every agent run must leave enough context in `artifacts/issue-/` for the repo owner to understand the result in five minutes: - `AGENT_RESULT.md` - Diff summary - Test or verifier result - Open risks - Concrete next issues Audit jobs should also produce `AGENT_FINDINGS.md`. Test jobs should also produce `AGENT_TEST_PLAN.md`. ## Master Prompt ```text You are working in a GitHub repository under the GH Token Furnace Harness. Your goal is NOT to write as much code as possible. Your goal is to convert existing uncertainty into verifiable artifacts. Working mode: - Work issue-based. - Create or use your own branch. - Do not change main/master. - Do not perform large rewrites. - Do not add new features outside the explicit issue scope. - Do not add new dependencies without rationale and an alternative. - Do not make architecture changes without a decision log. - If uncertain: document, do not improvise. Required artifacts at the end: 1. `artifacts/issue-/AGENT_RESULT.md` 2. Diff Summary inside the artifact directory 3. Test/verifier result inside the artifact directory 4. Open risks inside the artifact directory 5. Concrete next issues inside the artifact directory You may read, analyze, test, and compare extensively. You may make small, safe changes when they directly match the issue. You must stop once you detect scope expansion. Success criterion: The repo owner can understand within five minutes: - What you found - What you changed - Why it was safe - How to verify it - What should happen next ``` ## Phase 1 Scope This bootstrap phase defines the contract and verification path for ACT itself. - Do not extend `tower.py` with GitHub integration as part of the harness bootstrap. - Prefer documentation, templates, verifier scripts, and tests before CLI feature work. - If a later issue needs CLI changes, keep them isolated and explicitly scoped. ## Job Catalog ### READ_ONLY_AUDIT Goal: understand architecture, entry points, core modules, data flows, unclear areas, production readiness, experiments, dead or duplicated code, scope-creep risks, and the five highest-value next issues. Required artifacts: - `artifacts/issue-/AGENT_FINDINGS.md` - `artifacts/issue-/ARCHITECTURE_MAP.md` - `artifacts/issue-/RISK_REGISTER.md` - `artifacts/issue-/NEXT_ISSUES.md` ### TEST_GENERATION Goal: add tests for existing behavior without changing behavior. Rules: - No feature changes. - No business logic changes unless a test exposes a confirmed bug. - For a bug, document the failing test first, then propose the minimal fix. Required artifacts: - `artifacts/issue-/AGENT_TEST_PLAN.md` - New tests - Untestable areas list - PR with test output ### VERIFIER_SCRIPT Goal: create one command that checks repository health. Default command for ACT: `bash scripts/verify.sh`. Allowed files: - `scripts/verify.sh` - `scripts/verify.py` - README usage note Rules: - No new CI platform. - No large tooling framework. - No dependency if shell or Python standard library is enough. ### PR_REVIEW Goal: perform adversarial review of a diff without changing code. Required artifacts: - `artifacts/issue-/AGENT_REVIEW.md` - `artifacts/issue-/RISK_REGISTER.md` - `artifacts/issue-/PRIORITIZED_FIXES.md` - Ten concrete GitHub issue suggestions Evaluate each risk by impact, likelihood, repair cost, and whether an agent may safely fix it. ### CONSOLIDATION_DECISION Goal: decide what to keep, adopt, or archive across related repositories. Do not refactor during this job. Required artifacts: - `artifacts/issue-/CONSOLIDATION_DECISION.md` - `artifacts/issue-/KEEP_ADOPT_ARCHIVE.md` - `artifacts/issue-/MINIMAL_TARGET_ARCHITECTURE.md` - `artifacts/issue-/MIGRATION_ISSUES.md` Answer: - What is the anchor repository? - What gets adopted? - What gets archived? - What must not be merged together? - What is the smallest real next step? ## Labels Create these labels with `scripts/ensure-agent-labels.sh`: ```text agent:read-only agent:test-generation agent:small-fix agent:review agent:docs agent:decision agent:needs-human agent:safe agent:risky agent:blocked ``` ## Suggested First Four Runs 1. Agent A: read-only architecture audit 2. Agent B: test generation for core modules 3. Agent C: adversarial review and risk register 4. Agent D: consolidation decision and next issues After those runs, use a reviewer agent to combine the artifacts into `OWNER_DECISION.md`.