Hugging Face's logo

smlflg
/
ACT-agentcommandotower

Model card Files
xet
 Community
ACT-agentcommandotower / docs /GH_TOKEN_FURNACE_HARNESS.md
smlflg's picture
smlflg
Initial public upload from Projekte/ACT-agentcommandotower
a2be137 verified
preview code
|
Raw History Blame Contribute Delete
6.29 kB

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 

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:

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.