| name | quality-loop |
| description | Turn an outcome, optional discovery brief, or existing GitHub Issue into an approved system design, autonomously implemented and adversarially reviewed semantic Chapters, and a human-readable System Story. Use when the user wants agents to build a substantial change while the human reviews architecture and behavior rather than every code diff, invokes /quality-loop, or resumes an active Quality Run. |
Quality Loop
Build one understandable system per Quality Run. Let the human approve intent in a Design
Atelier, let agents implement and review the approved semantic Chapters, then let the human accept
the resulting system in a System Story Atelier.
<skill-dir> is the directory containing this file.
Start or resume a Run
- Run
<skill-dir>/scripts/next.sh [<run-dir>]; omit the argument to select the most recently
modified Run. Dispatch is resolved when stdout contains ACTION, REFERENCE, RUN_DIR, and
NEXT. A composition may also print PROFILE, EXPECTED_SCOPE, SESSION_BOUNDARY, and a
concise RESUME command.
- Bind the active session before scoped work with the runtime-provided identity:
QL_SESSION_ID=<runtime-id> <skill-dir>/scripts/ledger.sh session bind <expected-scope> <actor> <base|claudex>.
A claudex session then binds its printed profile with ledger.sh routing bind. Re-run next.sh
until SESSION_BOUNDARY=continue.
- Treat stdout as the dispatch contract. Export the printed
RUN_DIR, read only the printed
REFERENCE, and perform the printed NEXT action. When it prints CHAPTER, operate only on
that Chapter.
- Re-run
next.sh after every Ledger transition, human gate, completed review board, integration,
or resumed session. A transition is complete only when stdout reflects the newly recorded state;
never choose a later phase from memory.
- Before starting a long-lived human Atelier loop, inspect runtime context telemetry when the
harness exposes it. At 60% or more, record the current collaborator checkpoint, re-run
next.sh,
and resume the printed action in a fresh session. Do not infer a percentage when telemetry is
unavailable; the durable Run Record remains the resumption source.
For a new Run, next.sh prints the initialization action without requiring an existing record.
For an existing Run, the record is authoritative; never reconstruct state from chat.
Composition
- Compose
/atelier for the two human review surfaces. Operate ready Surfaces through its
scripts/atelierctl; do not issue raw HTTP calls or inspect the protocol store with ad hoc scripts.
- Compose
/agent-orchestration for collaborator ownership, bounded handoffs, durable checkpoints,
and reconnect-based resumption.
- When
/claudex-quality-loop is active, preserve this workflow and apply its Ledger-pinned
cross-family profile. Obey its fresh-session scope gates and do not add duplicate review lenses.
Prime rules
- Route every unresolved choice through the decision matrix. Freeze the Run for a material
deviation; batch a non-material choice into the Decision Inbox or, in AFK mode, a provisional ADR.
- Quote script output for every mechanical gate. Never replace an executable transition with prose
confidence.
- Keep the Driver out of product code. The Driver owns the Issue, semantic context, dispatch,
decisions, Ledger, and Atelier loops. Implementers and fixers edit and commit.
- Exchange approved designs, Chapters, bounded diffs, stable keys, evidence, and structured
findings—not transcripts.
- Record every gate, review round, deviation, disposition, skip, and decision when it occurs. If it
is absent from the Run Record, treat it as not done.
Routed references
Read only the reference selected by next.sh:
Load these supporting references only when the active expert requires them:
Durable Run Record
Keep authoritative state under .scratch/quality-loop/<run-slug>/:
state.json # <skill-dir>/scripts/ledger.sh is the sole writer
journal.md # append-only decisions, findings, deviations, and skips
spec.md # approved behavior and acceptance criteria
design.md # approved architecture, boundaries, decisions, and risks
concepts.md # stable concept keys, definitions, invariants, and relationships
timeline.md # generated proposed and actual build path
chapters/<NN>-<slug>.md # one semantic implementation Chapter
story.md # generated system narrative and evidence index
evidence/<chapter>/ # immutable gate logs, manifests, and deterministic review evidence
Author each fact once. Treat the Issue, timeline, Story, PR bodies, and Atelier content as generated
views of the authoritative record. Treat a PR as a merge/review boundary, never as a workflow
heartbeat.
Default role bindings
| Role | Default | Continuity |
|---|
| Driver and Design Coordinator | session model | persistent within the dispatched scope; fresh at required boundaries and the 60% Atelier gate |
| Planner | strongest judgment model | fresh |
| Implementer | strongest coding model | fresh per bounded Chapter slice; one writer at a time |
| Correctness / Test / Security reviewers | strongest judgment model | fresh per board, risk-scaled |
| Craft apply pass and bounded fixers | cheaper capable model | fresh, once after a clean board |
| Verifiers | strongest judgment model | fresh; batched per round, per finding on critical |
| Surface Builder | /atelier binding | persistent per active Surface |
Hard guardrails
- Implement nothing before approval of the exact Design revision.
- Open no final PR before acceptance of the exact System Story revision.
- Never force-push, bypass hooks, hand-edit
state.json, or leave unexplained dirty state.
- Split a Chapter that cannot complete RED→GREEN coherently or remain reviewable as one change.
- Keep complete diffs accessible even when the human-facing default is system comprehension.
- Let the human own mode changes, Design and Story gates, ADR ratification, and the final merge.
