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>
Per-skill prose tightening from the same audit swarm; each finding
passed an adversarial second reviewer. No behavioural change.
- audit: drop garbled "Conventions require deferred audits to
compound" sentence (says the opposite of intent; the preceding
line already closes the loophole).
- brainstorm: drop forward-pointing meta-comment about the
Rationalisations table.
- debug: drop third restatement that debugger.md is the single
source for the carrier/handoff fields.
- docwriter: drop motivational opener; Overview starts at the
waste argument.
- fieldtest: fold the 2-4-examples rationale into the dispatch
sentence instead of restating the count a fourth time.
- implement: drop "known platform constraint at the time" aside.
- planner: cut the verbose anti-drift paragraph (which restated
the very table it claimed not to) down to a cross-reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two consistency fixes across the skill suite, both found by a
prose-audit agent swarm.
Trivial-mechanical-edit carve-out: brainstorm and planner each
invented their own bound (≤30 LOC, single file) that contradicts
the canonical definition in the project's CLAUDE.md (which allows
a rename across N files and sets no LOC ceiling) and disagreed
with implement. Both now reference that carve-out instead of
restating a divergent shape.
Parse-block gate: brainstorm Step 7 and planner Step 5 spelled out
the parser-invocation protocol near-verbatim. Both now defer to
docs/profile-schema.md, which owns the protocol, and keep only
their skill-specific parts (target artefacts, failure semantics,
where the parse-trace goes) — matching the single-sourcing the
carrier contracts already use.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Apply the debug-skill pattern (commits 6410732..de42974) to the
remaining skills: the agent file is the single source for each
interface field's semantics; the SKILL.md copy is reduced to field
names plus a pointer, marking the agent's contract table
authoritative. Because SKILL.md loads into orchestrator context and
agents/*.md into the subagent's fresh system prompt with no
transclusion, duplicated field tables drift apart over time.
- brainstorm: carrier (spec_path/iteration_scope) -> grounding-check;
the absolute-path requirement now lives only in the agent.
- planner: carrier (spec_path/iteration_scope/focus_hint) ->
plan-recon, including the mandatory/optional markers and the
BLOCKED-on-missing rule SKILL.md had omitted.
- fieldtest: carrier + produced fields -> fieldtester; the skill-level
`status` roll-up (clean/friction_found/bugs_found/infra_blocked),
which is not part of the agent's run-status protocol, stays defined
in SKILL.md only.
- docwriter: carrier + produced fields -> docwriter agent.
- implement: carrier (iter_id scratch-dir/stats/not-a-branch
semantics) -> implement-orchestrator; per-task sub-status vocabulary
moved into the orchestrator-agent (it runs the loop in a fresh
context and could not read SKILL.md at runtime, yet referenced "the
sub-status table" by name); task_text_path single-sourced in
implementer with spec-reviewer cross-referencing.
audit was already the reference implementation (pointers, no restated
contracts) and is unchanged.
closes#2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Adds a third pass to the grounding-check agent: when the profile
declares `spec_validation.parsers`, every fenced spec block whose
fence label has an entry is run through its parser (temp file + `ext`,
`cmd` with {file}); a non-zero exit marks the block unparseable and
the aggregate status becomes BLOCK. Complementary to the existing
test-ratification search (checks the spec's own bytes, not codebase
behaviour) and independent of the orchestrator's Step-7 gate (Fix 1) —
a fresh-context second line of the same defense.
Amends the Iron Law to permit per-block parser runs (same read-only
spirit as test-list/type-check), adds an "Unparseable code blocks"
report section, a Common Rationalisation, a Red Flag, and the agent
description.
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds self-review check #6 to brainstorm Step 7: when the profile
declares `spec_validation.parsers`, every fenced spec block whose
fence label has an entry is written to a temp file (entry `ext`) and
run through the entry `cmd` ({file} substituted); non-zero exit is a
self-review failure that must be fixed before the spec proceeds. The
parse-trace goes into the brainstorm chat as the attestation the gate
fired. Labels with no entry are skipped-and-documented; a malformed
entry surfaces as a profile error; no `spec_validation` -> no-op.
Placed in Step 7 (not Step 4 as the issue's prose suggested) because
the spec file — and thus its code blocks — exists only after Step 6;
Step 7 also already re-runs on post-PASS edits, so a changed block
re-triggers the gate for free.
Also adds a Common Rationalisation ("it obviously parses") and a Red
Flag (configured parser, no trace in chat).
refs #1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Three minor-issues + three optional follow-ups identified by
the three parallel reviewers of debug/docwriter/audit,
fieldtest/planner/brainstorm, and implement. None blocking;
all close calibrated gaps the bulk migration left.
Minor-issues:
- audit/SKILL.md: handoff field `regression_results` now
explicitly carries "raw output verbatim (no rounding, no
summarisation)" — restores the verbatim-numbers emphasis
the original `bench_numbers` field name implied.
- audit/agents/bencher.md: hypothesis examples grouped by
axis (Tail-latency / Count reduction / Scalability /
Overhead vs floor) with concrete numerical anchors (2× of
median, ≥80%, 10-million-element, ±15%). Subjects stay
domain-neutral but the calibrated bite returns. The
preamble enumerates plausible subjects (allocators, query
plans, request handlers, parsing strategies, codecs,
caches) so the reader has concrete domains to anchor on.
- implement/agents/implementer.md: "Architecture rules"
section gains a 5-bullet kind-list (determinism contracts;
backend / FFI constraints; schema versions; memory /
resource models; effect / capability discipline) so the
implementer has scaffolding to look for even when the
project's CLAUDE.md is sparse. The "BLOCKED on
contradiction" mechanism stays the load-bearing rule.
Optional follow-ups:
- brainstorm/SKILL.md Step 7.5: failure-mode procedure
restores the structured backlog-issue fields (Title /
Label / Body with `depends on:` and `context:` lines)
and the milestone-container option for big deferred work
(Gitea milestones, GitHub milestones, Linear projects).
- templates/CLAUDE.md.fragment: adds an optional
"Lockstep-invariant pairs" section so projects that have
cross-file pairings can declare them in a way the
architect agent and plan-recon agent already know to
consult. Projects without such pairings omit the section;
both agents handle absence gracefully.
No discipline regressions; no Iron Law / Common Rationalisations
/ Red Flags edits. Pure scaffold-and-anchor improvements.
Seventh skill via the boss pattern. brainstorm is the
spec-generation hard-gate; grounding-check is its Step-7.5
read-only assumption-ratification reviewer.
Vocabulary substitutions:
- AILang → "this project"
- milestone → cycle
- Boss → orchestrator
- ailang-grounding-check → grounding-check
- "the AILang program" / ".ail Form-A" → "the user-facing
program in the project's canonical authoring/consumer form"
- "Brummel (orchestrator) + Claude" → "orchestrator + Claude"
AILang-specific bits dropped or generalized:
- `docs/specs/<milestone>.md` / `docs/plans/` → `paths.spec_dir`
/ `paths.plan_dir`
- AILang feature-acceptance criterion's three specific clauses
(LLM-author-reaches-for-it, measurable correctness/redundancy
improvement, no-reintroduction-of-core-constraint-bug) →
"the criterion declared in the project's CLAUDE.md", with the
three typical-shape clauses retained as illustrative
- `design/contracts/0004-feature-acceptance.md` cross-ref →
pointer to project CLAUDE.md
- "AILang's own thesis is structured concrete form over prose
description" → "concrete code first, prose second" (the
discipline survives without the project-thesis hook)
- The 2026-05-11 incident date → generic "recurring failure
mode" framing (the discipline survives without the date)
- `tea issues create --repo Brummel/AILang` → "the project's
issue-tracker create command (typically tea/gh)" with both
examples shown
- `cargo test --list -p <crate>` / `cargo check` → "the
project's test-list / type-check command" with Rust example
- `crates/*/tests/`, `crates/*/src/**/tests.rs`, `examples/`
→ derived from `paths.code_roots` and the project's examples
/ fixtures convention
- The `Spec-23 / prelude free-fn ne / typeclass elaboration`
worked example → generic "spec section that proposes
adding to a table or extending a pass without stating that
the existing entries / passes cover the new shape"
- AILang skill-system index reference (`skills/README.md`)
→ `../../README.md` (plugin's top-level)
- "Form-A / .ail / monomorphised compare__T symbol" examples
→ generic "function names, type names, schema fields, pass
names" example
Universal substance preserved verbatim:
- The hard-gate (3 lines) — NO IMPLEMENTATION UNTIL SPEC
APPROVED
- Nine-step process (explore context → clarify Q&A →
propose 2-3 approaches → apply feature-acceptance → present
in sections → write spec → self-review → grounding-check →
user-review-gate → hand off)
- "Concrete code first, prose second" discipline
(the universally-applicable form of what was the
AILang-thesis hook)
- "The criterion is unjudgeable without concrete code" rule
(universal good practice; project's CLAUDE.md picks the
specific criterion)
- Spec structure (Goal / Architecture / Concrete code shapes
/ Components / Data flow / Error handling / Testing strategy
/ Acceptance criteria)
- Step-7 self-review checklist (5 items)
- Step-7.5 grounding-check dispatch + PASS/BLOCK/INFRA_ERROR
three-way classification + failure-mode procedure + re-
dispatch on post-PASS edit rule
- All 8 Common Rationalisations rows
- All 9 Red Flags bullets
- grounding-check's six-step process incl. assumption
extraction, search design, ratification classification,
aggregate status computation
- grounding-check's Iron Law (5 lines), output format (exact
layout preserved), 6 Common Rationalisations rows, 8 Red
Flags bullets
The brainstorm is the largest skill in the migration (366 →
355 lines after substitutions). Calibrated discipline kept
intact per memory feedback_dont_strip_repeated_discipline.md:
"concrete code first" + grounding-check hard-gate + "re-
dispatch on post-PASS edit" are the load-bearing rules; all
survive verbatim except for project-specific identifiers.
Brummel