AILang/docs/journals/2026-05-11-iter-or.2.md

# iter or.2 — orchestrator-agent design correction

**Date:** 2026-05-11
**Branch:** none (trivial-mechanical carve-out — doc-only revision, single commit on main)
**Status:** DONE
**Tasks completed:** N/A (doc revision, not a plan-driven iter)

## Summary

This entry corrects a factual error in the `or.1` architecture that
surfaced during the first real dispatch (pr.1, same day). The
revision lands as one direct-on-main commit because the change is
doc-only: no code, no tests, no behaviour shift in any compiler
crate. The Iron-Law mini-fix from earlier today (`origin/main` →
`main`) is preserved unchanged — that fix remains correct.

### What was wrong

`or.1` and `pr.1` shipped the `ailang-implement-orchestrator` agent
with frontmatter `tools: Read, Edit, Write, Bash, Glob, Grep, Agent`
and an architecture that depended on the orchestrator-agent
spawning further subagents per task (implementer → spec-reviewer →
quality-reviewer → tester, each in fresh context). The architecture
was framed in `skills/README.md` as "agents do not call other
agents — one named exception" (the orchestrator-agent being the
exception).

The exception never existed in Claude Code. The platform forbids
**all** nested-subagent dispatch, categorically:

> "Subagents cannot spawn other subagents, so `Agent(agent_type)`
> has no effect in subagent definitions."
> — https://code.claude.com/docs/en/sub-agents

> "Subagents cannot spawn their own subagents. Don't include
> `Agent` in a subagent's `tools` array."
> — https://code.claude.com/docs/en/agent-sdk/subagents

The `Agent` tool was silently dropped from the orchestrator-agent's
tool set at dispatch time (no error, no warning). The pr.1 run
caught this empirically; the diagnosis closed the question today.

### Why the failure took the form it did

The Boss-Orchestrator (me) designed `or.1` on the false premise
that the project's house rule "agents do not call other agents"
was a local convention with a documented exception. In reality the
house rule was a *restatement of an external constraint* — and the
"named exception" was incompatible with the constraint itself.
This is a verification-of-capability failure: the architecture was
locked in before checking the platform docs for what subagents can
do. The right order is the other way around. (Memorised as a
feedback memory for future architecture decisions.)

### The corrected architecture

Same skill body, same skill triggers, same branch-and-merge
discipline, same Boss-side end-report contract. What changes is
*inside* the orchestrator-agent's run:

- Per-task phases (implementer → spec-compliance check → quality
  check) run sequentially as **role-switches in the orchestrator-
  agent's own context**, not as nested subagents.
- The `ailang-implementer.md` / `ailang-spec-reviewer.md` /
  `ailang-quality-reviewer.md` / `ailang-tester.md` files now serve
  as **phase reference files** — the orchestrator-agent consults
  them at each role-switch to inhale the discipline of that role,
  but does not dispatch them as separate subagents.
- The Boss-context offload property is preserved (the Boss still
  sees only the ≤500-token end-report; per-task chatter stays
  inside the orchestrator-agent's context).
- The fresh-per-phase context property — which was the design goal
  that drove `or.1` to attempt nested dispatch — is **given up**.
  Pure role-switching inside one context is a weaker discipline
  than fresh-context-per-phase. The trade-off is named openly: the
  cost is the loss of fresh-eyes review per phase; the benefit is
  that the architecture is buildable in Claude Code at all.
- The pr.1 "degraded mode" was not actually degraded — it was the
  only mode this agent can run in. The pr.1 journal's degraded-
  mode caveat is preserved as-is (historical record of how the
  constraint was discovered).

### Why option (A), not (B) or (C)

Three options were on the table:

- **(A)** Single-context inline phases (what landed) — preserves
  Boss-context offload, gives up fresh-per-phase context.
- **(B)** Roll back to pre-or.1: Boss dispatches each per-task
  subagent itself. Preserves fresh-per-phase context, gives up
  Boss-context offload.
- **(C)** Hybrid: orchestrator-agent for setup / branch / journal,
  Boss for per-task dispatches in between. Preserves both
  theoretically but multiplies moving parts.

(A) was chosen because the Boss-context offload is the scarce
resource (user chat budget). Empirically, the pr.1 run with the
plan template's verbatim per-task content blocks made fresh-per-
phase context contribute little additional signal beyond a careful
single-context phase loop. The decision was made by the user
2026-05-11 after the diagnosis was presented; the rationale belongs
in the user's hands, not the agent's.

### Files changed

- `skills/implement/agents/ailang-implement-orchestrator.md` —
  frontmatter (`Agent` removed from tools, description rewritten),
  Iron Law (sequential role-switches instead of fresh subagents),
  Phase 2.1 / 2.2 / 2.3 rewritten as inline phases, Phase 3 likewise,
  common rationalisations and red flags updated.
- `skills/implement/SKILL.md` — frontmatter description, Iron Law,
  per-task sub-status mechanics note (vocabulary is preserved but
  now describes inline role-phase status), one new
  Common-Rationalisation row, Cross-references rewritten (role-files
  recast as phase references, with a "Why inline phases" subsection
  pointing here).
- `skills/README.md` — Conventions: "Agents do not call other
  agents — one named exception" → "Agents do not call other agents"
  (the exception is gone, with an explanation of why). Agent roster
  rows for implementer / spec-reviewer / quality-reviewer / tester
  recast as phase references for the orchestrator-agent.
- `docs/roadmap.md` — P1 entry "`Agent` tool wiring for the
  dispatched orchestrator-agent" removed (resolved as
  categorically-not-fixable).
- `docs/journals/INDEX.md` — this entry appended.
- `docs/WhatsNew.md` — user-facing correction entry appended.

### Files NOT changed (and why)

- `CLAUDE.md` — no stale references; the file does not encode the
  named-exception story.
- `skills/implement/agents/ailang-implementer.md`,
  `ailang-spec-reviewer.md`, `ailang-quality-reviewer.md`,
  `ailang-tester.md` — these remain unchanged. Their content
  (discipline, reading list, output format) is correct in the new
  architecture; their *role* in the system has shifted from
  "dispatched subagent" to "phase reference for the orchestrator-
  agent". The shift is documented in the README roster row and the
  SKILL.md Cross-references; no in-file edits are required for
  correctness. A future cleanup iter may rewrite their frontmatter
  to drop the "subagent" framing if it begins to mislead — for now
  the cost of touching four files outweighs the marginal clarity
  gain.
- `docs/specs/2026-05-11-implement-orchestrator-agent.md` and
  `docs/specs/2026-05-11-plan-recon-subagent.md` — specs are
  historical records of the design as conceived; they remain
  accurate to that moment. Drift between spec and the corrected
  architecture is acknowledged here, not by editing the specs.

## Concerns

None. The revision is deliberate and self-contained.

## Known debt

- **Phase reference files frame themselves as dispatched subagents.**
  `ailang-implementer.md` and its three siblings still read like
  files describing a subagent receiving a carrier from a dispatcher.
  In the corrected architecture, the orchestrator-agent IS the
  dispatcher and the worker for those phases. If the next
  `/implement` run shows the orchestrator-agent confused by this
  framing during phase reads, a follow-up cleanup iter rewrites
  the four files. Not pre-emptive — wait for an empirical signal.
- **No verification ladder for the corrected design.** `or.1`'s
  verification ladder (items 1–5 in
  `docs/specs/2026-05-11-implement-orchestrator-agent.md`) was
  written for the nested-dispatch architecture. Items 1–3
  (Boss-side dispatch, branch creation, journal write) carry over
  unchanged. Items 4–5 (intentional BLOCKED, intentional re-loop)
  are weaker in the inline-phase world — re-loop is a same-context
  retry, not a fresh-context re-dispatch — and a new ladder entry
  for the inline phase-switch should be added the next time
  `/implement` runs against a non-trivial plan. Tracked
  informally; no ticket.

## Blocked detail

N/A — DONE.

## Commits

This entry's revision lands as a single trivial-mechanical commit
on `main` (no iter branch, no plan template). The commit subject is
`or.2: orchestrator-agent design correction — no nested subagent dispatch`.

## Stats

N/A — no orchestrator-agent dispatch (this is a doc-only revision
made directly by the Boss-Orchestrator).