https://github.com/mubaidr/gem-team

Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.
https://github.com/mubaidr/gem-team

ai-agents automation claude-code code-review cursor developer-tools devops e2e-testing github-copilot harness mobile-development multi-agent opencode orchestration playwright security-audit spec-driven-development tdd testing windsurf

Last synced: 3 days ago
JSON representation

Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.

Host: GitHub
URL: https://github.com/mubaidr/gem-team
Owner: mubaidr
License: apache-2.0
Created: 2026-01-12T09:20:28.000Z (4 months ago)
Default Branch: main
Last Pushed: 2026-05-20T11:35:05.000Z (6 days ago)
Last Synced: 2026-05-20T12:15:27.574Z (6 days ago)
Topics: ai-agents, automation, claude-code, code-review, cursor, developer-tools, devops, e2e-testing, github-copilot, harness, mobile-development, multi-agent, opencode, orchestration, playwright, security-audit, spec-driven-development, tdd, testing, windsurf
Homepage:
Size: 1.72 MB
Stars: 122
Watchers: 4
Forks: 7
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md

Awesome Lists containing this project

README

# Gem Team

Version

Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.

> **TLDR:** Gem Team is a multi-agent framework that orchestrates LLM agents for software development tasks. It emphasizes spec-driven workflows with persistent learnings, built-in verification loops, knowledge-driven execution, and token efficiency.

## 🚀 Quick Start

```bash
apm install -g mubaidr/gem-team
```

APM auto-detects your tools and deploys gem-team agents everywhere — VS Code, Claude Code, Cursor, OpenCode, Codex CLI, Gemini CLI, Windsurf, and GitHub Copilot CLI. See the [compatible tools table](#compatible-tools) for details.

See [all supported installation options](#installation) below.

---

## 📚 Contents

- [🚀 Quick Start](#quick-start)
- [🎯 Why Gem Team?](#why-gem-team)
- [🧠 Core Concepts](#core-concepts)
- [🏗️ Architecture](#architecture)
- [� The Agent Team](#the-agent-team)
- [📦 Installation](#installation)
- [🤝 Contributing](#contributing)

---

## 🎯 Why Gem Team?

### Performance

- **4x Faster** — Parallel execution with wave-based execution
- **Pattern Reuse** — Codebase pattern discovery prevents reinventing wheels

### Quality & Security

- **Higher Quality** — Specialized framework agents + TDD + verification gates + contract-first
- **Built-in Security** — OWASP scanning, secrets/PII detection on critical tasks
- **Resilient** — Pre-mortem analysis, failure handling, auto-replanning
- **Accessibility-First** — WCAG compliance validated at spec and runtime layers
- **Safe DevOps** — Idempotent operations, health checks, mandatory approval gates
- **Constructive Critique** — gem-critic challenges assumptions, finds edge cases

### Intelligence

- **Source Verified** — Every factual claim cites its source; no guesswork
- **Knowledge-Driven** — Prioritized sources (PRD → codebase → AGENTS.md → Context7 → docs)
- **Established Patterns** — Prefers established library/framework conventions over custom implementations
- **Continuous Learning** — Memory tool persists patterns, gotchas, user preferences across sessions/ repo etc
- **Skills & Guidelines** — Built-in special skill & guidelines (design-guidelines, debugger etc)
- **Auto-Skills** — Agents extract reusable SKILL.md files from successful tasks

### Process

- **Plan-Driven** — Multi-step refinement defines "what" before "how"
- **Contract-First** — Contract tests written before implementation
- **Verified-Plan** — Complex tasks: Plan → Verification → Critic
- **Traceable** — Self-documenting IDs link requirements → tasks → tests → evidence
- **Intent vs. Compliance** — Shifts the burden from writing "perfect prompts" to enforcing strict, YAML-based approval gates
- **Diagnose-then-Fix** — gem-debugger diagnoses → gem-implementer fixes → re-verifies
- **Resumable** — Execution can be paused and resumed without losing context
- **Scriptable** — Use scripts for deterministic, repeatable, or bulk work (data processing, mechanical transforms, migrations/codemods, generated outputs, audits/reports, validation checks, reproduction helpers)

### Token Efficiency

Optimized for reduced LLM token consumption without quality loss:

- **Concise Output** — No preamble, no meta commentary, no verbose explanations
- **File-Based** — Researcher/Planner save to YAML files (for reusable context)
- **Context Caching & Memory Management** — Self-validating cache prevents redundant work across sessions and agents

### Design

- **Design Agents** — Dedicated agents for web and mobile UI/UX with anti-"AI slop" guidelines for distinctive aesthetics
- **Mobile Agents** — Native mobile implementation (React Native, Flutter) + iOS/Android testing

---

## 🧠 Core Concepts

### The "System-IQ" Multiplier

Raw reasoning isn't enough in single-pass chat. Gem-Team wraps your preferred LLM in a rigid framework with verification-first loops, fundamentally boosting its effective capability on SWE tasks.

### Knowledge Layers

---

Agents build these knowledge layers over time while working with you, capturing patterns, decisions, and learnings that improve future execution.

## 🏗️ Architecture

```text
User Goal
↓
Orchestrator
↓
Phase 0: Init & Clarify
• Generate/load plan_id
• Read memory, detect effort (LOW/MEDIUM/HIGH)
• Route to appropriate path
↓
Phase 1: Route
• Routing matrix based on effort, task type, and context
↓
Phase 2: Planning
• Delegate to planner
• Validation: MEDIUM (reviewer) / HIGH (reviewer+critic)
• Loop on failure (max 3x)
• Present for approval if HIGH
↓
Phase 3: Execution Loop
Pre-Wave: Check cache, add guards
↓
┌─ Wave Execution ──────────────┐
│ • Delegate tasks (≤4 concurrent)│
└─────────────┬─────────────────┘
↓
┌─ Integration Check ──────────┐
│ • Reviewer(wave) │
│ • UI: Designer(validate) │
│ • If fail: Debugger → retry │
└─────────────┬─────────────────┘
↓
┌─ Persist Learnings ──────────┐
│ • Memory (deduped) │
│ • Conventions → AGENTS.md │
│ • Decisions → PRD │
│ • Skills extraction │
└──────────────────────────────┘
↓
Next wave? → No → Phase 5
│Yes
└────────┘
↓
Phase 4: Persist Learnings
• PRD updates (decisions, contracts, requirements)
• AGENTS.md updates (new conventions, rules)
↓
Phase 5: Output
• Present final status
```

---

## 👥 The Agent Team

### Core Agents

### Quality & Review

### Skill Management

### Specialized

### Agent Selection Suggestions

For **proprietary/closed models** (GPT-5.4, Claude, Gemini):

- Research/Plan: Gemini 3.1 Pro, GPT-5.4
- Implementation: Claude Opus, GPT-5.4
- Review: Claude Opus, GPT-5.4

For **open-source models** (Qwen, GLM, DeepSeek, Llama):

- Research/Plan: GLM-5, Qwen3.5
- Implementation: DeepSeek-V3.2, Qwen Coder
- Review: Kimi K2.5, DeepSeek-V3.2

> **Note:** These are suggestions only. Gem Team works with any LLM that supports structured output. Choose based on availability, cost, and your specific task requirements.

---

## 📦 Installation

### Install APM First

If you don't have APM installed, install it first:

```bash
# macOS/Linux
curl -fsSL https://microsoft.github.io/apm/install.sh | sh

# Windows (PowerShell)
irm https://microsoft.github.io/apm/install.ps1 | iex

# Or via npm
npm install -g @microsoft/apm
```

**Why APM?** Universal package manager for AI coding tools. One command installs to all your tools (VS Code Copilot, GitHub Copilot CLI, Claude Code, Cursor, OpenCode, Codex CLI, Gemini CLI, Windsurf). Handles version locking, updates, and dependencies automatically.

[APM Documentation](https://microsoft.github.io/apm/) | [GitHub](https://github.com/microsoft/apm)

---

### Quick Install via APM

Single command — APM auto-detects your tools and deploys to all of them:

```bash
apm install mubaidr/gem-team
```

#### Useful Flags

```bash
# Preview what would install (no writes)
apm install --dry-run mubaidr/gem-team

# Install only for specific tools
apm install --target claude,cursor mubaidr/gem-team

# Exclude a tool
apm install --exclude codex mubaidr/gem-team

# Install globally (user scope)
apm install -g mubaidr/gem-team
```

---

### Compatible Tools

APM deploys agents to every harness it detects. Below is what lands where:

| Tool | Auto-detection signal | Where agents land | Primitives supported |
| ------------------------- | ---------------------------- | ------------------- | -------------------------------------------------- |
| **VS Code** (Copilot IDE) | `.github/` | `.github/agents/` | instructions, prompts, agents, skills, hooks, mcp |
| **GitHub Copilot CLI** | `.github/` | `.github/agents/` | instructions, prompts, agents, skills, hooks, mcp |
| **Cursor** | `.cursor/` or `.cursorrules` | `.cursor/agents/` | instructions, agents, skills, commands, hooks, mcp |
| **OpenCode** | `.opencode/` | `.opencode/agents/` | agents, commands, skills, mcp |
| **Codex CLI** | `.codex/` | `.codex/agents/` | agents, skills, hooks, mcp |
| **Windsurf** | `.windsurf/` | `.windsurf/skills/` | instructions, agents, skills, commands, hooks, mcp |

---

### Via Marketplace

Add gem-team as a marketplace, then install. Useful for browsing available agents and managing updates.

#### GitHub Copilot CLI

```bash
# Add marketplace
copilot plugin marketplace add mubaidr/gem-team

# Browse
copilot plugin marketplace browse gem-team

# Install
copilot plugin install gem-team@gem-team

# Or from awesome-copilot (pre-registered by default)
copilot plugin install gem-team@awesome-copilot
```

#### Claude Code

```bash
# Add marketplace
/plugin marketplace add mubaidr/gem-team

# Browse
/plugin

# Install
/plugin install gem-team@gem-team
```

#### Cursor IDE

```bash
apm marketplace add mubaidr/gem-team
apm install gem-team@gem-team
```

---

### Local / Manual Installation

For development, testing, or offline use.

```bash
git clone https://github.com/mubaidr/gem-team.git
cd gem-team
```

#### Claude Code

```bash
claude --plugin-dir .
# Or: /plugin marketplace add ./
```

#### Cursor IDE

```bash
# Via chat command
/add-plugin /absolute/path/to/gem-team

# Or one-line copy to .cursor/rules/
mkdir -p .cursor/rules && cp .apm/agents/*.agent.md .cursor/rules/ && cd .cursor/rules && for f in *.agent.md; do mv "$f" "${f%.agent.md}.mdc"; done && cd ../..
```

#### GitHub Copilot CLI

```bash
copilot plugin marketplace add /absolute/path/to/gem-team
copilot plugin install gem-team@gem-team
```

#### Any Tool (Manual Copy)

```bash
cp -r .apm/agents
# Destinations:
# VS Code / Copilot CLI → ~/.copilot/
# Claude Code → ~/.claude/plugins/
# Cursor → .cursor/rules/
# OpenCode → .opencode/plugins/
```

---

### Verification

After installation, confirm your setup:

```bash
# Preview which tools APM detects
apm targets

# List installed packages
apm list

# View package details
apm view gem-team

# Tool-specific checks
copilot plugin list # GitHub Copilot CLI
/plugin list # Claude Code
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. [CONTRIBUTING](./CONTRIBUTING.md) for detailed guidelines on commit message formatting, branching strategy, and code standards.

## 📄 License

This project is licensed under the Apache License 2.0.

## 💬 Support

If you encounter any issues or have questions, please [open an issue](https://github.com/mubaidr/gem-team/issues) on GitHub.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/mubaidr/gem-team

Awesome Lists containing this project

README