Under /boss only, when the orchestrator hits a durable deficiency in the
plugin itself (a skill, agent, convention, or pipeline/cascade gap)
mid-run, it files an issue against the plugin's own tracker and continues,
marking provenance with a body block — no new label, so the fixed work-type
vocabulary stays intact.
Adds the trigger and its evidence gate (a citable path:line inside the
plugin), dedupe-as-gate over open and recently-closed issues, and the
discipline that filing is neither a notify event nor a substitute for a due
bounce-back. Wires the new section into issue/SKILL.md (boss joins the
issue-filing callers) and docs/conventions.md (Issue-tracker pointer).
closes#9
Retire the obligatory five-lens spec-skeptic auto-sign panel (worst case
18 agent runs per spec under /boss). The autonomous signature is now the
Step-5 grounding-check PASS alone — an independent fresh-context agent's
verdict against currently-green tests; a no-override BLOCK/INFRA_ERROR
routes to the human sign-off pause.
The judgement the panel applied moves upstream into specify Step 1.5,
whose stance inverts: a load-bearing fork the orchestrator can DERIVE an
answer for (sources, code, consistency, risk) is decided boldly and
recorded on the run's reference issue; only a pure-preference fork
bounces. spec-skeptic survives as an optional ad-hoc bias-breaker the
orchestrator pulls when unsure whether its leaning is judgement or bias —
not a gate, not a veto.
Every /boss run carries a mandatory reference issue (created if the cycle
had none): the fork-decision log, the orchestrator's cross-run memory,
and the only surviving trace of a hard-dropped attempt.
Relax main-sacrosanct below the session anchor: within an autonomous run
the orchestrator may git reset --hard its OWN UNPUSHED commits above the
anchor on a dead end — never below the anchor, never a pushed commit
(forward-only/revert). Discarded attempts are hard-dropped, no parking.
Verified across the 9 edited files by a 4-lens adversarial review
(retired-panel residue, cross-file contracts, rollback-boundary safety,
stance coherence): unanimous SOUND. Baseline tagged pre-autosign-rework.
closes#8
docs/specs and docs/plans hold only the active cycle's artefacts: a spec/plan is committed while its cycle is live and git-rm'd in the cycle-close commit (after audit drift-clean), so HEAD shows only in-flight work while git history keeps the full text. No issue-posting, no gitignore branch — git history + the design ledger are the durable record.
Rewrites conventions.md § Lifecycle as the single source of truth; pipeline.md, design.md, README.md, specify, planner, glossary, brainstorm, issue, and the CLAUDE.md fragment follow it. Naming stays NNNN-slug.md (a within-cycle handle; recycling on an emptied directory is fine).
The auto-sign panel earned its keep: in aura it signed ~20 specs autonomously and discriminates (several recent specs escalated to the human path). The needless complexity was the configuration freedom around it — spec_auto_sign was a per-project toggle that was only ever meant to be on.
Remove the toggle. Auto-sign is now fixed /boss behaviour, with the human sign-off pause as the escalation target (objective gate red / design BLOCK / INFRA_ERROR / budget spent). The panel itself, the Step-1.5 seeding machinery, grounding-check, and the spec-skeptic agent are unchanged; conventions.md can now state there is no per-project behavioural toggle at all.
The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.
Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
a verification/enumeration axis ahead of the settled-vs-fork question.
Each lighter arm carries a positive trigger matched by signature, not
reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
that propagates mechanically. Observe-then-bounce — make the edit,
build, run the suite; clean build AND suite green unchanged commits;
a hole bounces up (specify for a design choice, tdd for discovered
test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
mechanical/forwarding -> compiler-driven; encodes new behaviour ->
tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
not a heavy new skill ("the largest concrete win is small").
Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
phase (implementer -> spec-compliance -> quality, + tester for E2E) is
a separate top-level agent() call, so a single phase is independently
invokable and inter-phase aggregation/re-loop is code. Retires the
implement-orchestrator agent's inline-role-switch workaround (the four
phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
only the autonomous/mechanical loops moved. try-and-error is deferred.
Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.
Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).
closes#7
Step 1.5's issue-less in-context case used to fall back unconditionally
to the human sign-off: with no tracker issue, the `scope-fork` juror had
no auditable source for an in-context fork resolution and (correctly)
blocked, so auto-sign was structurally unreachable on that path.
Close it the same way the lagging-issue case is closed — give the juror
an auditable artefact instead of weakening the gate. When the cycle has
no seeding issue, the orchestrator now creates one recording each
resolved fork WITH provenance (a record of the user's decision, never a
fresh orchestrator one). A new tracker issue is independent and
auditable — unlike the self-referential spec-note the old text rejected
— so it, not the orchestrator's confidence, is what the juror checks.
The provenance gate is unchanged: no real user statement is a Step-1.5
bounce, not a manufactured issue; the orchestrator writes, the juror
enforces.
Also thread a `seeding_issue` field through the scope-fork carrier so
the juror can actually find the issue to read (the lagging issue, the
newly created one, or `none`). Without it the juror had no issue index
and the record was invisible — a latent gap the lagging-issue path
shared.
- specify Step 1.5: issue-less branch creates a provenance-bearing
seeding issue; body names the work (no forward ref to the unwritten
spec); explicit create command; capture-the-index instruction.
- specify Step 6 + handoff table: seeding_issue carrier field.
- spec-skeptic: juror reads seeding_issue from the carrier; accepts
provenance in a created issue's body, not only in a comment.
- consistency: README, pipeline.md, design.md.
The fence-label -> parser fact, the specify/grounding-check/planner
parse gates, the parse-trace attestation, and all their cross-references
served a single real user (ailang). Convention over configuration: the
generic machinery is removed plugin-wide; the one consumer carries an
equivalent project-local directive in its own CLAUDE.md.
Archive under docs/plans and docs/specs left intact as time documents.
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing).
Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign.
Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
The `spec-skeptic` `scope-fork` juror reads only the seeding issue plus
the spec. On the legitimate `specify` direct-entry path — a fork settled
in a long in-context design discussion — that resolution lives only in
ephemeral chat the juror cannot replay. When the issue body lags the
discussion (still lists the fork open), the juror correctly blocks, and
a design BLOCK escalates without self-correction. The result: auto-sign
was structurally almost unreachable for the in-context entry path.
Close the blind spot by giving the juror an auditable source instead of
weakening the gate. When `specify` enters in-context and a tracker issue
still lists a now-resolved fork as open, the orchestrator posts a
reconciliation comment recording each fork's resolution WITH provenance
(a record of the user's decision, never a fresh orchestrator one) before
writing the spec. The comment is persistent and audit-able — unlike a
carrier digest — so it, not the orchestrator's confidence, is what the
juror checks.
Separation of powers keeps it honest: the orchestrator writes the
comment, the adversarial juror enforces the provenance requirement. A
bare `decision: X` with no provenance does not resolve the fork — the
re-dispatched juror blocks on it. The escalation rule and the
three-field carrier are untouched; only the juror's information changes.
Mechanics:
- specify Step 1.5: reconciliation-comment sub-step, provenance format,
issue-less fallback (auto-sign -> human sign-off, no weak spec-note).
- spec-skeptic: replace the "quoted in the dispatch" drift; juror reads
the issue WITH comments via `issue_tracker.show_cmd`; provenance check.
- new profile slot `issue_tracker.show_cmd` (must render comments);
documented in schema + template.
- issue skill: `tea issues <idx>` is body-only; `--comments` required
(verified against tea 0.14.1 and Aura #55 — 180 vs 144 lines).
- consistency: design.md out-of-scope, README, pipeline.md, boss skill.
The spec-skeptic auto-sign panel was one-shot: under /boss with
spec_auto_sign on, any panel BLOCK fell straight back to the human
sign-off pause. Because the panel is adversarial-by-design and rarely
returns a unanimous SOUND, /boss escalated to the user even for defects
the orchestrator could mechanically repair.
Partition the five lenses by what a BLOCK means and run Step 6 as a
bounded loop:
- Editorial (criterion, ambiguity, plan-readiness) — the spec is
under-articulated; the orchestrator self-corrects in place, re-runs
Step 4 + Step 5, and re-dispatches all five lenses.
- Design (scope-fork, grounding) — the ground is not settled; escalate,
never self-correct.
Re-loop limit: <= 2 rounds, the 3rd unresolved editorial BLOCK
escalates (hard-coded N, matching implement-orchestrator's idiom).
INFRA_ERROR and exhausted budget escalate too. Auto-sign still requires
a fresh unanimous SOUND on a green objective gate.
Re-dispatching all five lenses every round is the backstop: an
editorial repair that launders an unsourced design decision is caught
by the re-run scope-fork / grounding jurors and escalates. A criterion
repair is bounded to supplying the worked evidence the criterion already
demands — not re-judging acceptance (architect drift item).
specify/SKILL.md owns the loop; spec-skeptic.md keeps the juror
lens-agnostic; boss/SKILL.md, README.md, docs/profile-schema.md and
docs/pipeline.md are synced to the new semantics.
closes#6
Add `pipeline.boss.spec_auto_sign` (default off). With it on, a /boss
run may sign a spec in the user's place — but only through a gate built
to never rely on the orchestrator's own confidence: all objective gates
green (precondition, parse, grounding-check PASS with no human override)
AND a unanimous five-lens adversarial spec-skeptic panel (criterion,
grounding, scope-fork, ambiguity, plan-readiness). Any single BLOCK
falls back to the human sign-off pause.
On a clean sign the orchestrator commits the spec ((boss-signed) in the
subject), fires a mandatory informational-with-veto notify, and proceeds
to planner without stopping. A later veto is a forward correction, never
a history rewind.
- new agent: specify/agents/spec-skeptic.md (read-only, one lens per dispatch)
- specify Step 6 + Iron Law: approval may come from the auto-sign gate,
never from model self-confidence
- boss: third notify category, §"Spec auto-sign", rationalisations, red flags
- profile-schema + template: the opt-in slot
- pipeline.md, agent-template.md, README: the auto-sign path documented
closes#5
migration.md and the README Status section described an AILang->plugin
migration as "in progress" with "the remaining seven skills" pending —
long since false; the whole roster has landed. The architect flagged
both at the specify cycle close as pre-existing debt.
Rather than re-listing every skill (which is exactly what drifted — the
"Expected layout after migration" ASCII tree had to mirror each new skill
and didn't), the fix removes the enumerating renderings:
- migration.md: reframed as a record of the completed migration. The
per-skill ASCII layout tree is replaced by the structural rule (every
top-level SKILL.md dir is a skill; agents live beside it under agents/;
the repo root is the authoritative roster). The per-skill and per-agent
authoring checklists are kept verbatim — they retain value for new
skills. Result: no enumeration, so nothing to drift.
- README Status: "migration in progress / remaining seven follow" ->
"migration complete"; the doc reference now points at the layout
convention and authoring checklists, not an "expected final layout".
Decision on the issue's open question (update vs retire): neither pure
form. The tracker's enumerating parts are retired; its still-useful
convention and checklists are preserved drift-proof.
Follow-up to f775881. The architect's diff-scoped review missed four
prose references outside the cycle diff that the brainstorm shrink left
stale — the aspirational-marker and parse-gate machinery moved to specify
(it writes the spec and runs the gates), but these still said brainstorm:
- profile-schema.md aspirational-source section: "a later brainstorm
tell aspirational content", "the brainstorm degrades", "consumed by
the brainstorm skill", and the "Step-7 parse-every-block gate" number
(specify's parse gate is Step 4, not Step 7).
- profile-schema.md spec_validation section: "The brainstorm parse-gate".
- README "Retrofitting spec_validation": "brainstorm Step 7 self-review"
-> "specify Step 4 self-review".
Found by sweeping every brainstorm reference in the two files for ones
that describe spec-production rather than discovery. planner Step 5
self-review and the grounding-check pass references were already correct.
Architect drift review (cycle 9e8b9ec..HEAD) returned drift_found. Three
cycle-introduced items, all repaired here as tidy edits:
- planner/SKILL.md: the cycle never touched it (recon never scoped it,
the feat commit body's "every pipeline rendering agrees" over-claimed).
Its Handoff Contract still named `brainstorm → planner` and the bounce
`planner → brainstorm`; the Input-source cross-ref and two
rationalisation rows still pointed at brainstorm as the spec producer.
All repointed to specify (specify produces and owns the spec; brainstorm
is the optional discovery stage upstream of it). The skip rule now lists
specify in the design path tdd bypasses.
- specify/agents/grounding-check.md: the agent move left one stale pair —
"self-review (Step 7) and user-approval (Step 8)" were brainstorm's old
numbers; in specify they are Step 4 and Step 6.
- profile-schema + template: the `optional: true` per-phase key I
introduced in the plan was undocumented AND rested on a semantic error —
`brainstorm: { gates: [specify] }` reads as "specify cannot start until
brainstorm has run", which is false (specify enters directly from
sources). Corrected to `brainstorm: {}` (an active phase with no hard
gate of its own, like implement); specify keeps `gates: [planner]` as
the one real hard gate. The optional key is gone; brainstorm's
optionality lives in the skip rules and SKILL prose, where it belongs.
Why these escaped the cycle's own grep suite: the consistency greps used
`brainstorm *-> *planner`, which does not match the real renderings
`` `brainstorm` -> `planner` `` (backticks between the words). The same
filter-string blind spot recurred twice this session; the verification
greps here tolerate optional backticks.
Pre-existing debt (NOT cycle-introduced), filed as backlog Brummel/Skills
issue #5 rather than fixed here: docs/migration.md's layout tree and
README's migration-status both predate tdd/glossary/pseudo/issue/
postmortem and misdescribe the roster.
Verdict: cycle drift-clean after these repairs (carry-on). No regression
gate (prose repo, no scripts). Not a milestone close.
Add `specify` as a third co-equal entry path into the dev cycle: it
produces an approved spec from already-settled sources (an exhaustive
issue, a long in-context design discussion, or a design brainstorm just
ratified) with review but no interview. This is the producing half of a
deliberate deciding/producing split — `brainstorm` shrinks to optional
discovery, `specify` becomes the sole spec-production gate before
`planner`, mirroring the RED->GREEN split that keeps tdd/debug honest.
What moved:
- brainstorm/SKILL.md: stripped of the hard-gate, the acceptance
criterion, write-spec, self-review, grounding-check, user-review, and
planner-handoff steps; terminal state is now handing a ratified design
narrative to specify. Steps renumbered 1-5 (production steps left).
- specify/SKILL.md (new): the production core, with a precondition gate
(Step 1.5) that bounces to brainstorm the moment the sources do not
resolve a load-bearing decision — the same discipline tdd uses.
- The grounding-check agent moved brainstorm/agents/ -> specify/agents/
(no-orphan-agents: it lives under its dispatcher), refs repointed.
- boss/SKILL.md: Entry-path reflection is now three-way (tdd / specify /
brainstorm). specify dispatches autonomously (bounded, no interview)
and pauses at its user-review gate; only a fresh brainstorm cycle
stays a pre-dispatch bounce-back.
- pipeline.md, README, profile-schema, the profile template, and the
migration layout updated so every pipeline rendering agrees; specify
is a CORE node (not opt-in, unlike tdd) carrying gates: [planner].
Design alternative rejected: parallel sibling skills sharing a
docs/spec-production.md (extract-to-doc). Chosen extract-and-chain
instead — the shared surface is ~70%, so a shared doc would either
become the skill body or drift; chaining keeps one executed home for the
gates.
Verification (prose repo, no test suite): the spec's internal-
consistency grep suite (no two-path drift, no direct brainstorm->planner
edge, specify referenced in every rendering, grounding-check single home
under specify, specify structural completeness) all green. Orchestrator
inspection additionally fixed two dead step-refs the plan under-scoped
(a "(Step 4)" lift-validation pointer and a "Skipping Step 7
self-review" red flag, both pointing at steps brainstorm no longer has)
and corrected six pre-existing brainstorm->planner renderings in
pipeline.md and tdd that predated this cycle.
Known follow-ups (non-blocking): the committed spec writes
`skills/specify/` in places (typo; skill dirs are repo-top-level) — to
be corrected separately. The grounding-check hard-gate was degenerate
for this very cycle (this repo has no profile and no test suite); the
skip is documented in the spec and the session.
Bite-sized plan for the specify spec-production entry path: create
specify/SKILL.md (full body inlined), move the grounding-check agent to
its new dispatcher, shrink brainstorm to discovery, and propagate the
three-path topology across boss, tdd, pipeline.md, README, profile-schema,
the profile template, and the migration layout. Verification is
grep-based internal-consistency checks (prose repo, no test suite).
Add a third dev-cycle entry path: a specify skill that produces an
approved spec from given sources (settled in-context discussion or an
exhaustive issue) with review but no interview. Splits brainstorm's
deciding half from its producing half — brainstorm becomes optional
discovery, specify becomes the sole production gate before planner,
mirroring the RED->GREEN split that keeps tdd/debug honest. specify
bounces to brainstorm on an unresolved design fork, the same
discipline tdd uses.
Flip the naming default from `flat` (slug.md) to
`stable_per_directory_4digit` and seed `counter_dirs` with the four
document-producing directories (specs, plans, design contracts,
design models) so the counter policy is effective out of the box.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A new opt-in alternative to the brainstorm -> planner design entry,
for work whose desired behaviour is test-specifiable. Instead of a
prose spec the user approves, `tdd` produces one minimal RED
executable-spec ("how it should work") and treats it like a bug to
be fixed: the GREEN side hands off to `implement` mini-mode, the
same two-stage RED-first handoff `debug` uses.
Skill + agent split mirrors debug/debugger: a thin SKILL.md owns
trigger, dispatch, the orchestrator-side loop, and handoff; the
agent (tdd-author) carries the authoring discipline. The agent
guards two failure modes specifically — guessing a design into a
test (a genuine design fork bounces back to `brainstorm` rather
than ratifying an un-chosen design), and pushing harder on a
headline test that won't go green (one iteration that can't reach
GREEN triggers a reactive decompose into a ladder of BLOCKER
sub-tests; two failed rounds bounce to `brainstorm`).
The boundary is the design line: `tdd` owns the work iff one honest
minimal assertion pins it; otherwise `brainstorm` reclaims it. This
is distinct from the per-task TDD the implementer already practices
inside `implement` — `tdd` authors the one headline spec above it.
Wires the phase into the docs it references:
- docs/profile-schema.md: opt-in `tdd` pipeline slot
- README.md: skill table row
- docs/pipeline.md: entry-path in the graph, phase description, skip rule
- templates/project-profile.yml: commented-out slot
install.sh picks up tdd/ automatically (top-level dir with SKILL.md).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Align the design_ledger profile-slot default and its illustrative
references with the docs/ layout used by the other path slots.
Historical specs/plans are left untouched as cycle records.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-skill cycle (59c2f4b..4fd5408).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/agent-template.md said the Iron Law is rendered
'as a numbered list' (the schematic placeholder at l.37 and the prose
at the § Iron Law section), but all 13 existing agents render it as a
code-fenced block of short imperative lines — and the cycle's new
glossary-extractor.md correctly followed that universal convention. So
the drift was the template wording, stale relative to every one of its
instances, not the new file. Resolution: align the template to reality
(both spots now say 'a code-fenced block of short imperative lines').
The new agent file was carry-on — 'fixing' it to a numbered list would
have made it the lone deviant among 14 agents, i.e. introducing drift,
not removing it.
- [low] CARRY-ON. README now classes issue/glossary as 'utility skills'
but that taxonomy is not mirrored in issue/SKILL.md's or
glossary/SKILL.md's own frontmatter. Accepted as low-severity: the
invocation-class label is a README-level descriptor; mandating every
skill self-declare its class in frontmatter is gold-plating with no
consumer. Revisit only if a tool starts keying off a per-skill class.
What holds: single-sourcing preserved (the new skill cites
glossary-convention.md and restates no rule; paths.glossary semantics
defer to profile-schema.md); authority consistent across the boss
sentence, the convention, and the skill's Authority section; the
utility-vs-phase distinction held (no claim that glossary is a pipeline
phase); glossary-extractor.md conforms to agent-template.md.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest run;
see docs/pipeline.md § Milestone-close gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Gives the plugin an executable procedure over a project's glossary,
closing the two gaps the glossary-convention infrastructure left open:
no on-ramp to build a glossary for an existing project, and no
conformance check around hand-maintenance.
New `glossary` utility skill (invoked on demand like `issue`, not a
pipeline phase) with a mode dispatch:
- maintain: guided add / change / remove of one entry under a local
conformance check (three-field shape, <=2-sentence definition,
collision scan against existing entries) plus a stale-usage sweep on
change/rename. A non-conforming entry is rejected with the named rule,
not written. The sweep reports drift; it does not block (guidance, not
enforcement).
- bootstrap (user-only): fans out one read-only glossary-extractor agent
per prose slice, merges and clusters their observed variants, auto-
includes clear winners, surfaces contested clusters to the user for the
canonical choice, and leaves unresolved clusters out (never coined).
New `glossary-extractor` agent (read-only, template-conforming): sweeps
one prose slice, reports recurring concept terms + competing variants
with frequencies and locations, coins nothing.
Single-sourcing held throughout: the skill applies the rules in
docs/glossary-convention.md and restates none of them. Authority is
unchanged — maintain keeps the user-any-time / boss-record-reality rule;
bootstrap is user-only, with boss allowed to recommend it via bounce-back
(one wired sentence in boss/SKILL.md). docs/glossary-convention.md gains
a one-line tooling pointer to the skill; README.md lists `glossary` and
`issue` as utility skills and drops the stale 'Eight skills' count the
fresh-context grounding-check flagged (it had silently omitted `issue`).
install.sh links the new skill + agent with no installer change (its glob
covers any top-level dir with a SKILL.md + agents/ subdir; verified).
Docs/prose-only repo, no test runner: all 13 grep presence-gates green
against verified zero baselines; final sweep ALL_PRESENT, install.sh
still parses (bash -n). Implements
docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan for the glossary-skill spec. Two create tasks
(glossary/SKILL.md mode-dispatch utility skill, glossary/agents/
glossary-extractor.md read-only per-slice prose extractor) carrying full
verbatim file bodies, plus three single-sentence wiring edits
(boss/SKILL.md bootstrap bounce-back, docs/glossary-convention.md tooling
pointer, README.md utility-skill listing + count-free framing) and a
final sweep.
Docs/prose-only repo, no test runner: every task closes on a grep
presence-assertion against the touched file. All edit-task gates use
single-token patterns or code-fence lines calibrated against verified
zero baselines (bootstrap/glossary/SKILL.md path / glossary all 0 today),
sidestepping the line-wrap pitfall recorded at c7a56c2.
Implements docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a new utility skill `glossary` (invoked on demand like `issue`,
not a pipeline phase) carrying two procedures over a project's glossary:
- maintain: guided add / change / remove of one entry with a local
conformance check (three-field shape, <=2-sentence definition,
collision scan against existing entries) plus a stale-usage sweep on
change/rename. A non-conforming entry is rejected with the named rule,
not written.
- bootstrap (user-only): a fan-out of read-only glossary-extractor
agents over the project's prose surface, merged and clustered into
conforming entries; clear winners auto-included, contested clusters
surfaced to the user, unresolved clusters left out (never coined).
Single-sources against docs/glossary-convention.md (the skill executes
the rules, restates none). Authority unchanged: maintain keeps the
existing user-any-time / boss-record-reality rule; bootstrap is
user-only with boss allowed to recommend it via bounce-back.
Grounding-check PASS (9/9 assumptions ratified against live repo bytes;
parse-gate a documented no-op, no spec_validation configured). The
fresh-context pass also surfaced that README's "Eight skills" framing
is already stale (omits the existing `issue` utility skill); the spec's
README edit reconciles that rather than assuming a non-existent
agent-roster note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-integration cycle (fc0e1d0..HEAD).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/glossary.md Avoid-lists `release`/`epic` while
profile-schema.md § vocabulary offered the same words as example
slot renamings — opposite verdicts on the same words in two in-repo
docs, with neither stating its scope, reading as contradiction.
Resolution (per the user's steer: the glossary is the new source of
truth for nomenclature): state that authority once, where the
glossary's role is owned. glossary-convention.md now declares the
set glossary the SoT for a project's nomenclature and that its
canonical entry + Avoid list win over any colliding vocabulary
example; profile-schema.md's vocabulary note defers to it with a
pointer rather than restating the rule, keeping the single-sourcing
the architect flagged as clean. The glossary itself is unchanged —
it is the SoT and was already correct.
- [low] CARRY-ON. glossary-convention.md mandates an `**Avoid:** —`
line for synonym-free terms, but no dogfood entry in glossary.md
exercises that arm (all five terms have real synonyms). Accepted as
low-severity documented debt: the rule is unambiguous prose, and
coining a synonym-free term solely to exercise a formatting arm
would be gold-plating. Revisit if a genuinely synonym-free canonical
term enters the dogfood.
What holds: wiring semantics single-sourced at the paths.glossary row;
convention/instance split clean; boss named as the only autonomous
glossary writer; all six spec acceptance criteria landed.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest
run; see docs/pipeline.md § Milestone-close gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pins canonical nomenclature per project so terminology does not drift
and LLM-driven work reuses the established term instead of coining a
synonym each session. The glossary rides the existing standing-reading
mechanism — one optional path slot, no new delivery path.
Single-sourcing, to avoid cross-doc drift:
- `paths.glossary` row in profile-schema.md owns the "set => standing
reading for every role; unset => no-op" semantics; agent-template.md
and pipeline.md each carry one referencing sentence, not a restatement.
- glossary-convention.md owns the format (flat per-term blocks: canonical
heading + Avoid line + <=2-sentence definition) and the boss
record-reality-never-invent write-rule; boss/SKILL.md only points to it.
- glossary.md dogfoods the format on the plugin's own vocabulary
(cycle, milestone, iteration, drift, hard-gate).
Write authority: user any time; boss autonomously but only to record
terms already in consistent use or to settle a drift it just resolved —
never to coin. All other roles are read-only consumers.
No executable surface; this repo has no test runner, so each task closed
on a grep presence-assertion against the file it touched. All eight gates
green (T1 3>=3, T2 5, T3 2, T4 1, T5 1, T6 1, T7 2, final sweep present).
Implements docs/specs/2026-05-31-glossary-integration-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task 1's Step-2 verification grepped for `record reality`, but in the
verbatim convention-doc content those two words straddle a line break
(`...**record` / `reality, never...`), so `grep -c` matched 0 lines and
the gate returned 2 against its own >= 3 expectation — a false BLOCKED on
byte-faithful content. Swap the pattern to `reality, never to invent`,
which matches the unwrapped line and yields 3. Content is unchanged; only
the proxy assertion was wrong.
Surfaced by the implement-orchestrator on first dispatch, which correctly
refused to reflow spec-dictated prose to satisfy the proxy and instead
escalated the plan defect.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan for the glossary-integration spec. Seven tasks
plus a final sweep: create docs/glossary-convention.md and the
dogfooded docs/glossary.md, document the paths.glossary slot in
profile-schema.md, add the commented slot to the project-profile
template, wire one standing-reading sentence each into
agent-template.md and pipeline.md, and point boss/SKILL.md at the
convention's write-rule.
Docs-only cycle: no test runner, so each task closes on a grep
presence assertion calibrated against verified zero baselines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Optional paths.glossary slot: when set, the file is standing reading
for every role (no separate standing_reading.always entry). Adds a
docs/glossary-convention.md single-sourcing the three-field format,
the standing-reading obligation, and the boss record-reality
write-rule; plus a dogfooded docs/glossary.md over the plugin's own
vocabulary. Guidance, not enforcement — no synonym check.
Grounding-check PASS: the one new semantic (paths.glossary auto-
promotion into standing reading) is carried as deliverable wiring,
not assumed to pre-exist.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Correct the cycle vocabulary description, add the milestone container
slot, fix the minimal-profile example, and document the
milestone_fieldtest phase that gates the milestone close.
Define the cycle/milestone distinction and the complete-and-functional
close gate once in pipeline.md; rename audit's cycle-close edge to
drift-clean so it no longer reads as a milestone close.
Nine bite-sized tasks across eight files; pipeline.md as the single
source, fieldtester.md for the milestone carrier, then the referencing
skills and the vocabulary/profile layer, closing with a cross-file
verification sweep.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Separate `cycle` (a pipeline-graph round) from `milestone` (a
Gitea tracker container that closes only when complete AND
functional). `audit` proves drift-clean, never functional, so no
audit signal — and no `/boss` done-state — may close a milestone.
Introduces a milestone-close gate (complete ∧ functional) defined
once in docs/pipeline.md, and a milestone-wide fieldtest as a
carrier-scope variant of the existing fieldtest skill. The
milestone fieldtest runs curated end-to-end scenarios derived
top-down from the milestone's promise — proving the shipped
implementation delivers what the milestone as a whole promised,
not a mechanical union of per-cycle axes. The actual tracker
close stays a manual act; this spec only defines when a milestone
is closeable.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The nested-subagent-dispatch constraint is unchanged in Opus 4.8.
Workflows added a top-level fan-out mechanism alongside it, but a
workflow's spawned agents still cannot spawn further agents. Record
this in both the design rationale and the README capability list so a
future reader does not read the plugin as unaware of Workflows.
Documents a recommended (not plugin-enforced) frontmatter marker for
files under `design_models` / RFCs / proposals:
`status: aspirational` + `validated-against: <sha|"no validation">`,
plus a recommendation that the design ledger distinguish model rows
from contract rows mechanically.
Wires the brainstorm skill to consume the signal: Step 1 notes the
marker when reading model files, Step 4 flags code lifted from an
aspirational source as the spec's most suspect bytes that must clear
the Step-7 parse gate. This is the upstream signal whose downstream
catch is the Fix-1 parse-every-block gate. Adds a Common
Rationalisation and a Red Flag. Missing marker -> signal absent,
graceful degradation, never a hard fail.
Closes the issue #1 hardening set (P0 + Fixes 1-5).
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Defines an optional top-level `spec_validation` profile section: a
registry mapping each markdown fence label to the tool that validates
a spec code block of that kind (`ext` + `cmd`, with a `{file}`
placeholder; exit 0 = clean parse, non-zero = BLOCK). Labels without an
entry are skipped-and-documented; a malformed entry fails closed.
This is P0 of issue #1 — the shared prerequisite for the brainstorm
Step-4 parse gate (Fix 1) and the grounding-check code-block pass
(Fix 2). Contract only; no consumer reads the slot yet.
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fifth skill via the boss pattern. fieldtest empirically tests
whether a shipped cycle is usable by a downstream consumer
who has only the public interface.
Profile gains two slots:
- `paths.public_interface` — list of dirs/files the fieldtester
may read (the project's outward-facing surface: README, design
ledger, docs, examples)
- `paths.fieldtest_examples` — where the fieldtester writes its
fixtures
The forbidden zone is derived: everything not in
`paths.public_interface` (especially `paths.code_roots` and
`paths.bench_dir`) is closed to the fieldtester. This is the
load-bearing source-isolation discipline.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-fieldtester → fieldtester
- "AIL Surface form / .ail" → "the project's canonical
authoring or consumer form"
- "design/INDEX.md + design/models/" → `paths.public_interface`
- "crates/, runtime/, bench/" → `paths.code_roots`,
`paths.bench_dir`
AILang-specific bits dropped:
- The form-a-default-authoring milestone history (2026-05-13)
and the eight `.ail.json` carve-outs — AILang-specific
schema-migration detail; the universal rule is just
"canonical authoring form only"
- The ail check / ail build / ail emit-ir CLI commands — the
fieldtester now uses "the project's user-facing entry point"
- Per-iter journals reference — replaced with recent iter
commit bodies (universal)
- Example ideas calibrated to AILang (FizzBuzz, Newton's method
on Float, JSON-tree depth, ADT functors) — generalised to
"realistic tasks an end-user might be asked to do"
- `design/contracts/0004-feature-acceptance.md` cross-ref —
dropped (AILang-specific contract); the empirical-vs-
prospective brainstorm symmetry survives in prose
Universal substance preserved verbatim:
- All three Iron Law clauses (public-interface-only,
canonical-form-only, record-don't-fix)
- Five-phase process structure
- Four-class finding taxonomy (bug / friction / spec_gap /
working)
- Spec template
- Status protocol (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT /
BLOCKED)
- All 8 Common Rationalisations rows (vocabulary-substituted)
- All 10 Red Flags bullets (vocabulary-substituted, with the
AILang-specific .ail.json hand-write bullet generalised to
"intermediate representations")
The source-isolation contract (Iron Law clause 1) is the
load-bearing discipline. Profile slot
`paths.public_interface` makes it machine-checkable; the
agent's hard limit on opening paths outside that list is the
discipline.
Fourth skill via the boss pattern. audit is the cycle-close
cleanup gate; architect does read-only drift review against
the design ledger; bencher does hypothesis-driven performance
diagnostics.
Profile gains one slot:
- `commands.architect_sweeps` — optional list of project-
specific architect sweep commands. The architect agent runs
these in addition to its universal checks; non-zero exit =
drift suspicions. AILang uses this for the
bench/architect_sweeps.sh design-honesty / history-anchor
/ lockstep-invariant detector.
The existing `commands.regression` slot now does double duty:
the audit skill walks it in Step 2; the bencher agent reads
the failing script for diagnostics.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-architect, ailang-bencher → architect, bencher
AILang-specific bits replaced or removed:
- `bench/check.py && bench/compile_check.py && bench/cross_lang.py`
→ `commands.regression` list
- `bench/architect_sweeps.sh` → `commands.architect_sweeps`
- design/INDEX.md / design/contracts/ / design/models/
→ `paths.design_ledger` / `paths.design_contracts` /
`paths.design_models`
- `bench/run.sh`, `bench/orchestrator-stats/`, `runtime/rc.c`,
`runtime/bump.c` (in bencher) → generic harness / production-
path references
- RC + uniqueness + bump + implicit-mode/explicit-mode
framework (the entire AILang allocator-comparison
calibration) → generic "cost-paying variant vs control"
framing; the hypothesis examples generalised to abstract
perf claims
- The two specific lockstep invariants in architect
(Pattern::Lit::* ↔ pre_desugar_validation; lower_app ↔
is_static_callee) → "the project's CLAUDE.md enumerates
the known pairings; walk each one against the cycle diff"
(the concrete pairings stay AILang-only, in AILang's
CLAUDE.md, not in the plugin)
- The Floats fieldtest "B1 canonical example" reference →
dropped (AILang-specific anchor)
- `design/contracts/0007-honesty-rule.md` cross-ref → dropped
(AILang-specific contract); the honesty principle survives
in the architect's commit-body-truthfulness check
Universal substance preserved verbatim:
- All three Iron Law clauses for audit, architect, bencher
- audit's four-step process; architect's eight-step process;
bencher's hypothesis-first methodology + fixture-pairing
rule + honesty rules
- audit + architect + bencher exit code 0/1/2 semantics
- All Common Rationalisations (5/6/8) and all Red Flags
(5/6/7) rows across the three files, vocabulary-substituted
- bencher's "tie is not a result" doctrine intact
Bencher is the most language-coupled of the seven (was
AILang-allocator-specific). Generalised to a performance-
benchmarker; the discipline (hypothesis-first, design-against
not around, ties-are-bench-info) survives intact. AILang's
RC+bump examples kept in spirit via the generic "cost-paying
vs control" framing.
~/dev/skills/skills/boss/ was visually awkward (skills/skills
read twice) and structurally unnecessary — the skills ARE the
repo's main content, not a sub-collection inside it.
Layout changes:
- boss/SKILL.md moves to the repo root
- skills/README.md (migration notes) moves to docs/migration.md
where documentation-about-the-system belongs
- install.sh discovers skills via the SKILL.md marker file
instead of a hardcoded skills/<name>/ path, so future skill
additions just drop in at the root
Cross-references in boss/SKILL.md (../README.md, ../brainstorm,
etc.) now resolve against the repo root instead of the old
skills/ subdir, which is what they describe: top-level
README is the skill table; sibling skill dirs are the other
migrated skills.
First skill migrated from AILang's in-tree skills/. boss carries
the autonomous orchestrator authority (god-mode: dispatches every
other skill, decides done-state vs bounce-back), so it is the
load-bearing pilot for the migration pattern.
Profile schema gains three slots that boss needs:
- `git.issue_tracker.url` — browsable issue list URL
- `git.issue_tracker.list_cmd` — shell command listing open issues
- `notifications.command` — script invoked on done-state /
bounce-back; falls back to chat if empty
AILang-specific bits dropped from the prose:
- AILang/Gitea URL + tea CLI hardcoding → profile slots
- `design/contracts/0004-feature-acceptance.md` cross-reference
→ project CLAUDE.md (not the plugin's concern)
- "Boss" terminology → "orchestrator" (the plugin term; "Boss"
was AILang vocabulary)
- "Brummel-as-LLM" → "the orchestrator"
- "milestone" → "cycle" (the profile's vocabulary slot)
Universal substance preserved verbatim: Iron Law, the five
process steps, the four bounce-back triggers + new-cycle
rationale, notification protocol, done-state editorial rules,
Common Rationalisations, Red Flags. No discipline-prose compression.
design/out-of-scope claim retracted: boss DOES generalise, and
its body now demonstrates how — the queue mechanic is a single
shell-command slot, not a transport-coupled contract.
skills/README.md flags boss as the landed pilot; the other seven
skills follow once the pattern is approved.
Establishes the repository structure for the skills plugin:
- README + INSTALL describing the two-layer split (plugin
mechanics vs per-project profile)
- docs/design, profile-schema, pipeline, agent-template covering
the universal discipline constants and the profile slot model
- templates/project-profile.yml as a copy-and-fill starting point
- templates/CLAUDE.md.fragment with the baseline orchestrator
rules a project can import
- install.sh / uninstall.sh wiring skills/ + agents/ into
~/.claude/ via idempotent symlinks
- skills/ and agents/ directories empty except for migration
READMEs; the actual SKILL bodies and agent files migrate
from ~/dev/ailang/skills/ in the next iteration.
No skill or agent runs yet — this commit only stands up the
structure and documents the substitution model.
Brummel