Skip to content
Orcho Docs

Prompt Engine for Orcho Runs

Orcho’s prompt engine is not a folder of long prompts. It is the composition layer that turns a profile step into the exact instruction surface a worker runtime receives.

The important split is:

profile step
  → prompt spec: role + task + format
  → prompt engine: parts + contracts + context + turn payload
  → worker runtime: Claude, Codex, Gemini, or another adapter

The worker runtime executes. The prompt engine decides what the worker is asked to do, which contracts are protected, and which project or workspace overrides are allowed to participate.

Role, task, format

Section titled “Role, task, format”

Profiles can select composable prompt parts for a phase:

{
  "phase": "review_changes",
  "prompt": {
    "role": "code_reviewer",
    "task": "code_review",
    "format": "detailed"
  }
}

Read the three axes separately:

AxisMeaningExamples
roleWho is speaking.systems_architect, implementation_engineer, code_reviewer, release_manager
taskWhat this phase does.plan, implement, repair_changes, code_review, final_acceptance
formatHow detailed the answer should be.terse, detailed, bullets, handoff

This is why Orcho can use the same worker runtime in different roles without collapsing every phase into one generic agent prompt.

Resolution order

Section titled “Resolution order”

Prompt overrides are composable parts. Resolution is intentionally layered:

1. project/.orcho/multiagent/prompts/{roles|tasks|formats}/NAME.md
2. workspace-orchestrator/.orcho/multiagent/prompts/{roles|tasks|formats}/NAME.md
3. core/_prompts/{roles|tasks|formats}/NAME.md

Project overrides win over workspace overrides. Workspace overrides win over core defaults. Core defaults are always present.

Use this for targeted tuning:

project/.orcho/multiagent/prompts/tasks/code_review.md
project/.orcho/multiagent/prompts/roles/code_reviewer.md
workspace-orchestrator/.orcho/multiagent/prompts/formats/handoff.md

Do not create old flat prompt names like developer_build.md or reviewer_code_review.md. The engine resolves composable parts by layer.

Protected contracts

Section titled “Protected contracts”

Not every instruction is user-editable. Orcho separates editable prompt parts from code-owned contracts.

LayerOwned byPurpose
roles/*project, workspace, or corePersona and posture.
tasks/*project, workspace, or corePhase procedure.
formats/*project, workspace, or coreOutput style and detail level.
system-tail contractsOrcho codeMachine output shape, parser contract, language posture, git policy, review target.
dynamic partsOrcho codeCurrent task, plan, diff, artifacts, feedback, codemap, verification context.

This boundary is load-bearing. A project can tune how a reviewer behaves, but it should not accidentally delete the JSON contract that the review parser depends on. A workspace can tune a task procedure, but it should not own the git handoff policy or the review target semantics.

Prompt turn anatomy

Section titled “Prompt turn anatomy”

A rendered turn is assembled from stable parts and volatile parts:

bootstrap
  → role
  → phase/task procedure
  → bound skill content
  → protected contracts
  → project/workspace context
  → current turn payload

The late turn payload is where task text, feedback, artifacts, and round-local state live. The earlier parts are more stable and easier to reuse across similar runs. This is why Orcho treats prompt composition as engineering infrastructure, not only copywriting.

What to tune where

Section titled “What to tune where”

Use the smallest layer that solves the problem:

NeedUse
Name the project, stack, architecture, important paths.plugin.py
Add project-specific test or review hints.plugin.py
Route a subtask to a repeatable specialist procedure.skill registry
Change review style or implementation procedure for one project.project prompt override
Apply the same prompt posture to several repos.workspace prompt override
Change which role/task/format a phase uses.profile prompt spec
Change workflow order, retries, gates, or handoff.profile and gate policy
Change parser schema, review target, git policy, or language contract.Orcho code-owned contract

The rule is simple: project facts belong in the plugin, behavior phrasing belongs in prompt parts, specialist procedures can live in skills, and machine contracts belong in code.

Measuring the prompt layer

Section titled “Measuring the prompt layer”

The engine treats “is this prompt layer worth its cost?” as a measurable question, not a matter of taste:

Does this prompt layer improve task outcomes enough to justify its cost?

The comparison primitive for that already lives inside the engine: an internal ablation mode can render any phase with the editable role/task/format layer swapped for a short code-owned minimal intent, while keeping the identical system-tail contracts. It is deliberately not a user-facing feature — no profile field, CLI flag, or MCP option — because disabling the system tail would test protocol breakage, not prompt quality. Every production run uses the full layer.

A separate evaluation bench on top of that primitive — repeatable cases, expected and forbidden behaviors, scored comparisons — is planned; its docs will live separately when it is ready. This page explains the engine primitives it depends on.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Next

Section titled “Next”