# Gauntlet Loop

> Use when a user asks to run a Gauntlet Loop, improve work against a concrete reference until it passes, turn a rough software request into an autonomous iterative quality run, or resume an existing .gauntlet effort in a new or existing project.

- **Type:** Skill
- **Install:** `agentstack add skill-yash-1511-gauntlet-loop-gauntlet-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Yash-1511](https://agentstack.voostack.com/s/yash-1511)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Yash-1511](https://github.com/Yash-1511)
- **Source:** https://github.com/Yash-1511/gauntlet-loop/tree/main/skills/gauntlet-loop

## Install

```sh
agentstack add skill-yash-1511-gauntlet-loop-gauntlet-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Gauntlet Loop

## Overview

Turn a rough goal into a resumable evidence loop: initialize the project, keep a real quality bar fixed, divide only independently judgeable work, and route each failed artifact through a fresh critic until all gates pass or an honest stop condition applies.

Core laws:

1. The builder never grades itself.
2. The critic inspects the real artifact, not a builder summary.
3. A supplied reference stays in the bar; a proxy cannot quietly replace it.
4. A failed round returns one largest gap and one next proof.
5. No reproducible evidence means no pass.

## Workflow

### 1. Initialize or resume

Verify the harness can create fresh agent contexts and let them inspect files/tools. If it cannot, follow **No fresh-agent capability** in [role-contracts.md](references/role-contracts.md); do not fake independent criticism.

Run from this skill directory:

```bash
python3 scripts/init_project.py --project /absolute/path/to/project
```

Read `.gauntlet/project-context.md` and `.gauntlet/harness-assessment.md`. Then read [context-and-harness.md](references/context-and-harness.md) and inspect only the relevant repository instructions, docs, source, tests, and current changes.

If resuming, refresh context and reproduce the best-known artifact before accepting old evidence. Preserve every pre-existing working-tree change as user-owned.

### 2. Anchor intent and choose the bar

Write the user's verbatim request to `.gauntlet/request.md`. Do not polish or reinterpret it there.

Read [quality-bars.md](references/quality-bars.md). Write `.gauntlet/contract.md` with:

- outcome and observable user impact;
- constraints and non-goals;
- real artifacts the critics inspect;
- direct reference or measurement used as the bar;
- required gates, reproduction commands, and blocker conditions;
- authority, safety, time, and compute limits;
- success, `BLOCKED`, and `PLATEAU` stop conditions.

When the user supplied a comparison, keep it. For visual or textual work, use direct side-by-side and blind A/B when practical. For backend work, prefer deterministic behavior, failure, recovery, performance, and security gates. Every required gate must pass; never average away a losing category.

Record the machine-readable headline:

```bash
python3 scripts/update_progress.py --project /absolute/path/to/project \
  set-contract --goal "Observable outcome" --bar "Direct inspectable bar"
```

The recorded goal and bar are locked once a critic round exists. If intent materially changes, preserve the old evidence and start a new Gauntlet run instead of carrying its verdicts onto a new contract.

Also write `.gauntlet/prompt.md`: a short reusable prompt containing the goal, bar, constraints, fresh-critic rule, and permission boundaries. Keep it portable to another capable agentic harness.

Resolve ordinary ambiguity from repository evidence. Ask only when a missing choice is materially irreversible, requires new authority, or changes the intended outcome.

### 3. Build the workstream graph

Read [role-contracts.md](references/role-contracts.md). Let the lead agent decompose the goal into the smallest artifacts or coherent concerns that can be improved and judged separately.

Write `.gauntlet/workstreams.md`. For every node record:

- ID, goal, owned artifact/files, and required gates;
- dependencies and shared contracts;
- whether it is independent or coupled;
- reproduction commands;
- integration impact.

Parallelize ready independent nodes only. Give each parallel builder exclusive ownership. Shared schemas, mutable state, rendering/global styling, integration surfaces, and performance budgets are coupled: use one sequential owner, then rerun downstream evidence.

Add every node to progress state:

```bash
python3 scripts/update_progress.py --project /absolute/path/to/project \
  add-workstream dashboard-shell "Dashboard shell and density"
```

Include an `integration` node that depends on all component nodes.

### 4. Run each gauntlet

For each ready node:

1. Dispatch a builder with the role contract, goal, owned boundary, direct bar, baseline, commands, and latest accepted largest gap.
2. Have the builder make one coherent improvement and produce raw evidence. The builder does not declare success.
3. Dispatch a **fresh critic** with no builder rationale or claimed result. Give it the verbatim request, gates, direct reference/baseline, current real artifact, and reproduction commands.
4. Require the exact critic output in [role-contracts.md](references/role-contracts.md): per-gate verdicts, evidence, overall verdict, one largest gap, one next proof, invalid evidence, uncertainty, and risks.
5. Reproduce enough evidence to validate the verdict. An uninspectable or contaminated result remains `FAIL`.
6. Record the round.

Failure:

```bash
python3 scripts/update_progress.py --project /absolute/path/to/project \
  record dashboard-shell FAIL \
  --gap "Hierarchy still loses the blind A/B at dense table state" \
  --gate "Reference comparison|FAIL|Reference won 3/3 blind comparisons" \
  --evidence "artifacts/round-002/comparison.png" \
  --evidence "3/3 blind critics selected the reference" \
  --next-proof "Candidate wins a new 3-vote blind comparison at the same viewport" \
  --invalid-evidence "Mobile capture was unavailable" \
  --uncertainty "Only the required desktop state was reproduced" \
  --risk "Responsive hierarchy remains unmeasured"
```

Pass:

```bash
python3 scripts/update_progress.py --project /absolute/path/to/project \
  record dashboard-shell PASS \
  --gate "Reference comparison|PASS|Candidate won 3/3 blind comparisons" \
  --gate "Browser behavior|PASS|Required interactions passed in Chromium" \
  --evidence "All required states passed blind A/B and browser checks" \
  --next-proof "None — all required gates passed" \
  --uncertainty "Production analytics were outside this local run" \
  --risk "Production traffic remains unobserved"
```

On failure, route only the largest gap and next proof back to the builder. Keep the best-known accepted artifact; a regression never becomes the baseline. Use a new fresh critic every round.

### 5. Recover from wrong prescriptions and plateaus

If the same prescribed fix worsens the same measurement twice, stop repeating it. Preserve the observation, reject the prescription, restore the best-known state, and run the root-cause/strategy-reset protocol in [role-contracts.md](references/role-contracts.md).

Try up to two materially different strategy resets with new falsifiable evidence. If neither moves the bar, record the honest terminal state:

```bash
python3 scripts/update_progress.py --project /absolute/path/to/project \
  plateau dashboard-shell \
  --reason "Two root-cause strategy resets produced no measurable improvement"
```

Do not lower the bar, call a resource limit success, or stop merely because a fixed round count elapsed.

### 6. Integrate and smooth

After a wave, give one integration owner the assembled artifact and all passed contracts. Its job is to remove inconsistencies and conflicts, not redesign passed workstreams.

Then dispatch a fresh integration critic against:

- `.gauntlet/request.md` (verbatim request);
- every global gate in `contract.md`;
- the assembled real artifact;
- the direct references and exact reproduction commands.

Record integration like any other workstream. Component passes do not imply product success.

### 7. Report and leave a resumable result

Keep `.gauntlet/progress.md` current throughout the run. On completion, block, or plateau, report:

- final status: `PASS`, `BLOCKED`, or `PLATEAU`;
- what changed and where;
- direct bar and per-gate evidence;
- integration verdict;
- surviving risks and invalid evidence;
- exact next action;
- reusable prompt location.

Never say “done,” “production-ready,” or “better than the reference” unless the recorded evidence supports that exact claim.

## Stop Conditions

| Status | Apply when |
|---|---|
| `PASS` | Every component gate and fresh integration critic pass with reproducible evidence. |
| `BLOCKED` | Missing authority, credentials, fresh-agent capability, safe isolation, required external state, or reproducible inspection prevents progress. |
| `PLATEAU` | Two evidence-producing strategy resets fail after root-cause diagnosis. |
| Stopped by user/budget | Preserve best-known state and report incomplete gates; never translate the ceiling into `PASS`. |

A user may set a resource ceiling. Do not invent a fixed number of quality rounds when none was supplied.

## Quick Reference

| Need | Action |
|---|---|
| Refresh project map | `python3 scripts/init_project.py --project PATH` |
| Record contract | `update_progress.py --project PATH set-contract --goal GOAL --bar BAR` |
| Add node | `update_progress.py --project PATH add-workstream ID TITLE` |
| Record critic | `update_progress.py --project PATH record ID PASS\|FAIL ...` |
| Honest stop | `update_progress.py --project PATH block\|plateau ID --reason REASON` |
| Resume view | `update_progress.py --project PATH status` |

## Common Mistakes

| Mistake | Correction |
|---|---|
| Replacing a named real reference with an invented rubric | Keep direct comparison; add the rubric as supporting gates only. |
| Returning a broad critic backlog or “issue batch” | Select one largest evidenced gap and one next proof. |
| Letting the builder explain the artifact before criticism | Give a fresh critic the artifact, bar, and commands without builder rationale. |
| Maximizing fan-out across coupled work | Use sequential ownership for shared contracts and measure after integration. |
| Repeating a critic prescription that worsens evidence | Diagnose root cause and reset strategy; preserve the observation, not the remedy. |
| Declaring success at a round/budget cap | Record incomplete gates and stop honestly. |
| Trusting a summary, screenshot description, or unreproducible score | Inspect the real artifact and rerun the evidence. |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Yash-1511](https://github.com/Yash-1511)
- **Source:** [Yash-1511/gauntlet-loop](https://github.com/Yash-1511/gauntlet-loop)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yash-1511-gauntlet-loop-gauntlet-loop
- Seller: https://agentstack.voostack.com/s/yash-1511
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.