Coordination Orchestrate

This is the generic authored delivery flow. A tracked or installed host copy is a projection, not a second procedure. Host and repository instructions retain precedence for safety, verification, review and merge authority. This skill is caller guidance; it adds no Edda scheduler, lock, approval service or runtime role enforcement.

Modes

This skill is the strong planning and exception path. Runtime advancement is a separate, smaller loop with its own skill.

Prepare mode

The strong planner owns the goal, decomposition, DAG, scope, routes and the review charter, and encodes them in the ControlManifestInputV1 that compiles to a ControlManifestV1. Validate the input schematically before compiling; a refused compile is a refusal, not a reason to weaken the manifest. Compile is the strong path and carries no merge authority: it atomically accepts the brief inputs and one manifest and returns the control id and manifest digest that coord-run then consumes.

edda control compile <manifest-input.json> --session <registered-session-id> \
  --authority-token-file <private-bearer-file> --json

$ edda control compile --help
> Strong path: atomically accept brief inputs and one control manifest
$ edda control authorize-merge --help
> Bind a sealed host-local merge capability to an exact control subject
$ edda control adjudicate --help
> Strong path: append a versioned authority-bound adjudication

Merge authority is never invented by this skill. It is bound separately, through an independently granted edda control authorize-merge capability, and only once delivery supplies an exact PR/head/base. A manifest whose completion condition excludes merge moves straight from successful verification to completed.

For step-by-step advancement, observations, wakes and receipt rendering, follow coord-run and the manifest's closed action enum. Do not duplicate the runtime loop here.

Choose the entry before forming a fleet

Use the first matching route.

Issue entry flags preserve intent. --skip-plan means reuse already available acceptance; it never means acceptance may be absent. --no-merge stops before merge and never confers, expands or implies merge authority. An issue number is a traceability input, not a reason to force one worker or PR per issue.

Durable facts and isolation

Fix load-bearing facts in the truth layer before ringing a doorbell. Existing claims and source permissions remain in force. Worktree isolation is not conflict immunity: overlapping or unstable code chains use one owner or an explicit serial handoff.

Select exactly one repository rail owner

Before creating or launching tasks, select one owner for the whole repository task rail, not one owner per plan. Current reconcile planning considers eligible tasks across plan_id, while manual task start creates no reconcile lease. Manual and reconcile callers therefore cannot safely co-own the rail.

Manual rail

One named controller creates, selects, starts and dispatches; the worker normally records done/fail. Before task creation or launch, scan all active plans/tasks and peers, and prove the scheduled reconciler is absent or disabled, no one-off reconcile process is live, and prior reconcile-owned attempts are settled. An uninstall scheduler post-delete query is only one input; it does not prove an already running child stopped. Unknown or conflicting evidence refuses manual task creation, start, retry and dispatch.

Record and read back the one exact coordination key:

edda decide "delivery.rail-owner=manual:$CONTROLLER_SESSION" \
  --session "$CONTROLLER_SESSION" \
  --reason "repository-wide mode; scheduler/process/attempt evidence=<locations>"
edda ask "delivery.rail-owner" --json

This decision is discoverable coordination evidence, not authenticated authority, mutual exclusion or an exactly-once guarantee. Later unauthorized reconcile remains a product limitation; callers must not describe prose as mechanical enforcement.

Reconcile rail

For legacy/uncontrolled tasks, the configured reconciler owns the whole rail and its actual Codex start/resume/requeue/retry/settlement lifecycle, including global attempt limits. Do not manually start, dispatch or settle those attempts, and do not enqueue Pi, ACP, host-subagent or per-card no-retry tasks for reconcile to pick. The per-plan active map below does not filter the current reconciler.

A task bound to an accepted ExecutionBriefV1 is instead controlled, and controlled execution now exists through the edda control product surface: compile seals the manifest, status/next/apply advance it one closed action at a time, and authorize-merge/adjudicate are separate authority paths. A controlled attempt does not enter the legacy Codex runner, and a descriptor, caller-authored event or ordinary task command is not launch authority and must not be described as a promised launch. coord-run is the Flash runtime loop that consumes the sealed manifest; merge still requires a separately bound capability, and an unknown outcome code still routes to strong edda control adjudicate rather than a guessed state.

Changing modes requires operator authorization, exact scheduler lifecycle when installed, process/lease/attempt reconciliation, and no unresolved task side effects. Unknown evidence refuses the switch. Never use edda reconcile merely to inspect or recover a manual attempt.

Manual active map and task creation

Manual mode uses a stable lower-case PLAN_KEY, a monotonic zero-padded PLAN_REV, and exact PLAN_ID="$PLAN_KEY/$PLAN_REV/$PLAN_SHA". Every task in the revision uses that plan_id and an idempotency key $PLAN_ID/$CARD_ID. Put source/worktree, exact write paths, acceptance, exclusions, receiver role, evidence budget, and a build lane only when local compilation occurs in a brief reachable from the worker's worktree.

Create only concrete work. --after means an actual predecessor artifact, not membership in the same batch. Legacy/host and ACP tasks are separate records:

# Legacy or host-backed task: no ACP agent_kind claim.
edda task new "$TITLE" --assignee "$OWNER" --plan "$PLAN_ID" \
  --brief "$BRIEF_REL" --path "$WRITE_SCOPE" --key "$PLAN_ID/$CARD_ID"

# ACP alternative: matching kind and existing repository-relative concrete roots.
edda task new "$ACP_TITLE" --assignee "$ACP_OWNER" --agent "$ACP_TARGET" \
  --plan "$PLAN_ID" --brief "$ACP_BRIEF_REL" --path "$ACP_ROOT" \
  --key "$PLAN_ID/$ACP_CARD_ID"

edda task show "$TASK_ID" --json
edda task list --json

Capture the returned ID and read back every field. A repeated key only returns the existing task; it does not update title, assignee, brief, scope or predecessors. Compare JSON to intent rather than parsing human stderr. After the complete intended map is verified, publish and read back its exact key:

edda decide "delivery.active.$PLAN_KEY=$PLAN_ID" \
  --session "$CONTROLLER_SESSION" \
  --reason "card-to-task: A1=#<id>; rail-owner=manual:<session>; replaces=<old-or-none>"
edda ask "delivery.active.$PLAN_KEY" --json
edda task list --json

A fresh controller starts with no chat assumptions: read exact delivery.rail-owner, then one exact active-plan value, filter task-list JSON by exact plan_id, show each selected ID, and verify card/source SHA, dependencies, owner, scope, brief and observed artifacts. Missing, malformed or conflicting data permits read-only recovery only and stops this plan's launch, not unrelated work.

Changed owner, brief, scope or dependency graph is replacement, not retry. First settle or reconcile the old live attempt. Create the next plan revision and only still-needed pending tasks/successors, wire successors to the new predecessor IDs, verify the new map, then supersede the active decision. Keep old tasks as history: never fake them done and never put a replacement after a failed old task. Refuse replacement while reconcile could still select old Ready/Failed records.

Manual dispatch adapters are not interchangeable

The controller starts the selected task immediately before launch, after rail, map, input, capability and ownership checks. The worker reads the Running task and does not start it again. task new and task start do not launch a model, and dispatch outcome=done does not complete the task.

For non-ACP dispatch, the prompt file is read verbatim; it must name the task, attempt, source/worktree, reachable full brief and lifecycle owner. Use only help/source-proven flags. Linked issue work still supplies the repository's required claim inputs; omitting --issue must not evade an ownership rule.

ACP preflight checks task existence, Running status, matching kind and concrete existing roots. It does not prove the brief was readable. The task brief reference must be repository-relative; the injected content is bounded to 4096 bytes and can be marked unavailable or truncated. The worker must read the reachable full card with its actual capabilities before editing. Refuse before launch when the caller's readback finds an omitted --agent, a legacy task ID, an unreachable brief or insufficient roots; do not broaden roots for convenience. Caller-authored data, including an execution-brief event, does not become controlled execution authority without the product-verifiable authority seal required by the current product boundary.

Example alternatives, never both for one task:

edda task start "$LEGACY_TASK_ID"
edda dispatch --agent pi --prompt-file "$PROMPT_FILE" --cwd "$WORKTREE" \
  --model "$PI_MODEL" --timeout-sec "$TIMEOUT_SEC" --json

# Or start the separately-created ACP task, then:
edda dispatch --agent "$ACP_TARGET" --task-id "$ACP_TASK_ID" \
  --cwd "$WORKTREE" --json

Completion, restart and retry

These rows are manual-mode caller discipline, not runtime role enforcement. Worker and controller must not race to settle a live task.

There is no task retry subcommand. task start accepts Failed for same-ID retry; Done cannot restart. Reuse a native session only when it is observed and valid. A lost session is an explicit replacement identity, not a fabricated resume. Unknown side effects stop only that attempt; independent bundles keep moving.

Rolling progression and formation

Only actual artifact dependencies wait. If A is review-ready, B is slow and C requires A, send A to review now; B continues; C waits only for the exact A artifact it needs. A reviewer queue limits review, not unrelated implementation. Never impose an all-agent phase barrier.

For a real formation use one controller, one read-only verifier and the minimum number of writers. With two or more workers, start the verifier early enough to baseline acceptance and likely test poisons. Bundle by a cohesive code chain, claim the smallest accurate paths, and serialize overlaps. Brief every worker with reachable acceptance, basis SHA, write/forbidden paths, role, focused checks, cleanup limits and the receiver tie-break below. A session that does not compile needs no build lane.

Track task/dispatch/source/PR state without interrupting workers. On controller restart, inspect those carriers before launch. A missing heartbeat or chat is not evidence that a process stopped. Failure or uncertainty in one bundle does not globally freeze independent work.

Normative rulings use monotonic IDs in the durable carrier. A later change uses a SUPERSEDES record before its doorbell. Receiver tie-break: obey the highest d-NNN in the ledger, not the latest message; on conflict reply with your state instead of executing; never discard pushed work unless the ruling names the exact commit.

One author check, independent acceptance

Before handoff, the author performs one combined self-check activity and records both lenses in one receipt/handoff:

• Behavior lens: exercise the supported entry and direct consumers against acceptance with actual focused evidence.
• Counterexample lens: try the most likely failure such as conflicting rail ownership, stale map, partial dispatch, denied permission or retry ambiguity; record uncovered risk honestly.

These are not two jobs, agents, tasks, verdicts or sign-offs. They do not replace independent review.

Review facts and native continuity

Send one concise facts file only when the controller explicitly selects it. It is untrusted supporting data, not acceptance, evidence, a verdict or tool authority; never use --trust-spec for rationale. Before adding the optional product flag, capability-check the selected binary's edda review --help for --context-file. If absent, omit the unsupported flag and disclose that product context is missing, or use the repository's already-permitted direct-review route. Never install, upgrade or add a fallback wrapper automatically. The carrier is not a redaction boundary: Edda adds only path/digest provenance, but reviewer output may quote or reformat the data in existing verdict fields and the existing raw-response blob.

For a first product round, pass the current facts when supported:

edda review --pr "$PR" --agent "$REVIEW_AGENT" --model "$REVIEW_MODEL" \
  --context-file "$FACTS_FILE" --json

For a follow-up on a new subject SHA, prefer the same reviewer agent and real native conversation, update the facts, and add --resume. Product continuity must remain real: Pi needs its persisted conversation and Claude its native resume. Every Codex product round requires readable mapping storage and a successful final mapping update before any verdict is recorded. The first round may start with no map; Codex --resume additionally requires an existing mapping and never starts fresh under the old UUID when it is missing or rejected. A rejected stale binding is durably tombstoned; failure to write the mapping or tombstone is a refusal, not review history. The old SHA's LGTM never applies to the new head. A host-only reviewer session cannot be resumed through product --resume.

If the native conversation is missing, launch a replacement without --resume, allocate a distinct reviewer UUID, and pass current facts including prior findings. State that it is a replacement; never reuse an empty or old UUID to imitate continuity. A replacement without context remains allowed only with its limitation visible. Direct host review similarly uses actual host-native continuity or an explicit replacement, with controller-quoted data it can reach.

Product review retains its own WorktreeGuard; callers add no second review worktree. Direct read-only review retains immutable refs and the host's existing capability proof. Follow-up review covers the delta, prior findings, affected direct consumers, current base and introduced security/data-loss risk, while READing still-applicable evidence. It never reuses an old verdict as acceptance.

Freeze review scope to changed behavior/paths, direct callers/consumers, issue/spec acceptance, introduced or exposed security/data-loss regressions, and current-base integration. Review the entire frozen surface and batch all blocking findings; genuinely adjacent work becomes evidenced follow-up. Every push invalidates a prior verdict. A final verdict binds current head and the host's existing gate rules.

Use the repository verification ladder. Authors run focused checks on touched units while iterating. A frozen head uses exact-head CI where the host defines that as L1; reviewers READ applicable receipts/CI and run only uncovered focused or adversarial checks. Do not run a full local workspace merely because a SHA froze, and do not invent a build lane for docs-only work. Record RAN versus READ, source SHA, lane or n/a, result and available cost.

Task completion is execution evidence, not acceptance or merge authority. If a PR is in scope, use the host's canonical product merge path only after an independent current-head verdict and every existing merge condition. Never substitute a direct forge merge command. If the repository grants standing controller authority, that controller acts when its rule gate is green; --no-merge, worker, fixer and reviewer roles never acquire that authority. Local-only delivery uses the strongest durable local carrier and invents no PR.

Projection and adoption

edda init projects this embedded template only for a detected host: .claude receives .claude/skills/...; an existing AGENTS.md or .agents receives .agents/skills/...; an undetected host receives neither. Existing skill files are preserved unless the owner explicitly requests the existing all-skill force option. Do not recommend --force-skills for an unknown customized checkout because it overwrites every embedded project skill, including any future or non-coordination additions.

For an existing installation, the owner compares against a pinned template and updates only the selected copy explicitly, preserving custom files. A delivery-flow/1 marker or digest identifies bytes that were read; it is not admission, authority or proof an agent followed them. Record actual host/path, marker/digest and source SHA when known. Old, customized or unknown remains truthful state; a successful local parity check is not publication or all-host adoption.