Orchestrata Ultimate › Plans › spec-021-implementation-plan
SPEC-021 OpenCode integration — full implementation plan (session 227+)
Source: plans/spec-021-implementation-plan.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-13 · 89 lines.
Prose pending.
Plan text
SPEC-021 OpenCode integration — full implementation plan (session 227+)
User ruling 2026-07-13: no retire, no re-scope — a THOROUGH implementation of SPEC-021, retargeted from the frozen monorepo paths to orchestrata_ultimate. 299 requirements (checklists/requirements.md).
Ground truth (recon 2026-07-13)
- The complete original artifact set SURVIVES:
~/workspace/orchestrata/open-code/(READ-ONLY source of truth to port FROM):plugins/orchestrata.ts(3,236 lines),agents/(2),commands/(query-kg.md),tools/(5 Python KG query tools incl. project-scoped arbitrary Cypher),config/,install.sh, docs. - A deployed copy at
~/.opencode/runs against@opencode-ai/plugin@1.3.17(spec pinned 1.3.3 — already forward-compatible). - The opencode editor source is local (
~/workspace/opencode, bun). - GENUINELY MISSING (audit-verified, must be BUILT not ported):
Conversation/ConversationTurnnode writers (the Redisorchestrata:conversation:queuehas NO consumer anywhere), the KG-sync queue consumer wiring, deception-detection backend hooks in ultimate, and the arbitrary-Cypher CLI capability in ultimate's scripts.
Non-negotiables (apply to every wave)
- Ontology BEFORE graph writes (recorded emphatic ruling):
Conversation/ConversationTurn (+ edges to Session/ToolCall) enter
knowledge_graph/canonical_schema.py(SPEC-106) with project-qualified ids (multi-project invariant:{project}:{natural_id}) and constraint DDL applied viakg_schema.pybefore any writer lands. - Rule 8 wiring gate: every deliverable names its production seam (consumer in kernel boot component / plugin deployed via install.sh / tools on PATH); orphan ratchet must stay at 0 new.
- Full standards pack per step: code-review ERROR=0, test-review clean, architecture 0, ruff/black/pyright, @traces with real REQ-021 ids, no mock/monkeypatch/skip/xdist, live-observed test runs, review before every commit, Mohamed-only authorship.
- Spec is the oracle (spec.md 1,722 lines + 470-line requirements + 303-line testing checklist); deviations surfaced, never silent.
- TS side: typecheck via opencode's toolchain; validate with
scripts/serialize_js_ts_ast.py; runtime-smoke against the REAL local opencode before declaring done.
Waves
W0 — Design + inventory (analyst + auditor, parallel)
- Analyst contract A: KG ontology extension — Conversation, ConversationTurn, edges (Session)-[:HAS_CONVERSATION]-, turn ordering, ToolCall linkage; canonical merge keys; migration DDL. Output to plans/contracts/spec-021-ontology.*.
- Auditor: line-by-line inventory of
orchestrata.ts+ tools vs the 299 REQs — classify each as PORT-CLEAN / RETARGET (path/id changes) / BUILD-NEW (missing backend) / OBSOLETE (superseded by ultimate features, e.g. session CLI path, new pub/sub). Output: plans/spec-021-port-map.md.
W1 — Python backends (builder swarm, after W0)
- canonical_schema + kg_schema apply (ontology contract).
- Conversation-queue consumer: Redis list → Neo4j writer (project-qualified, MERGE-idempotent), lifecycle component in kernel boot (the plugin-system component pattern from 73cc2d58), backpressure + poison-message handling.
- KG-sync queue consumer wired to the existing knowledge_graph sync engine.
- Arbitrary-Cypher project-scoped query capability: port the 5 tools into
scripts/(or extend neo4j_query.py) with the scoping rewriter targeting the NEW{project}:id scheme. - Tests: real Redis/Neo4j, queue round-trip, scoping isolation proofs (two projects, no bleed — same style as the W1/W2 identity migration).
W2 — Plugin port (TS builders, after W1 backends exist)
- New top-level
opencode/dir in this repo mirroring the source layout; port orchestrata.ts retargeted: ultimate paths, session CLI, new KG ids, Redis queue names confirmed against W1 consumers, 24 tools, 7 lifecycle hooks, 5-gate review pointing at ultimate's review scripts, deception detection, read throttle, git checkpoint. - Agents (2) + /query-kg command + install.sh (idempotent, versioned).
- Typecheck + JS-AST validation + unit tests per the testing checklist.
W3 — Verification + close
- E2E: real opencode session against this repo — hooks fire, context injects, conversation turns land in Neo4j, deception detection triggers on a seeded false claim, /query-kg scoped.
- @traces stamped across TS (header annotations) + Python; RTM regenerated — SPEC-021 goes from ~0 to measured green; checklist statuses updated.
- Full suite + gates; commit per wave throughout.
Open items to resolve in W0
- Plugin activation predicate (spec: any ~/workspace project with context.json) — confirm still wanted vs ultimate-only.
- Where TS tests run in CI (bun not on PATH; opencode ships its runtime).
- Whether conversation capture should ALSO fan out on the new volk pub/sub
(
topic:conversation.turn) — cheap now, not in the original spec.