# Pge Harness

> Use when implementing a planned batch of features (two or more) mostly autonomously on a branch - overnight or attended - in any project (web, CLI, API, or library), where each feature is independently verified before its own commit and the human is pulled in only for checks a machine cannot decide. Use this whenever someone wants to build several features and verify each, run an unattended or overnight build, knock out a multi-feature goal or spec one feature at a time, have a fresh agent QA every feature before commit, or points at a .harness/ adapter or spec.md - even if they never say "harness". Not for a single edit or bugfix, a one-page build, writing a plan, brainstorming, or reviewing an existing diff.

- Skill: `valeera-s/pge-harness` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add valeera-s/pge-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/valeera-s/pge-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Valeera-S (https://skillmd.com/u/valeera-s)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/valeera-s/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.