Skip to content
Orcho Docs

Prompt engine

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.

Prompt Utility Lab connection (planned)

Section titled “Prompt Utility Lab connection (planned)”

The prompt utility lab is not built yet — this section explains the connection, not a feature you can use today. The prompt engine creates the foundation for it. The question it will answer is not “can we write a nicer prompt?” The useful question is:

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

That requires separable prompt parts, repeatable cases, expected and forbidden behaviors, and the ability to compare a fuller method layer against a minimal intent plus the same system contracts. The docs for that evaluation surface should live separately when it is ready; this page explains the engine primitives it depends on.

Next

Section titled “Next”