Spec: opencode-architect 1.0.0 — v2-native plugin, Effect-first guidance suite, one-shot consumer v2 upgrade

Problem Statement

opencode v2 replaced the extension SDK. v1 plugin implementations do not run under a v2 host, so opencode-architect — itself a v1-era plugin — silently fails to register its agents for consumers on v2. Worse, our entire product is teaching: the bundled references, templates, agent definitions, and conformance checklist all assert v1 config keys, hook names, and API shapes that are now wrong or legacy. Consumers who built extension packages with our guidance have no assisted path to v2, and nothing in the suite tells them which v2 capabilities they should adopt.

Solution

Port the plugin itself to the v2 Effect-first plugin API so its agents register under a v2 host. Rewrite the whole guidance surface in place to v2 facts, Effect-first, validated against the pinned opencode source rather than against docs or DeepWiki alone. Migrate the installer and config machinery to write v2-native registrations while tolerating legacy reads. Add a one-shot upgrade capability: a consumer says "upgrade my plugin/extensions package to opencode v2" and the suite inventories, ports, rewrites configs, and recommends v2 features. Release the result as 1.0.0.

User Stories

1. As a consumer on opencode v2, I want the architect and its nine specialists to register and run, so that I can keep creating extensions with the suite.
2. As a consumer, I want to say "upgrade my plugin/extensions package to opencode v2" and get a one-shot upgrade, so that I do not have to learn v2's breaking changes myself.
3. As a consumer, I want the upgrade to rewrite my config files to v2-native keys, so that my project stops relying on legacy normalization.
4. As a consumer, I want the upgrade to port my v1 plugin code to the Effect-first v2 plugin API, so that it actually runs on v2.
5. As a consumer, I want the upgrade to port my v1 file-based custom tools to v2 plugin-registered tools, so that my tools keep working.
6. As a consumer, I want the upgrade to leave my project untouched if it is already v2-native, so that upgrades are safely repeatable.
7. As a consumer, I want the upgrade to recommend v2 capabilities I should adopt (richer session hooks, plugin RPC, TUI plugins, MCP Code Mode, saved approvals), so that I gain more than parity.
8. As a consumer, I want the upgrade to leave the opencode app itself alone, so that my toolchain versions change only when I choose.
9. As a consumer building a new plugin, I want guidance that teaches the Effect-first v2 plugin API with the Promise API as a documented fallback, so that what I learn matches what actually runs.
10. As a consumer authoring an agent, I want v2 frontmatter and permissions guidance, so that my agent definitions use current fields instead of deprecated ones.
11. As a consumer configuring MCP, I want v2 server configuration guidance, so that my servers keep working under the new schema.
12. As a consumer packaging an extension suite, I want the packager to generate v2-native packages, so that what I distribute installs cleanly on v2 hosts.
13. As a consumer publishing to npm, I want the publisher to emit v2-correct consumer instructions, so that my users get working install snippets.
14. As a maintainer of this suite, I want every API fact in our guidance traced to a pinned opencode source snapshot, so that docs, DeepWiki, and source disagreements never ship into our teaching.
15. As a maintainer, I want a verification harness that loads the plugin against a v2 host in CI, so that SDK drift fails a build instead of failing a consumer.
16. As a maintainer, I want the conformance checklist to judge packages against v2 mechanics, so that conformance reviews stay meaningful.
17. As a maintainer, I want ADRs recording why we went v2-native and dropped v1 hosts, so that the decision is auditable.
18. As a maintainer, I want the domain glossary updated for v2 vocabulary, so that agents and docs speak one language.
19. As a contributor, I want README and contributing content reflecting v2 reality, so that onboarding material does not lie.
20. As a consumer with a consumer-modified installed package, I want upgrades to respect my modifications, so that one-shot upgrades never clobber my work.
21. As an agent (extension auditor), I want v2 inventory targets, so that my inventories find what actually runs on v2.
22. As an agent (plugin engineer), I want the v2 hook-family map, so that I translate any v1 hook intent into its v2 replacement.

Implementation Decisions

• v2-native only. Drop v1 host support; the released package targets the v2 line only. No dual entrypoint. Released as 1.0.0. Recorded in ADR-0012 (written during execution, not now).
• Source-of-truth ladder. Pinned anomalyco/opencode source at tag v2.0.23 (record its commit hash) > official v2 docs > DeepWiki. An adjudication produces a verified-facts record resolving every contradiction relevant to our surfaces: the plugin-authoring package name and subpath exports (Effect and Promise variants), config schema keys (plugin registration array, permissions, agents, commands, MCP servers, skills), permission action vocabulary and the fate of external-directory permissions, tool registration and argument schema style, discovery directories, install/distribution mechanics and cache locations, and the TUI/RPC/Effect surfaces we will recommend. Facts the source cannot settle are marked for empirical confirmation. Docs freeze is gated on the harness, so guidance never asserts an unverified fact.
• Effect-first. Our own port, all templates, all examples, and the upgrade skill's default port target use the Effect-based v2 plugin API. The Promise API is documented as the lightweight fallback for trivially simple plugins. General Effect-TS teaching is delegated to the repo's effect-ts skill (maintainer installs it before execution); our guidance covers only opencode-specific Effect usage.
• Runtime port. The plugin registers via the v2 Effect plugin definition with a stable id; agents are injected through the v2 agent domain transform; permission registration migrates to v2 permission semantics (the external-directory allow is re-derived from the verified-facts record); prompt path rewriting, at-most-once advisories, and the startup non-interference invariant are preserved.
• Installer and config machinery. The config editor writes v2-native registration entries and tolerates legacy entries read-only with an upgrade advisory. Manifest gating, registration-scope detection, zero-write no-op, partial-cache-artifact detection, and the copy-mode refusal for code-backed packages are preserved; cache-location assumptions are re-validated against the verified-facts record.
• Verification harness. CI loads the built plugin against a v2 host and asserts registrations, and validates produced fixture configs against the v2 schema. It gates the guidance rewrite (C5–C7) and stays green thereafter.
• Guidance rewrite in place. References, oneshots, conformance checklist (the v1 singular-key item is inverted; v2 items added), templates, and all ten agent definitions are rewritten to v2. Repo content updates — ADR-0012, glossary additions and renames (plugin registration key, plugin definition shape, tool registration), superseding notes on ADR-0010/0011, README, CONTRIBUTING, AGENTS.md content — land with the docs ticket. No v1 archive; git history is the archive.
• Tools. Plugin-registered tools are canonical; v1 file-based tool definitions are legacy. The tool-builder gains a port path and the upgrade skill uses it.
• Upgrade capability. A new skill plus slash command orchestrates the one-shot consumer upgrade: inventory (extension auditor), code port (plugin engineer, tool builder), config rewrite (per the verified mapping), and a v2 feature-recommendations report. It no-ops safely on already-v2 projects and never touches the opencode app installation.
• Effect-ts skill precondition. Installed by the maintainer before any child ticket executes; tickets reference it rather than re-teaching Effect.

Testing Decisions

• Good tests assert external behavior only: what a consumer or a v2 host can observe, never internal structure.
• Seams, fewest and highest first: (1) the plugin registration surface — the harness loads the built plugin under a v2 host and asserts what registers; (2) the CLI — install/uninstall/status/clear-cache against fixture config trees; (3) the config editor — fixture config in, spliced v2-native config out (pure function); (4) generated packages — rendered templates pass the generated package's own gates; (5) the docs-fact gate — asserted API facts traced to the verified-facts record and schema-validated fixture configs.
• Prior art: the existing bun test suite (load hook, config editor fixtures, installer fixtures, deployment plan, tarball whitelist, readme checks) — these are migrated, not reinvented.

Out of Scope

• Dual v1/v2 entrypoints or v1 host support.
• Upgrading, installing, or pinning the opencode application itself.
• Changes to the release mechanism (tag-push publish stays).
• Changes to the skills-market compatibility model, unless adjudication surfaces v2 impacts — then flag, do not silently redesign.
• General Effect-TS tutorials (owned by the effect-ts skill).

Further Notes

• Guidance baseline pinned to v2.0.23; if a newer patch exists at execution time, flag it — never silently upgrade the pin.
• Known doc-vs-source contradictions to adjudicate (non-exhaustive): package name/subpath exports for plugin authoring, permissions key shape, plugin entry export convention, npm cache location.
• The live v1→v2 migration guide is an input to adjudication; its assertions are validated against source before our guidance repeats them.