Profile Reference for Orcho Runs

Profiles are Orcho’s executable run-shape contracts.

For a visual walkthrough, open the profile workflow maps. Every built-in profile has a diagram with roles, stages and feedback loops.

Use Profile semantics for the first mental model and Profiles and gates for policy design. Use this page when you need the expert vocabulary: every profile mode, every major profile key, and what each setting controls.

Profile vocabulary

Several different things are easy to call “profile mode”. Keep them separate:

Surface	Values	What it controls
concrete profile	small_task, feature, complex_feature, planning, research, delivery_audit, code_review, refactor, migration	The executable workflow shape.
selector	auto-detect	Recommendation step before dispatch; resolves to a concrete profile and mode.
operating mode	fast, pro, governed	Strictness posture for the selected work kind.
recipe kind	full_cycle, focused, internal	Broad shape family used by built-in profiles.
profile kind	custom, full_cycle, scoped	JSON authoring typology for built-in and plugin profiles.
profile variant	lite, advanced, enterprise, plan, review, task, or custom strings	Legacy/custom subcategory; built-in semantic profiles do not use it for identity.
phase execution mode	linear plus registered plugin modes	How one profile step is invoked.
implementation execution	whole_plan, subtask_dag	How the implement phase consumes a parsed plan.
session split	stateless, per_phase, per_role, common	How runtime sessions are scoped across phases.
session continuity	fresh_only, loop_continue, same_zone_continue	Whether a phase resumes its own prior runtime session on a repeat call.
handoff type	human_bypass, human_feedback_on_reject, human_feedback_always	When a run pauses for operator decision.
cross scope	global, project, both, skip	Where a step is projected in orcho cross.
cross gate run mode	always, auto, manual_confirm, never	Whether runner-owned cross gates execute.
cross gate skip policy	block, allow_with_gap, allow	What happens when a cross gate is skipped.
worktree isolation	per_run, off	Whether the run uses a run-owned checkout or the project checkout.

Built-in profiles

The operator-facing built-ins are semantic work kinds. Internal profiles exist for scoped follow-up flows but should not be presented as first-run choices.

Profile	Default mode	Recipe	Implementation	Isolation	Cross gates	Shape
small_task	fast	full_cycle	pipeline default	off	no	plan/validate once, then implement
feature	pro	full_cycle	subtask_dag	global default	yes	plan/validate loop, implement, review/repair loop, final acceptance
complex_feature	pro	full_cycle	pipeline default	global default	yes	feature-like flow plus compliance/audit phase
planning	pro	focused	none	off	no	plan/validate loop only
research	fast	focused	none	off	no	plan/validate loop for investigation
delivery_audit	pro	focused	none	off	no	review current diff, then final acceptance
code_review	pro	focused	none	off	no	review current diff, then final acceptance
refactor	pro	full_cycle	subtask_dag	global default	yes	feature-like flow for restructuring
migration	pro	full_cycle	pipeline default	global default	yes	complex-feature-like flow for migration
task	internal	internal	pipeline default	off	no	implement against an existing plan
correction	internal	internal	pipeline default	global default	no	system follow-up after rejected delivery

global default means the profile does not override the workspace or app-level setting. For worktree isolation that usually means worktree.isolation = per_run unless local config or CLI override changes it.

Top-level profile keys

Profile objects are strict. Unknown keys are rejected so typos do not silently disable policy.

{
  "feature": {
    "kind": "custom",
    "semantic_profile": "feature",
    "default_mode": "fast",
    "recipe_kind": "full_cycle",
    "description": "...",
    "change_handoff": "uncommitted",
    "implementation_execution": "subtask_dag",
    "worktree_isolation": "per_run",
    "steps": [],
    "cross_gates": {}
  }
}

Key	Required	Meaning
kind	yes	JSON authoring family: custom, full_cycle, or scoped. Built-ins use custom except internal task.
variant	no	Optional subtype for custom/plugin profiles. Not the identity source for built-ins.
semantic_profile	no	Work-kind identity for built-ins, for example feature.
default_mode	no	Default operating mode when the caller does not pass an explicit mode.
recipe_kind	no	Broad family: full_cycle, focused, or internal.
description	no	Human-readable profile summary.
change_handoff	no	Authoring-to-review diff contract. Defaults to pipeline config when absent.
implementation_execution	no	Profile-level implement delivery policy. Defaults to pipeline config when absent.
worktree_isolation	no	Profile-level isolation intent. Defaults to worktree config when absent.
steps	yes	Ordered phase steps and loop wrappers.
cross_gates	no	Runner-owned terminal gates for cross-project mode.

Operating modes

Operating mode is not the same as profile. It is the strictness posture applied to a selected work kind. It does not change which gates exist or which commands run — it rewrites, deterministically, two things: each gate’s blocking tier and the action taken when a gate fails. Cost is never an input: a required gate blocks even when it is expensive.

Blocking-tier rewrite. A gate’s declared tier is suggest (advisory) / warn / require (blocking). The mode rewrites it:

Declared tier	fast	pro	governed
suggest	→ off (dropped)	suggest	suggest
warn	warn	warn	→ require (escalated)
require	require	require	require

Gate-failure action rewrite.

Situation	fast	pro	governed
Failed require after implement	continue_warn	repair_loop	repair_loop
Failed gate at delivery	continue_warn	handoff	handoff
Everything else	continue_warn	continue_warn	continue_warn

So pro and governed share the same failure routing (auto-repair after implement, human handoff at delivery). governed adds only the tier escalation: every warn becomes a hard require, so a run cannot quietly deliver over a soft failure.

When to use each.

Mode	Use when
fast	Low blast radius, reversible work: prototypes, spikes, docs, changes you will eyeball yourself. Advisory checks are skipped and a failed non-critical gate does not stop the run.
pro	Production work you intend to ship: every declared gate is honored, a failed post-implement require auto-routes into repair, a delivery-time failure pauses for you.
governed	High cost-of-error or irreversible/outward-facing work — money, hard-to-roll-back migrations, or anywhere a warning must be a hard stop. Never a default; always an explicit opt-in.

Pick the profile for what you are doing, then raise the mode above its default only when the cost of a silent miss justifies the extra blocking and handoffs.

Built-in defaults:

Default mode	Profiles
fast	small_task, feature, research
pro	complex_feature, planning, delivery_audit, code_review, refactor, migration
none	internal task, internal correction

--profile auto-detect can recommend both a concrete work kind and an operating mode. It is still a selector, not a profile.

Change handoff modes

change_handoff controls what authoring phases leave for review phases.

Mode	Authoring contract	Review target
uncommitted	Leave task changes in the working tree.	Review status, diff, and relevant untracked files.
commit	Produce one coherent task commit.	Review the latest task commit and leftover working-tree state.
commit_set	Produce a small coherent set of task commits.	Review the commit range and leftover working-tree state.

This is code-owned policy. Prompt overrides should not redefine review target semantics.

Step types

steps can contain phase steps and loop wrappers.

[
  {
    "loop": {
      "steps": [
        {"phase": "plan"},
        {"phase": "validate_plan"}
      ],
      "until": "validate_plan.approved",
      "max_rounds": 2,
      "round_extras_key": "plan_round"
    }
  },
  {
    "phase": "implement"
  }
]

Step type	Role
PhaseStep	One registered phase invocation.
LoopStep	Retry block around phase steps. Nested loops are not the public authoring path.

Common phase IDs:

plan
validate_plan
implement
review_changes
repair_changes
final_acceptance

Profiles may also use registered extension phases such as a compliance or audit phase when an embedder registers a handler.

PhaseStep keys

{
  "phase": "review_changes",
  "execution": {
    "mode": "linear",
    "session_split": "per_role",
    "session_continuity": "fresh_only"
  },
  "prompt": {
    "role": "code_reviewer",
    "task": "code_review",
    "format": "terse"
  },
  "handoff": {
    "type": "human_feedback_on_reject"
  },
  "quality_gates": [],
  "cross": {
    "scope": "project"
  }
}

Key	Meaning
phase	Registered phase name.
execution	Invocation mode plus session policy.
skill	Optional registered skill name for specialist routing.
effort	Optional phase-level effort hint.
overrides	Runtime or phase-specific overrides.
prompt	Composable prompt parts: role, task, format.
hypothesis	Optional pre-plan hypothesis policy.
handoff	Operator pause policy used by shipped profiles.
quality_gates	Phase-local gates and feedback routing.
cross	Projection policy for cross-project mode.

Execution and session modes

execution can be a string or object. Shipped profiles use the object form.

{
  "mode": "linear",
  "session_split": "per_role",
  "session_continuity": "loop_continue"
}

Key	Values	Meaning
mode	linear plus registered plugin modes	How one phase step is invoked.
session_split	stateless, per_phase, per_role, common	Session scope across phases.
session_continuity	fresh_only, loop_continue, same_zone_continue	Resume policy for repeated calls.
read_only	reserved	Future fanout/review policy field.
join	reserved	Future fanout/review policy field.
surfaces	reserved	Future fanout/review policy field.

Session split values:

Value	Behavior
stateless	No reusable physical runtime session.
per_phase	One session per phase per run/runtime/model.
per_role	One session per prompt role per run/runtime/model. Requires prompt.role.
common	One session per run/runtime/model.

Session continuity values:

Value	Behavior
fresh_only	Always start fresh; use compact handoff for prior context.
loop_continue	Resume the phase’s prior session on round 2+ of the same loop.
same_zone_continue	Resume only for a same-write-zone follow-on such as implement to repair.

Implementation execution modes

Implementation delivery is selected at profile or pipeline level. It is not a PhaseStep.execution.mode.

Mode	Meaning
whole_plan	One implement invocation consumes the plan.
subtask_dag	Implement executes parsed plan subtasks as tracked delivery units.

subtask_dag is sequential today. It is a controlled subtask execution policy, not a promise of parallelism.

Loop settings

{
  "loop": {
    "steps": [
      {"phase": "review_changes"},
      {"phase": "repair_changes"}
    ],
    "until": "review_changes.clean",
    "max_rounds": 2,
    "round_extras_key": "repair_round",
    "oscillation_halt_after": null
  }
}

Key	Meaning
steps	Phase steps executed inside the loop.
until	Predicate such as validate_plan.approved or review_changes.clean.
max_rounds	Automatic retry budget.
round_extras_key	Metadata key used to record loop round state.
oscillation_halt_after	Optional guard for repeated unstable loop behavior.

until reads phase log fields. not <phase>.<field> exits when the field is falsy.

Prompt spec

Profiles choose prompt parts; the prompt engine resolves their content.

{
  "prompt": {
    "role": "systems_architect",
    "task": "plan",
    "format": "terse"
  }
}

Axis	Examples	Meaning
role	systems_architect, plan_reviewer, implementation_engineer, code_reviewer, release_manager	Persona and responsibility.
task	plan, validate_plan, implement, repair_changes, code_review, final_acceptance	Procedure for the phase.
format	terse, detailed, bullets, handoff	Output detail and shape.

Read Prompt engine for resolution order and protected contracts.

Hypothesis policy

hypothesis is normally attached to a plan step.

{
  "hypothesis": {
    "attempts": 1,
    "format": "compact"
  }
}

Key	Meaning
attempts	Number of pre-plan hypothesis attempts. 0 disables the prelude.
format	Optional hypothesis prompt format; otherwise inherits the plan format.

Handoff settings

Shipped profiles use handoff to decide when a phase pauses with an operator decision.

{
  "handoff": {
    "type": "human_feedback_on_reject",
    "repair_attempts": 1,
    "on_exhausted": "auto_waiver"
  }
}

Key	Values	Meaning
type	human_bypass, human_feedback_on_reject, human_feedback_always	Pause policy.
repair_attempts	integer	Automatic substance-repair budget for implement subtasks before handoff/fallback.
on_exhausted	halt, auto_waiver	Fallback after repair budget is spent.

Handoff type meanings:

Type	Behavior
human_bypass	Never pause for this step.
human_feedback_on_reject	Pause only after the final automatic round rejects or remains incomplete.
human_feedback_always	Pause on every round for human decision.

Quality gate settings

{
  "quality_gates": [
    {
      "name": "tests",
      "kind": "computational",
      "on_fail": "feed_into_next",
      "feed_target": "last_test_output",
      "config": {}
    }
  ]
}

Key	Values	Meaning
name	registered gate name	Gate identifier.
kind	computational, inferential	Whether the gate runs a concrete check or evaluates output.
on_fail	halt, feed_into_next, trigger_replan, informational	Failure routing.
feed_target	state/extras key	Required when on_fail is feed_into_next.
config	object	Gate-specific settings.

Quality gates are phase-local policy. Verification receipts are the durable proof surface. Read Verification receipts for the proof model.

Cross projection settings

Every step intended for orcho cross needs a cross annotation.

{
  "cross": {
    "scope": "global",
    "handler": "cross_plan"
  }
}

Key	Values	Meaning
scope	global, project, both, skip	Whether the step runs at cross level, project level, both, or not at all.
handler	cross_plan, cross_validate_plan	Cross-level dispatcher. Required for global or both.

contract_check is not a step handler. The cross runner appends it as a terminal gate when the profile opts into cross gates.

Top-level cross_gates:

{
  "cross_gates": {
    "contract_check": {
      "enabled": true,
      "mode": "artifact_bundle",
      "run": "always",
      "on_skip": "block"
    },
    "cross_final_acceptance": {
      "enabled": true,
      "run": "always",
      "on_skip": "block"
    }
  }
}

Key	Values	Meaning
enabled	boolean	Whether the gate is active.
mode	artifact_bundle for contract_check	Gate input mode.
run	always, auto, manual_confirm, never	Gate execution policy.
on_skip	block, allow_with_gap, allow	Release behavior when the gate is skipped.

Full-cycle delivery profiles opt into strict cross terminal gates. Focused and small-task profiles do not.

Worktree isolation in profiles

Profile-level worktree_isolation overrides the global worktree config. This is a policy setting, not only a filesystem setting: it decides what checkout workers may mutate and what checkout reviewers and receipts should treat as the subject.

Value	Meaning
off	Run directly in the project checkout. Used by focused/current-diff profiles.
absent	Use global worktree config, normally per_run.

Policy consequences:

Posture	Consequence
per_run via global config	Agents and verification work in a run-owned checkout; delivery back to the project is a later boundary.
off	Agents and verification work directly in the project checkout; useful for review/audit/current-diff workflows but with less mutation isolation.

Resolution order is:

CLI override
  > profile worktree_isolation
  > worktree config

Read Workspace model for {project} vs {checkout} and Profiles and gates for the operator-facing policy model.

Profile overlays

Local config can patch shipped profiles without copying the whole profile.

{
  "profiles_v2": {
    "feature": {
      "_profile": {
        "worktree_isolation": "off"
      },
      "review_changes": {
        "handoff": {
          "type": "human_feedback_always"
        }
      }
    }
  }
}

Overlay target	Meaning
_profile	Deep-merge into the top-level profile object.
phase name	Deep-merge into the matching phase step.

Lists are replaced, not appended. To change quality_gates, restate the full list. If a phase name is missing or ambiguous inside the profile, loading fails.

Authoring checklist

Before creating or overriding a profile, answer:

1. Is this a new work kind or only a local policy override?
2. Which concrete phase graph does the run need?
3. Which loop predicates prove readiness?
4. Which handoff points need human control?
5. Should implementation be whole_plan or subtask_dag?
6. Should sessions be common, per_role, per_phase, or stateless?
7. Which prompt role/task/format should each phase use?
8. Which gates are phase-local feedback versus durable verification receipts?
9. Should the profile work in cross-project mode?
10. Should it run in a run-owned checkout or the project checkout?

Deep reference

The canonical engineering docs live with the code:

• docs/reference/profile_schema.md — the profile dataclass contract
• docs/guides/profile_authoring.md — authoring custom profiles end to end

Related

• Configuration reference shows where profile settings fit in the wider config stack.
• Profile semantics explains the beginner mental model.
• Profiles and gates explains policy design.
• Plan contract and DAG explains subtask_dag.
• Cross-project mode explains cross projection in operation.