Skip to content
Orcho Docs

Profile advisor

Manual profile choice is still the cleanest first mental model: choose feature for a normal first delivery run, then learn what the lifecycle feels like.

The advisor path answers the next question: “I have a real task, but I am not sure how much process it deserves.” In that case Orcho can inspect the task and recommend a concrete semantic profile plus operating mode.

manual profile = operator already knows the work shape
auto-detect    = Orcho recommends the work shape, operator keeps control

What auto-detect is

Section titled “What auto-detect is”

auto-detect is a selector token, not an executable profile.

When you pass it as the profile, Orcho resolves it before normal profile dispatch:

Terminal window
orcho run \
  --project ~/www/my-workspace/my-project \
  --task "Add validation to the login endpoint." \
  --profile auto-detect \
  --output live

The selector asks the advisor to classify the task into:

  • a semantic work kind, such as small_task, feature, planning, code_review, refactor, or migration;
  • an operating mode, such as fast, pro, or governed;
  • confidence, rationale, and risk flags;
  • optional topology advice, such as “this may span more than one project”.

Then Orcho runs the selected concrete profile. The run is not executed under an abstract “auto” profile.

Interactive flow

Section titled “Interactive flow”

On a confirm-policy terminal, the advisor prints the recommendation before the run starts:

auto-detect -> feature · fast (confidence 0.82)
   This is a focused implementation task with review value.
  [Enter] accept, or type a work kind (...):

Press Enter to accept, or type a different work kind to override. That keeps the recommendation useful without hiding the decision from the operator.

Non-interactive flow

Section titled “Non-interactive flow”

In non-interactive contexts, Orcho cannot stop for a prompt. The configured auto-detect policy decides what happens:

ConditionBehavior
confidence is high enoughaccept the recommendation and run the selected profile
confidence is lowapply fallback policy or fail, depending on config
detector errorsapply fallback policy or fail, depending on config
explicit --mode is provideduse the explicit mode over the recommended mode

The default safe shape is recommendation with fallback. Expert teams can tune thresholds and fallback behavior in local config.

MCP client behavior

Section titled “MCP client behavior”

orcho_profiles_list exposes concrete profiles separately from selectors. The auto-detect selector should be shown as an advisor option, not as a normal profile row.

An MCP client can start a run with:

orcho_run_start(
  project_dir="/abs/path/to/project",
  task="Add validation to the login endpoint.",
  profile="auto-detect",
)

After the run starts, status and evidence projections can expose the recorded auto-detect result: selected profile, selected mode, confidence, rationale, risk flags, fallback state, and any topology next actions.

The client should surface that as a decision record:

requested selector: auto-detect
selected profile:   feature
selected mode:      fast
confidence:         0.82
rationale:          focused implementation task with review value

If auto-detect falls back or cannot produce a trusted choice, the client should ask the operator for an explicit profile. It should not silently invent one.

Topology advice is separate

Section titled “Topology advice is separate”

The advisor may also detect that the task probably crosses project boundaries. That is topology advice, not profile selection.

Topology advice can say “this looks cross-project”, but it does not start a cross run or widen delivery by itself. The operator still chooses whether to:

  • continue strict mono;
  • continue mono while disclosing sibling changes;
  • start an explicit cross-project run.

This keeps profile choice, topology, and delivery scope separate.

Read Cross-project mode when the topology advice is the important part of the recommendation.

When to use it

Section titled “When to use it”

Use the advisor when:

  • the task is real enough that profile depth matters;
  • the operator is unsure between small_task, feature, planning, review, refactor, or migration;
  • a client should explain why it picked a workflow shape;
  • you want recorded evidence of the recommendation.

Use a concrete profile when:

  • you already know the work kind;
  • the task is a known quick edit;
  • a script or CI job must be deterministic without advisor calls;
  • you are comparing profiles and need an exact profile name.

For unattended runs, read CI autopilot. It explains when --no-interactive should use an explicit profile and when advisor-backed selection is safe enough to trust.

Section titled “Related”