Orchestrator Agent

[MKuckert]

• Drafts next plan
• Streamlines and review-approves plan
• Fixes add orchestrator. rework primary agents to subagents #101

[MKuckert]

Implementation summary (issue #101)

All 5 plan tasks are implemented. Canonical changes live in the agent-harness submodule (feature/101-orchestrator, 6 commits on its main) and are synced into this repo's .opencode/, AGENTS.md, opencode/opencode.jsonc, and .harness-sync.

Per-task

1. Orchestrator & modes (agent-harness@72e8c67)
   • New Orchestrator.md (mode primary, not hidden) — sole coordinator; delegates to Planner, Builder, Testing, PlanReviewer, CodeReviewer, Explorer, Librarian; never plans/codes/reviews/commits itself.
   • Planner, Builder, Testing → hidden subagents; Buddy remains the visible primary (default) and delegates lifecycle intent to the Orchestrator.
   • Deny-by-default task mappings per the plan's graph (Builder → Committer only; Explorer/Librarian/Testing/Committer are leaves); built-in build/plan/general/explore agents stay disabled; subagent_depth: 5 in both configs.
2. Contracts (afe1e76)
   • PLAN.md template: Task ID, Depends On, Owned Paths, Shared Resources, Parallel Safe, Validation Commands.
   • PlanReviewer rejects missing/unknown/cyclic dependencies, ambiguous ownership, overlap among parallel-safe tasks, and missing/unsafe validation.
   • Builder works only the Orchestrator-supplied task ID/scope; cannot edit PLAN.md, invoke review, or commit outside finalization. CodeReviewer reviews exactly one identified task/scope (no vague general review); critique leaves a task incomplete, acceptance alone sets [x]. Committer stages only an explicit path list and aborts on unrelated/ambiguous scope.
3. Commands (2683195)
   • New /plan (foreground Planner, user questions, no silent replacement of a nonempty PLAN.md); /implement_next_task replaced by /continue_implementation (≤2 dependency-ready, parallel-safe, path-disjoint Builders; batch barrier; sequential finalization: Testing → CodeReviewer ≤3 rounds → [x] → Committer; failed batch aborts review/commit for the whole batch).
   • /review_plan, /review_code, /research rerouted to the Orchestrator; /archive_plan unchanged (Buddy); old files removed, no alias.
4. Librarian research (aca2bfc + adaptation 310075f, see below)
5. Sync, docs, validation (64952c4)
   • README documents the agent graph, task mapping, command routing, cooperative parallelism limits (explicitly non-atomic, session-local — not safe across independent OpenCode processes), retry policy (one same-session resume; Builder additionally one fresh continuation), batch finalization, and a manual smoke checklist.
   • New bin/check-harness.sh: 48 dependency-free static checks (modes, task mappings, built-in disablement, depth, command routing, plan fields, Librarian confinement) — all passing; both JSONC configs parse.

Research location: adapted to main's contract

agent-harness main gained fad3ae1 (Research Artifact Contract, from #99) after this plan was approved. Per decision, the implementation was adapted to that contract instead of the plan's docs/research/ location:

• Librarian write scope is now research/results/** (workspace-relative, deny-by-default), destination provisioned as research/results/.gitkeep in the canonical repo; per-workspace provisioning as the contract specifies.
• Librarian prompt embeds the full contract (it has no read permission): unique YYYYMMDDTHHMMSSmmmZ-<slug>-<32hex> filenames, required YAML frontmatter (verified always "false"), fixed body sections, no-overwrite, partial/failure handling, Research artifact: … success line.
• Orchestrator no longer assigns filenames; /research, README, and check-harness.sh updated; docs/research/ removed.
• Note: the approved PLAN.md text still says docs/research/ — the contract on main supersedes it; plan checkboxes intentionally left unchecked pending review.

Retry policy (as planned)

Same-session resume exactly once for technical Task failures (timeout, API/tool error, step-limit/incomplete result, unavailable session); only Builders get one further fresh session that must continue the partial work. Review critique, test failure, user rejection, and invalid state are not technical failures.

Sync note

bin/harness-sync.sh targets the maintainer's local paths, so sync was applied manually here: .opencode/ copied from the submodule, submodule pointer → 310075f, .harness-sync base updated, opencode/opencode.jsonc (local runtime config) got subagent_depth: 5 only. Remaining work per the plan: the manual OpenCode smoke checks.