Repository navigation
C5: Rewrite guidance suite and repo content to v2 (Effect-first) #28
Description
Parent
Part of #23 (Spec: opencode-architect 1.0.0)
What to build
All bundled references, the oneshots, and the conformance checklist rewritten in place to v2 facts drawn from the verified-facts record: the v1 singular-key checklist item is inverted (v2 plural registration key becomes conformant) and new v2 items added (Effect plugin definition, permissions array, JSON-Schema tool arguments). Repo content updates land here too: ADR-0012 (v2-native, drop v1 hosts), glossary additions and renames (plugin registration key, plugin definition shape, tool registration), superseding notes on ADR-0010/0011, README, CONTRIBUTING, and AGENTS.md content. Effect-first throughout; general Effect-TS teaching defers to the repo's effect-ts skill. No v1 archive ΓÇö git history is the archive. Every changed fact traces to the verified-facts record.
Acceptance criteria
- No known-false v1 claims remain in references, oneshots, or checklist
- Every changed API fact cites the verified-facts record
- ADR-0012, glossary updates, and ADR-0010/0011 superseding notes written
- README, CONTRIBUTING, AGENTS.md content consistent with v2
- Docs-fact gate (C5 of testing seams) passes
Blocked by
- #C4
Activity
docs(references): rewrite plugins reference to v2 — Effect-first defi…
docs(references): rewrite config reference to v2 — key table from fac…
docs(references): rewrite agents reference to v2 — frontmatter mappin…
docs(references): rewrite commands reference to v2 — command fields, …
docs(references): rewrite tools reference to v2 — plugin-registered t…
docs(references): rewrite skills reference to v2 — frontmatter fate, …
docs(references): rewrite mcp-servers reference to v2 — snake_case oa…
docs(references): live-knowledge fallback follows the source-of-truth…
docs(references): rewrite oneshots to v2 — Effect-first plugin snippe…
docs(references): conformance checklist inverted for v2 — plugins key…
test(gate): docs-fact gate — ban known-false v1 claims in guidance, r…
refactor(gate): class module per coding standards — no comments, help…
docs(references): review fixes — facts §13 row 10 for legacy plugin t…
diegohb commentedon Oct 6, 2026
Acceptance criteria verified (C5, #28)
All five boxes checked off. Evidence per criterion:
tests/docs-fact-gate.test.ts+tests/docs-fact-gate.ts) scans all ofreferences/*.mdplus README/AGENTS.md/CONTRIBUTING/CONTEXT.md for known-false v1 assertion forms (v1 package name, singular config keys emitted as keys,tool.schema,config.jsonoutside read-only legacy advisories, v1 hook/frontmatter assertion forms, pinned consumer versions) with documented migration-mapping exemptions. 3/3 tests green oncb5c59e.pluginread-only tolerance) rather than resolved locally, per §15.docs/adr/0012-v2-native-only.mdwritten; ADR-0010 and ADR-0011 each carry a superseding note (v2 default-export contract, facts §2; mandatoryexports["./server"], facts §13.9/§14.6); glossary gained plugin registration key, plugin definition shape, tool registration, with Plugin install / Partial cache artifact / Zero-write no-op reworded for v2.exports["./server"]packaging.bun test tests/docs-fact-gate.test.ts→ 3 pass, 0 fail;bun run checkclean; fullbun testat the pre-existing win32 baseline only (5 environment failures verified identical on base commit72bb363, tracked in Win32-only test failures: tarball path resolution and chmod-based removal-failure injection #36; ubuntu CI unaffected).Effect-first throughout; general Effect-TS teaching defers to the repo's effect-ts skill by reference (maintainer-installed precondition, spec #23). Templates and agent definitions untouched (C6/C7 scope). Work in 17 commits on
v2/issue-28-rewrite-guidance.