Multi-Agent Orchestration Workflow — Production Skill

Version: 2.2.2  |  Runtime: Orca IDE ≥ 1.x  |  License: MIT

Reference flowchart: docs/workflow.md

1. Architecture Overview

The coordinator stays on the main branch for the entire run. It never runs git checkout; its only git operations in its own checkout are git fetch origin (and optionally git pull --ff-only). All implementation work happens in one feature worktree created in Phase 4.

┌───────────────────────────────────────────────────────────────────────┐
│               COORDINATOR (This Agent — stays on main)                 │
│                                                                        │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐  │
│  │ Phase 1 │→│ Phase 2  │→│ Phase 3  │→│        Phase 4         │  │
│  │ Gather  │  │ Plan+Rev │  │ Confirm  │  │ git fetch origin main │  │
│  └─────────┘  └──────────┘  └──────────┘  │ create ONE worktree   │  │
│                                            │ decompose → dispatch  │  │
│                                            │ wave 0                │  │
│                                            └───────────┬────────────┘  │
│                                                        │               │
│     ONE FEATURE WORKTREE   feature/<slug>   (base: origin/main)        │
│     ┌──────────────────────────────────────────────────┼───────────┐   │
│     │ Wave 0  (parallel, disjoint owns)                ▼           │   │
│     │   sub-1: [exec r0]→[review r0]→[fix r1]→[review r1] → PASS   │   │
│     │   sub-2: [exec r0]→[review r0]─────────────────────→ PASS    │   │
│     │          each […] = FRESH terminal + NEW task                │   │
│     │ Wave 1  (dispatched only after ALL parents PASS)             │   │
│     │   sub-3: sees parents' committed code in the same worktree   │   │
│     └──────────────────────────────────────────────────┬───────────┘   │
│  ┌──────────┐  ┌───────────────────────────────────────┘           │   │
│  │ Phase 6  │←│ collect every subtask verdict (PASS/FAIL)          │   │
│  │ Decide   │  └───────────────────────────────────────────────────┘   │
│  └────┬─────┘                                                          │
│  ┌────┴─────────────────────────────────────────────────────────────┐  │
│  │ Phase 7 (inside the feature worktree):                            │  │
│  │   rebase origin/main → autofix ≤2 → run tests →                   │  │
│  │   INTEGRATION REVIEW (fresh review terminal, ≤2 rounds) →         │  │
│  │   gh pr create (ONE PR) → poll gh pr view every 60s               │  │
│  └────┬──────────────────────────────────────────────────────────────┘  │
│  ┌────┴─────┐   ┌────────────────┐   ┌───────────┐                      │
│  │ Phase 8  │→ │ history.jsonl  │→ │  Notify   │  afterwards:          │
│  │ Cleanup  │   │ + park manifest│   │  User     │  git fetch only —    │
│  └──────────┘   └────────────────┘   └───────────┘  never checkout     │
└───────────────────────────────────────────────────────────────────────┘

Design Principles

2. State Machine

v2.2.0 adds INIT to the current_phase/current_state enums, makes EXECUTING wave-based (waves are topological levels of the subtask DAG), gives MERGING explicit sub-steps (rebase → autofix → tests → integration review → PR monitor), and makes PARKED a feature-level state (the whole feature is parked, never an individual subtask).

INIT → GATHERING → PLANNING → CONFIRMING → DISPATCHING → EXECUTING ⇄ DECIDING → MERGING → CLEANING → DONE — PARKED and TERMINATED are side exits reachable from several states (see the transition table).

State Transition Table

The full Mermaid diagram and the authoritative state transition table live in docs/workflow.md (状态流转表). They cover every transition — including the MERGING sub-steps, the PARKED exits, and fatal-error termination — and are the single source of truth for guards and triggers.

3. Prerequisites & Environment

3.1 Runtime Checks

Run scripts/check-prerequisites.sh before every run. It checks: Orca running & reachable; the coordinator is inside an Orca-managed checkout (orca worktree current) and on the main branch; required tools git ≥ 2.30, gh ≥ 2.0 (authenticated), jq; and a clean working tree. Missing hard requirements fail the run; checkout/branch/clean-tree problems warn (ORCA_WORKFLOW_STRICT_PREREQ=true escalates the Orca-checkout check to a hard failure).

Deleted in v2.2.0: the worker-terminal count check. Terminal objects have no type/tags fields and orca terminal create has no --tags flag, so a pre-flight "is there a tagged worker?" probe was meaningless. The coordinator spawns every worker terminal itself, fresh, at dispatch time. ORCA_WORKFLOW_STRICT_PREREQ is retained for the remaining checks in scripts/check-prerequisites.sh.

3.2 Required Tools

Environment variables are defined in §4.1 below. Agent routing variables (ORCA_WORKFLOW_*_AGENT, ORCA_WORKFLOW_FALLBACK_CHAIN) are defined in docs/agent-routing.md — the single source of truth for routing, including precedence and the fallback chain.

4. Configuration

4.1 Tunable Parameters

📖 Agent routing is defined in docs/agent-routing.md — the single source of truth. To change a preference, edit agent-routing.md plus the matching ORCA_WORKFLOW_* environment variable; never hardcode agent names into task specs.

The routing.*_agent_type values below are cold-start defaults only; at runtime the effective values come from agent-routing.md + env overrides.

{
  "workflow": {
    "version": "2.2.0",
    "limits": {
      "max_review_rounds": 3,
      "max_escalate_count": 2,
      "max_user_confirm_rounds": 3,
      "max_subtask_retries": 3,
      "max_global_retries": 2,
      "max_autofix_attempts": 2,
      "max_integration_review_rounds": 2,
      "max_clarification_rounds": 5
    },
    "timeouts_ms": {
      "worker_execution": 1800000,
      "human_response": 0,
      "pr_review_poll_interval": 60000
    },
    "routing": {
      "_note": "Single source of truth: docs/agent-routing.md. These are cold-start defaults only.",
      "plan_agent_type": "claude",
      "review_agent_type": "pi",
      "execution_agent_type": "kimi",
      "complex_execution_agent_type": "kimi",
      "image_agent_type": "grok",
      "fallback_agent_type": "pi",
      "default_model": "sonnet"
    },
    "terminals": {
      "spawn_per_role": true,
      "close_intermediate_terminals": true,
      "_note": "A fresh terminal is spawned for every round of every role, all inside the ONE shared feature worktree. `orca terminal create` has no --tags flag and terminal objects carry no type/tags fields: agent identity is carried by the --title prefix convention '[<role>:<agent>] …' and by the coordinator's state record (handle → role/round/agent_type)."
    },
    "merge": {
      "mode": "pr_only",
      "auto_merge_on_approval": false,
      "require_ci_pass": true,
      "delete_branch_after_merge": true
    },
    "observability": {
      "log_level": "INFO",
      "state_file": ".orca/workflow-state.json",
      "trace_all_gates": true
    }
  }
}

Environment variables override the config keys above (highest precedence, §4.2). Each variable is defined only here:

# VAR → config key
export ORCA_WORKFLOW_MAX_REVIEW_ROUNDS=3        # limits.max_review_rounds
export ORCA_WORKFLOW_MAX_ESCALATE=2             # limits.max_escalate_count
export ORCA_WORKFLOW_MAX_USER_CONFIRM=3         # limits.max_user_confirm_rounds
export ORCA_WORKFLOW_MAX_SUB_RETRY=3            # limits.max_subtask_retries
export ORCA_WORKFLOW_MAX_GLOBAL_RETRY=2         # limits.max_global_retries
export ORCA_WORKFLOW_MAX_AUTOFIX=2              # limits.max_autofix_attempts
export ORCA_WORKFLOW_MAX_INTEGRATION_REVIEW=2   # limits.max_integration_review_rounds
export ORCA_WORKFLOW_STATE_FILE=.orca/workflow-state.json  # observability.state_file
export ORCA_WORKFLOW_LOG_LEVEL=INFO             # observability.log_level

# Env-only switches (no config key)
export ORCA_WORKFLOW_STRICT_PREREQ=false  # true → check-prerequisites.sh fails hard on a missing prerequisite (recommended for CI)
export ORCA_WORKFLOW_DRY_RUN=false        # true → plan only, no dispatch (see references/runbooks.md)

4.2 Configuration File Resolution

The workflow looks for configuration in this order (first wins):

1. Environment variables (ORCA_WORKFLOW_*)
2. .orca/workflow-config.json (project-local)
3. ~/.config/orca/workflow-defaults.json (user-global)
4. Built-in defaults (shown above)

5. Phase 1 — Requirements Gathering

Full procedure: references/phase-1-gathering.md — read it before executing this phase.

• Clarify the raw user request; state INIT → GATHERING.
• Ask via the coordinator's native user-interaction channel only — never orca orchestration ask --to coordinator (that channel is worker → coordinator only).
• Hard cap MAX_CLARIFICATION_ROUNDS=5; exceeding it → TERMINATED.
• Gap checklist (5 items: Goal / Scope / Constraints / Context / Acceptance Criteria); ≥ 2 items missing → pause and clarify.
• Output: clarified_requirement JSON; on success → PLANNING.

6. Phase 2 — Plan Generation & Review

Full procedure: references/phase-2-planning.md — read it before executing this phase.

• The plan agent generates the plan; a separate review agent reviews it.
• Review is an independent task; the verdict arrives via worker_done — never gate-create.
• The plan artifact travels as text only; it is never written as a file into the main checkout.
• Caps: MAX_REVIEW_ROUNDS=3 + human escalation MAX_ESCALATE=2; exhaustion → TERMINATED (Terminate1).
• Review checklist includes declared owns, disjoint same-wave owns, and an acyclic DAG.
• Review PASS → CONFIRMING.

7. Phase 3 — User Confirmation

Full procedure: references/phase-3-confirming.md — read it before executing this phase.

• User sign-off via the native channel; three options only: Approve / Revise / Abort.
• Revise cap MAX_USER_CONFIRM=3; Abort terminates immediately at any round (Terminate2).
• No reduce-scope option (removed in v2.2.0).
• Approve → DISPATCHING; Revise → back to PLANNING with the user's feedback.

8. Phase 4 — Task Decomposition & Dispatch

Full procedure: references/phase-4-dispatching.md — read it before executing this phase.

• Create the ONE feature worktree + branch feature/<slug> based on origin/main; decompose the plan into the subtask DAG, compute waves, dispatch wave 0.
• Same-wave owns must be disjoint; the review agent is never the implementation agent.
• Every fresh terminal: orca terminal wait --for tui-idle before dispatch --inject.
• Fallback chain default claude,grok,pi; each fallback = a NEW task + a NEW terminal.
• Output: worktree record, waves, and per-subtask base_sha/initial_base_sha state.

9. Phase 5 — Parallel Execution & Sub-Review

Full procedure: references/phase-5-executing.md — read it before executing this phase.

• Subtasks run wave by wave in the shared worktree; every execute/fix/review round = a fresh terminal + a NEW task (chained with --parent).
• Rounds 0..MAX_SUB_RETRY (default 3); review covers only <base_sha>..HEAD within the subtask's owns.
• Coordinator waits with check --wait in a rolling loop; a timeout is a checkpoint, not a failure.
• Final-round FAIL records verdict=FAIL; sibling subtasks continue unaffected.
• Only when every subtask in the wave has PASS does the next wave get dispatched.

10. Phase 6 — Aggregation & Decision

Full procedure: references/phase-6-deciding.md — read it before executing this phase.

• Collect every subtask's terminal verdict; all PASS → MERGING.
• On failures, ask the user via the native channel: Retry (failed subtasks only, cap MAX_GLOBAL_RETRY=2, guard checked before incrementing) / Degrade / Abort.
• Abort → TERMINATED (Terminate3).
• Degrade: revert each failed subtask's initial_base_sha..HEAD range within its owns; an unclean revert parks the whole feature (PARKED).
• Degrade sets delivery_mode=degraded; the PR body carries a ⚠️ banner.

11. Phase 7 — Merge & Pull Request

Full procedure: references/phase-7-merging.md — read it before executing this phase.

• Rebase onto origin/main (autofix ≤ MAX_AUTOFIX=2; success = rebase complete AND zero ^UU paths) → run the project tests → integration review (≤ MAX_INTEGRATION_REVIEW=2, fresh read-only terminal) → create ONE PR → poll every 60s.
• No gate-create inside the poll loop; Changes Requested → a fresh pr-fix terminal.
• All git operations run inside the feature worktree; the coordinator never checks anything out.
• MERGED → CLEANING; CLOSED → park the feature.

12. Phase 8 — Cleanup & Archival

Full procedure: references/phase-8-cleaning.md — read it before executing this phase.

• MERGED → delete the remote/local branch, remove the worktree, close terminals; PARKED/CLOSED → keep branch + worktree, write .orca/parked/<slug>.md.
• An OPEN PR at cleanup is guarded — refuse destructive actions, treat as parked.
• All state writes are jq atomic tmp-file + mv; afterwards the coordinator runs only git fetch origin.
• Output: one workflow-history.jsonl line + user notification.

13. Observability & Logging

Moved to references/observability.md — the workflow state-file example, terminal role enum, log levels, and key metrics to track.

14. Error Recovery Matrix

15. Security & Permission Model

15.1 Honest Isolation Model

A git worktree is not a sandbox. In v2.2.0 all subtasks share one feature worktree, so any worker terminal can technically write anywhere in it. Isolation is an owns convention enforced by the coordinator, not by the filesystem:

1. Every worker preamble restricts writes to the subtask's owns globs (§8.5).
2. After each round, the coordinator runs git status --porcelain / git diff --name-only <base_sha>..HEAD in the feature worktree and maps changed paths against the subtask's owns. Anything outside is reverted (git checkout -- <paths> / git clean -fd <paths>) and recorded as an owns violation (§14).
3. Review and integration-review terminals are read-only by preamble mandate; the coordinator additionally verifies they produced no diff outside owns (for subtask reviews) or no diff at all (for reviews).

15.2 Boundaries

15.3 Principles

1. Coordinator-Enforced Ownership: owns is a convention; the enforcement is the coordinator's post-round verification + revert loop (§15.1), not the filesystem. Plan-review disjointness validation (§6.3) keeps same-wave workers from legitimately needing the same paths.
2. Least Privilege: Workers can commit locally but cannot push, merge, delete branches, or create PRs. All of those are coordinator-only.
3. No Automated Merge: The workflow NEVER merges a PR. Human approval is always required.
4. Single Push Path: Pushes happen only from the coordinator in Phase 7 (initial PR + pr-fix follow-ups); subtask workers never push.
5. Immutable Audit Trail: All decisions, terminal spawns, and state transitions are written to .orca/workflow-state.json (jq atomic writes) before being acted upon; tasks.subtasks[*].terminals[] is the per-round audit trail.
6. Secret Isolation: GitHub tokens and API keys come from the environment / credential store — never hardcoded in task specs, preambles, or the PR body.

16. Testing & Validation

Moved to references/runbooks.md — dry-run mode, the per-phase validation checklist, and the integration test scenario.

17. Operational Runbooks

Moved to references/runbooks.md — starting, resuming (parked), crash-recovery, and cancelling runbooks.

18. API Command Reference

Moved to references/api-reference.md — the verified Orca CLI surface: orca orchestration / worktree / terminal commands and the external git/gh/jq commands.

Appendix A: Full Workflow Diagram

See docs/workflow.md for the complete Mermaid flowchart with all states, transitions, and termination conditions.

Appendix B: Example Walkthrough

See examples/basic-workflow.md for a step-by-step annotated example.

Appendix C: State File Schema

See .orca/workflow-state.schema.json for the JSON Schema definition of the state file.

Next Steps: cd into your project's Orca-managed main checkout, run ./scripts/check-prerequisites.sh, then describe your task to the coordinator agent in chat. The coordinator will guide you through each phase. For first-time setup, see Prerequisites.