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
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.
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>
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>
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.
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