The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
Third and terminal iteration of the standalone loop/recur
milestone (plan eae73bf). Replaces the iter-1 lower_term
CodegenError::Internal stub for Term::Loop/Term::Recur with real
LLVM-IR lowering: loop binders as entry-block allocas (mut.3
pending_entry_allocas, reusing mut_var_allocas so the existing
Term::Var load path is byte-unchanged), a fresh loop-header block,
recur stores + back-edge br, a loop_frames stack saved/restored at
the lambda boundary. clang -O2 mem2reg promotes the allocas to
phi. Four Boss design calls implemented verbatim and journalled
(alloca-not-hand-phi; mut_var_allocas reuse; emergent loop-exit
via the if/match join; single block_terminated field + parallel
SET site). Diff confirmed surgical: codegen/lib.rs 3 hunks (field
+ init + stub->2-arms), lambda.rs 2 hunks (save+restore); zero
edits to any existing block_terminated SET/READ site, tail-app
lowering, or verify_tail_positions (Boss call 4, the spec-pinned
invariant). Three new .ail fixtures: sum_to->55,
deep-n 1e6->500000500000 (clause-2 correctness made executable),
infinite-loop build-only. Codegen-only: no schema/typecheck
change; hash pins + drift trio stay green untouched.
One DONE_WITH_CONCERNS (T3): the plan's `cargo test ... tail`
filter resolved to no tests; ran via real names + the full 619/0
which subsumes it (feedback_plan_pseudo_vs_reality class, no
behaviour change). Boss systemic fix folded in: planner SKILL.md
Step-5 gains item 8 (verification-command filter strings must
resolve) — the second planner-meta-gap this milestone surfaced.
cargo test --workspace 616 -> 619 / 0 red (Boss-reran
independently); the 3 loop/recur e2e explicitly green. All three
components shipped: the loop/recur milestone is structurally
complete. Milestone-close audit + fieldtest is the next step.
Second of three iterations of the standalone loop/recur milestone
(plan 5ac57fe). Replaces the iter-1 synth CheckError::Internal stub
for Term::Loop/Term::Recur with real binder typing + positional
recur arity/type checking via a new loop_stack: &mut Vec<Vec<Type>>
frame threaded as mut.2's mut_scope_stack, a new private
verify_loop_body tail-position pass (sibling of the byte-frozen
verify_tail_positions — 0 deletions there), and the four Recur*
diagnostics firing point-exactly on four negative fixtures. The
iter-1 loop_sum_to.ail fixture now also typechecks clean; an
infinite loop typechecks (no termination claim). NO codegen (the
iter-1 lower_term stub stays — iter 3); NO Diverge/guardedness
(spec boundary).
Three Boss design calls implemented verbatim and journalled:
RecurTypeMismatch is an Assign-style structural pre-check (not a
unify-propagate); loop_stack is positional Vec<Type> (binder names
via ordinary locals); diagnostic-code precedence is by pass
ordering (no explicit logic).
Two DONE_WITH_CONCERNS, both journalled: a plan-ordering defect
(Task 2's compile gate forced the check_fn threading the plan
deferred to Task 4 — resolved byte-identically, only resequenced)
and the recurring mut.2-class recon-undercount of cross-module
synth callers (resolved via the plan's compile-sweep oracle).
Boss systemic fix folded in: planner SKILL.md Step-5 gains item 7
(compile-gate vs. deferred-caller ordering) so the plan-ordering
defect class is scrubbed at plan time. cargo test --workspace
608 -> 616 / 0 red (Boss-reran independently).
Recurring-class plan defect, now twice (iter-revert Concern 2;
iter effect-doc-honesty Task 2): a presence-pin asserts a
single-line contains()/grep substring while the verbatim
replacement body that must contain it soft-wraps the substring
across two lines — two authoritative artefacts that cannot both
be applied literally. The implementer absorbs it (preserve
wording + pin, move the wrap column) but it is a planner
self-review miss, not an implementer judgement call. Add an
explicit Step-5 checklist item so plans pairing a presence-pin
with a verbatim text edit are scrubbed before handoff.
The effect-op-arg-modes brainstorm spec bundled a real, self-contained
DESIGN.md honesty fix with speculative build-ahead infra (an EffectOpSig
arg-mode field whose only consumer was a synthetic test op). Recon had
already destroyed the "effect-handler infrastructure" premise: the effect
raise/declare/subset/propagation machinery is fully generic over any
effect string; the only real prerequisite was one struct field, not a
milestone. The user rejected the bundle as incoherent and the
build-ahead half as the iteration-discipline trap repeated.
- Retire the uncommitted effect-op-arg-modes spec (deleted from the
working tree; never committed).
- roadmap: drop the false "sub-ms-2 = effect-handler infrastructure"
framing; mark Stateful-islands sub-milestone sequencing as UNDER
RE-THINK with the user (no !Mut planning until that conversation);
add the split-out effect-doc-honesty as an in-flight P2 [~] todo.
- plan docs/plans/2026-05-16-effect-doc-honesty.md: placeholder-free
tidy plan (the three DESIGN.md fictions + form_a.md + main.rs +
a new doc-presence pin) over recon-mapped exact byte sites.
- brainstorm SKILL: specs and design talk LEAD with the AILang (.ail)
program that should work (= the feature-acceptance clause-1
evidence); the Rust implementation shape is secondary, never a
substitute; a no-surface infra milestone still shows concrete .ail
(often a must-fail fixture). Codifies user feedback from this session.
One forward iteration; main never rewound. 1ff7e81 (the pre-9973546
commit) is the per-region byte oracle — every reverted source/test
file is byte-identical to it; crates/ailang-check/src/lib.rs fully so.
Root cause being corrected: the Iteration-discipline milestone was an
over-escalation of fieldtest finding F1 (a [friction] item whose own
minimal recommendation was a DESIGN.md note). Its totality dichotomy
made the maximally-LLM-natural build(d:Int)=Node(1,build(d-1),
build(d-1)) inexpressible (it.3 BLOCKED); the only in-thesis escape
(A1/it.2b) conceded the language's first documented-unenforced
totality precondition — a purity-pillar dilution the user rejected in
favour of a full revert + rebuild.
Removed: Term::Loop/Term::Recur/LoopBinder; the verify_structural_
recursion guardedness pass + term_contains_loop + Diverge-injection +
the transitively-it.2 module_fns plumbing; the five Recur*/
NonStructuralRecursion CheckError variants (+ code() + the 3 dedicated
ctx() arms); the it.1 codegen loop-header/phi/back-edge + parallel
block_terminated setter; all Loop/Recur walker arms; 16 it.1/it.2
fixtures; 2 pin files; bench/it3-oracle/. Restored: 2 RC fixtures to
1ff7e81 content.
Surgically kept (not in 1ff7e81, landed with the milestone but
independently sound): feature-acceptance clause 3 in DESIGN.md and
skills/brainstorm/SKILL.md, with its worked example de-claimed from
"shipped" to hypothetical-illustration form; the F3 P2 todo.
bench/orchestrator-stats/2026-05-15-iter-it.{1,2,3}.json kept as
historical record (like journals/plans).
Sole net addition: an honest F1/F4 documented-idiom note in DESIGN.md
(the tail-recursive accumulator fallback; examples/mut_counter.ail),
guarded by a doc-presence test — "a documentation note is not a
reshape", asserts nothing at the typecheck level.
Roadmap: the Iteration-discipline block + blocking-fork section
removed; the genuine total-Int-recursion ambition preserved as a
deferred P2 milestone sequenced behind a future Nat/refinement-types
milestone (not abandoned — correctly sequenced after the type
machinery it needs). 2026-05-15-iteration-discipline.md carries a
superseded header; it.1/it.2/it.3 journals + plans stay as history.
Correctness gate PRISTINE: 164 surviving 1ff7e81-era fixtures
ail check/ail run byte-identical to pre-milestone behaviour (verified
against a 1ff7e81 worktree reference compiler, zero drift);
cargo test --workspace 600/0; zero residual it.1/it.2 production
surface.
Spec docs/specs/2026-05-16-iteration-discipline-revert.md (b3853bf),
plan docs/plans/2026-05-16-iter-revert.md (abf0013).
Sharpen the feature-acceptance criterion (DESIGN.md, mirrored in the
brainstorm gate) with a third conjunctive-necessary clause: a feature
reintroduces no bug class the core constraint exists to eliminate.
Criterion 1 ("an LLM reaches for it") does not discriminate — an LLM
reaches for every construct native to its imperative training
distribution, so utility alone would launder the imperative paradigm
back in one construct at a time. Clause 3 is the discriminator; a
documentation note is not a reshape (the gate is whether the wrong
code fails to typecheck).
Record the decided iteration story as a P1 milestone: structural
recursion permitted (total-by-construction under Decision 10's
acyclic-ADT invariant) + named loop/recur as the only other
repetition + tail-app retired. Discharges fieldtest finding F1 without
introducing an imperative construct; closes the residual "forgot to
mark tail" trap completely; unifies with Decision 10 (acyclic values
AND acyclic implicit call graph). Supersedes the "while-loops legal"
scope bullet of the Stateful-islands milestone, which is amended for
internal consistency. The escaping-state path (ref/MutArray/Stateful)
is unaffected and stays in Stateful-islands.
Boss-dispatched fieldtest at milestone close. Agent authored 4 .ail
fixtures (factorial smoke + Show user-ADT + user-class Describe with
two instances + two-module workspace) from DESIGN.md + form_a.md only
(no compiler-source reads, no spec-of-milestone reads). All four
fixtures `ail check` ok and `ail run` produces expected stdout.
Findings (1 bug, 1 friction, 2 spec_gaps, 3 working):
- [bug] instance-method-body unbound-var bypasses `ail check` —
forma_3 first attempt called `str_concat` inside the instance
method body; `ail check` returned ok, `ail build` died with the
monomorphise_workspace "unknown identifier" diagnostic. Same
shape at fn-body level correctly fires `[unbound-var]` at check
time. Next: debug skill, RED-first against `ail check`.
- [friction] no `str_concat` primitive. Every realistic Show MyType
body wants string concatenation; the absence forced the agent to
shape examples around bare int_to_str / ctor-arity-1 patterns.
Next: small planner tidy iter wiring `str_concat` symmetric to
`str_clone` and `int_to_str`.
- [spec_gap] form_a.md has zero references to class, instance,
constraint, or method productions — pre-22 surface only. The
form-a-default-authoring milestone made .ail the authoring form,
but the form_a spec doc remains pre-typeclass.
- [spec_gap] form_a.md leaves the class-qualifier ambiguity in
`(instance (class X))` unspecified — bare-class-name vs canonical-
form rule from mq.1 is not documented at the surface level. The
agent picked the bare-name reading from the corpus; the canonical-
form reading is equally plausible from the schema.
Boss-side cleanup at commit time:
- Deleted 8 stale .ail.json sidecars in examples/fieldtest/ (4
forma_* derived by the fieldtester per old dual-form workflow + 4
pre-existing floats_* from the prior fieldtest milestone that
iter form-a.1 T8 missed because the bash deletion loop globbed
only examples/*.ail.json direct children).
- Updated skills/fieldtest/agents/ailang-fieldtester.md to remove
the now-obsolete "generate canonical JSON sidecar" step (Phase 3
rewritten + Iron Law + Reading list + Common Rationalisations +
Red Flags all aligned to the post-form-a single-form doctrine).
cargo test --workspace: 557 passed, 0 failed, 3 ignored (unchanged
from audit-form-a — the fieldtest fixtures are standalone, not
referenced by any test).
Findings deferred to follow-up iters; the milestone close itself is
still clean.
Cross-milestone hops are high-context work and I cannot compact my own
context window. Adding a `brainstorm`-on-an-unspec'd-roadmap-item rule
that forces a bounce-back lets the user decide whether the next
milestone wants a fresh session or a continuation of the current one,
instead of consuming tens of thousands of tokens on a fresh spec Q&A
on top of whatever the just-closed milestone left behind.
Mechanics: Iron Law gains a fourth clause; Direction-Freedom-Bouncebacks
list a fourth trigger with the rationale spelled out; Step 3 reroutes
"new milestone → brainstorm" through the trigger; Problem-state
notification list, Common Rationalisations, and Red Flags all gain
the corresponding entries.
The surface-form file extension changes from .ailx to .ail. AILang's
authoring surface now uses the same .ail stem as its canonical JSON
form (.ail.json), giving the language a single coherent extension
family: .ail is the LLM-authored Form A, .ail.json is the canonical
JSON-AST Form B.
Scope (touched):
- 61 example renames examples/**/*.ailx → .ail (git mv)
- 1 rename experiments/.../rendered/ailx.md → ail.md
- 35 content-edited live-toolchain files (crates/, docs/DESIGN.md,
docs/roadmap.md, docs/PROSE_ROUNDTRIP.md, skills/, bench/reference/*.c,
experiment crates under experiments/.../{render,harness,master})
- Experiment-crate cohort rename Cohort::Ailx → Cohort::Ail,
Form::Ailx → Form::Ail, per_cohort/ailx → per_cohort/ail,
{form-only: ailx} → {form-only: ail}, ```ailx → ```ail
Out of scope (deliberately untouched, to preserve honest history):
- docs/journal-archive.md (content-frozen per CLAUDE.md)
- docs/journals/, docs/specs/, docs/plans/, bench/orchestrator-stats/
- experiments/.../runs/ (frozen LLM-output artefacts; models actually
saw .ailx — renaming would falsify the experimental record)
Verification: cargo build/test --workspace green; experiment crate
cargo test green; bench/check.py + compile_check.py + cross_lang.py
all 0-regressed; negative grep for ailx|Ailx|AILX outside the
out-of-scope paths returns zero matches.
Opens immediate follow-up: roadmap.md P2 todo `ail check`/build/run
accept .ail extension — after this rename, .ail is canonical
authoring surface but the CLI still produces a misleading JSON-parse
error on `ail check foo.ail`. That's the next iter.
CLAUDE.md previously mixed universal facts (agent role boundaries,
commit discipline, design rationale, file roles, TDD-for-bugs) with
mode-specific autonomy rules (direction freedom, notifications,
WhatsNew procedure). Autonomous-by-default conflicted with the user's
intent that a fresh session should be collaborative-interactive unless
explicitly elevated.
Add `skills/boss/` containing only the three genuinely mode-specific
subsections — Direction freedom, Notifications, Done-state notifications:
WhatsNew.md. Trim CLAUDE.md from 343 to 243 lines; extend the skill-
system pointer paragraph with a one-sentence /boss gate. Universal
orchestrator discipline stays in CLAUDE.md because it applies whether
/boss is active or not.
Two cross-references that named the moved subsections by sub-heading
are repointed: skills/implement/SKILL.md and the implement-orchestrator
agent's standing reading list. The other ~11 agent-file references to
"orchestrator framing" still resolve correctly because that framing
stays in CLAUDE.md.
skills/README.md skill table extended with a `boss` row (now eight
skills); pipeline-diagram caption notes /boss wraps the pipeline.
.claude/skills/boss symlink follows the existing relative-path
convention.
Closes the P1 todo from earlier today: Step 7.5 PASS report is
bound to the exact bytes of the spec at dispatch time. Any
subsequent edit — wording polish, user-requested change, anything
— invalidates the report and forces a fresh dispatch before the
Step 8 commit.
Three edits:
- Step 7.5 gets a 'Re-dispatch on any post-PASS edit' subsection
stating the rule and explaining why (PASS attests to bytes).
- Step 8 wording: '... edit in place, re-run Step 7 AND re-dispatch
Step 7.5, then return here. Only proceed after approval AND a
fresh Step 7.5 PASS.'
- Common Rationalisations + Red Flags gain matching entries
('just polishing wording, no need to re-dispatch' / 'Editing the
spec after PASS without re-dispatching').
Roadmap P1 todo retired with this commit.
Two project-wide rules are now explicit across every skill:
1. Only the Boss commits. No skill agent (implementer,
brainstormer, planner, debugger, fieldtester, docwriter,
architect, bencher) runs `git commit`. Agents write their
artefacts to the working tree as unstaged changes; the Boss
inspects, decides commit shape, and commits.
2. main HEAD is sacrosanct. No actor runs `git reset` or
`git revert` on main. Bad work stays in the working tree
where it is still discardable via `git checkout -- <paths>`.
Implement loses the `iter/<iter_id>` branch mechanic entirely;
Phase 0 of the orchestrator-agent now does a clean-tree check
and refuses to start on a dirty tree. Per-task agent commits
are removed everywhere; reviewers operate against
`git diff HEAD` instead of `pre_task_sha..head_sha`.
Motivation: 2026-05-11 iter 23.4 stranded prep2/prep3 commits on
an iter-branch that never integrated to main, then a corrected
spec falsely claimed those commits had shipped. Branch-per-iter
+ manual-Boss-merge + iter-stacking made the strand structurally
possible. See docs/journals/2026-05-11-iter-disc.1.md for the
full per-task notes and motivation.
The orchestrator-agent ends its run with the worktree on
iter/<iter_id>. Step 3 previously listed 'append INDEX line' as
item 3 and 'switch+merge' as item 4 — natural reading order is
top-to-bottom, so the INDEX append (and any other Boss edit) was
landing on the iter branch by mistake. Observed three times on
2026-05-11 during the iter 23.4 family's prep iters.
Fix: explicit warning at the top of Step 3, plus reorder so the
'git switch main && git merge --ff-only' happens before any
Boss-side edit. Summary rewrites (step 2's decision) now defer to
step 5, which runs after the switch, so they also land on main.
Claude Code categorically forbids subagents from spawning other
subagents (code.claude.com/docs/en/sub-agents and the Agent SDK
subagents page). The `or.1` architecture (and `pr.1` that ran on
top of it) presumed a named-exception for `ailang-implement-
orchestrator` to dispatch implementer / spec-reviewer / quality-
reviewer / tester per task. That exception never existed at the
platform level; the `Agent` tool was silently dropped from the
orchestrator-agent's tool set at dispatch time.
Architecture revised, doc-only:
- Per-task phases (implementer → spec-compliance check → quality
check) now run as sequential role-switches in the orchestrator-
agent's own context, not as nested subagents.
- The four role-files (implementer / spec-reviewer / quality-
reviewer / tester) become phase reference files the
orchestrator-agent consults at role-switch boundaries.
- Boss-context offload preserved; fresh-per-phase context given
up (the property that drove or.1's nested-dispatch design is
not buildable in Claude Code).
Files touched:
- skills/implement/agents/ailang-implement-orchestrator.md
(frontmatter, Iron Law, Phase 2/3 rewrite, rationalisations,
red flags)
- skills/implement/SKILL.md (frontmatter, Iron Law, sub-status
vocabulary note, cross-references)
- skills/README.md (Conventions: no more named exception; agent
roster: role-files recast as phase references)
- docs/journals/INDEX.md (or.2 entry appended)
- docs/journals/2026-05-11-iter-or.2.md (new — full rationale)
- docs/roadmap.md (P1 tool-wiring item removed; resolved as
categorically-not-fixable)
- docs/WhatsNew.md (user-facing correction entry appended)
No code changes; no bench impact; CLAUDE.md untouched (no stale
references to fix there).
The or.1 Iron Law said `git switch -c iter/<iter_id> origin/main`,
which silently presupposed that the plan-commit lives on origin/main.
The Boss commits plan+spec to local main and dispatches immediately
without pushing, so origin/main lags. The first real dispatch (pr.1)
hit this and worked around it by mid-flight ff-merging local main
into the iter branch — clean end-state but pure rationalisation
through a 'branch already exists' clause meant for repair re-dispatch.
The intent of branch-per-iter was iter-isolation from main, not
push-state coupling. Branch from local main; let push remain
orthogonal.
Touches Iron Law (twice — agent + SKILL.md), Phase 0 step
(orchestrator-agent), Boss-merge explanation (SKILL.md). Also drops
the now-obsolete `git fetch origin main` Phase 0 prelude.
Recorded in docs/journals/2026-05-11-iter-pr.1.md Boss-side addendum;
this commit closes the first follow-up item from that addendum.
Anthropic now reserves /plan as a UI command, so the Skill tool refuses to
dispatch it. Rename the project's plan skill to planner, update the symlink
under .claude/skills/, and adjust references in CLAUDE.md, DESIGN.md,
skills/README.md, and the cross-references between brainstorm / implement /
audit / fieldtest / fieldtester. Plan files themselves (docs/plans/*.md)
keep their name — only the skill ID changes.
The four-phase debug process and the five-phase fieldtest process
each lived twice — once in SKILL.md (orchestrator-facing) and once
in the dispatched agent's file (subagent-facing). The orchestrator
does not execute these phases; the subagent does. Duplicating them
in SKILL.md just bloated the orchestrator's main context with bytes
that only the subagent ever needs.
SKILL.md now carries only what the orchestrator must consult at
dispatch time: trigger gating, Iron Law as headline, the carrier
contract, the produced handoff, and cross-references. Iron Law in
operational form, full process, Common Rationalisations, Red Flags,
and (for fieldtest) the spec template now live solely in the agent
file. Net −160 LOC across the skills tree.
CLAUDE.md pointer for 'Bug fixes — TDD, always' updated to reflect
that the substantive discipline lives in the agent file, not the
skill file.
New skill that runs after a clean audit at milestone close. Picks
2-4 real-world programming tasks within the milestone's scope,
implements each in the AIL Surface form (.ailx), runs the binaries,
and writes a friction-and-bug spec to docs/specs/<date>-fieldtest-
<milestone>.md.
The dispatched agent (ailang-fieldtester) is restricted to DESIGN.md
plus the public examples/ corpus — crates/, runtime/, bench/ are
forbidden reads. This simulates a downstream LLM author who has only
the specification, which is the empirical complement to brainstorm's
prospective application of the LLM-utility criterion.
Findings classify as bug / friction / spec_gap / working, each with
a one-line downstream recommendation (debug / plan / ratify /
carry-on). The orchestrator dispatches the follow-ups; fieldtest
does not self-resolve.
Files:
- skills/fieldtest/SKILL.md
- skills/fieldtest/agents/ailang-fieldtester.md
- .claude/skills/fieldtest, .claude/agents/fieldtest (discovery
symlinks)
- skills/README.md updated (skill table → 6, pipeline ASCII,
agent roster, discovery list)
All six existing agents (implementer, tester, architect, bencher,
docwriter, debugger) restructured into the same superpowers-derived
layout the SKILL.md files use: Iron Law, Carrier contract, Standing
reading list, Status protocol (DONE / DONE_WITH_CONCERNS /
NEEDS_CONTEXT / BLOCKED), Common Rationalisations, Red Flags. Agents
now know about docs/specs/<milestone>.md and docs/plans/<iteration>.md
but do not open them directly — context curation lives at the skill
level (controller hands the agent task_text, hypothesis, etc.).
Implementer carries TDD as an independent discipline layer, mirroring
the superpowers split between subagent-driven-development (outer loop)
and test-driven-development (inner loop). RED-first applies even when
a plan task forgot to script the failing test.
Debugger scope corrected: RED-first only, hands GREEN to implement
mini-mode. Previously the agent self-applied the fix, which
contradicted skills/debug/SKILL.md Phase 4. The skill is the source
of truth; the agent now matches it.
Two new named reviewer agents:
- ailang-spec-reviewer: did the diff match the task text?
- ailang-quality-reviewer: is the diff well-built? (only after spec
is compliant)
Both replace the ad-hoc general-purpose dispatch in skills/implement
Step 2.3 and 2.4. With named agents, AILang quality conventions are
amortised across dispatches instead of being re-stated inline per
prompt.
skills/implement/SKILL.md updated to dispatch the new reviewers.
skills/README.md agent roster expanded; conventions clarified to
state that agents do not open plan/spec files directly.
The skills are functionally complete and standalone — superpowers
references were attribution-only. Removed so a reader without the
superpowers plugin loaded isn't sent chasing dead links.
Plus: .claude/skills/<name> symlinks so Claude Code's Skill tool can
invoke them by name (analogous to the existing .claude/agents/
symlinks). Discovery section in skills/README.md updated to cover
both symlink sets.
agents/ contained only README.md after the 2026-05-09 migration. The
roster information is more naturally located alongside the skills it
points into. skills/README.md is now the single index (skill table,
pipeline diagram, agent roster, discovery, conventions, how-to-add).
CLAUDE.md updated: code-layout entry consolidated, @-reference points
to skills/README.md.
Brummel