Define the Ourocode product vision around terminal-native orchestration

[Q00]

SSOT

This issue is the single source of truth for the ourocode terminal-native orchestration vision.

Issue #2 is closed as superseded because it framed the work too narrowly around one plugin-dispatch path and contained implementation-specific artifact assumptions. Future planning should start here, then split into focused implementation issues only after the product boundary and primitives are clear.

Vision

ourocode should become the terminal-native orchestration layer for Ouroboros work, not a thin command launcher and not a second implementation of Ouroboros internals.

The user should be able to stay in one focused TUI while ourocode:

• understands intent from natural language and direct ooo ... prompts,
• routes work to the right Ouroboros capability, plugin, child session, or workflow,
• keeps trust and permission boundaries visible,
• captures generated artifacts, handoffs, evidence, and review outputs,
• shows progress, blocked states, and next actions in a durable session model,
• lets the user continue, replay, inspect, or cancel work without dropping to shell glue.

In short: Ouroboros owns execution semantics; ourocode owns the operator experience.

Product boundaries

ourocode should own:

• Prompt intake and intent routing for interactive terminal use.
• Child panes, progress surfaces, status, and recoverable session state.
• Human-readable continuation UX after tools produce Seeds, handoffs, evidence, or review artifacts.
• Safe bridges into Ouroboros MCP, CLI, plugin, and child-session APIs.
• Clear rendering of trust, permission, ambiguity, failure, and blocked states.
• A durable orchestration timeline that can be replayed or recovered.

ourocode should not own:

• Plugin trust policy or firewall semantics.
• Arbitrary shell execution assembled from model output.
• A duplicate plugin registry, marketplace, or package manager.
• Core Ouroboros workflow definitions that belong in Ouroboros itself.
• Hidden automatic permission grants.
• Plugin-internal storage conventions or implementation paths.

Why this matters

Without this product boundary, each new capability can become a one-off integration: core workflows, plugins, Superpowers handoffs, child sessions, review loops, release flows, and future agents all risk growing separate routing and rendering paths.

A clear vision lets us build fewer, stronger primitives:

• one intent routing model,
• one capability resolution and preflight model,
• one invocation/result envelope,
• one artifact and continuation model,
• one trust/permission presentation layer,
• one durable session timeline.

Core primitives

1. Intent routing

   • Direct commands and natural-language prompts should resolve through the same routing boundary.
   • Ambiguous intent should produce clarification or an explicit blocked state, not guessing.

2. Capability resolution

   • Installed capabilities should be resolved through authoritative Ouroboros surfaces where possible.
   • Resolution should expose identity, command metadata, trust state, expected inputs, expected outputs, and risk class.
   • Discovery is read-only and must never install, trust, or execute by itself.

3. Preflight

   • Before execution, ourocode should show what capability will run, why it matched, what trust boundary applies, and what side effects are expected.
   • Missing trust should be actionable but non-destructive.

4. Invocation/result envelope

   • Core workflows, plugins, and child sessions should report through a shared envelope for status, output, artifacts, errors, and continuation hints.
   • This should prevent each integration from inventing its own rendering and recovery path.

5. Artifacts and continuations

   • Generated Seeds, handoffs, reports, logs, and evidence should become first-class session artifacts.
   • Continuation into ooo run or another workflow should be suggested, confirmed, or blocked according to explicit policy.
   • Artifact handling should rely on stable runtime/plugin artifact contracts, not internal storage paths.

6. Durable session timeline

   • User intent, routing decisions, trust blocks, invocations, artifacts, continuation choices, and verification signals should survive refresh and recovery where possible.
   • The user should be able to inspect how a workflow got from prompt to outcome.

Suggested milestone breakdown

1. Define and document the product boundary in docs/.
2. Extract or align code around the shared primitives above where the current implementation is already drifting.
3. Add a capability resolution/preflight path for the first trusted workflow surface.
4. Normalize invocation/result reporting across at least one core workflow and one plugin or child-session path.
5. Surface generated artifacts and continuation choices as session objects.
6. Add replay/recovery support for the orchestration timeline.
7. Validate the direction through implementation PRs, not standalone vision text only.

Acceptance criteria

• A short vision document exists in docs/ describing this product boundary and linking back to this issue as the SSOT.
• Future workflow/plugin integrations can point to the same routing, resolution, result, artifact, continuation, trust, and timeline concepts.
• Implementation issues reference this issue and stay scoped to one primitive or vertical slice.
• At least one implementation PR updates or validates the vision against real code rather than leaving it as standalone product text.
• No implementation issue depends on plugin-internal storage paths as a public contract.

Non-goals

• Rewriting the current TUI architecture in one large PR.
• Designing a marketplace or plugin catalog.
• Moving Ouroboros execution semantics into ourocode.
• Auto-installing, auto-trusting, or silently escalating plugin permissions.
• Treating one plugin workflow as a hard-coded special case.

Supersedes

• Support natural-language dispatch for installed Ouroboros UserLevel plugins #2, which is closed in favor of this SSOT.

[Q00]

Added the repository-side vision document for this SSOT:

• docs/product-vision.md
• Commit: d469ac2 docs: define ourocode orchestration product vision

This document keeps the product boundary and implementation primitives close to the codebase, so future plugin/workflow implementation issues can reference #25 for SSOT and the docs file for day-to-day engineering guidance.

[shaun0927]

Implementation task list (UserLevel plugin dispatch slice)

Splitting this SSOT into five reviewable PRs. Each PR closes only the issues directly addressed; deferred issues stay open with defer:awaiting-signal style notes.

• PR 1 — docs rescope + umbrella close (this PR: docs: rescope userlevel plugin dispatch around SSOT #25 (PR 1/5) #3)
  • Closes Vision: make Ourocode the terminal-native front door for trusted Ouroboros plugins #4, Vision: make ourocode the orchestration front door for trusted plugin workflows #6, Vision: make ourocode the terminal-native orchestration layer for Ouroboros #12, Vision: make ourocode the plugin-native orchestration surface for Ouroboros #13, Vision: make ourocode a policy-driven workflow conductor #14
• PR 2 — Ourocode.Plugin.UserLevel.{Capability, Discovery, Registry} + OuroborosCLI adapter + Command.Registry plugin source wiring
  • Closes Build a plugin capability index for intent-driven workflows #5, Establish a plugin capability registry for natural-language dispatch #8, Vision: define an authoritative plugin capability contract for ourocode #9, Vision: keep plugin capability resolution fresh across session changes #18, Vision: make plugin capability discovery portable across CLI and MCP surfaces #27, Vision: make installed plugin identity stable across local workspaces #29
• PR 3 — Ourocode.Plugin.UserLevel.{PreflightResult, Resolver} + router :user_level_plugin route + dispatcher route validation
  • Closes Vision: make plugin resolution an explicit preflight step #16, Vision: make plugin command resolution explainable when names are ambiguous #23
• PR 4 — Ourocode.Runtime.UserLevelPluginInvocation + PreflightPanel TUI + Superpowers vertical slice
  • Closes Vision: use Superpowers as the golden path for plugin-native workflows #15, Vision: make plugin workflow failures recoverable inside ourocode #17 (minimal trust-blocked structured error), Vision: make plugin trust understandable at the moment of use #20, Vision: preview plugin side effects before workflow execution #21
• PR 5 — ArtifactWatcher + Continuation policy + DecisionJournal
  • Closes Vision: treat plugin run artifacts and continuations as first-class session objects #7, Vision: make plugin workflow decisions observable and auditable #10, Vision: turn plugin intent into reviewable workflow plans #11, Vision: make plugin workflows completion-aware from intent to verified outcome #26, Vision: make plugin handoffs first-class workspace artifacts #28

Deferred (stay open with trigger conditions)

• Vision: turn trusted plugin workflows into reusable recipes #19 — recipes: ships after a recurring user pattern emerges (same plugin command + same shape, ≥5 invocations by one user)
• Vision: make plugin workflows context-aware without leaking session state #22 — context packets: ships once a plugin declares an accepts_context capability
• Vision: make plugin workflow runs controllable as durable sessions #24 — durable sessions + full failure recovery: ships when long-running (>10 min) plugin runs or plugin pause/resume hooks appear

Detailed PR-by-PR scope, file list, and non-goals: docs/userlevel-plugin-dispatch.md (updated in PR 1).