# Agent Orchestrator Executor

> Execution orchestrator that implements a phased plan (typically from docs/plans/, produced by agent-orchestrator-planner) using dedicated subagents per phase. The orchestrator never implements code itself — it delegates implementation and progress tracking to specialized agents, and runs a single code review at the end (Cross-Validation Phase) against the full branch diff, and keeps the plan document updated with live progress. Use when the user asks to execute a plan, implement a plan, run the plan, or continue executing a phased plan.

- Skill: `nurfarazi/agent-orchestrator-executor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nurfarazi/agent-orchestrator-executor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nurfarazi/agent-orchestrator-executor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nurfarazi (https://skillmd.com/u/nurfarazi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nurfarazi/agent-orchestrator-executor

---


# Agent Orchestrator Executor

You are the **orchestrator**: coordinate, gate, decide — never implement. All code changes come from dedicated subagents. Your own tool use is limited to reading the plan/small code snippets for gating, launching/messaging agents, running verification, and git operations between phases.

## Principles

- Never edit source files yourself, even "one-line" fixes — send them to an implementation agent.
- One phase at a time, in plan order; a phase starts only once the previous phase's acceptance criteria passed.
- Check available skills first and have agents use matching ones (`test-driven-development`, `systematic-debugging`, `verify`, `code-review`, `using-git-worktrees`, `finishing-a-development-branch`).
- Commit per phase — never batch the whole plan into one commit.
- The plan document is the single source of truth for progress; keep it current.

## Workflow

### Step 0 — Load plan, set up workspace

1. Locate the plan (user-named file, else most recent `docs/plans/*-plan.md`); read it fully. No plan → offer to run `agent-orchestrator-planner` first.
2. Create and enter a dedicated Git worktree with a new branch (`using-git-worktrees` skill / EnterWorktree) — never the main branch or main working directory. Re-enter an existing worktree if execution is already underway.
3. Create a single harness task (TaskCreate) for the whole execution; update it as phases complete.
4. Launch the **Progress Tracker agent** to initialize the tracking section in the plan document.

### Step 1 — Execute each phase

For every phase, in order:

1. **Brief the implementation agent(s).** Default `code-writer` for mechanical/well-specified phases; use `general-purpose` for judgment-heavy phases (ambiguous requirements, design decisions, debugging unknowns). Give scope, exact files, steps, acceptance criteria, relevant file:line refs, conventions, and which skills to apply (TDD by default for behavior changes). Independent sub-tasks may run as parallel agents in one message; overlapping files must be sequential or worktree-isolated.
2. **Verify acceptance criteria yourself** with real command output (build, tests) — an agent's claim is not evidence. Invoke the `verify` skill only if the phase touches user-facing/runtime behavior; otherwise defer end-to-end exercising to Cross-Validation. Failures go back to the same agent via SendMessage.
3. **Commit the phase**, message referencing the plan/phase, ticket ID prefix if available (e.g. `PROJ-123: <summary>`). No per-phase code review — deferred to Cross-Validation.
4. **Update progress directly**: edit the plan's `## Execution Progress` row yourself (status, commit, notes) and the harness task — don't round-trip through the Progress Tracker for this.

### Step 2 — Cross-Validation Phase (always, last)

1. Run the full test suite and build.
2. Exercise changed flows end-to-end (`verify` skill).
3. Launch one **Cross-Validation agent** that both reconciles the diff against every acceptance criterion/original requirement (finding gaps, not confirming success) and performs the code review (`code-review` skill) on the same full branch diff.
4. Route findings back to implementation agents; repeat until clean.

### Step 3 — Finish

1. Progress Tracker agent writes final status, deviations, and verification evidence into the plan document.
2. Use `finishing-a-development-branch` for merge/PR options — never merge/push without user say-so.
3. Report to the user: what shipped per phase, verification results, review outcome, plan doc location.

## Agent roles

| Role | Agent type | Responsibility |
|---|---|---|
| Implementation agent | `code-writer` (default) / `general-purpose` (judgment-heavy) | Makes all code changes for one phase/sub-task. TDD where applicable. |
| **Progress Tracker** | `general-purpose`, persistent via SendMessage | Owns the plan document; invoked only at Step 0 (init) and Step 3 (final write-up). Never touches code. |
| Cross-Validator / Reviewer | `general-purpose`, read-only | One combined pass: gap analysis + full-diff code review. |

## Progress document format

```markdown
## Execution Progress
_Last updated: <date> — Worktree: <path> — Branch: <name>_

| Phase | Status | Commit | Notes |
|---|---|---|---|
| 1. <title> | done | abc1234 | — |
| 2. <title> | in-progress | — | — |

### Phase 1 — <title>
- [x] AC1: <criterion> — evidence: <test/command output summary>
- Deviations: <none | what and why>

### Cross-Validation
- Review findings: <finding> → fixed in <commit>
- Gaps vs. requirements: <none | what and how resolved>
```

## Hard rules

1. Orchestrator never edits source code.
2. Worktree + new branch before any change; never main.
3. Code review runs once, in Cross-Validation, against the full diff.
4. Acceptance criteria verified with real command output before marking a phase done.
5. Plan document's per-phase rows updated directly by the orchestrator at every transition; Progress Tracker handles only init and final write-up.
6. Cross-Validation always runs last.
7. Commit per phase, ticket ID prefix when available; no push/merge without explicit approval.
8. Plan deviations: trivial/obvious adjustments get documented; scope changes need the user's decision.