Pge harness

pge-harness

Overview

Run feature work as three file-coordinated agents with zero shared context: Planner -> Generator -> Evaluator. All coordination is through files on disk, never shared memory. Project specifics come ONLY from .harness/adapter.md; this skill is project-agnostic.

Core principle: the builder never grades its own work. A fresh, no-context Evaluator is the sole correctness authority. Human review fires only where a check is not machine-decidable.

When to use

• You have a planned batch of features to implement mostly autonomously on a branch.
• You want clean per-feature rollback (one green commit each) and fresh-eyes verification.
• Any project type - web, CLI, HTTP API, library - via the per-project adapter.

Default is fully autonomous. Human gates are opt-in (see below).

Three layers (what makes it portable)

• This skill (A) - the methodology. Invariant. Contains zero project specifics.
• .harness/adapter.md (B) - all project specifics, by field name. Written once per project (see references/bootstrap.md). Fields: BOOT/SMOKE, BUILD/SETUP, CODE TESTS, LIVE VERIFY, HUMAN-GATE, GUARDRAILS, STYLE, COMMITS. The LIVE VERIFY strategy is one of: web -> playwright-mcp, cli -> invoke+assert, http-api -> call, library -> unit-only.
• .harness/<goal>/spec.md (C) - per goal: feature list + intent ("what good looks like") + dependency graph + per-feature gate flag. High-level, NOT a test matrix. Template: references/spec-template.md.

This skill references the adapter only by field NAME. Example: "Start the app with BOOT/SMOKE; verify each feature with LIVE VERIFY + CODE TESTS; if HUMAN-GATE applies, write review.md and wait; commit per COMMITS."

The three agents

• Planner (human + assistant, a planning session). Produces a HIGH-LEVEL spec.md (and bootstraps the adapter on first use), then STOPS and hands off. Do NOT keep building in the planning session.
• Generator (a FRESH session - a NEW agent, separate from the Planner). Start it new so it carries ZERO planning context: it reads ONLY spec.md + the adapter, never the planning conversation. Then one continuous session, no resets: build one feature at a time; run only the trivial BOOT/SMOKE; make NO correctness judgment. Dispatch a FRESH Evaluator per feature, apply its findings, handle gates. Commit only on Evaluator-certified green, one feature per commit. Follow STYLE.
• Evaluator (a fresh no-context subagent per dispatch). The sole correctness authority. Brief: references/evaluator-rubric.md.

The loop (per feature)

Before the loop: create + checkout a dedicated branch, and pick a short <goal> slug for this run (e.g. phase3) - its coordination files live in .harness/<goal>/.

1. Build the feature in the working tree.
2. Run BOOT/SMOKE so you never hand rubble to the Evaluator. This is NOT a correctness call.
3. Dispatch a fresh Evaluator: a new subagent (Agent/Task tool, no inherited context) whose brief is references/evaluator-rubric.md + this feature's spec slice + the adapter. It writes findings.md.
4. Red? Read findings.md, fix, dispatch a NEW fresh Evaluator. Loop until green.
5. Human-gated? The Evaluator will have written its question to review.md instead of passing it. Handle it per Human gate protocol (below).
6. Green + signed off -> commit. Update progress.html.
7. Next feature.

End of run: one holistic Evaluator pass (2-3 passes) across the whole change for cross-feature regressions; findings -> fix -> re-verify.

Dependency-aware human gates

Gates are opt-in - default is fully autonomous. Two controls: the adapter's HUMAN-GATE says HOW a human observes this project's output (and none = no judgable surface, so every feature runs auto regardless of its flag); the per-feature gate: auto | human-gated in spec.md decides WHICH features gate. Gating is independent of depends-on (a feature may be gated with no deps, or have deps with no gate).

Protocol. When the Evaluator hits a check it cannot decide, IT writes the question into review.md with a blank VERDICT: line (it never guesses). Then:

• Attended: pause, ask the human, apply their verdict.
• Unattended: park this feature and anything that depends-on it; keep building independent features; leave the open review.md question + an amber badge in progress.html. When the human fills each VERDICT:, do a follow-up pass to apply it, re-verify, and commit.

"Block" = do not START a feature until every feature in its depends-on is green + committed and any upstream gate is signed. Commit a gated feature only after its verdict is in. Fully idle only if everything left is behind a pending gate.

File contracts (all on disk, under .harness/<goal>/)

File	Direction	Content
spec.md	Planner -> Generator	high-level features + intent + dependency graph + gate flags
repo + git	Generator	one green commit per feature, on a dedicated branch
findings.md	Evaluator -> Generator	pass/fail + evidence + repro
review.md	Evaluator <-> human	judgment questions + verdicts
progress.html	-> human	per-feature log (template: references/progress-template.html)

Code is edited in-place in the existing repo (not a fresh app/ dir).

Guardrails (categories; specifics from the adapter's GUARDRAILS)

• Local only - never push/merge/deploy unless the goal says so.
• Isolate and clean up test data; leave the workspace as found.
• Restart the app after edits to cached assets before testing.
• Scope process kills to the dev-server PID/port.
• Commit hygiene per COMMITS; never commit .harness/ artifacts.

New project? Bootstrap once

First use in a repo: detect the stack and draft .harness/adapter.md, then confirm with the human. See references/bootstrap.md. After that, every future goal in the project reuses the adapter.

Common mistakes

• Generator grading its own work - the smoke is NOT a correctness check; only the Evaluator certifies.
• Pre-writing exhaustive edge cases in spec.md - keep it high-level; the Evaluator derives them.
• Reusing the same Evaluator subagent - each dispatch must be fresh, no context.
• Running the Generator in the planning session - it then drags the planning context along (defeats zero shared context). Sequence: plan -> write spec.md -> start a NEW session for the build.
• Blocking on a gate nothing depends on - defer it and keep building.
• Putting project specifics in this skill - they belong in the adapter.