Two roll-ups were vacuously satisfiable by a no-op and guarded only in
agent prose, never re-verified at the consuming gate:
- The milestone-close functional leg trusted a fieldtest `clean` roll-up
even from a run with zero examples. The gate now requires
examples_added >= 2 for a `clean` to be honoured (the empty-report and
internal-milestone escapes are preserved); a `clean` with fewer over
user-visible surface is itself a `spec_gap`.
- The audit carry-on accepted an architect `clean` with no evidence of
review. It now requires a non-empty "What holds" (added as an explicit
handoff field); a bare `clean` with nothing held — worst when no
regression scripts run, so the architect is the sole gate — reads as
unreviewed and is re-dispatched.
Both are second-layer checks: the consumer verifies the field rather
than trusting the agent's discipline. Lower-severity defense-in-depth,
not code-level floors (milestone-close and audit carry-on are
orchestrator-judgment acts with no script to instrument).
closes#14
Step 5 emitted PASS on "all assumptions ratified", which is vacuously
true when the extraction yielded nothing. Under /boss a grounding PASS
IS the autonomous spec signature, so an under-extraction on a real spec
(zero assumptions -> PASS) would auto-sign an unread spec.
An empty assumption list is now a PASS only on a demonstrably trivial
spec (pure rename / doc-only / cosmetic, with the kind named as positive
evidence). An empty extraction over a spec that adds or changes
behaviour is an under-extraction -> BLOCK, which routes the spec to the
human sign-off pause it should have hit. Tightened consistently across
Step 5, the Iron Law, the trivial-spec clause, the Status protocol
table, and the Common Rationalisations.
closes#13
The #11 vacuous-green shape on the main path: `outcome = DONE` was set
purely from the absence of a BLOCKED task, with no check that the
iteration actually wrote anything. `files_touched` was even computed by
the finalize agent but never asserted > 0, `e2e.status` was never read,
and in mini mode the handed-off RED test was never independently re-run
(GREEN was asserted from the implementer's self-report, never observed).
Add a positive-evidence precondition on DONE, taken from git ground
truth — never a self-report, which must not be able to fail a run that
actually did the work:
- Standard mode: a dedicated `tree-check` agent runs `git status
--porcelain | wc -l` after the per-task loop but BEFORE E2E/finalize.
Zero (or a non-returning agent) downgrades DONE to BLOCKED. `git
status --porcelain` (not `git diff HEAD`) so a brand-new untracked
file — the implementer leaves edits unstaged — still counts; running
pre-E2E/finalize keeps fixtures and the stats/BLOCKED.md artefacts
from inflating it.
- Mini mode: an independent `mini-verify` agent re-runs the RED test by
name and the suite and checks the tree is dirty; a still-red test, a
regression, or a clean tree is BLOCKED (route back to debug).
- Per-task `applied_changes` (OR-ed across the initial dispatch and
every repair) feeds only a neutral concern, never the outcome.
- `e2e.status` is now read: a non-DONE status or a zero-fixture run
surfaces as a concern.
A clean-tree no-op is BLOCKED with no BLOCKED.md (nothing to clean up);
the status + reason ride the end-report. SKILL.md documents the
precondition, the no-BLOCKED.md carve-out, and the Step-4 handling.
closes#12
The done-signal `build_clean && suite_green_unchanged` was vacuously
true on a clean working tree, so a no-op edit (the edit agent touched
nothing and reported sites: 0) read as DONE. An orchestrator trusting
that verdict would "commit the unstaged changes" — committing nothing
under a DONE banner.
Add positive evidence that an edit actually landed, checked at two
independent points:
- Phase 1 (cheap, pre-suite): the edit agent reports `applied_changes`
as ground truth from `git status --porcelain` / `git diff HEAD`. No
hole + clean tree -> distinct BLOCKED (kind: no-op-edit), skipping a
pointless suite run against an empty tree.
- Phase 3 (authoritative backstop): DONE now also requires the verify
agent's independent `working_tree_dirty` observation. The verify
agent never sees the edit agent's self-report, so a false
applied_changes is still caught. A green build+suite over a clean
tree routes to the same BLOCKED, not to debug (a clean tree is no
regression — nothing to reproduce RED-first).
The precondition keys on tree-dirty, not sites > 0: a legitimate
behaviour-preserving edit can touch only the definition site (sites: 0)
and still dirty the tree. Also fix the DONE note to report a legitimate
sites: 0 as 0 rather than coercing it to null.
closes#11
The per-task quality re-loop treated every `changes_requested` as
"deviate to satisfy", and the quality-repair dispatch was not even
given the task text. When a finding's only remedy contradicted a
plan-prescribed name/signature, the implementer renamed off-plan, the
next review flagged "diverges from plan", and the loop oscillated
name-misleads <-> diverges-from-plan until the retry cap, emitting a
false BLOCKED on code that was green the whole time.
Fix (issue's option 2 — the plan knowledge lives with the implementer,
which holds the task text; the quality-reviewer is deliberately blind
to it, so option 1 would have breached that separation):
- The quality-repair dispatch now receives the task text and a HOLD
CLAUSE. A cosmetic finding (plan kept => build+tests green) is KEPT
and recorded in a new `held` field; the loop surfaces it as a concern
instead of chasing a deviation. A finding the implementer judges
correctness-breaking escalates to BLOCKED, never a silent hold.
- The hold is keyed on two structural signals, never on a self-reported
status enum (which the implementer contract overloads): the `held`
array, and a no-op backstop over a required `diff_fingerprint` (a
changes_requested verdict over an already-seen diff-state means the
repair was a no-op or cycled back — re-running quality is futile).
Fingerprints are tracked in a Set so A-B-A edit-then-revert is caught.
- A no-op-backstop concern is labelled neutrally (a byte-identical diff
cannot tell a principled plan-hold from an ignored bug); implement
SKILL.md Step 3 now routes a held/unresolved quality finding to
orchestrator hand-verification before committing, even under /boss.
The held/no-op partition is the implementer's judgement, not enforced
in code — the residual fail-open is bounded to cosmetic-on-green
findings and disclosed, with the orchestrator's Step-3 inspection as
the backstop, the same trust placed in its other self-reports. Verified
across three rounds of adversarial review (held-the-plan paths, fail-
open laundering, schema/Set mechanics) — all closed.
closes#10
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.
Add a 'Render diagrams and formulas natively' section to the wiki skill:
prefer native Mermaid for diagrams and KaTeX ($...$) for formulas over ASCII
art / unicode-in-code, as the default (but not for the sake of it). Records the
mechanics learned in practice — Mermaid label/colour discipline and real-render
validation; KaTeX as a LaTeX-math subset, dollar-only delimiters, the table
pipe/percent escapes, and the closing-$-glued-to-slash boundary trap — plus the
two-gate validation discipline (parser gate + Gitea render-parity, table
integrity, adversarial semantic-equivalence), since valid != correct != rendered.
Also a checklist item and a description clause.
Standalone utility skill (manual /wiki, not a pipeline phase). Fixes the house rules for repository-wiki articles: durable project-neutral knowledge only (no implementation state — that belongs in docs/), every load-bearing fact backed by a validated external source, claims marked law/convention/corrected, an overview page plus cross-linked detail pages each with a References section, written in English. Documents the wiki mechanics (own <repo>.wiki.git, slugs, edit paths, special files) and the wiki-vs-docs/ decision rule.
README: list `wiki` among the on-demand utility skills, kept out of the pipeline table.
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>
boss pointed at 'the project's CLAUDE.md' as the sole source of
universal rules, in both the Iron Law and the cross-references.
That misses the user-level ~/.claude/CLAUDE.md identity/security
layer, which the dev architecture documents as loaded in every
session above the project file — and which carries the most
autonomy-relevant binding of all: external-service-consent rules
that explicitly name /boss and that autonomy does not lift.
The asymmetry was one-directional: the user-level file is
boss-aware (it constrains /boss by name), but boss was not
user-level-aware. Reference both layers so a reader deriving
'what binds me' from boss alone cannot miss the top layer. No
user-specific content is encoded — the consent rule is named
generically and portably.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Forbid the footnote/legend pattern: explanations for a marked
line must live inline at that line (rule 2), never in a
post-block `[1] = …, [2] = …` key that forces the reader to
bounce between code and a legend below it. A marker is purely a
label so the user can point ('expand [2]'); a line that reads
for itself carries a bare marker and no comment.
Rework rule 4 accordingly, add the Iron Law line, guard rule 1's
supporting-prose clause against becoming a legend, and rewrite
the worked example's trailing commentary to demonstrate inline
explanation with no marker key. Frontmatter and README updated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add rule 2: comment only what the code cannot say itself;
self-explanatory pseudocode needs none. Put any comment on its
own line above the code; reserve trailing end-of-line comments
for the briefest notes (a bare marker, one or two words), since a
column of trailing prose scans worse than a short note above.
Rework rule 4 (markers) so the bare marker rides trailing while
any explanation it needs moves to an own line. Renumber the rule
list (now 1-10) and fix the mechanics->reduce cross-reference.
Iron Law, worked example, frontmatter, and README updated to
match; the example now demonstrates the sparse-comment style.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the hard one-screen length limit entirely; replace the
former cap (rule 9) with a single-altitude guidance that leans
on the reference markers to let the user steer the zoom instead
of a fixed length.
Loosen the prose ban: prose is now allowed, but only in a
supporting role — the pseudocode block stays the centre of every
answer and prose explains what the code cannot show on its own.
Iron Law, overview, rule 1, worked example, frontmatter, and
README updated to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add rule 7: alongside the control flow, sketch the layout of the
data structures the code in focus reads or builds — record
fields, collection nesting, variant cases relevant to the
question — placed beside the code that touches them and reduced
in the same spirit (only the fields on the topic path). When the
data layout is the question, it leads and the flow becomes the
stub. Iron Law, worked example, frontmatter, and README updated
to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A user-invoked conversational skill: while active, every reply
explains code in commented, human-readable pseudocode instead of
prose. Each answer opens with a source-file-and-approximate-line
anchor, tags notable steps with reference markers ([1], [A]) the
user can point back at, reduces off-topic paths to stubs, omits
low-level mechanics unless asked, defaults to the project main
entry, and never runs longer than one screen.
Dispatches no agents and runs no pipeline; documented in the
README as a conversational skill standing outside the pipeline.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the price-table cost derivation entirely. The transcript carries
no metered cost, and list prices vary by plan — so converting tokens to
a dollar figure dressed an estimate up as a number. Report raw token
counts instead, kept split by class (input / output / cache-creation /
cache-read) with a `total_tokens` sum per scope.
Script: drop DEFAULT_PRICING / load_pricing / rate_for / cost_of and the
--pricing flag; aggregate_transcript and analyze_subagents no longer take
a pricing arg; every `cost_usd` field becomes `total_tokens`; the pricing
warning is gone. SKILL.md: the first graded axis is now "Token spend &
efficiency", the scorecard and output format cite token counts, and the
Iron Law / Red Flags now forbid converting tokens to a cost.
cache_hit_ratio and the active-session warning are unchanged.
The subagent terminal-status classifier scanned the whole final report
text for status keywords, so `\bBLOCKED\b` fired on the implement
end-report's own template lines (`BLOCKED file: BLOCKED.md`,
`Blocked detail:`) and on prose narrating a surmounted blocker. Shipped
implement runs whose end-report reads `Status: DONE` were flipped to
BLOCKED — making the agent-effectiveness axis actively misleading.
Anchor on the structured `Status:` line of the end-report instead (the
implement-orchestrator emits a fixed `Status: DONE|PARTIAL|BLOCKED|...`
header, optionally markdown-bold). Fall back to a status token standing
alone on its own line for agents that emit a bare terminal token; prose
mentions and `BLOCKED.md`-style substrings no longer match. Agents with
no structured status now read `unknown` rather than a fabricated BLOCKED.
Add an executable spec (postmortem/tests/test_terminal_status.py, plain
asserts, no pytest dep) pinning the issue-#3 case plus the genuine
BLOCKED / bare-token / no-signal guards. RED before, GREEN after.
Verified on the real AILang-style session 2811d227: 3 BLOCKED (one a
false positive) -> 2 genuine BLOCKED + 13 honest unknown.
closes#3
The postmortem skill writes per-run reports under docs/postmortems/.
Those are session artifacts, not source — ignore them so running the
skill inside this repo leaves no tracked output.
A new utility skill that grades a finished session on three axes —
cost & efficiency, toolchain health, agent effectiveness — from the
session's own Claude Code flight recorder (the JSONL transcript plus
one sidechain log per dispatched subagent).
The heavy lifting lives in scripts/postmortem.py, a stdlib-only,
read-only aggregator. It handles the two accounting traps the raw log
sets: usage is repeated per streamed assistant line under a shared
requestId (deduped max-per-field, then summed across requests), and
the transcript carries no costUSD/durationMs (both null) — so cost is
derived from tokens x an overridable list-price table and labelled an
estimate, wall-clock from timestamp deltas. Subagent spend is billed
separately from its own usage objects and graded by terminal status.
Single-session by design: defaults to the newest transcript in the
project's log dir (flagged active if still live), or --session <id>
for a finished run. Secret files are out of bounds in both the Iron
Law and the Red Flags.
Verified end-to-end against a real 15-subagent session.
Step 3 framed `tdd` as a conditional add-on ("if the profile enables
the tdd phase, dispatch tdd") while `brainstorm` read as the default
spine. The orchestrator inherited that tilt and routed feature work to
`brainstorm` by reflex.
Replace it with an explicit Entry-path reflection run before every
feature dispatch: the two are co-equal, the choice is made per item by
the design line, and the one-line verdict is recorded in the loop. The
autonomy asymmetry (tdd proceeds, a fresh brainstorm cycle bounces
back) is reframed as a context-budget consequence, not a ranking, with
a guard against hardening it into an "im Zweifel brainstorm" reflex.
The one principled tilt now lives inside the test: genuine doubt that
one assertion can pin the behaviour is itself the design-fork signal.
Add two rationalisation rows and a red flag naming the default-to-
brainstorm bias.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The tdd skill referenced its neighbours (implement, brainstorm,
debug) but none referenced it back. Close the loop so the new
executable-spec-first entry path is reachable and consistent from
every skill that describes a relationship it now belongs to:
- implement: mini-mode trigger + dispatch example now cover a
RED-first handoff from `debug` OR `tdd` (was debug-only); the
orchestrator's task template and Phase-3 skip note generalised.
This was real drift — mini-mode is no longer debug-exclusive.
- planner: skip rule gains the `tdd` case (it skips brainstorm
AND planner — the RED executable-spec is the plan).
- brainstorm: `tdd` added to the permitted-skip list as the
profile-gated alternative entry path, plus a cross-ref marking
brainstorm as the bounce-back target when behaviour stops being
test-specifiable.
- boss: pipeline diagram, Step-3 routing prose, and cross-refs.
A test-specifiable feature issue is dispatched to `tdd`
autonomously, the same way a bug issue goes to `debug`; this is
NOT a new-cycle bounce-back (the test is the spec). The
bounce-back fires only reactively, when tdd surfaces a genuine
design fork.
- debug: reciprocal sibling note + cross-ref (new behaviour is
tdd's job; debug is for regressions of existing behaviour).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rule 2 (validated-or-flagged) now suggests dropping in a fenced code
snippet where it sharpens the point — the input that triggers the
failure or the call as it should behave — preferred over a prose
paraphrase.
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>
Brummel