| # 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-<id>/`. |
| - 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-<id>/` 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-<id>/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-<id>/AGENT_FINDINGS.md` |
| - `artifacts/issue-<id>/ARCHITECTURE_MAP.md` |
| - `artifacts/issue-<id>/RISK_REGISTER.md` |
| - `artifacts/issue-<id>/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-<id>/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-<id>/AGENT_REVIEW.md` |
| - `artifacts/issue-<id>/RISK_REGISTER.md` |
| - `artifacts/issue-<id>/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-<id>/CONSOLIDATION_DECISION.md` |
| - `artifacts/issue-<id>/KEEP_ADOPT_ARCHIVE.md` |
| - `artifacts/issue-<id>/MINIMAL_TARGET_ARCHITECTURE.md` |
| - `artifacts/issue-<id>/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`. |
|
|
