# Agent Orchestration

> SKILL: Implement the `vscode-agents` orchestration model using `@github/copilot-sdk` (Node.js)

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

---

# SKILL: Implement the `vscode-agents` orchestration model using `@github/copilot-sdk` (Node.js)

## Purpose
You are implementing a **multi-agent development system** (Intake → Tech Lead → Strategist → Specialists → Reviewer) modeled after `simkeyur/vscode-agents`, but **running in your own Node.js process** using `@github/copilot-sdk`.

This skill exists because the agent keeps “kind of” implementing it and getting the control-flow wrong. Follow this skill **exactly**.

Reference model: the repo’s workflow explicitly starts with Intake, then Tech Lead delegates to specialized agents, and a Reviewer is the final quality gate.  
Copilot SDK primitives you must use: `CopilotClient`, `createSession`, session events, `sendAndWait`, tools via `defineTool`, and (optionally) `onUserInputRequest`/`ask_user`.

---

## Non-negotiable rules (you must comply)
1. **ALWAYS start with Intake.** No exceptions. If unclear, Intake asks targeted questions before any work proceeds.
2. **Tech Lead NEVER implements.** It only decomposes, delegates, coordinates, and escalates.
3. **Strategist produces a plan, not code.**
4. **Specialists produce work outputs.** (Code, diffs, instructions, etc.)
5. **Reviewer is mandatory** before final output to the user.
6. **Adaptive escalation:** start with the lightest competent dev agent and escalate only when needed (explicitly defined in Tech Lead).

If you violate any rule above, the implementation is wrong.

---

## What you are building (mental model)
You are building a **controller** (your Node app) that:
- Spawns and manages **one Copilot session per role** (Intake, Tech Lead, Strategist, etc.)
- Provides a **tool** the Tech Lead can use to “call” specialist agents (since outside VS Code you must implement delegation yourself)
- Enforces the exact workflow ordering and quality gate

Copilot SDK gives you:
- A long-lived `CopilotClient`
- Multiple independent sessions (`client.createSession`)
- A robust tool callback mechanism (`defineTool`) so the model can trigger deterministic host behavior

---

## Required architecture

### A. Sessions (one per agent role)
Create a session per role:
- `intakeSession`
- `techLeadSession`
- `strategistSession`
- specialist sessions: `juniorDev`, `frontendDev`, `backendDev`, `fullstackDev`, `srFrontend`, `srBackend`, `srFullstack`, `dataEngineer`, `designer`, `promptWriter`, `devOps`
- `reviewerSession`

**Do not** “roleplay all agents in one session.” That defeats isolation and breaks delegation.

**Model selection:** pass `model` in session config. The SDK requires `model` to be set when creating sessions (especially with custom providers), and it supports multiple sessions with different models.  
(Use `listModels()` if you need to confirm exact model IDs in your environment.)

### B. System prompts (role definitions)
Each agent session must have a role-specific system prompt derived from the `.agent.md` content.

Minimum viable approach:
- Put each role prompt into `systemMessage.content`.
- Prefer `mode: default/append` unless you have a very specific reason to replace the full prompt. The SDK notes your content is appended after SDK-managed guardrails by default; `mode:"replace"` removes guardrails.

Critical: the Tech Lead prompt must include “NEVER implement anything yourself” and the escalation strategy wording (that’s the core behavioral constraint).

### C. The Tech Lead must delegate via a tool you provide
In VS Code, “agent calling” is a built-in capability. In Node, **you must implement it**.

Provide a tool (via `defineTool`) named, e.g., `delegate_to_agent` that:
- Accepts `{ agent: <enum>, prompt: string, context?: object }`
- Runs the chosen agent session with `sendAndWait`
- Returns the agent’s response text + metadata (agent name, timestamps)

This is not optional. Without this tool, the Tech Lead will hallucinate delegation or try to implement work itself.

---

## Exact runtime workflow (state machine)
Implement this as a strict controller loop:

### Step 0 — Clarify (always)
1. Send the user request to `intakeSession`.
2. Intake must output one of:
    - **A. “NEEDS_CLARIFICATION”** + a list of questions; OR
    - **B. “CLEAR”** + a rewritten “clarified request” the rest of the pipeline will use.

If needs clarification:
- Return questions to the user.
- STOP. Do not proceed.

### Step 1 — Orchestrate (delegate only)
Send the clarified request to `techLeadSession`.

Tech Lead must produce:
- A structured task list
- Which agents to delegate to
- Whether escalation is required
- Any parallelizable groups
- A “review package” instruction for the Reviewer

**Hard constraint:** the Tech Lead must not write code, diffs, or implementation steps beyond delegation and coordination.

### Step 2 — Plan (Strategist session)
Send the clarified request + Tech Lead task list to `strategistSession`.
Strategist returns:
- Ordered phases
- Dependencies
- Acceptance criteria / done conditions

### Step 3 — Execute tasks (Specialists)
For each task, the Tech Lead must call your `delegate_to_agent` tool.
Your Node controller will:
- Route to the correct session
- Pass required context (clarified request, plan, relevant prior outputs)
- Collect results

Parallel execution:
- Only run tasks in parallel if you can prove they don’t conflict.
- If you can’t prove that, run sequentially.

Escalation:
- If a lower-level agent reports being stuck / security concerns / architectural decision, escalate to the next agent per the Tech Lead rules.

### Step 4 — Review gate (mandatory)
Send the full execution bundle to `reviewerSession`:
- clarified request
- plan
- all specialist outputs
- any diffs/files produced

Reviewer returns:
- PASS/FAIL
- issues found (security/bugs/perf)
- required fixes (who should fix them)

If FAIL:
- route fixes back through Tech Lead → delegate tool → specialists
- re-review
  Repeat until PASS or user stops.

### Step 5 — Final response
Only after Reviewer PASS:
- Tech Lead composes the final user-facing summary (still not implementing; just presenting integrated results).
- Return final output.

---

## Output contracts (force the model to behave)
To prevent the model from “winging it,” enforce structured outputs:

### Intake output format
Require the Intake to respond in **JSON only**:

{ "status": "NEEDS_CLARIFICATION" | "CLEAR", "questions": ["..."], "clarified_request": "..." }

### Tech Lead output format
Require Tech Lead to respond in **JSON only**:

{
"tasks": [
{
"id": "T1",
"agent": "JUNIOR_DEV" | "FRONTEND_DEV" | "BACKEND_DEV" | "FULLSTACK_DEV" | "SR_FRONTEND" | "SR_BACKEND" | "SR_FULLSTACK" | "DATA_ENGINEER" | "DESIGNER" | "PROMPT_WRITER" | "DEVOPS",
"goal": "...",
"inputs": { "files": [], "constraints": [] },
"can_parallelize_with": ["T2"]
}
],
"escalation_rules_reminder": "Start low, escalate on defined signals.",
"review_instructions": "What the reviewer must check."
}

### Reviewer output format
Require Reviewer to respond in **JSON only**:

{ "status": "PASS" | "FAIL", "findings": [{ "severity": "low|med|high", "issue": "...", "fix": "...", "suggested_agent": "..." }] }

Enforcement:
- If parsing fails, your controller must re-prompt the same agent with: “Output valid JSON only, matching schema; no prose.”

---

## Copilot SDK specifics you must implement correctly

### Session creation & message sending
- Use `CopilotClient`, `start()`, and `createSession()` per the SDK.
- Use `sendAndWait()` for deterministic “wait until idle” behavior.
- Use session event handlers if you need streaming or telemetry (`assistant.message`, `session.idle`, etc.).

### Tools (delegation)
- Implement delegation using `defineTool`, with Zod schemas for parameters.
- The handler performs the real work (routing prompts to other sessions) and returns JSON-serializable results.

### System message behavior
- Default behavior appends your system message after SDK-managed sections.
- Use `mode:"replace"` only if you truly want to remove guardrails (usually you do not).

### Infinite sessions
- Default “infinite sessions” persist workspace state; you may keep enabled for long multi-step tasks.
- If you need stateless behavior, disable it explicitly.

---

## Common failure modes (and what to do instead)

### Failure: Tech Lead starts coding
Fix:
- Strengthen Tech Lead system message: “NEVER implement.”
- Add controller-side validation: if Tech Lead output contains code fences/diffs, reject and re-prompt: “You violated role boundaries—output tasks only.”

### Failure: Skipping Intake
Fix:
- Controller must hard-enforce Step 0.
- Never allow direct user request → Tech Lead.

### Failure: “Delegation” is just text
Fix:
- The Tech Lead must call `delegate_to_agent` tool.
- Controller rejects any plan that doesn’t include tool calls during execution.

### Failure: No review gate
Fix:
- Controller refuses to respond to user with final output unless Reviewer PASS exists.

---

## Definition of Done (DoD)
This system is implemented correctly when:
- Every request runs Intake first
- Tech Lead only outputs structured delegation/tasks (no implementation)
- Strategist outputs a plan
- Specialists are invoked via a real tool callback
- Reviewer PASS is mandatory before final answer
- Escalation happens according to Tech Lead rules when agents struggle
- Structured JSON contracts are enforced