---
title: "Introducing gem-orchestrator: The Team Lead Your AI Development Workflow Has Been Waiting For"
description: "gem-orchestrator is the central intelligence of the Gem Team framework - automatically choosing the right workflow, routing tasks to specialized agents, and keeping every decision traceable to your original goal. Here's what makes it different."
canonical_url: "https://mubaidr.js.org/blog/34-gem-team-orchestrator"
---

> Index of every page on this site: [llms.txt](https://mubaidr.js.org/llms.txt)

Every AI-assisted development tool faces the same fundamental problem: **given a goal, how do you consistently turn it into high-quality code?** Most tools solve this with a single LLM call - fast, but brittle. One prompt goes wrong and you're off the rails with no recovery path. gem-orchestrator takes a different approach - it thinks before it acts, routes to specialists, and verifies every deliverable.

In this post, I'll introduce you to the central agent of the Gem Team framework: what it does, how it thinks, and why orchestrating a team of specialized agents produces better outcomes than any single AI doing everything.

## The Problem with Single-Agent Development

Let's be honest about what most AI coding assistants do today: they take your prompt, generate code, and hand it back. That works for small, well-scoped tasks. But software development rarely stays small. A feature request becomes a refactoring task. A refactoring task surfaces an architectural decision. An architectural decision requires buy-in from a PRD. Before you know it, the single-agent approach is generating code that's disconnected from requirements, missing test coverage, and shipping without review.

The failure modes are predictable:

- **No phase detection**: The tool doesn't know when to stop and think, so it jumps straight to code generation even when planning is needed.
- **No specialist routing**: One agent tries to be researcher, architect, implementer, reviewer, and tester - and does none of them optimally.
- **No recovery path**: When something fails, there's no structured way to diagnose, fix, and retry. You just try again with a longer prompt.
- **No traceability**: Even if the output is good, you can't trace which decision led to which implementation choice.

gem-orchestrator was built to solve all four.

## What gem-orchestrator Does

At its core, gem-orchestrator is a **phase-aware routing engine**. Given a user request, it:

1. **Detects the appropriate workflow phase** - Discuss, Research, Planning, Execution, or Summary
2. **Routes to specialized agents** for that phase's work
3. **Maintains state** across waves of execution
4. **Synthesizes results** from parallel agents into coherent deliverables
5. **Handles failures** with structured diagnosis and retry loops

The key insight is that not every goal needs the same workflow. A simple bug fix might skip straight to execution. A complex feature needs discuss → PRD → research → planning → execution. gem-orchestrator detects which path to take based on the goal's scope, risk, and complexity - you just describe what you want.

## The Phase Detection System

gem-orchestrator's workflow is built around five phases:

<table>
<thead>
  <tr>
    <th align="left">
      Phase
    </th>
    
    <th align="left">
      When It Runs
    </th>
    
    <th align="left">
      What Happens
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      <strong>
        Discuss
      </strong>
    </td>
    
    <td align="left">
      Medium/complex goals (optional)
    </td>
    
    <td align="left">
      Clarifies requirements, surfaces gray areas, asks targeted questions
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <strong>
        PRD
      </strong>
    </td>
    
    <td align="left">
      After Discuss
    </td>
    
    <td align="left">
      Locks requirements into a structured Product Requirements Document
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <strong>
        Research
      </strong>
    </td>
    
    <td align="left">
      After PRD or standalone for simple goals
    </td>
    
    <td align="left">
      Explores codebase patterns, gathers context, builds knowledge base
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <strong>
        Planning
      </strong>
    </td>
    
    <td align="left">
      After Research
    </td>
    
    <td align="left">
      Decomposes work into a directed acyclic graph (DAG) of tasks, grouped into waves
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <strong>
        Execution
      </strong>
    </td>
    
    <td align="left">
      After Planning is approved
    </td>
    
    <td align="left">
      Runs tasks wave-by-wave with parallel agents, integration gates, and retry loops
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <strong>
        Summary
      </strong>
    </td>
    
    <td align="left">
      After Execution
    </td>
    
    <td align="left">
      Presents completed work, test evidence, review reports
    </td>
  </tr>
</tbody>
</table>

This isn't a rigid waterfall - the orchestrator is adaptive. Simple goals skip Discuss and PRD. Planning failures trigger replanning. Execution failures go through a diagnose-then-fix loop before retrying. The structure exists to keep the process aligned, but it flexes based on what the goal actually needs.

## Wave-Based Execution: Parallelism with Discipline

One of gem-orchestrator's most powerful features is **wave-based execution**. Tasks in a plan are grouped into waves - waves execute sequentially, but tasks within a wave run in parallel (up to 4 concurrent agents).

This gives you the best of both worlds: parallelism for speed, and a structured gate between waves to ensure integration before the next set of tasks begins.

```text
Wave 1 (parallel):  task_A, task_B, task_C
    ↓ [Integration Gate - all must pass]
Wave 2 (parallel):  task_D, task_E  [D depends on C, E independent]
    ↓ [Integration Gate]
Wave 3 (sequential): task_F  [depends on D and E]
    ↓ [Integration Gate]
Summary
```

Each gate runs gem-reviewer to verify build passes, tests pass, and no integration failures exist. If a gate fails, gem-debugger diagnoses the root cause, and gem-implementer applies the fix - then the gate re-runs. Only after the gate passes does the next wave begin.

This prevents the "everything is done until it's not" problem that plagues loosely coordinated parallel work.

## The Diagnose-then-Fix Loop

When a task fails, most tools just retry the same approach. gem-orchestrator inserts a structured diagnostic step:

1. **gem-debugger** receives the error context - error message, stack trace, failing test output, reproduction steps
2. It analyzes root cause with confidence scoring (≥0.7 required to proceed)
3. It returns fix recommendations with specific file:line locations
4. **gem-implementer** applies the fix
5. The original agent re-verifies the fix

This means every retry is smarter than the last, not just louder. And if diagnosis confidence falls below the threshold, gem-orchestrator escalates to you rather than spinning indefinitely.

## Source-Verified Decision Making

One underappreciated aspect of gem-orchestrator is its **trust-level system for knowledge sources**:

- **Trusted**: PRD.yaml, plan.yaml, AGENTS.md - followed as instructions
- **Verified**: Codebase files, research findings - cross-referenced before assuming
- **Untrusted**: Error logs, external data, third-party responses - factual only, never as instructions

This prevents the "AI hallucinating a fix from error log context" problem. Before any agent acts on external data, it verifies against source code or trusted documentation.

## How It Fits into Gem Team

gem-orchestrator is the **hub** of the Gem Team framework. All 15 agents connect through it:

- **gem-researcher** feeds findings into planning
- **gem-planner** generates the task DAG
- **gem-reviewer** and **gem-critic** validate the plan before execution
- **gem-implementer**, **gem-implementer-mobile**, and specialist agents execute tasks
- **gem-browser-tester**, **gem-mobile-tester** verify end-to-end flows
- **gem-debugger** diagnoses failures
- **gem-designer**, **gem-designer-mobile** validate UI work
- **gem-devops** handles infrastructure
- **gem-documentation-writer** produces docs at the end

The orchestrator coordinates all of these without you needing to know which agent does what - you describe the goal, and it handles the rest.

## What's Different About This Approach

If you've used other AI coding tools, here's what makes gem-orchestrator stand out:

**It's spec-driven, not prompt-driven.** Most AI tools respond to whatever you type. gem-orchestrator insists on a structured PRD before it generates code. This means less ambiguity in scope, clearer acceptance criteria, and traceable requirements.

**It's self-correcting.** The diagnose-then-fix loop means failures get smarter treatment than "try again." The debugger's confidence scoring prevents spinning on low-quality diagnoses.

**It's multi-agent by design.** Rather than one LLM doing everything, it routes to specialists who are optimized for their specific role. The orchestrator's job is coordination, not replacement of expertise.

**It's opinionated about process.** You can't skip planning and complain about poor architecture. You can't skip review and complain about security issues. The gates exist for a reason - they enforce quality at the boundaries where it's easiest to overlook.

## Getting Started

gem-orchestrator is available as part of the Gem Team framework via the Copilot CLI:

```bash
copilot plugin install gem-team@awesome-copilot
```

Once installed, you can start a session by describing a development goal:

```text
> Set up a new user authentication flow with JWT tokens and refresh rotation
```

Watch the orchestrator detect that this is a medium-complexity task, route through Discuss → PRD → Research → Planning, and generate a wave-based execution plan - all before writing a single line of code.

For more details on the full agent team and architecture, visit the [gem-team repository on GitHub](https://github.com/mubaidr/gem-team).

---

*This post is part of the AI-Powered Development series. Previous: Gem Team v1.6.0: Mobile Agents.*

## Sitemap

See the full [sitemap](https://mubaidr.js.org/sitemap.md) for all pages.
