OpenAgentsControl/docs/architecture/canonical-refactor/12-DISPATCH.md

12 — Dispatch Guide (for subagents executing the refactor)

Status: Operational — read this BEFORE starting any subtask. Date: 2026-07-15 · Companion to 07-EXECUTION-PLAN.md and 08-STRUCTURE-AND-PACKAGING.md. Task briefs live at .tmp/tasks/canonical-refactor/ (task.json + subtask_01–31). They are worktree-local (gitignored); this doc is the durable contract.

---

Environment

• Work here: /Users/darrenhinde/Documents/GitHub/MYBUSINESS/worktrees/OpenAgentsControl/refactor-canonical on branch refactor/canonical. Never work in the main checkout.
• The main checkout is at ../../../OpenAgentsControl — read-only reference (e.g. comparing live plugin state); never write there.
• .env files are present in this worktree (untracked); never commit, move, or glob them into any build output.
• Never use bare git stash — the stash stack is shared across all worktrees.

Doc map (canonical numbering — do not create colliding numbers)

Doc	Content	Exists?
00–06	Spec set + adversarial review	✅
07	Execution plan (stages, gates, kill criteria)	✅
08	Repo structure, build flow, packaging (@controlstack/oac)	✅
09	MERGE-RULES (created by subtask 08; signed off by subtask 10)	✅
10	PRECEDENCE-EXPERIMENT transcript (created by subtask 09)	✅
11	ROLLBACK story (created by subtask 10)	✅
12	This dispatch guide	✅

Where a subtask brief and a spec doc conflict, precedence is: 06-REVIEW dispositions > 08 > 07 > 00-INDEX > 01–05. Anything still ambiguous: STOP and report — do not guess.

Current runtime facts (verified 2026-07-15 — so you don't guess)

• packages/cli — tests run under bun test today; 15 files use Bun-only APIs (Bun.file/Bun.write/Bun.version in lib/installer.ts, lib/config.ts, lib/registry.ts, lib/manifest.ts, lib/sha256.ts, lib/bundled.ts, lib/ide-detect.ts, commands/apply.ts, commands/doctor.ts; import.meta.dir in lib/bundled.ts:37). Bun removal is Stage 5 (subtask 25) — until then, Stage-0 CI runs cli tests with Bun installed via setup action. Do NOT introduce new Bun APIs anywhere.
• packages/compatibility-layer — vitest, Node-clean (zero Bun usage). New packages (packages/core, packages/adapters) use vitest (locked, 05 Q1).
• packages/plugin-abilities — deleted (commit cce5255). It had zero consumers in its entire history, did not compile, and failed 23 of its own tests. packages/ is now exactly cli and compatibility-layer. Do not re-add it or reference it.
• evals/framework — has NO ESLint config; its deterministic baseline = build + the test:ci vitest allowlist + validate:suites:all. Do not add lint gates to it in Stage 0.
• Context census is recorded from disk in 09-MERGE-RULES.md §9. Recount before asserting it after any content-tree change; historical numbers in 00–07 are not runtime authority.
• CC plugin agents live in plugins/claude-code/agents/ (7 agents: 5 sonnet, 2 haiku). .claude-plugin/marketplace.json is live production config — touch only when a brief says so.

Build & code standards

• TypeScript strict; no any without a comment justifying it; Node ≥ 20 APIs only.
• Load the context standards listed in your brief's context_files before writing code (canonical names: code-quality.md, documentation.md, test-coverage.md, typescript.md, security-patterns.md under .opencode/context/core/standards/).
• Tests ship with the feature, never after. A subtask whose acceptance criteria mention a test is not done until that test runs in CI.
• Determinism rules for anything that writes files: stable input sort, no timestamps in content, fixed key order (07 Stage 3 / 04 §2.1).
• Match surrounding code style; do not reformat files you aren't changing.

Commits & PRs

• Conventional commits (feat:/fix:/docs:/chore:/test:), one commit per coherent change, subtask id in the body (e.g. Task: canonical-refactor-01).
• No Claude/AI co-author or generated-by lines in commits or PRs. Attribute to the user only.
• Small PRs into refactor/canonical; the branch merges to main per completed stage.

Execution protocol

1. Read your subtask_NN.json fully; read every reference_files entry (or the cited sections for large docs) and this guide.
2. Verify claims against disk before acting on them — counts, paths, and line numbers in briefs were verified at authoring time but the tree moves.
3. Implement; run the relevant tests locally; then run verification (oac:verification-before-completion — evidence before assertions, paste command output).
4. Commit. Update your subtask JSON: status: "completed" plus a result note (what changed, evidence, any deviations).
5. Stop-and-report conditions (do not improvise): a gate test fails in a way that suggests a spec error; you hit a kill criterion (07 §Kill); a brief contradicts disk reality; newly-discovered failures outside your scope (user requires stop-and-approve before fixing pre-existing breakage).

Parallelism rules

• Only run subtasks marked parallel: true concurrently, and only when their deliverables touch disjoint files. Same worktree = shared working tree: overlapping edits are forbidden.
• Gate subtasks (10, 16, 20, 24, 28) run alone after their dependencies complete.
• Stage order is strict 0→1→2→3→4→5→6 (Stage 1 docs may overlap Stage 0).