claude
e1932e81f4
An agent report is authoritative only inside its documented `## Output format`. Consuming one is the operation a /boss run performs most often and the one nothing governed: Step 4 offered "agent output is good" with "good" left undefined. Field evidence (issue #37): a spec took six grounding rounds. The orchestrator's dispatch prompts asked grounding-check for output its contract forbids — a fix proposal, an invented report section, a budget override. The agent obeyed the caller over its contract and returned reports 3-5x the documented size. The orchestrator then wrote each advisory remark into the spec as a commitment, converting optional observations into falsifiable claims about the tree; rounds 4, 5 and 6 all blocked on claims it had itself volunteered in answer to earlier non-findings. docs/conventions.md gains `## Report and carrier authority` as the single source of three rules: the output format bounds a report's authority (and an in-format field carries the weight its own entry gives it, so a `no prescriptions` field stays a lead); a dispatch prompt adds focus but never output obligations (harness parameters — model, effort — are exempt, per issue #30); a finding is verified before it is acted on, because acting writes it into a durable artefact the next gate audits. Both ends bind: a carrier cannot lift an agent's contract. boss Step 4 defines "good" against that section and adds the two consequences that are the loop's own — an out-of-contract report means the dispatch was wrong, so re-dispatch rather than mine it; and under /boss nothing stands between a report and a durable artefact, so an unverified lead becomes queue work, never a commitment. specify Step 5 documents the third BLOCK outcome. Revise-and-re-dispatch is what every blocked spec actually takes; undocumented, it carried no bound, and the observed run improvised a stopping rule and talked itself out of it twice. A revision answers the `Unratified assumptions` block only — drop the reliance, or point at a green test the search missed — never the `Why no ratification` diagnosis, since a spec cannot ratify itself by asserting more. Bound: two revisions, and escalate early when the same assumption class blocks twice, because that means the spec's shape is wrong rather than its wording. A BLOCK is `terminal` once it is neither overridden nor clearable within the bound; every downstream routing now hangs off terminal rather than the first BLOCK. Under /boss this draws the override/revise line: an override signs the unchanged spec over the verdict and stays forbidden, while a revision hands the gate different bytes and is legitimate. grounding-check closes the loop from the agent end: the carrier is two fields in both directions, the output format is the whole report, and the contract outranks the caller. `Why no ratification` is scoped to the gap it describes and never to what the spec should assert instead — reconciling the field with the Iron Law's no-fix-proposals rule, the exact seam the incident exploited. closes #37
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 - Report and carrier authority: an agent report is authoritative only
inside its documented
## Output format; a dispatch prompt adds focus, never output obligations; a finding is verified before it reaches a durable artefact - 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 grounding BLOCK
is answered by a bounded revise-and-re-dispatch (at most two revisions,
cut short when the same assumption class blocks twice); once that
BLOCK is terminal — as an INFRA_ERROR is immediately, having no
revise path — it routes to the human sign-off pause. Revising is not
overriding: the fresh dispatch judges different bytes, whereas signing
the unchanged spec over the verdict is what autonomy may never do.
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.