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).