Vision: preview plugin side effects before workflow execution

[Q00]

Context

Issue #2 defines the immediate bridge: ourocode should run installed Ouroboros UserLevel plugins from natural language or direct ooo <plugin> ... prompts, then surface generated artifacts and possible continuations inside the terminal workflow.

That bridge should not make plugin execution feel like a black box. Before a workflow-producing plugin runs, users should be able to see the likely side effects: which plugin command will run, which project or user files may be written, which run directory will be created, what artifacts are expected, and whether a follow-up ooo run continuation might happen.

Vision

Make ourocode a product surface where plugin side effects are visible before execution.

A prompt such as:

ooo superpowers test-driven-development --goal "Add retry behavior"

should resolve into a preview that answers practical user questions before crossing the plugin firewall:

• Which installed plugin and command will run?
• What arguments or inferred inputs will be passed?
• Is the command read-only, handoff-producing, or potentially destructive?
• What files or directories are expected to be created or modified?
• What generated artifacts should ourocode watch for?
• Will the workflow stop after plugin execution, offer ooo run, or continue automatically under policy?
• What trust or capability checks still block execution?

The goal is not to require confirmation for every harmless command. The goal is to make meaningful side effects inspectable so natural-language dispatch remains safe, predictable, and easy to trust.

Product Direction

Add a reviewable side-effect preview layer between plugin intent resolution and plugin dispatch:

1. Reuse the plugin preflight result as the source of truth for plugin, command, trust state, risk class, expected artifacts, and continuation policy.
2. Ask plugins or the Ouroboros plugin runtime for declared side-effect metadata when available.
3. Fall back to conservative defaults when metadata is incomplete, especially for write-capable or handoff-producing commands.
4. Render the preview in the TUI before execution when the command may write files, create handoff artifacts, request elevated capability, or trigger continuation.
5. Allow already-trusted read-only commands to execute with minimal friction.
6. Record the accepted preview in session or journal state so later artifacts and continuations can be explained against the original plan.

Why This Matters

Natural-language plugin execution compresses a lot of intent into one prompt. Without a side-effect preview, users may only discover after the fact that a plugin created files, selected a run directory, generated a Seed, or tried to continue into another workflow.

A preview makes the workflow feel intentional:

• users understand what will happen before it happens
• artifact detection has an expected target instead of being guessed after execution
• continuation into ooo run is presented as a policy decision, not a surprise
• tests can assert the plan before any plugin code runs
• trust and safety decisions remain visible without making the product feel defensive

Acceptance Criteria

• Workflow-producing plugin commands can produce a reviewable side-effect preview before dispatch.
• The preview includes plugin, command, arguments, trust state, risk class, expected artifact locations, and continuation policy.
• Commands with file writes, generated handoffs, missing trust, or destructive capability require an explicit review state before execution.
• Already-trusted read-only commands can bypass the full preview or show a compact status only.
• If side-effect metadata is missing, ourocode uses conservative language rather than pretending to know exact writes.
• Accepted previews are recorded so generated artifacts and follow-up continuations can be traced back to the original user-approved plan.
• Tests cover read-only previews, handoff-producing previews, missing metadata, trust-blocked previews, and continuation policy rendering.

Non-goals

• Replacing the Ouroboros plugin firewall.
• Auto-trusting or auto-installing plugins.
• Predicting arbitrary filesystem writes from unstructured shell execution.
• Building a full plugin marketplace or permission editor.
• Blocking every trusted read-only command behind a confirmation dialog.

Related

• Builds on Support natural-language dispatch for installed Ouroboros UserLevel plugins #2.
• Complements Vision: make plugin resolution an explicit preflight step #16 by focusing on user-visible side effects rather than plugin resolution itself.
• Complements Vision: make plugin trust understandable at the moment of use #20 by focusing on execution consequences rather than trust comprehension alone.