|
|
@@ -0,0 +1,94 @@
|
|
|
+# 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) | ⏳ |
|
|
|
+| 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` — check its `package.json` scripts before wiring CI; do not assume.
|
|
|
+- `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.
|
|
|
+- Known census discrepancy: 00-INDEX says 296 context `.md`, 07 says 294 files + 3 symlinks.
|
|
|
+ **Recount from disk with the leading-window rule before asserting either.**
|
|
|
+- 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).
|
darrenhinde