Krystal Loop Protocol

Use fast AI agents for the grunt work. Use a lead agent and real checks to keep the project coherent, working, and under your control.

AI coding agents can produce a lot of code quickly. The harder problem begins after the first impressive demo: agents lose context, overlap each other's changes, trust confident summaries, reopen solved problems, and quietly break features that worked yesterday.

Krystal Loop Protocol (KLP) is a practical operating pattern for continuing to build with multiple AI agents without handing them control of the project.

The 90-Second Version

1. Scope it. Write down the outcome, allowed files, forbidden actions, checks, budget, and stop conditions.
2. Split it. Give each worker one small outcome that can be judged on its own.
3. Build it. The worker returns the exact revision and a factual handover, not its own pass verdict.
4. Check it. Run tests, linters, builds, or other deterministic checks before asking another model what it thinks.
5. Critique it. A fresh, read-only critic reviews the exact revision against the original task and direct evidence.
6. Adjudicate and repair it. Confirm or refute each critic finding with direct evidence, then fix confirmed blockers within declared limits.
7. Integrate it. Treat the combined system as a new artifact and check it again.
8. Govern it. The loop completes automatically inside its delegation. A person decides only material changes and consequential actions.

What This Prevents

Start With One Prompt

Give this to the lead agent before a multi-agent build:

Work under Krystal Loop Protocol Core.

Before changing files, write a bounded task contract containing:
- its ID, revision, parent identity, and coordinator delegation;
- the exact outcome;
- allowed and protected paths;
- forbidden actions and live side effects;
- deterministic checks and required evidence;
- time, cost, and repair-round limits;
- conditions that require stopping for human review.

Split the task into independently judgeable work units. Workers must return
factual handovers tied to exact revisions and must not certify their own work.
Run deterministic checks before independent, read-only criticism. Confirm,
refute, or leave each critic finding unresolved using direct evidence. Treat
the integrated result as a new artifact. Normal repair rounds may proceed under
the recorded delegation; material changes and consequential actions stop at
the authority boundary.

KLP does not require a special model, database, vector store, or message bus. You can start with Git and Markdown files, then add durable coordination when the project needs it.

Run a Worker and Critic

The included examples demonstrate one complete bounded path:

DeepSeek Flash worker
  -> exact revision and deterministic checks
  -> controller-redacted, sealed review packet
  -> different-family read-only critic
  -> evidence-backed finding dispositions
  -> bounded repair or integration

Start with the DeepSeek Codex worker, then use the OpenAI-compatible critic harness. The worker launcher uses an isolated Codex profile and a reviewed assignment. The critic makes one request, validates its structured verdict locally, and cannot edit or authorize any action. The examples do not automatically connect worker output to critic input; the controller must inspect and redact the review packet first.

Run the Offline Lifecycle Proof

The fail-review-repair fixture proves a complete bounded lifecycle without provider egress or model spend:

output="$(mktemp -d)/klp-fixture"
python3 examples/fail-review-repair/run_fixture.py --out-dir "$output"
python3 -m json.tool "$output/final-receipt.json"

It creates a temporary Git project, records a deliberately incomplete worker revision, captures a failed check, runs the sealed critic harness against a loopback fake provider, confirms one real finding, refutes one false finding, applies one authorized repair, and re-checks the integrated artifact. A second test proves a zero-round repair budget stops instead of overrunning authority.

Read Next

• KLP Core protocol
• Instructions for AI agents and orchestrators
• Optional runtime profiles
• Safety and limits
• DeepSeek Codex worker example
• OpenAI-compatible critic example
• Offline fail-review-repair fixture
• Hermes Kanban adapter example

What KLP Is Not

KLP is not an autonomous software factory, deployment platform, model router, or claim that tests prove a product has no defects. It is a portable way to bound multi-agent work, retain useful evidence, and make uncertainty visible.

KLP is inspired by public builder/critic systems such as the Gauntlet Loop. It does not claim to invent multi-agent coding, independent review, or automated testing. Its focus is what happens after the demo, when a real project must remain understandable and working across many changes.

Project Status

KLP Core v0.2 is a provisional public profile. This repository includes a portable worker launcher, a sealed-packet critic harness, local fake-provider tests, example contracts, and a reproducible offline fail-review-repair fixture. The fixture proves protocol mechanics; it does not certify model quality, production safety, or a particular agent framework.

License

Krystal Loop Protocol uses split licensing:

• software, scripts, schemas, configuration examples, and tests are licensed under Apache License 2.0 (Apache-2.0);
• protocol and documentation text are licensed under Creative Commons Attribution 4.0 (CC-BY-4.0).

See the licensing map for the file-level boundary.