claude
5606ca0213
A quality changes_requested verdict whose findings are all Minor,
arriving after at least one repair dispatch, now breaks the loop with
the findings surfaced as concerns instead of consuming the retry budget
toward a hard BLOCKED.
Grounding (aura runs, 2026-07-12/13): each quality round reads the diff
fresh, so late rounds keep surfacing NEW polish with severity trending
down (Important -> Minor -> comment-only Minor). Run sab-246-t56
(wf_643ee9fa) fixed its one Important finding in round 1, then hard-
BLOCKed an 85-minute green task in round 3 over two stale comment
cross-references; the sibling task was never attempted and the
re-dispatch cost another 32 minutes. Three of 14 runs across the last
three cycles ended review-loop-exhausted with no commit-blocking
residue.
Mechanically, the QUAL_SCHEMA issues array is now structured as
{severity: 'important'|'minor', text} so the valve keys on a declared
classification instead of parsing free-text prefixes; the fingerprint
backstop and the repair-brief prompt render the new shape, and the
quality-reviewer persona documents the honest-severity requirement.
Important findings still consume the full retry budget and BLOCK.
skills
A self-contained set of development-cycle skills and agents for
Claude Code. Originally distilled from the AILang project's
in-tree skills/ directory and generalised so it can carry the
same discipline across any project.
The plugin is mechanics: pipeline shape, hard-gates, TDD,
RED-first bug fixing, agent-template, working-tree-as-quarantine,
status protocol. It does not know your project's paths,
build commands, or domain-specific contracts. Those few facts live
in the project's own CLAUDE.md under a ## Skills plugin: project facts heading; everything else is a fixed convention (see
docs/conventions.md). There is no separate profile file.
What's in the box
The pipeline skills, each with the agents it primarily dispatches:
| Skill | Trigger | Output | Mandatory? |
|---|---|---|---|
brainstorm |
New cycle with an open design | ratified design handed to specify (writes no spec itself) |
Optional discovery front-end |
specify |
Design settled in sources, or handed over by brainstorm |
spec under docs/specs |
Hard-gate before plan |
planner |
New iteration within an open cycle | plan under docs/plans |
Hard-gate before implement |
implement |
Plan exists, OR a debug/tdd RED handoff | code + tests, uncommitted in working tree (via the implement-loop Workflow) |
Standard iteration path |
audit |
Cycle closing OR baseline drift suspected | drift report + regression report | Mandatory at cycle close |
debug |
Bug observed | RED test in working tree + cause analysis | Mandatory RED-first for any bug |
tdd |
Test-specifiable feature / issue (third entry path, alongside brainstorm and specify) |
RED executable-spec in working tree → implement mini-mode |
Standard entry path; bounces to brainstorm on a design fork |
fieldtest |
Orchestrator-dispatched post-audit | example fixtures + friction spec | Per-cycle optional; milestone fieldtest is the closing gate for a surface-touching milestone |
docwriter |
API surface stable across N cycles | rustdoc / docstring sweep | Optional |
boss |
User types /boss |
autonomous-orchestrator session — dispatches the other skills until done-state or bounce-back; signs specs in the user's place on the grounding-check PASS (see below) |
User-invoked, never auto-dispatched |
Entry is a selector cascade, not a single door. New feature work is
routed on a verification / enumeration axis, walked top to bottom, first
match wins: an observed bug → debug (RED-first, always first); a design
fork → brainstorm; a behaviour-preserving type/signature edit at a
definition site → the compiler-driven arm; new behaviour pinnable as
one assertion → tdd; everything else → spec-driven (specify →
planner). The compiler-driven arm is observe-then-bounce: make the
edit, build, run the suite — clean build AND suite green unchanged
commits; a hole bounces up (specify, or tdd for test-specifiable new
behaviour), a regression bounces to debug. It is not a standalone skill
but an arm of implement plus a shipped Workflow.
The autonomous execution loops run on the Workflow substrate. The
per-task implement loop and the compiler-driven loop are shipped as
Workflow scripts under implement/workflows/ (implement-loop.js,
compiler-driven-edit.js), symlinked into ~/.claude/workflows/ by
install.sh. A Workflow orchestrates from the top level, so each per-task
phase (implementer → spec-compliance → quality) is a real,
independently-invokable agent() call — which retired the old
implement-orchestrator agent's inline-role-switch workaround. The four
phase agents survive as the agent-types the scripts dispatch. The
interactive paths (specify, brainstorm) stay prose skills — their
oracle is human intent and needs a human in the loop.
Three further utility skills are invoked on demand rather than as
pipeline phases: issue (file or update a tracker item), glossary
(build or maintain the project glossary — see docs/glossary-convention.md),
and wiki (write or edit a repository-wiki article — durable, project-neutral,
sourced knowledge, deliberately kept out of docs/ and the pipeline).
One conversational skill stands outside the pipeline entirely:
pseudo (typed /pseudo) switches replies into commented,
human-readable pseudocode for explaining code — each answer opens
with a source-file-and-line anchor, marks notable steps with
reference markers that are pointing handles for the user (not
footnotes — explanations stay inline at the code, never in a
legend below), sketches the layout of the data structures the
code touches alongside the
flow, reduces the irrelevant to stubs, and omits low-level
mechanics. The pseudocode leans on the source language's idiom
in a language-tagged fence so it renders with syntax
highlighting, and keeps comments sparse — on their own line and
only where the code is not self-explanatory. Prose is allowed
only in a supporting role — the pseudocode block stays the
centre of every answer. It dispatches no agents.
The vocabulary is fixed. A cycle is one round in the
pipeline graph, and its sub-unit is an iteration. A
milestone is a distinct, higher axis — a Gitea milestone
that spans potentially many cycles and closes only when
the work it promised is complete and functional (see
docs/pipeline.md § Milestone-close gate). A cycle close is a
loop step; it is never a milestone close. A single design-ledger
entry is a contract. (A project with a glossary may pin
different domain nomenclature — see docs/glossary-convention.md.)
The two-layer split
This repo (the plugin) carries everything that is universal:
- Pipeline form:
design → plan → execute → review → close - Hard-gates between phases
- TDD as an independent inner-loop discipline
- RED-first bug fixes
- Agent template (frontmatter / Iron Law / standing reading / process / status / output / rationalisations / red flags)
- Status protocol:
DONE / DONE_WITH_CONCERNS / PARTIAL / BLOCKED / NEEDS_CONTEXT - Working-tree-as-quarantine and only-orchestrator-commits
- main HEAD sacrosanct below the session anchor (the one narrow
exception is the
/bossrollback sandbox — own unpushed autonomous commits above the run's start anchor) - No nested subagent dispatch (Claude Code platform constraint; Workflows orchestrate at the top level but do not lift it — the execution loops run as Workflow scripts so their phase agents are top-level calls, not nested ones)
- No orphan agents
The constants that used to be configurable but were the same in
every project are now fixed conventions — named directly in the
skills and documented once in docs/conventions.md: spec dir
docs/specs, plan dir docs/plans, slug-only slug.md naming,
the vocabulary above, standing reading (CLAUDE.md + git log -10),
git discipline, Gitea + closes #N, and the whole pipeline graph.
Specs and plans are ephemeral — git-ignored, held only for the active
cycle, then shell-rm'd at cycle close (never committed, so there is
nothing to git rm and no git-history copy); the design ledger is the
durable record and no durable artefact cites a spec/plan
(docs/conventions.md § Lifecycle).
The handful of facts that genuinely vary per project live in the
project's own CLAUDE.md under ## Skills plugin: project facts:
- Code roots; build / test / lint / doc-build commands
- Regression scripts; architect sweeps
- Design ledger / glossary / contracts / models / bench / public interface / fieldtest-examples paths
- Per-role standing reading
- Issue-tracker repo slug + list / show commands
The per-fact reference is the table in docs/conventions.md; the
copy-and-fill template is templates/CLAUDE.md.fragment. There is no
profile file and no parser — the skills read these facts from the
project's CLAUDE.md, which is standing reading on every dispatch.
Spec auto-sign
Under /boss, the orchestrator signs a spec in the user's place rather
than pausing at the sign-off gate — so a /boss run carries on across
spec boundaries unattended. (Outside /boss the user signs every spec
directly.) The autonomous signature is the grounding-check PASS:
an independent fresh-context agent's verdict against currently-green
tests, not the orchestrator's confidence. On PASS the orchestrator
keeps the signed spec as a git-ignored working file (never committed) and
records the sign on the run's reference issue, sends a mandatory
informational notify that names the signed capability and invites a
veto, and continues to planner without stopping. A no-override
grounding BLOCK / INFRA_ERROR routes to the human sign-off pause.
The judgement work happens upstream: under the bold stance, specify
Step 1.5 decides every load-bearing fork it can derive an answer for
(from the sources, the code, consistency, risk) and records the decision
on the run's reference issue, pulling an ad-hoc spec-skeptic lens as a
bias-breaker when it is unsure whether its leaning is judgement or bias;
only a pure-preference fork bounces to the human. The former obligatory
unanimous five-lens spec-skeptic panel is retired (baseline tag
pre-autosign-rework) — editorial roughness it would have caught is let
through deliberately, cheap to patch inline downstream. A wrong derived
call is recovered by the user's veto or, within the run, the rollback
sandbox (boss/SKILL.md § Direction freedom): the orchestrator may
hard-reset its own unpushed autonomous commits back toward the session
anchor on a dead end. See specify/SKILL.md Step 6,
specify/agents/spec-skeptic.md, and boss/SKILL.md §"Spec auto-sign".
Install
See INSTALL.md. In short: clone, run install.sh, then add a
## Skills plugin: project facts section to each project's
CLAUDE.md (template in templates/CLAUDE.md.fragment).
Status
The migration from AILang's in-tree ~/dev/ailang/skills/ into
this plugin is complete — the pipeline skills, the specify and
tdd entry paths, the boss orchestrator, and the utility and
conversational skills documented above have all landed.
docs/migration.md records the repo-layout convention and the
per-skill and per-agent authoring checklists.