Keeping control of your AI-driven process

PDCA Harness turns each AI-driven contribution into one Plan → Do → Check → Act cycle. A deterministic driver does the work; a human stays at the three touch points that matter — authoring the spec, signing off the check, and improving the process.

PDCA — Plan, Do, Check, Act: the improvement loop from quality control, applied one contribution at a time.

Read the walkthrough Read the model spec Get it on GitHub

What it is

A prepared harness, not tribal knowledge.

An AI model can write a plausible fix for almost any issue in seconds — which is exactly the danger. A plausible diff is not a verified one, and at volume the maintainer becomes both the bottleneck and the only safety net. PDCA Harness funnels AI-generated contributions through a quality cycle so each one arrives scoped, proven, and ready to sign off.

Render the Copier template into a new project, concretize it to your tracker / branches / gates once, and a deterministic driver advances every contribution through a file-derived state machine — stopping only where a human is irreducible.

How it works

One contribution, one cycle.

PLAN      ◆  author the brief — the spec every beat is measured against
  │
  ▼
DO           a headless builder writes the patch + a red→green test
  │
  ▼
CHECK        deterministic gates (red→green) + a decorrelated reviewer
  │
  ▼
SIGN-OFF  ◆  the human verdict — accept · iterate · discontinue
  │
  ▼
PUBLISH      a draft PR — the harness never marks it ready
  ┊
ACT       ◆  every N cycles: recurring misses → new gates · rules · fields
  └──▶ back to a better-baselined PLAN

◆  one of the three human touch points — everything else is automated

PlanAuthor the brief. A precise, field-structured spec every later beat is measured against.
DoBuild against the spec. A headless builder writes the patch, a shipped test, and its rationale — and can't open a PR.
CheckVerify it. Deterministic gates (red→green), a decorrelated reviewer, and a 5/5/1 verdict assembled into one SUMMARY.
Sign-offThe human verdict. Accept, iterate-do, iterate-plan, or discontinue — accept is refused while anything is unresolved.
ActImprove the process. Across cycles, recurring misses become new gates, brief fields, and rules — a better baseline every time.

Key features

Built for a backlog, not a single fix.

Parallel processingMany issues at once. The unattended Do + Check band fans across a pool of lane workers, each with its own git worktree and $PDCA_LANE slot — while Plan, sign-off, and Act stay serial, so the human touch points never fork.
Dependency resolutionOrder computed, not hand-run. Declare Depends on: / Conflicts with: and the scheduler levels the batch deterministically — conflicting bundles split into different waves, and an unschedulable graph (a cycle, an unknown prereq) is rejected before any build.
Dependency wavesA whole chain in one run. Each wave's accepted work is folded onto a run-scoped integration branch the next wave builds on, so a B-needs-A batch lands as a reviewable PR stack — push-only and fork-safe; the harness never merges for you. pdca waves previews the plan.
Per-issue model selectionThe right backend per fix. Route a bundle's builder by a brief field (Difficulty: high → a frontier model) or pin it explicitly (Do model: keeps a sensitive fix local). Issues in one wave can run on different models; a repeatedly-failing one escalates.
Structured verificationCorrectness, not vibes — the 5/5/1. Deterministic gates (a red→green proof, the only thing allowed to block — no LLM in the gating path), a decorrelated reviewer, and the irreducibly human judgments, assembled into one SUMMARY with an explicit NEEDS-HUMAN checklist.

Why it holds up

Correctness as the headline, not a vibe.

The one thing allowed to block a sign-off is a deterministic, LLM-free check: a test that is red before the fix and green after it. Everything a gate can't adjudicate — an ambiguous-scope lint, an environmental failure, the irreducibly human judgments — surfaces as an explicit checklist for a person, never silently passed or silently blocked.

State lives in files, so the driver is idempotent and resumable; one planning session can brief several issues that build unattended and queue for a fast, cheap-first sign-off. And a full cycle rehearses entirely offline — stub models, stub gates — so you can learn it and prove the plumbing before spending a token.

See it for real

A worked example, end to end.

The walkthrough drives one real contribution — a fix to the Gramps genealogy project — through every beat: the actual brief, the actual patch, the gate table, the §6 checklist, a two-iteration sign-off, and the Act entry that turned a maintainer's review comment into a new gate. Plan → Do → Check → Act, on a live codebase.