S1: the three-mode surface — plan · develop · research, auto implied (#858)

[aarontrowbridge]

Closes #858 (spec-20260907-011500 D1 — the spec is the contract).

What lands

The renames (read-resolve, never migrate-on-write). The director modes rename: autodev → develop, autoresearch → research. packages/schema carries the canonical alias table (MODE_ID_ALIASES + resolveModeId); the dependency-free plugin surfaces (mode_block, session_spawn) carry parity-pinned duplicates, and the app picker's resolveAgent covers persisted selections. build is NOT aliased — it exits the picker, not the vocabulary (valid everywhere: default_agent, spawn params, CLI args). Append-only artifacts (session ledgers, .deploy-receipt.json, the campaign fixtures) keep old ids forever and resolve at read. The alias window's END rides the next mode-bundle CONTRACT-VERSION bump (removal is non-additive) — pinned by a lint test in packages/schema/test/mode_aliases.test.ts.

The picker. The extension writes agent_order: ["plan", "develop", "research"] into the session config (fork PR #305's field); the overlay's picker sort honors it APP-SIDE with #305's exact precedence (order primary → default_agent pin → alphabetical), so the product order renders even on an engine build without the #305 sort. Stock build stays reachable (selection, Tab-cycle, old sessions) and is MARKED implied — one i18n'd suffix (agent.picker.implied, en + 17 locales, placeholder-parity checked), never a fourth named tile.

The registry lint independence. The mode registry passes the shared validator with the renamed set (validateModeRegistry green); the freeze validator is exercised as a borrowed lint on the renamed surface (a synthetic develop-shaped card merges all four method fields), and the public path is proven to ship under a HOSTILE premium overlay (malformed/mismatched/bad-field registry → rejection records, base cards byte-identical, no throw) and with no entitlement at all. The borrow is one-way — validateModeRegistry never reads the overlay source.

The vocabulary sweep. Director cards + mode bundles (manifest mode/agent ids, pack handoff targets, cards), the research skill rename, director-core/develop/migrate-research-project skill prose, CONTEXT.md glossary (with _Avoid_ alias notes), AGENTS.md (root + extension), README, deploy-agents.mjs, and the amico-run doctor/upgrade fixtures. The picker sort reads the config defensively (the SDK type may predate agent_order).

Design decisions worth review

• The mode-protocol skill keeps id autodev — the workflow skill develop (the issue-DAG walk) owns that id; two skills cannot share one. The alias covers the id at every reference surface; the skill retitles to "Develop — the director's protocol" and its manifest entry documents the retention. The mirror skill renames cleanly: skills/autoresearch → skills/research.
• The four seeded role cards keep their old prose (analyzer/experimenter/hypothesizer say "autoresearch loop"): they are seed-gated registry artifacts (Slice 2: director role cards become versioned registry artifacts (human-gated seed) #806) — any content drift needs a recorded, SIGNED amendment, which an implementer cast cannot mint. The alias covers them at read time; the signed sweep is a follow-up for Aaron.
• The engine-side --agent alias is fork territory — opencode run --agent validates against the engine's agent list (read-only fork, patch-stack PRs); every amicode-owned surface that joins on a mode id resolves through the table.

Out-of-repo surfaces (noted, not edited)

• The live hub's staged bundles (~/.config/opencode/agents + modes/, the server staging root) re-cut on the next extension deploy via the server's staging pipeline; the deployed .deploy-receipt.json keeps old card names until then (append-only, resolved at read).
• The vendored engine binary: picker order renders correctly via the app-side sort regardless of the binary's vintage; the Add CONTRIBUTING.md, issue templates, and PR template (#303) #305 engine-side sort remains an open fork PR (amends its order per D1).

Verification (run on the branch)

• pnpm -r run typecheck — clean (schema, amico-run, extension).
• pnpm -r run test — schema 246 green; amico-run 1 pre-existing failure (agent_spawn.test.ts OPENCODE_CONFIG_DIR env leak, present on clean main — machine-local env); extension 4 pre-existing failures (terminal.test.ts ×2, editable_diffs_wiring.test.ts ×2 — the known set, present on clean main). All NEW tests green: alias table (5), plugin alias binding + parity (6), spawn-param alias (2), picker sort/implied (13), rename-pinning registry/staging/skills/naming suites, the public-rename independence lint (4).
• Overlay gates: committed overlay vs manifest verified in sync from HEAD blobs (594 files) — drift_gate.mjs PASS; app-domain i18n parity across all 18 locales with placeholder preservation; bun test on the picker unit suite: 16/16.
• Note: the chore(test): overlay-sync test applies to the local fork checkout's committed tree — point it at a temp tree #842 overlay-sync hazard struck repeatedly during the session (fork-content dirt in packages/app-bundle); every strike was restored before staging and the final commits were verified against HEAD blobs — the committed tree carries zero hazard content.

Refs #858 · spec-20260907-011500 (rev 2, approved) · S2 = #859, S3 = #860

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}