💎 Gem Team: Multi-Agent Orchestration Framework

Transform complex projects into coordinated, verified, production-ready deliverables — with intelligent agents that research, plan, implement, test, and document autonomously.

A modular, high-performance multi-agent team designed for complex project execution, feature implementation, and automated verification.

---

📦 Installation

Available in awesome-copilot — the official GitHub repository for Copilot extensions.

---

⚡ Why Gem Team?

The Problem with Single-Agent AI

Traditional AI coding assistants hit walls when projects get complex:

• Context overload — One agent trying to hold everything leads to mistakes
• No specialization — Jack of all trades, master of none
• Sequential bottlenecks — Tasks execute one-by-one, wasting time
• Missing verification — Changes ship without proper testing
• No audit trail — What changed? Why? Who knows...

The Gem Team Solution

Challenge	Gem Team Approach
🧠 Context Overload	Specialized agents with focused expertise — each holds only what it needs
🎯 Lack of Specialization	7 expert agents: researcher, planner, implementer, tester, reviewer, devops, and documentation specialist
🐢 Sequential Bottlenecks	DAG-based parallel execution — up to 4 agents work simultaneously
❌ Missing Verification	Verification-first: no task completes without passing its verification command
📜 No Audit Trail	Persistent plan.yaml state file tracks every decision, status, and outcome

Key Benefits

• 🚀 10x Faster Execution — Parallel agent execution eliminates bottlenecks
• 🎯 Higher Quality Output — Specialized agents + mandatory verification = fewer bugs
• 🔒 Built-in Security — Dedicated reviewer agent applies OWASP scanning on critical tasks
• 📊 Full Visibility — Real-time plan status, clear approval gates, comprehensive summaries
• 🔄 Resilient Workflows — Pre-mortem analysis, failure handling, and automatic replanning
• 📋 Strict Communication Protocol — Standardized input/output formats for reliable delegation and handoffs
• 🎯 Autonomous Execution — Most agents work independently without user intervention (except approval gates)
• 🔧 Context-Efficient Operations — Smart file reading (semantic search, 200-line limits) and batch operations for speed
• 📄 PRD Support — Machine-readable Product Requirements Document with state machines, error codes, and decision tracking

---

🚀 Overview

Gem Team follows a Delegation-First pattern. The Orchestrator never executes—it only detects phase, routes to agents, and synthesizes results. All state operations are managed directly by the Orchestrator via plan.yaml.

┌─────────────────────────────────────────────────────────────────┐
│                         USER GOAL                               │
└──────────────────────────────┬──────────────────────────────────┘
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                      ORCHESTRATOR                               │
│  • Phase Detection    • Route to agents (runSubagent)          │
│  • Synthesize results • Manage plan.yaml state                │
│  • Manage todos       • Never execute directly                  │
└──────────────────────────────┬───────────────────────────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        ▼                      ▼                      ▼
┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐
│  RESEARCHER       │  │    PLANNER        │  │  (other agents)   │
│  (Phase 1)        │  │  (Phase 2)        │  │  (Phase 3)        │
│  Focus areas      │  │  DAG + Pre-mortem │  │  Execute tasks    │
└───────────────────┘  └───────────────────┘  └───────────────────┘
                                    ▼
                          ┌────────────────────────┐
                          │  plan.yaml             │
                          │  (Task DAG + State)    │
                          └────────────────────────┘

---

🤖 Agent Roles

Agent	Role	Primary Responsibility
gem-orchestrator	ORCHESTRATOR	Team Lead - Coordinate workflow with energetic announcements. Detect phase → Route to agents → Synthesize results. Manage plan.yaml state and todos. Never execute.
gem-researcher	RESEARCHER	Explore codebase, identify patterns, map dependencies. Deliver structured findings in YAML. Never implement.
gem-planner	PLANNER	Design DAG-based plans, decompose tasks, identify failure modes. Create plan.yaml. Never implement.
gem-implementer	IMPLEMENTER	Write code using TDD. Follow plan specifications. Ensure tests pass. Never review.
gem-browser-tester	BROWSER TESTER	Run E2E scenarios in browser (Chrome DevTools MCP, Playwright, Agent Browser). Verify UI/UX, accessibility. Deliver test results. Never implement.
gem-devops	DEVOPS	Deploy infrastructure, manage CI/CD, configure containers. Ensure idempotency. Never implement.
gem-reviewer	REVIEWER	Scan for security issues, detect secrets, verify PRD compliance. Deliver audit report. Never implement.
gem-documentation-writer	DOCUMENTATION WRITER	Write technical docs, generate diagrams, maintain code-documentation parity. Never implement.

---

🔄 Core Workflow

The Orchestrator follows a 4-Phase workflow:

Phase Detection (Automatic)

Current State	Next Phase
No plan exists	Phase 1: Research
Plan + user feedback	Phase 2: Planning
Plan + pending tasks	Phase 3: Execution Loop
All tasks complete/blocked	Phase 4: Summary

Phase 1: Research

• Orchestrator detects complexity (simple/medium/complex)
• Identifies focus areas from user goal
• Delegates to gem-researcher (up to 4 concurrent) per focus area
• Output: docs/plan/{plan_id}/research_findings_{focus_area}.yaml

Phase 2: Planning

• Complex tasks: Delegates to gem-planner 3x (variants a/b/c), selects best
• Simple/Medium: Delegates to gem-planner once
• Validates against existing PRD
• Output: docs/plan/{plan_id}/plan.yaml with DAG tasks and waves

Phase 3: Execution Loop

• Reads plan.yaml, gets pending tasks (dependencies=completed)
• Executes in waves (wave 1 first, wave 2 after wave 1 completes, etc.)
• Up to 4 agents work in parallel per wave
• Contracts presented for verification (wave > 1)
• Loops until all tasks done or blocked

Phase 4: Summary

• Presents status, summary, next steps
• User feedback routes back to Phase 2: Planning

---

🛠 Key Features

🎯 VS Code Copilot Steer Support

Send a steer message to gem-orchestrator and it automatically redirects to the appropriate agent — researcher for new context, planner for plan updates — integrating your request into the active workflow.

🎯 Team Lead Personality

The Orchestrator acts as an energetic team lead — announces phase/wave starts, celebrates wins, acknowledges setbacks. Keeps the team motivated with concise, action-oriented updates.

🔍 Focus-Based Context Gathering

The Orchestrator identifies key domains or features and launches multiple Researcher agents in parallel, each targeting a specific focus_area. This ensures deep, specific context is gathered for every part of the system before the Planner synthesizes it all into a unified plan.yaml.

🧪 Verification-First (TDD)

No task completes without passing its defined verification command. Implementers follow strict TDD discipline:

• Write tests FIRST
• Confirm tests FAIL
• Write MINIMAL code to pass
• Check get_errors after every edit

🌐 Multi-Browser Testing

Browser Tester supports Chrome DevTools MCP, Playwright, and Agent Browser — run E2E tests across different browser tools for maximum coverage.

🛡️ Security-First Review

The Reviewer agent acts as a security gatekeeper for critical tasks:

• OWASP Top 10 scanning
• Secrets/PII detection
• Compliance verification
• Tiered review depth (Full → Standard → Lightweight)

📊 Pre-Mortem Analysis

Planner identifies failure modes (likelihood, impact, mitigation) for complex plans BEFORE execution.

📝 Plan Continuity & Audit Trail

State in docs/plan/{plan_id}/plan.yaml provides recovery, retry handling, and full decision traceability.

📋 Product Requirements Document (PRD)

Machine-readable spec at docs/prd.yaml — Orchestrator creates and maintains PRD based on completed plans and reviewer feedback. Contains state machines, error codes, performance thresholds, and decision log.

🔒 Agent Hierarchy

User → ORCHESTRATOR → WORKERS (execute)

• Orchestrator: disable-model-invocation: true — delegates ALL work, manages plan.yaml state and todos, never executes
• Workers: disable-model-invocation: false — execute tasks via tools
  • RESEARCHER, PLANNER, IMPLEMENTER, BROWSER TESTER, DEVOPS, REVIEWER, DOC WRITER
• Isolation: Workers cannot call other subagents — all collaboration mediated by Orchestrator

---

📁 Project Structure

gem-team/
├── gem-*.agent.md               # Agent definitions (7 agents)
├── docs/
│   ├── prd.yaml                 # Product Requirements Document (project-level)
│   └── plan/{plan_id}/
│       ├── plan.yaml             # Task DAG + state
│       ├── research_findings_*.yaml    # Researcher output
│       ├── walkthrough-*.md      # Completion documentation
│       ├── evidence/{task_id}/   # Browser test failures
│       └── logs/                  # Failure logs
└── README.md

Generated Artifacts by Agent

Agent	Generates	Path
gem-planner	plan.yaml, PRD (draft)	docs/plan/{plan_id}/plan.yaml, docs/prd.yaml
gem-researcher	findings YAML	docs/plan/{plan_id}/research_findings_{focus}.yaml
gem-documentation-writer	walkthrough, PRD (final)	docs/plan/{plan_id}/walkthrough-*.md, docs/prd.yaml
gem-browser-tester	evidence (on failure)	docs/plan/{plan_id}/evidence/{task_id}/
All agents	failure logs	docs/plan/{plan_id}/logs/{agent}_{task_id}_{ts}.yaml

---

📋 Agent Protocol

Input → Output

Delegation (Input):

task_id, plan_id, plan_path, task_definition (agent-specific)

Completion (Output):

{"status": "completed|failed|needs_revision", "task_id", "plan_id", "summary": "≤3 sentences", "extra": {}}

Core Rules

• Output ONLY requested deliverable (code: code ONLY)
• Think-Before-Action via internal <thought> block
• Batch independent operations; context-efficient reads (≤200 lines)
• Agent-specific verification criteria from plan.yaml

Verification by Agent

Agent	Verification
Implementer	get_errors → typecheck → unit tests
Browser Tester	validation matrix → console → network → accessibility
Reviewer	OWASP scan → code quality → logic
DevOps	deployment → health checks → idempotency
Doc Writer	completeness → code parity → formatting

Autonomous Execution

• Most agents: Fully autonomous
• DevOps: Approval gates for production/security
• Planner: Mandatory plan review before execution
• Orchestrator: Delegates all via runSubagent

---

🎯 Use Cases

Scenario	How Gem Team Helps
Large Feature Implementation	Decomposes into parallel subtasks, implements with TDD, verifies each component
Codebase Refactoring	Researches patterns, plans migration, executes incrementally with tests
Security Audit	Reviewer scans for OWASP issues, secrets, compliance gaps
Documentation Overhaul	Doc Writer generates accurate docs maintaining code-documentation parity
CI/CD Pipeline Setup	DevOps agent creates containers, pipelines, deploys with health checks
UI/UX Testing	Chrome Tester automates validation matrix, captures visual evidence

---

📄 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

---

Built for Gem Team — Precision. Parallelism. Progress.

Transform complexity into coordinated execution.