Cross-project mode

Cross-project mode is where Orcho becomes most different from a normal single-agent workflow.

It is not “run several agents in several repositories.” It is one delivery intent that Orcho plans once, projects into participating projects, executes as separate sub-pipelines, then checks again at the system boundary.

feature intent cross plan project handoffs sub-pipelines contract check system gate

A feature starts as one idea. Orcho splits the work across aliases such as api, web, mobile, analytics, MCP, or infra, then brings the result back to a single delivery decision.

Why this matters

Many real failures happen at system boundaries:

the API emits one field name while the web consumer expects another;
a backend change ships without the frontend state transition;
analytics events are added after rollout instead of as part of the feature;
an SDK, MCP surface, or docs page drifts from the runtime behavior;
each repository passes its own tests while the integrated change is still wrong.

A normal mono-run can be excellent inside one checkout. Cross-project mode is for the moment when the task itself crosses ownership, repository, or subsystem boundaries.

one feature intent
  -> shared interface contract
  -> per-project subtasks
  -> per-project implementation and review
  -> cross-level contract check
  -> one system release decision

Run shape

The operator starts with project aliases:

orcho cross \
  --projects api:/repo/api web:/repo/web \
  --task "Fix 500 error bug in user creation form" \
  --profile feature \
  --workspace /repo/workspace-orchestrator \
  --output live

The aliases are not decoration. They become the delivery map: every cross plan, handoff, sub-pipeline, contract check, artifact, and usage rollup can be read back through those names.

What the live stream should reveal

The live CLI output should make the system shape readable before anyone opens the artifacts:

Orcho Cross-Run  20260629_231315  mode=full
Task      Fix 500 error bug in user creation form
Projects  2 aliases
  [api]  /repo/api
  [web]  /repo/web
Profile   feature
Plan source  cross
Projection   global + per-project

Pipeline
  cross_hypothesis -> cross_plan -> cross_validate_plan
    -> [api] sub-pipeline
    -> [web] sub-pipeline
    -> contract_check
    -> cross_final_acceptance

The compact pipeline DSL remains useful here:

⟳² (▶ plan [Claude] -> · validate_plan [Codex])
  -> project handoffs
  -> [api] implement/review/final
  -> [web] implement/review/final
  -> · contract_check [Codex]
  -> · cross_final_acceptance [Codex]

The important shift is that review happens at two levels:

Level	Question
Project sub-pipeline	Did this alias satisfy its assigned subtask?
Contract check	Do the aliases agree at the integration boundary?
Cross final acceptance	Can the coordinated change ship as one system?

Profile projection

Cross-project mode is driven by profile projection.

The operator still chooses one profile. Orcho projects that profile into:

global steps, such as cross planning and cross plan validation;
project steps, such as implementation, review, repair, and final acceptance inside each alias;
runner-owned cross gates, such as contract_check and cross_final_acceptance when the selected profile enables them.

This matters because cross is not a separate bag of scripts. It uses the same profile and policy language as mono-runs, then adds topology.

Handoffs

After the cross plan is approved, each project receives a handoff.

A good handoff should contain:

the shared feature intent;
the alias-specific subtask;
the sibling aliases and their responsibilities;
interface assumptions;
verification expectations;
the reason the work is scoped to this project.

The handoff is how Orcho prevents “multi-repo” from becoming vague. Each project gets a concrete job, but the job still belongs to the same system delivery.

When to use it

Use cross-project mode when:

one feature requires coordinated changes in two or more repositories;
a bug appears only when producer and consumer code meet;
a schema, event, SDK, MCP, or API contract changes;
backend, frontend, mobile, analytics, docs, or infra must move together;
separate teams can each be locally correct while the system is globally wrong.

Stay with a mono-run when:

one repository owns the whole change;
the boundary is not yet clear;
the task is exploratory and should first become a smaller contract;
the extra planning and gates would cost more than the risk they reduce.

What it guarantees

Cross-project mode gives the operator a stronger delivery protocol:

one top-level plan instead of disconnected repo-local plans;
explicit participant aliases;
per-project handoffs;
per-project run evidence;
cross-level contract review;
one terminal system release gate;
usage split across aliases and cross-level phases.

It does not remove the need for project-local verification. The final state still needs normal diff review, tests, lint, and domain checks in the affected repositories.