Brainforge Knowledge

openwork-platform-integration-plan

5 min read

OpenWork Standup Plan

Status: Draft
Updated: 2026-03-07
Related: openwork-private (dev branch), env contract

Recommendation

Start with separate hosting at labs.brainforge.ai and add a lightweight entry route in Platform (/openwork) that links or embeds Labs. This decouples runtime risk (pnpm/orchestrator/sidecars/persistent storage) from the core Next.js app and lets us validate OpenWork in production-like conditions before deep integration.

Why This Path

  • apps/openwork is not a native Next.js route package; it is a pnpm multi-package runtime (UI + server + orchestrator + OpenCode sidecars).
  • Platform auth middleware currently protects almost all paths and would complicate immediate same-origin proxying under /openwork.
  • OpenWork expects /opencode/* proxy behavior and writable workspace/data volumes, which is easier to validate first in an isolated service.

External Architecture Inputs

  • Clarence system architecture (Slack artifact): keep a copy under knowledge/engineering/openwork-platform-integration/ or team Drive if you need it in-repo; do not reference machine-local Cursor asset paths.
  • Reconciliation + launch gate note: OpenWork architecture reconciliation + Labs launch gate
  • How it informs this plan:
    • (ALIGN) Use it as the reference for ownership boundaries (platform-managed vs OpenWork-managed services).
    • (ALIGN) Validate identity/session and ingress assumptions before Phase 2 routing decisions.
    • (DECOUPLE) Keep OpenWork runtime components isolated unless the architecture review shows a strong reason to collapse services.
    • (ALIGN) Create a reconciliation note mapping this plan’s phases to the architecture artifact before ticket execution.

Alignment vs Decoupling Framework

  • Use ALIGN for cross-cutting platform concerns: access policy, secrets management, observability, CI governance, rollout controls, and runbooks.
  • Use DECOUPLE for OpenWork runtime concerns: orchestrator/sidecars, storage layout, container lifecycle, and release cadence.
  • Current bias (Phases 0-2): ~70% DECOUPLE, ~30% ALIGN.
  • Rebalance trigger: move toward tighter ALIGN only after Phase 0 reliability checks pass and internal adoption validates demand.

Phase 0 - Feasibility Spike (1-2 days)

  • (DECOUPLE) Validate deploy shape for OpenWork in a Linux container with persistent volume assumptions.
  • (DECOUPLE) Run a smoke checklist: health endpoint, session create, SSE stream, basic workspace operations.
  • (DECOUPLE) Decide sidecar strategy on Railway: downloaded vs bundled vs external for orchestrator/server.
  • (ALIGN) Reconcile plan assumptions against Clarence architecture and capture deltas/unknowns.
  • (ALIGN) Publish a go/no-go note in vault with blockers, mitigations, and owners.
  • Decision note: phase-0-labs-host-decision-note-2026-03-07.md

Phase 1 - Labs Deployment (MVP Standup)

  • (DECOUPLE) Deploy OpenWork host stack as a standalone service for labs.brainforge.ai.
  • (DECOUPLE) Configure required env vars/tokens and stable data directory mount.
  • (ALIGN) Keep Platform untouched except an entrypoint (nav link or simple route card).
  • (ALIGN) Implement from contract: standards/03-knowledge/engineering/setup/openwork-hosted-runtime-contract.md.

Phase 2 - Platform Entry Route

  • (ALIGN) Add /openwork route in Platform under (main) shell.
  • (ALIGN) Choose one entry mode:
    • external link/button to Labs, or
    • iframe wrapper route to Labs (fastest in-app UX).
  • (ALIGN) Gate route with existing platform auth and role checks as needed.

Phase 3 - Tight Integration (Optional)

  • (ALIGN) Evaluate same-origin /openwork/:path* proxying via Next rewrites/route handlers.
  • (ALIGN) Proceed only if we need shared cookies/domain behavior and can support OpenWork base-path plus proxy requirements end-to-end.
  • (ALIGN) Add explicit middleware exceptions/auth bridging for OpenWork endpoints if this mode is chosen.
  • (ALIGN) Use same-origin proxy + auth investigation (PLT-1080) as the gate input for go/no-go.

Phase 4 - Operational Hardening

  • (ALIGN) Add CI checks for openwork sub-tree basics (typecheck/smoke) without slowing platform CI too much.
  • (ALIGN) Add observability/alerts for /health, token errors, and sidecar startup failures via OpenWork hosted ops runbook and hosted health workflow.
  • (DECOUPLE) Define rollback process and release cadence for upstream OpenWork syncs in the same runbook.

Ticket Backlog Draft (Epics + Starter Tickets)

Epic A: OpenWork Infra Readiness

  • A1 (DECOUPLE): Railway/container feasibility spike for OpenWork host runtime.
  • A2 (DECOUPLE): Define persistent storage strategy for /workspace and /data.
  • A3 (ALIGN): Finalize env var contract and secret source-of-truth.
  • A4 (ALIGN): Document runbook in playbook setup docs.
  • A5 (ALIGN): Add architecture reconciliation memo based on Clarence’s system diagram.

Epic B: Labs Launch

  • B1 (DECOUPLE): Provision labs.brainforge.ai service plus domain wiring.
  • B2 (DECOUPLE): Deploy OpenWork host stack and verify health/smoke flow.
  • B3 (ALIGN): Add basic access policy (token/auth guard) and usage logging.

Epic C: Platform Access

  • C1 (ALIGN): Add platform sidebar entry for OpenWork Labs.
  • C2 (ALIGN): Add /openwork entry route (link or iframe).
  • C3 (ALIGN): Add feature flag for controlled rollout to internal users.

Epic D: Deep Integration (Optional)

  • D1 (ALIGN): Technical spike for /openwork reverse proxy and base-path rewrites.
  • D2 (ALIGN): Middleware/auth exception model for proxied OpenWork APIs.
  • D3 (ALIGN): End-to-end regression test plan for platform plus OpenWork co-hosting. See Co-hosting Regression Test Plan.

Decision Gates

  1. Phase 1: Use Option A (subtree) from dev branch into apps/openwork — in progress
  2. Phase 2: Start with 2b (landing-style pages) and 2a (web UI route)
  3. Defer: Tauri desktop, server, orchestrator as separate deployments (post-Phase-2)
  4. Track deferred deployment work in the Deferred Work (Post-Phase-2) register
  • Gate 1 (after Phase 0): Can OpenWork run reliably on Railway/container with current sidecar strategy?
  • Gate 2 (after Phase 2): Is iframe/link good enough for internal adoption, or do we need same-origin proxying now?
  • Gate 3 (after Phase 3 spike): Does tight integration justify complexity and auth/proxy risk? Reference: PLT-1080 investigation.

Risks and Mitigations

  • Sidecar download/runtime mismatch in PaaS: pin versions and preflight with smoke checks.
  • Missing persistent state on ephemeral deploys: require mounted data volume before launch.
  • Auth complexity with same-origin proxy: defer until product value is proven.
  • CI drift (npm platform vs pnpm openwork): add scoped openwork checks only when openwork files change.

Deliverables for This Planning Cycle

Graph View

Backlinks