Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / orchestration-and-autonomous-workflows

Orchestration and autonomous workflows

ECC coordinates engineering work as a set of planned stages, bounded worker sessions, and visible progress records. It lets an operator split a task across agents or models, keep changes isolated, apply review and approval gates, and recover safely when a worker or loop stops making progress.

Orchestration model

Workflow definitions

An ECC workflow is a named sequence of engineering stages that turns a request into a reviewed change. The main multi-model path moves through research, ideation, planning, execution, optimization, and review. Each stage has a clear purpose and may use a different model or agent role.

The orchestrator remains responsible for the plan and for human approval. Lightweight analysis can stay in the main session. Work that needs parallel terminals or separate Git state moves to external worker orchestration. Native workflows are a pilot for autonomous, fan-out-heavy parts of a stage. They run in the background with bounded concurrency, structured results, and resumability, but they do not replace approval gates that need the operator.

The main workflow choices are:

  • Feature delivery for a new capability.
  • Defect repair for a reproducible broken behavior.
  • Code refinement for behavior-preserving restructuring.
  • MVP construction for turning a design or product document into a thin vertical slice.
  • Review for independent quality, language, and conditional security checks.

The wider system view is covered in Coordination inventory and goals.

References: commands/multi-workflow.md• L5-11 commands/multi-workflow.md• L120-189 commands/orch-add-feature.md• L7-34 commands/orch-fix-defect.md• L7-37 commands/orch-refine-code.md• L7-37 commands/orch-build-mvp.md• L7-34 workflows/README.md• L1-11

Coordination boundaries

The system separates planning, execution, review, and publication so that one stage cannot silently approve the next. Gate 1 protects the plan before implementation. Gate 2 protects the final change before commit or publication. Agents can provide analysis and findings, while the orchestrator and operator retain control of repository writes and approval decisions.

This separation also defines when to use a worker swarm. In-process agents suit analysis or review when the main session is the only writer. External orchestration suits parallel implementation where workers need independent terminals, branches, or build environments.

References: commands/multi-workflow.md• L102-112 commands/multi-workflow.md• L146-168 commands/multi-workflow.md• L193-197 commands/orch-add-feature.md• L28-34 workflows/README.md• L9-12

Workflow stages

The standard delivery flow moves from understanding the request to a selected plan, then to bounded implementation and evidence-based review. A stage must finish before the next stage uses its result. Parallel model work is therefore a controlled part of a stage rather than an untracked background activity.

The flow below shows the relationship between the plan, worker execution, review, and the human decision points.

flowchart LR
    Request[Engineering request] --> Research[Research and analysis]
    Research --> Gate1[Plan approval]
    Gate1 --> Execute[Worker or main-session execution]
    Execute --> Review[Quality and safety review]
    Review --> Gate2[Commit or publish approval]
    Gate2 --> Result[Delivered change]

References: commands/multi-workflow.md• L104-107 commands/multi-workflow.md• L120-189 commands/orch-review.md• L26-107

Worker execution

Worker sessions

A worker session is a bounded unit of engineering work with one objective, one execution context, and one reported result. A plan names the session and its workers. ECC gives each worker a task record, a handoff record, and a status record so the parent process can observe work without relying on live conversation state.

Workers report through their final output and launcher-managed artifacts. The worker contract keeps the task narrow, forbids nested agents, and requires a summary of changed files, validation, and remaining risks. This makes each result suitable for review or handoff to the next stage.

For the detailed plan-to-launch path, see Workflow execution and worktrees.

References: scripts/…/tmux-worktree-orchestrator.js• L108-173 scripts/…/tmux-worktree-orchestrator.js• L175-251 scripts/orchestrate-codex-worker.sh• L58-78 scripts/orchestrate-codex-worker.sh• L80-106

Agent collaboration

ECC uses role-based agents and model routing to match work with the needed skill. The multi-model workflow gives backend authority to Codex, frontend authority to Antigravity, and keeps Claude as the orchestrator. Native review workflows fan out by concern, then combine the results before verification.

Independent work is useful because different agents can inspect the same change from different views. The orchestration barrier collects those views before it removes duplicate findings or decides which high-severity findings need adversarial verification. Quality review always runs. A matching language adds a language review, and security signals in the diff or changed paths add a security review. If any selected dimension fails, the review stays incomplete instead of treating the missing result as approval.

References: commands/multi-workflow.md• L22-34 commands/multi-workflow.md• L77-87 workflows/README.md• L12-20 workflows/orch-review.workflow.js• L179-217 workflows/orch-review.workflow.js• L219-240

Execution isolation

Worktree boundaries

A worktree is an independent Git checkout attached to a worker branch. ECC uses worktrees when parallel workers must edit, build, or test without sharing an index or working directory. Each worker starts from the plan's base reference and receives only the task context that the plan allows.

The parent checkout and sibling worktrees are protected from worker changes. Selected local seed paths can provide shared context, but they must stay inside the repository boundary. This isolation allows several workers to progress at once while keeping each change attributable to one branch.

References: scripts/…/tmux-worktree-orchestrator.js• L53-105 scripts/…/tmux-worktree-orchestrator.js• L207-232 scripts/orchestrate-codex-worker.sh• L59-68

Resource lifecycle

Orchestration treats branches, worktrees, coordination files, and terminal sessions as one managed run. It checks the repository and terminal environment before launch. If setup fails, it removes only resources created by that run. Replacement of an existing run is explicit because it can discard an old session or branch.

After execution, lifecycle reporting separates work that is safe to remove from work that needs salvage or operator action. Fully merged work can be removed. Dirty, conflicting, or unmerged work stays available for recovery.

References: scripts/…/tmux-worktree-orchestrator.js• L390-423 scripts/…/tmux-worktree-orchestrator.js• L426-480 scripts/…/tmux-worktree-orchestrator.js• L482-587 scripts/…/lifecycle.js• L27-61 scripts/…/lifecycle.js• L149-182

Review gates

Review is a control point between worker output and delivery. The native review workflow gathers independent findings in parallel, merges findings that point to the same evidence, and then verifies each unique CRITICAL or HIGH finding. Lower-severity findings remain advisory.

The workflow validates its review input before it starts and reports both blocking and advisory results for Gate 2. A failed review dimension makes the result incomplete. A verifier that fails or cannot confidently refute a blocker leaves it blocking. Only a complete run with no blocking finding can return APPROVE; the human still decides whether the change can pass the final gate.

References: workflows/README.md• L7-20 workflows/README.md• L39-53 workflows/orch-review.workflow.js• L150-187 workflows/orch-review.workflow.js• L192-217 workflows/orch-review.workflow.js• L219-287 commands/orch-review.md• L76-107

Loop operations

Autonomous loop control

An autonomous loop is a managed series of delivery iterations. The operator selects a pattern and a safety mode, then ECC prepares a run plan with checks and an explicit stop condition. Safe mode keeps strict gates and checkpoints. Fast mode reduces gates when the operator accepts more speed and less control.

The loop operator watches for stalled progress, repeated failures, cost drift, and blocked merge work. It pauses or narrows the run when failure repeats, then resumes only after the required checks pass. A rollback path and worktree isolation are required before autonomous work starts.

For work-item ownership, epic state, loop patterns, and session handoffs, see Work items, loops, and epics.

References: commands/loop-start.md• L5-30 agents/loop-operator.md• L18-45 commands/santa-loop.md• L5-12 commands/santa-loop.md• L108-135

Progress tracking

Progress tracking turns worker and loop activity into records that another process or operator can inspect. Orchestration status joins session information with worker state, worktree location, objectives, and handoff output. The shared session view lets different runtimes present comparable state.

Loop status uses local Claude transcript records to detect attention signals. It identifies overdue scheduled wakes, pending shell results, and transcript parse errors. Watch mode refreshes the view, while JSON snapshots and exit codes let a sibling terminal or watchdog act without controlling the underlying session.

References: scripts/orchestration-status.js• L9-50 scripts/…/registry.js• L8-17 scripts/…/registry.js• L99-141 scripts/loop-status.js• L401-526 scripts/loop-status.js• L745-799

Work-item coordination

A work item is the durable record for a unit of engineering work from an external source or a local plan. ECC can assign an item to an agent or human, connect it to a session and repository, and move it through open, running, blocked, and done states. This gives autonomous workers a queue that remains visible outside the active conversation.

Epics add a larger coordination boundary around tasks and dependencies. GitHub holds the canonical epic state. Local state mirrors it for operator views. Decomposition, claiming, synchronization, validation, review, unblocking, and publication keep ownership and readiness visible as work moves between systems. The GitHub coordination and policy page describes the policy and external-state rules for this boundary.

References: scripts/work-items.js• L29-59 scripts/work-items.js• L317-343 scripts/…/work-item-mutations.js• L35-108 commands/epic-decompose.md• L5-18 commands/epic-claim.md• L5-20 commands/epic-sync.md• L5-18 commands/epic-validate.md• L5-20 commands/epic-publish.md• L5-18

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep workflow phase order and human gate ownership aligned across command wrappers, skills, and native workflow scripts.
  • Keep native workflow boundaries aligned with the main conversation so background work cannot bypass interactive approval.
  • Keep worker task, handoff, and status records compatible with session inspection and the canonical session snapshot.
  • Keep launcher template variables and worktree paths within the same repository and worker boundaries.
  • Keep rollback and cleanup rules conservative. Never turn dirty or unmerged work into an automatic removal candidate.
  • Keep review dimension selection, finding schemas, deduplication keys, verifier confidence rules, and Gate 2 verdicts aligned.
  • Keep review failure and uncertainty fail-closed so an incomplete review cannot look like approval.
  • Keep loop status signal names, snapshot schemas, and exit codes aligned with watchdogs and sibling-terminal consumers.
  • Keep work-item claim rules shared across command-line and control-pane surfaces to prevent duplicate ownership.
  • Keep GitHub epic state, labels, audit comments, dependency checks, and local projections synchronized when lifecycle rules change.

Important failure modes

TriggerConsequenceGuard
A workflow skips a required phase or approval gateImplementation or publication can proceed without an agreed plan or final review.Preserve the staged workflow and keep Gate 1 and Gate 2 in the controlling session.
A native workflow is asked to perform an interactive gateBackground work can appear to approve a plan or commit without operator input.Keep native execution between the human-controlled gates.
Two workers resolve to the same worker identityBranches, worktrees, and coordination records can collide.Require unique worker slugs before launch.
A worker task file is missing or unreadableThe worker does not run, and the run produces a failed handoff instead of useful work.Materialize and validate task artifacts before launch.
Setup fails after some worktrees or panes existThe repository can retain partial orchestration resources.Roll back only resources created by the failed run and inspect cleanup errors.
A worker changes a sibling worktree or parent checkoutParallel changes can become mixed and attribution becomes unreliable.Enforce the current-worktree-only worker contract.
A review dimension fails or a high-severity finding is uncertainThe review cannot provide a clean approval.Keep the result at CHANGES_REQUESTED until the missing or uncertain work is resolved.
Review input is empty or malformedThe workflow cannot establish what it reviewed.Reject the payload and fail the gate closed.
A loop has an overdue wake or unresolved shell callThe session can appear active while making no progress.Inspect loop-status and follow its intervention signal.
An unmerged or dirty worktree is treated as disposableIn-progress or unrecovered work can be lost.Keep it in the operator queue or salvage it before cleanup.

Key files

FileWhy to read it
commands/multi-workflow.mdDefines the main multi-model stage model, routing, gates, and worker selection boundary.
commands/orch-add-feature.mdShows the gated path for new feature delivery.
workflows/README.mdExplains the native workflow pilot and its boundary between human gates.
workflows/orch-review.workflow.jsDefines autonomous review fan-out, conditional dimensions, input validation, deduplication, verification, and fail-closed results.
scripts/orchestrate-worktrees.jsExposes dry-run, artifact-only, and live worker-session launch modes.
scripts/…/tmux-worktree-orchestrator.jsDefines the plan, worker resources, isolation, launch, and rollback model.
scripts/orchestrate-codex-worker.shDefines the single-worker task, output, handoff, and failure contract.
scripts/…/lifecycle.jsDefines worktree state classification and safe cleanup decisions.
scripts/orchestration-status.jsProvides the operator-facing session status entry point.
scripts/loop-status.jsConverts transcript activity into loop health signals, snapshots, and watchdog exit status.
agents/loop-operator.mdDefines the safety checks and escalation rules for autonomous loops.
scripts/work-items.jsProvides the durable local queue for assignment, progress, closure, and GitHub imports.
scripts/github-coordination.jsRoutes epic claim, decomposition, synchronization, validation, review, unblocking, and publication actions.