Saraev AI Agent Orchestration System

// When should you use the Saraev AI Agent Orchestration System?

Use this skill whenever you need to design, prompt, or orchestrate AI agents — whether building a single self-improving agent, delegating tasks across Claude/Gemini/Codex, or running stochastic ideation sweeps across a fleet of sub-agents.

// What do you need before orchestrating AI agents?

• Primary task or goalrequired
  The high-level objective the agent(s) must accomplish — e.g., 'build a full-stack SaaS app', 'generate growth strategy ideas', 'scrape and contact leads'.
• Definition of Donerequired
  The specific constraints and technical specifications the agent must satisfy before it concludes the loop. Without this, agents will underdeliver.
• Platform selectionrequired
  Which agentic coding platform(s) to use: Codex (OpenAI), Claude Code (Anthropic), or Anti-Gravity (Google/Gemini). Each can serve as orchestrator or sub-agent.
• Agent instruction file (agents.md / claude.md / gemini.md)
  The self-modifying markdown file prepended to every session. Can start empty; grows with learned rules over time.
• Skills files
  Pre-built markdown skill specs that standardize repeatable workflows (e.g., video-to-action pipeline, stochastic consensus). Stored in the workspace and invoked by name.
• API keys
  Required for multi-agent MCP orchestration across providers. One key per platform (Anthropic, OpenAI, Google).
• Number of sub-agents (n)
  For stochastic multi-agent consensus runs. Typically 3–10; higher n yields wider search space coverage.

// What are the core principles behind AI agent orchestration?

// How do you orchestrate AI agents step by step?

1. 1

   Define the task and write an explicit Definition of Done

   Before opening any platform, write: (a) the high-level goal in plain language, (b) the specific measurable conditions that signal completion (e.g., '10+ empirical sources compiled', 'app renders in browser with no console errors'). This Definition of Done goes directly into the prompt. Without it, the agent will stop arbitrarily or never stop.

2. 2

   Select your platform(s) based on task type

   Single-model tasks: use Claude Code for interpretability/orchestration, Gemini/Anti-Gravity for frontend or video tasks, Codex for backend/math/testing. Multi-model tasks: designate Claude Code as orchestrator by default. Do not over-engineer — for most tasks, one model is sufficient.

3. 3

   Create or open your agents.md / claude.md / gemini.md instruction file

   On first use, create the file with this meta-prompt structure: 'Before starting any task, read this entire file. When the user corrects you or you make a mistake, immediately append a new rule to the Learned Rules section. Format: [Category] Never/Always do X because Y.' Place this file at both global (user-wide) and local (project) levels. The file starts sparse and grows with every session.

4. 4

   Invoke a skill file if the task is a repeatable workflow

   Check whether a skill already exists for the task type (e.g., video-to-action, stochastic consensus, algorithmic art). If yes, invoke it by name in the prompt. If no, create a new skill file with: title section (three-hyphens delimiters), name, description, optional tools, and step-by-step procedure. Store it in the workspace skills folder.

5. 5

   Write the prompt using the Core Agent Loop structure

   Structure every prompt as: (1) Context/role, (2) Task description, (3) Any constraints or style rules, (4) Explicit Definition of Done. For multi-agent runs, add: (5) Delegation instructions — which subtasks go to which model. Keep prompts tight; instruction files and skills carry the persistent context.

6. 6

   For multi-agent orchestration: configure MCP server connections and API keys

   Register each model (Claude, Gemini, Codex) as an MCP server accessible to the orchestrator. Add API keys for each platform. In the orchestrator's claude.md, specify its role: 'You plan, reason, delegate, validate, and fix integration issues. Break tasks into frontend, backend, and test subtasks. Delegate to the appropriate model.' Front-end → Gemini. Backend/testing → Codex. Reasoning/review → Claude.

7. 7

   For video-to-action: feed YouTube URL through Gemini API via Claude orchestrator

   Invoke the video-to-action skill. Claude receives the URL, calls Gemini API (which has native video understanding), Gemini watches the video at 1 frame/second, extracts hyper-precise numbered steps with timestamps and UI details, returns structured steps to Claude, which then executes each step using its tool suite. Output: a markdown file of detailed steps the agent references continuously during execution.

8. 8

   For stochastic ideation: spawn N sub-agents with framing variations

   Take the core question/problem. Write N versions (3–10) of the prompt, each with a different analytical framing (e.g., 'assume limited budget', 'focus only on measurable results', 'reason from the end-user perspective', 'be contrarian'). Spawn all N simultaneously as sub-agents. Each operates in its own isolated context window. They all report back to the parent orchestrator.

9. 9

   Aggregate sub-agent outputs: calculate consensus, divergence, and outliers

   Orchestrator collects all N responses. Calculate mode (answers appearing in majority of agents = consensus — high confidence, act on these). Identify divergent items (some agents agree, others disagree — reason carefully before acting). Flag outliers (appear in 1–2 of N agents — could be brilliant wild cards or hallucinations; evaluate individually). Synthesize into a consensus map document.

10. 10

    Run sub-agent verification loops on outputs

    Route completed work from one agent (or model) to a separate agent for peer review. The reviewer checks for errors, inconsistencies, or missed requirements against the original Definition of Done. If issues found, loop back to the relevant agent or model. This catches what single-agent review misses.

11. 11

    Close the session: trigger instruction file update

    Before ending the session, prompt the agent: 'Update the Learned Rules section of [gemini.md / claude.md / agents.md] with any corrections, preferences, or patterns identified in this session.' This ensures the next session starts with accumulated knowledge. The file grows; errors relative to your preferences decrease over time.

12. 12

    Monitor interpretability and steer mid-run when using Claude Code

    Claude Code exposes a reasoning tab showing the agent's think step in real time. Use this to: verify the agent is on the correct path, identify wrong assumptions early, inject new resources or constraints mid-run without restarting. Gemini and Codex are less interpretable — treat them as fire-and-forget rockets. Set target and Definition of Done precisely before launch.

// What are real-world examples of AI agent orchestration?

// What mistakes should you avoid when orchestrating AI agents?

• Omitting the Definition of Done from prompts — this is the primary reason agents underdeliver or loop indefinitely. Always specify the exact conditions for task completion.
• Treating all three platforms as interchangeable for everything — use Claude for orchestration and interpretability, Gemini for frontend/video, Codex for backend/math. Minor differences matter at the bleeding edge.
• Starting multi-agent MCP orchestration before simple single-agent workflows are working — orchestration costs more tokens and adds complexity. Only use it when percentage-point quality differences are critical.
• Never updating the agents.md / claude.md / gemini.md instruction file — without self-modifying rules, every session starts from zero and repeats the same errors.
• Accumulating too many rules in a single instruction file (hypothetically 1,000+) — rules begin to conflict with each other. Prune or restructure when the file becomes unwieldy.
• Using the subsidized platform plan (e.g., Claude Max at $200/month) for multi-model API orchestration — API usage is not subsidized and can cost significantly more than platform plans. Budget accordingly.
• Running stochastic multi-agent consensus sequentially instead of in parallel — sequential re-querying takes N times as long and loses the core time advantage. All N agents must run simultaneously.
• Treating outlier wild-card ideas from stochastic consensus as automatically valid — outliers appear 5–10% of the time and may be hallucinations. Evaluate each individually before acting.
• Ignoring the interpretability advantage of Claude's reasoning tab — failing to monitor and steer mid-run means catching errors only after expensive compute has been consumed.
• Building skills or instruction files that are overly long — longer context degrades model quality and increases cost. Collapse knowledge into concise, imperative rules and well-scoped skill specs.

// What key terms should you know for AI agent orchestration?

Core Agent Loop

The three-step cycle every agent runs continuously: Observe (read all context), Think (reason and plan), Act (call tools, edit files, run commands). Repeats until the Definition of Done is met.

Definition of Done

The explicit series of constraints and technical specifications that signal to the agent that it should stop looping and output a final response. Omitting this is the primary cause of agent underperformance.

agents.md / claude.md / gemini.md

The self-modifying instruction file prepended to every agent session. Accumulates learned rules in the format '[Category] Never/Always do X because Y' from user corrections and mistakes, reducing errors over time.

Self-Modifying Instruction File

The design pattern where the agents.md/claude.md/gemini.md file is updated by the agent itself at session end with new rules derived from corrections, causing the agent to improve its alignment with user preferences across sessions.

Skills

Markdown files encoding standardized, repeatable workflows. They collapse statistical variance in LLM outputs into a deterministic procedure, ensuring consistent results for recurring task types.

Multi-Agent MCP Orchestration

Registering multiple AI models (Claude, Gemini, Codex) as MCP servers under a single orchestrator model, which routes subtasks to the model best suited for each and recombines outputs at the end.

Router

The decision hub within a multi-agent system that receives a high-level task, splits it into subtasks by type (frontend, backend, testing, video, etc.), delegates each to the appropriate model, and recombines outputs.

Stochastic Multi-Agent Consensus

Spawning N sub-agents simultaneously with slight framing variations of the same prompt to exploit LLM stochasticity, then aggregating results by mode (consensus), divergence, and outliers to traverse a wider solution space than sequential querying.

Stochasticity

The property of LLMs where minor statistical variations in input or model state cause slightly different outputs each run. Exploited deliberately in stochastic multi-agent consensus to surface rare, high-value ideas.

Traversing the Search Space

The mathematical concept underlying stochastic consensus — running multiple parallel queries covers more of the total space of possible answers than a single query, surfacing ideas the model would rarely produce on any single run.

Sub-Agents

Agents spawned by a parent orchestrator to operate in their own isolated context windows on a specific subtask. They report results back to the parent for aggregation or validation.

Sub-Agent Verification Loops

A quality-control pattern where completed work from one sub-agent is routed to another agent for peer review in real time, catching errors that a single agent's self-review would miss.

Video-to-Action Pipeline

A skill that feeds a YouTube URL to Claude (orchestrator), which calls the Gemini API to watch the video and extract hyper-precise numbered steps, which Claude then executes using its tool suite — enabling agents to learn from video the same way humans do.

Parallelization

Running multiple agent instances simultaneously to accomplish tasks faster and explore more solution paths than sequential execution. Described as the core strength of AI agents versus humans.

Wild Cards

Outlier ideas or solutions that appear in only a small percentage (5–10%) of stochastic consensus runs. Potentially brilliant and unlikely to surface through single queries; farmed deliberately by running large agent fleets.

Global vs. Local Instruction Files

Two-layer system: a global agents.md applies user-wide preferences across all projects; a local project-specific .md applies only to the current project. Stacked beneath: skills, then inline prompt.

Prompt Contracts

Explicitly structured prompts that define the agent's role, task, constraints, and Definition of Done in a binding, unambiguous format — reducing interpretive drift and improving output consistency.

Agent Chat Rooms

Centralized shared contexts where multiple agents can communicate, debate ideas, and build on each other's work — pushing collective output quality beyond what any single agent produces in isolation.

MCP (Model Context Protocol)

The communication standard used to register and query different AI models and tools as servers within an orchestrated multi-agent system.

// FREQUENTLY ASKED QUESTIONS