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.
ailang-implementer/-tester -> skills/implement/agents/
ailang-architect/-bencher/-docwriter -> skills/audit/agents/
ailang-debugger -> skills/debug/agents/
agents/ now contains only README.md (rewritten in next commit as
roster of skill-bound agents).
Brummel