# Runtime LLM Flow

Open Orchestra is the local control plane. The active LLM runtime is the parent
agent today.

That means Claude, Codex, Cursor, VS Code, Windsurf, or another LLM starts the
work, reads the relevant project instructions, and calls `orchestra` commands to
coordinate tasks, roles, skills, handoffs, reviews, evidence, gates, and model
routing metadata. When a workflow role is configured with a non-`none`
provider, `orchestra workflow run` also invokes the configured provider for
that phase and records phase artifacts plus model provenance.

## Startup Flow

Use this sequence for a new project or a new task:

```bash
orchestra init
orchestra health --json
orchestra task add --id STORY-001 --title "Short title" --owner developer --goal "Outcome"
orchestra context --task STORY-001 --json
orchestra delegation decide --task STORY-001 --json
orchestra plan --task STORY-001 --json
orchestra memory hook --point before_plan --task STORY-001 --json
orchestra skills plan --task STORY-001 --json
orchestra skills render --target codex --task STORY-001
orchestra protocol render --target codex --task STORY-001
orchestra workflow render --target codex --task STORY-001
orchestra commands manifest --json
orchestra runtime bootstrap --target codex
orchestra evidence add --task STORY-001 --role developer --type command --summary "npm run precommit passed" --command "npm run precommit" --exit-code 0
orchestra gate --gate architecture --task STORY-001
orchestra summary --json
```

Use `--target claude`, `--target cursor`, `--target codex`, `--target vscode`,
`--target windsurf`, or `--target generic` when rendering skills, protocol, or
workflow instructions for a specific runtime.

`orchestra init` also refreshes compact managed bootstrap blocks in
`ORCHESTRA.md` and `AGENTS.md`. These blocks tell the active LLM how to discover
commands and which task loop to run without copying the full manual into the
always-loaded context.

Open Orchestra does not own the entire instruction file. It appends or refreshes
only the marked managed block between `<!-- open-orchestra:start ... -->` and
`<!-- open-orchestra:end ... -->`. Project-authored rules before or after that
block remain owned by the project and are preserved. If the managed block was
edited manually, refresh reports drift and refuses to overwrite it unless
`--force` is supplied; `--force` replaces only the managed block, not the rest of
the file.

Use explicit init targets when a project should generate runtime-specific files:

```bash
orchestra runtime adapters --json
orchestra init --target claude,cursor,windsurf
```

## Parent Agent Prompts

Claude:

```text
Use Open Orchestra as the local control plane for this repo. Treat yourself as
the parent agent. Start by running health, context, delegation, plan, skills
plan, and target-specific skill/protocol render commands. Do not spawn or claim
subagents unless the local workflow state and user approval make that explicit.
Record evidence and reviews before saying work is complete.
```

Codex:

```text
Use the local orchestra CLI before implementation. Confirm the task exists,
inspect context and delegation, render Codex skills/protocol/workflow context,
implement with focused tests, run precommit, then record evidence and review
artifacts in Open Orchestra.
```

Cursor:

```text
Use Open Orchestra for task state and context. Render Cursor-targeted skills and
protocol instead of copying large rule files. Keep generated MDC/MD blocks
managed, record test evidence, and do not overwrite user-authored content.
```

Generic LLM runtime:

```text
Act as the parent agent. Use Open Orchestra commands as the source of truth for
tasks, roles, skills, workflow templates, evidence, reviews, and gates. Ask the
user before changing architecture or spending budget. Use provider-backed
workflow execution only when the workflow config has approved routing.
```

## Model Routing

Model routing controls which provider/model each role uses during autonomous
workflow phases. The default `none` provider keeps the deterministic workflow
behavior. Configure a role or default route to `fake` for local structured
execution tests, `openai` for the OpenAI Responses API, `anthropic` for the
Anthropic Messages API, `gemini` for the Gemini `generateContent` API, or
`ollama` for a local OpenAI-compatible Ollama endpoint.

```bash
orchestra model providers --json
orchestra model profile set --name local-fast --provider fake --model fake-model --roles developer,qa --activate
orchestra model profile list --json
orchestra model profile smoke --name local-fast --json
orchestra workflow run --task STORY-001 --profile local-fast --gates phase
orchestra model set-role --role qa --provider fake --model fake-model
orchestra model connect --provider gemini --model gemini-3-pro-preview --roles qa,reviewer_critic --api-key-file /absolute/path/to/gemini-key --allow-direct-provider-api
OPENAI_API_KEY=... orchestra model set-role --role architect --provider openai --model gpt-5.2
ANTHROPIC_API_KEY=... orchestra model set-role --role qa --provider anthropic --model claude-sonnet-4-20250514
GEMINI_API_KEY=... orchestra model set-role --role product_manager --provider gemini --model gemini-2.5-pro
orchestra model set-role --role developer --provider ollama --model llama3.2
orchestra model provenance list --json
orchestra budget check --json
orchestra workflow run --task STORY-001 --gates phase
```

Use `model connect` when a project wants to route one provider to several
roles, allow direct provider API calls, and store a local secret-file reference
in one idempotent config update. This is provider-agnostic: `--provider`,
`--model`, `--roles`, and optional credential env names define the actual
routing. Project-specific choices such as "Codex for developer and Gemini for
QA" belong in the consuming workspace config, not in Open Orchestra defaults.

Use named provider runtime profiles when a workspace needs repeatable routing
presets such as `local-fast`, `premium-review`, `offline`, or `regulated`.
`model profile set` stores role routing, fallback chains, and required
environment variable names without storing secrets. `model profile apply`
updates active role routing deterministically, and `workflow run --profile`
applies the profile before execution and records command evidence on the task.
`model profile smoke` performs local configuration checks and reports missing
secrets or policy failures with sanitized messages.

The OpenAI adapter reads `OPENAI_API_KEY` from the environment and optionally
`OPENAI_BASE_URL` for an HTTPS-compatible endpoint. API keys must not be stored
in workflow config, evidence, docs, or committed files.

The Anthropic adapter reads `ANTHROPIC_API_KEY` from the environment and
optionally `ANTHROPIC_BASE_URL` for an HTTPS-compatible endpoint. It uses
`ANTHROPIC_VERSION` when provided, otherwise the default API version is
`2023-06-01`. JSON-mode requests add an explicit JSON-only instruction because
Claude Messages API responses are normalized through text content rather than
OpenAI-style JSON schema response formatting.

The Gemini adapter reads `GEMINI_API_KEY` or `GOOGLE_API_KEY` from the
environment. For local secret files, set `GEMINI_API_KEY_FILE` or
`GOOGLE_API_KEY_FILE` to an absolute path containing only the key value. The
adapter also reads optional `GEMINI_BASE_URL`; the base URL must be HTTPS and
defaults to `https://generativelanguage.googleapis.com`.

The Ollama adapter defaults to `http://localhost:11434/v1` and uses the
OpenAI-compatible `/chat/completions` endpoint. Set `OLLAMA_BASE_URL` only for
loopback or private-network endpoints; public internet hosts are rejected unless
a future trusted-provider policy explicitly implements that exception. Endpoint
URLs must use `http` or `https`, must not include credentials, and are recorded
in evidence only as redacted local-provider provenance. Set `OLLAMA_API_KEY`
when the local endpoint requires one.

### Internal Ollama Agent Improvement Path

Ollama-backed internal agents must follow the governed local evaluation and
tuning path before any training or fine-tuning work. The default improvement
sequence is:

1. deterministic fake/mock provider contract evidence;
2. governed evaluation fixture curation with manifest provenance;
3. versioned prompt/context pack tuning with rollback metadata;
4. optional loopback/private real Ollama smoke;
5. separate Product, Architect, Security, Compliance/Privacy, QA, and Release
   approval before any model-weight training, LoRA, quantization, export, or
   publication.

Agents should consume Orchestra commands for provider discovery, model profile
smoke checks, workflow execution, provenance review, evidence, and reviews.
They must not call `ollama`, provider SDKs, or training tools directly for this
path unless a future task defines an approved command contract and safety
policy. See
[Internal Ollama Agent Evaluation And Tuning Design](internal-ollama-agent-design.md).

## Runtime Execution

Runtime execution is separate from model provider routing. `ModelProvider`
adapters call vendor APIs directly and therefore require provider API keys.
Runtime execution adapters prepare work for an already-authenticated runtime
such as Claude CLI, Codex CLI, OpenCode CLI, Cursor, VS Code, or Windsurf.

Use runtime execution when the user wants the active CLI/IDE agent to perform
the work and does not want Orchestra to call OpenAI, Anthropic, or another
vendor API directly:

```bash
orchestra runtime adapters --json
orchestra runtime brief --task STORY-001 --runtime claude-cli
orchestra runtime brief --task STORY-001 --runtime opencode-cli
orchestra runtime delegate-plan --task STORY-001 --runtime claude-cli --roles architect,developer,qa
orchestra runtime handoff --task STORY-001 --runtime claude-cli --artifact .agent-workflow/runs/STORY-001-runtime-claude-cli-delegation.md
```

Runtime briefs and delegation packets are written under `.agent-workflow/runs/`
and record provenance events. They are brief-only control artifacts in this
release; Orchestra does not launch arbitrary runtime processes or silently fall
back to vendor APIs.

Runtime policy can force executor selection without API keys:

```json
{
  "runtimePolicy": {
    "defaults": { "executor": "generic-runtime" },
    "byRole": { "developer": { "executor": "codex-cli" } },
    "byTask": { "STORY-001": { "executor": "claude-cli" } },
    "delegation": {
      "mode": "runtime-native",
      "allowDirectProviderApi": false
    }
  }
}
```

If a runtime does not support native subagents, Orchestra renders a delegation
packet in `brief-only` mode and requires user approval before any other
execution strategy. Direct provider API calls remain forbidden by runtime
execution packets.

Provider policy can restrict real adapters with `allowedProviders` and
`blockedProviders`. Cross-vendor fallback is blocked by default; enable
`allowVendorFallbackWithoutApproval` only after recording the required approval
for cost, privacy, and capability risk.

Future multi-model delegation should route by role capability, risk, budget,
latency, and required evidence. For example, a parent agent could keep planning
local, route security review to a stronger security model, route Playwright
analysis to a browser-capable runtime, and request user approval before any
budget fallback.

## Current Limits

- Provider-backed workflow execution has a fake adapter for deterministic tests,
  an OpenAI adapter for the Responses API, and an Anthropic adapter for the
  Claude Messages API. Additional vendors need explicit implementation and
  approval.
- Runtime execution adapters render briefs and delegation packets, but they do
  not yet launch external CLI/IDE processes non-interactively.
- `workflow run --phase-execution auto|subagents|single-agent` records phase
  executor provenance and can render role-scoped runtime-native delegation
  packets, but the parent runtime still owns any real spawn/interaction with
  external CLI or IDE subagents.
- Parallel independent CLI commands are expected to work, but dependent commands
  still need parent-agent ordering or future DAG semantics.
- Workflow files are local state. Promote durable lessons into docs, skills, or
  managed instruction blocks only after review.

## Related Docs

- [Skill Loading Strategy](skill-loading-strategy.md)
- [Runtime Adapters](runtime-adapters.md)
- [Internal Ollama Agent Evaluation And Tuning Design](internal-ollama-agent-design.md)
- [Open Orchestra MVP](orchestra-mvp.md)
- [Source of Truth and Agent Learning](source-of-truth-and-agent-learning.md)
- [Dogfooding Findings](open-orchestra-dogfooding-findings.md)