Skip to content
Skills Library
AI & agents · Automation

contract-conformance-loop

/contract-conformance-loop

Drive an implementation until EVERY criterion of an authored contract holds — a Plan-Generate-Evaluate (PGE / GAN-style) loop where the builder implements toward one not-yet-passing criterion and a FRESH-CONTEXT evaluator subagent (contract-auditor, spawned with no Write/Edit tools, default-FAIL) grades all criteria against evidence and never lets the builder self-grade. This is the loop form of the contract-author / contract-auditor pair. Use when a contract or acceptance-criteria spec exists and an implementation must be built or verified against it. Trigger on "build until the contract pass

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Drive an implementation until EVERY criterion of an authored contract holds — a Plan-Generate-Evaluate (PGE / GAN-style) loop where the builder implements toward one not-yet-passing criterion and a FRESH-CONTEXT evaluator subagent (contract-auditor, spawned with no Write/Edit tools, default-FAIL) grades all criteria against evidence and never lets the builder self-grade. This is the loop form of the contract-author / contract-auditor pair. Use when a contract or acceptance-criteria spec exists and an implementation must be built or verified against it. Trigger on "build until the contract pass

Original author description

Drive an implementation until EVERY criterion of an authored contract holds — a Plan-Generate-Evaluate (PGE / GAN-style) loop where the builder implements toward one not-yet-passing criterion and a FRESH-CONTEXT evaluator subagent (contract-auditor, spawned with no Write/Edit tools, default-FAIL) grades all criteria against evidence and never lets the builder self-grade. This is the loop form of the contract-author / contract-auditor pair. Use when a contract or acceptance-criteria spec exists and an implementation must be built or verified against it. Trigger on "build until the contract pass

How it works

  1. The 5-part contract
  2. The proof: a fresh evaluator's verdict, default-FAIL
  3. Step 1 — Build the default-FAIL criteria JSON
  4. Step 2 — Generator: implement toward ONE failing criterion
  5. Step 3 — Evaluator: grade ALL criteria from fresh context
  6. Step 4 — Feed failures back, checkpoint, repeat
  7. Guardrails specific to this loop
  8. Choosing the driver primitive
  9. Using it under the orchestrator
  10. How this differs from its neighbors
Original SKILL.md headings · 162 lines, 1,405 words
SKILL.md preview
---
name: contract-conformance-loop
version: 1.0.0
description: >-
  Drive an implementation until EVERY criterion of an authored contract holds —
  a Plan-Generate-Evaluate (PGE / GAN-style) loop where the builder implements
  toward one not-yet-passing criterion and a FRESH-CONTEXT evaluator subagent
  (contract-auditor, spawned with no Write/Edit tools, default-FAIL) grades all
  criteria against evidence and never lets the builder self-grade. This is the
  loop form of the contract-author / contract-auditor pair. Use when a contract
  or acceptance-criteria spec exists and an implementation must be built or
  verified against it. Trigger on "build until the contract passes", "implement
  the spec until all criteria hold", "conform to the contract", "drive this to
  spec", "make the implementation match the contract", "loop until acceptance
  criteria pass", "build-until-spec", "PGE loop", "evaluate against the
  contract", "/contract-conformance-loop". A configuration of loop-controller.
requires_claude_code: true
min_plan: starter
disable-model-invocation: true
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Agent"]
composes_with: ["loop-controller", "contract-author", "contract-auditor", "orchestrator", "fix-until-green"]
spawned_by: ["orchestrator"]
---

# contract-conformance-loop

> **A configuration of [`loop-controller`].** That skill supplies the loop
> machinery — primitive selection, the full guardrail stack, state
> externalization. This skill supplies the two things specific to
> "build until the spec holds": a **fresh-context evaluator** as the proof
> (the [`contract-auditor`] graded against an authored contract, default-FAIL)
> and the **generator/evaluator split** that keeps the builder from grading its
> own work. Read `loop-controller` for the guardrails; they're inherited, not
> repeated here.
>
> **Why `disable-model-invocation`:** this loop edits and commits code on its
> own and spends tokens spawning an evaluator subagent each round, until every
> contract criterion passes. You want to *type* `/contract-conformance-loop` (or
> have the orchestrator dispatch it) — not have Claude silently start an
> autonomous build loop because a contract happened to exist.

## The 5-part contract

| Part | This loop |
|---|---|
| **trigger** | an authored contract exists ([`contract-author`] output in `contracts/`) plus an implementation to build or verify against it, or an explicit `/contract-conformance-loop` (optionally scoped to one contract) |
| **action** | ONE iteration: the **generator** (the builder / role agent) implements or fixes toward **one** not-yet-passing criterion → a **fresh-context evaluator subagent** ([`contract-auditor`], spawned with **no Write/Edit**) checks **ALL** criteria against evidence and returns a default-FAIL verdict with per-criterion pass/fail + feedback → failing criteria + feedback feed the next iteration |
| **proof** | every entry in the criteria JSON has passing **evidence confirmed by the fresh-context evaluator** (not the builder) — default-FAIL: each criterion starts `"passed": false` and only the evaluator's verdict, citing evidence, flips it |
| **memory** | `criteria.json` (the default-FAIL criteria, one entry per contract criterion), `PROGRESS.md` (what's done / next), a git checkpoint per criterion turned green |
| **stop** | the evaluator confirms **all** criteria pass **OR** iteration cap **OR** no-progress for 3 rounds **OR** budget cap |

## The proof: a fresh evaluator's verdict, default-FAIL

"Done" is **not** "the builder thinks the feature is built." It is **every
criterion in `criteria.json` flipped to `"passed": true` by the fresh-context
evaluator, each citing concrete evidence** — and re-confirmed against the *whole*
criteria set on the final round, not just the criterion last touched.

Two rules make this convergent rather than a rubber-stamp:

- **The grader is not the doer.** The builder is a pathological optimist about
  its own work; a same-context critic approves mediocre output. The evaluator is
  a *fresh* subagent that sees only the artifact + the contract, never the build
  reasoning. This is the PGE / GAN pattern from `loop-controller` Step 2.
- **The evaluator cannot edit.** It is spawned with **no Write/Edit tools** — so
  it can only *report* a failure, never "fix" one by quietly lowering the bar. It
  inspects (Read / Grep / Bash-to-run-tests) and returns a verdict.

This maps onto the existing pair: [`contract-author`] writes the spec the loop
builds against; [`contract-auditor`] **is** the evaluator. This loop does not
re-implement either — it sequences them in a bounded, default-FAIL loop. The full
generator/evaluator split, the `criteria.json` schema, and the evaluator dispatch
prompt are in [`references/pge-loop.md`](references/pge-loop.md).

## Step 1 — Build the default-FAIL criteria JSON

Read the authored contract from `contracts/` (the [`contract-author`] output:
`openapi.yaml`, `data-layer.yaml`, `types.<ext>`, and the Domain Rules in
`contracts/README.md`). Decompose it into **one testable criterion per checkable
fact** and write each as a JSON entry with `"passed": false`. Store it at the
profile-defined path (default `criteria.json`). A criterion the evaluator cannot
check against evidence is not a criterion — split it until it is. Schema and a
worked example: [`references/pge-loop.md`](references/pge-loop.md).

## Step 2 — Generator: implement toward ONE failing criterion

Pick the highest-leverage `"passed": false` criterion and have the builder
implement or fix **just that one**. One criterion per iteration — don't batch
features; batching destroys the signal about which change moved which criterion
(`loop-controller` Step 5). Update `PROGRESS.md` with what was attempted.

## Step 3 — Evaluator: grade ALL criteria from fresh context

Spawn the evaluator subagent ([`contract-auditor`]) **fresh, with no Write/Edit
tools**, blind to the builder's reasoning. Hand it only the contract + the
implementation + `criteria.json`. It re-checks **every** criterion against
evidence (re-verify the whole, not just the one touched — `loop-controller`
Step 5) and returns the criteria JSON with each entry either still `false` (plus
feedback) or flipped to `true` (plus the evidence that flipped it). The builder
never edits `criteria.json`; only the evaluator's verdict does.

## Step 4 — Feed failures back, checkpoint, repeat

Merge the evaluator's verdict into `criteria.json`. On a green-ward round (a
criterion newly `true`, nothing regressed), **commit a checkpoint** naming the
criterion satisfied — the git trail is the loop's undo and post-mortem. Feed the
still-failing criteria + their feedback into the next generator pass. When the
evaluator confirms **all** criteria pass on a single whole-set re-check, the loop
is done; report the final `criteria.json` as evidence.

## Guardrails specific to this loop

Inherits the full stack from `loop-controller` → `references/safety.md`. The
caps this loop sets:

- **Iteration cap** — default ~10–15 build/evaluate rounds (read from
  `.claude/profile.yaml` if set). Hitting the cap is a *stop-and-escalate*, not a
  license to weaken the contract or have the builder self-pass a criterion.
- **No-progress detection** — if **the same set of criteria stays `false`** for
  **3 consecutive rounds**, stop and escalate. Three rounds with the criterion
  count unchanged means the approach is wrong, or the criterion is ambiguous —
  surface it (it may be a contract gap, which [`contract-auditor`] flags rather
  than failing the implementation against).
- **Budget cap** — the evaluator subagent costs a full fresh context **per
  round**; a long run is materially more expensive than a self-graded loop.
  Watch `/cost`; terminate at the ceiling, don't just warn.
- **Never let the builder grade itself.** Forbidden, and each is a *finding*:
  the builder flipping a `criteria.json` entry to `true`, softening a criterion,
  or the evaluator being reused with the builder's context (it must be fresh and
  Write/Edit-free). A green that the builder wrote is not proof — only the
  evaluator's verdict is.
- **HITL before irreversible.** If satisfying a criterion would touch something
  irreversible (a migration against a real DB, an external API), that's an HITL
  checkpoint — pause for the human (`loop-controller` guardrail 4).

## Choosing the driver primitive

The canonical form is **a skill orchestrating a generator + an evaluator
subagent** — the evaluator subagent *is* the proof, so this loop always spawns it
(hence `Agent` in `allowed-tools`). Per `loop-controller` Step 1:

- **Canonical — generator + fresh-context evaluator subagent.** Use whenever any
  criterion is subjective or needs cross-file judgment (does the implementation
  *import* the shared types, do the domain rules actually hold). The evaluator's
  default-FAIL verdict is the stop signal.
- **`/goal` may substitute** *only* when **every** criterion is fully provable
  from command output (e.g. a contract reduced entirely to a test suite +
  schema-validation exit codes). Then `/goal "every criterion in criteria.json is
  passed:true, confirmed by the contract's own checks — or stop after N turns"`,
  and the loop degenerates toward [`fix-until-green`]. The moment a criterion
  needs judgment, fall back to the fresh evaluator.

## Using it under the orchestrator

This is the **build-until-spec inner loop** (archetype 2). The orchestrator
authors the contract via [`contract-author`] (its Phase 4), then dispatches this
loop with the builder role as generator and [`contract-auditor`] as the
evaluator. The orchestrator does **not** override a stuck loop — if the loop
escalates after no-progress, that's a real conformance blocker or a contract gap,
not a number to paper over. A satisfied `criteria.json` informs the build; the
`qe-agent`'s `qa-report.json` still decides the gate (`loop-controller`'s rule:
the loop informs, the gate decides).

## How this differs from its neighbors

- **vs. [`contract-auditor`]** — the auditor is a *one-shot* static audit that
  reports mismatches. This is the bounded *iterative* loop that drives them to
  zero, wrapping the auditor as its default-FAIL evaluator harness.
- **vs. [`fix-until-green`]** — that loop's proof is three exit codes; this
  loop's proof is per-criterion contract evidence graded by a *fresh evaluator*.
  Use fix-until-green when "done" is the test suite; use this when "done" is "the
  contract's criteria all hold," some of which no single exit code can prove.

## Reference files

- [`references/pge-loop.md`](references/pge-loop.md) — the generator/evaluator
  split in full, the `criteria.json` default-FAIL schema with a concrete JSON
  example, and the fresh-context evaluator dispatch (no Write/Edit, blind to the
  build reasoning, returns a per-criterion verdict).

[`loop-controller`]: ../loop-controller/SKILL.md
[`fix-until-green`]: ../fix-until-green/SKILL.md
[`contract-author`]: ../../contracts/contract-author/SKILL.md
[`contract-auditor`]: ../../contracts/contract-auditor/SKILL.md
Files in this package (2)
  • SKILL.md 11 KB
  • references/pge-loop.md 8 KB

Versions

The database has no other skills named contract-conformance-loop.

Database snapshot: 13.11.2026 · package version 102209fb21ef (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 82subagent-contract
    MUST activate when you ARE a subagent — you were spawned by an orchestrator, you received a delegated task, you are executing within a subagent context. Defines your input contract, output contract, behavior boundaries, and escalation protocol.
  • 90black-box-test
    Use as an INDEPENDENT tester agent to test another agent's `in_testing` ticket from the OUTSIDE — never your own, and never from the implementation diff. You test from the operational test contract + acceptance criteria only (never HOW it was built), writing one automated test…
  • 90goal-loop
    Run a task as a goal loop. Write a contract (goals, exit criteria, checks, budget), work, verify with an independent agent, repeat on FAIL until PASS or budget. Use for "goal loop", "verify until done", or exit criteria plus a verifier.
  • 100execute-plan
    Execute a structured implementation plan produced by /make-plan, delegating implementation to a subagent and iterating with an independent review subagent until quality criteria are met. Args: [plan] [step-scope IDs…]. Use when the user asks to execute a plan or mentions /execute-plan.
  • 100st-plan-loop
    Write a numbered plan with an acceptance check for each step, critique it once in a fresh pass, revise it, then execute one step at a time. Use when a task touches more than one file, has unclear scope, or failed before because steps were missed. Invoke as /st-plan-loop.
  • 10002-implement
    Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.