Profile Semantics for Agent Runs

Orcho starts by deciding what shape of work a task deserves.

A profile is not a visual theme, a model preset, or a convenience flag. It is the semantic contract for a run: lifecycle depth, gates, evidence, recovery policy, runtime posture, and operator control.

intentprofilephasesgatesevidence

The task says what you want. The profile says how carefully Orcho should handle the work before a result can be trusted.

Pick a profile — or let it cycle — and watch the same intent project to a different run-shape, with its own gates and proof depth:

profiles · one intent · how careful to be

▶ Play

one task “Add validation to the login endpoint” → how careful to be?

small_task light feature strict complex_feature strictest

1. plan
2. validate_plan
3. implement

mode fast gates no QA loop · no cross gates ships operator's call

a scoped change — plan it, then do it. No review loop, no final gate.

Not every profile ships code: planning stops at a reviewed plan (plan → validate_plan); code_review audits your working tree (review_changes → final_acceptance). Same plane, different shape.

The profile is the first semantic choice — it does not change the task, it changes how much plan, review, and proof the run produces. intent → profile → pipeline → gates → evidence.

One intent, three run-shapes. A profile is the strictness dial: the same task projects to small_task’s quick cycle, feature’s full plan-review-repair-accept arc, or complex_feature’s added compliance gate. Profile names, phases, modes, and cross-gate policy are the engine’s own catalogue.

Why profiles come first

If one agent can solve the task cleanly, use one agent.

Orcho begins where agent work intersects delivery risk: review, cost, gates, workspace boundaries, recovery, and accountability. Profiles keep that from becoming a vague “more process” decision. They turn it into an explicit operating shape.

What a profile decides

Profiles can decide:

• whether the run is planning-only, review-only, implementation, or full delivery;
• whether review and final acceptance are required;
• what counts as a blocking finding;
• which evidence surfaces must be produced;
• whether repair and correction follow-ups are part of the lifecycle;
• how much state is preserved across phases;
• whether the run stays in one project or coordinates a participant set.

Gates then enforce the profile. A profile chooses the workflow; a gate decides whether a phase result is good enough to continue.

Advisor selection

If you do not know which profile fits a task, Orcho can act as a profile advisor. Use --profile auto-detect to ask Orcho to recommend a concrete work kind and mode before normal profile dispatch.

auto-detect is not a profile. It is a selector. The operator can accept the recommendation, override it, or configure threshold/fallback behavior for non-interactive runs.

Read Profile advisor before treating auto-selection as an autopilot.

Read runs through the profile

When a run finishes, do not only ask “did the agent change code?”

Ask:

• What profile did this run use?
• Which phases did that profile require?
• Which gates approved or rejected?
• Which receipts did the profile expect?
• Is the final decision strong enough for this task’s risk?

This is the difference between a transcript and an operating system for agent delivery. The transcript shows what happened. The profile tells you whether what happened was enough.

Starter shapes

Use these as mental models, not as a complete product matrix:

Light mono-runOne project, one focused task, enough lifecycle to inspect the result.Controlled deliveryPlanning, implementation, review, repair if needed, and final acceptance.Review or planning modeUse Orcho to structure thinking, findings, and decisions without forcing implementation.Participant-set workflowOne feature intent split across project boundaries, with cross-surface evidence.

The named profiles behind those shapes, at a glance:

Profile	Shape	What it catches	Relative cost
small_task	plan → validate once → implement	plan mistakes before code; no review loop	lowest
code_review	review the current diff → final acceptance	false-done in work you already have, without new implementation	low
feature	plan loop → implement → review/repair loop → final acceptance	the full false-ready class: plan drift, review blockers, unverified checks	standard
complex_feature	feature plus a compliance gate, stricter verification	higher-risk changes that need stronger receipts	highest

The cheapest run that still blocks false-done on new work is feature. For a diff you already have, code_review is cheaper. The full catalogue — all nine public profiles with phases, modes, and schema keys — lives in Profile reference.

Next

• Run the smallest profile path in Quickstart.
• Let Orcho recommend a profile in Profile advisor.
• Learn the concrete lifecycle in Your first run.
• See how participant-set work becomes Cross-project mode.
• See deeper policy design in Profiles and gates.
• Use Profile reference when you need every profile mode and schema setting.