Gem Team

Turn AI coding into an orchestrated loop: plan, build, review, debug, learn.

Spec-driven multi-agent orchestration for software development, verification, debugging, and reusable project knowledge.

TL;DR: Gem Team installs 16 specialist agents that turn AI coding into an engineering process. Plan, implement, review with structured waves, dependency resolution, integration gates, and progressive context management. Works with Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Windsurf.

Why Gem Team?

Gem Team wraps your AI with a disciplined engineering delivery system — plan, build, review, debug, learn. The Features section below covers every capability in detail. Here's the gist:

• Better delivery flow — spec-driven execution, wave-based parallelism, verification gates, resumable plans.
• Better code quality — 16 specialist agents, TDD by default, diagnose-then-fix, security and accessibility audits.
• Better context management — progressive context envelope, three-tier memory, skill extraction, PRD management.
• Better cost control — model routing, output hygiene, context pruning, discovery depth scaling.

Quick Start

Install APM first:

# macOS / Linux
curl -sSL https://aka.ms/apm-unix | sh

# Windows PowerShell
irm https://aka.ms/apm-windows | iex

# Verify
apm --version

Install Gem Team into your current project:

apm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf

Or install for one target only:

apm install mubaidr/gem-team --target copilot

After the first install, commit the generated APM files that belong to your repo, especially apm.yml, apm.lock.yaml, and the generated harness directories such as .github/, .claude/, .cursor/, .opencode/, .codex/, .gemini/, or .windsurf/. Do not commit apm_modules/.

APM can auto-detect targets from existing harness directories, but explicit --target is recommended for predictable installs and fresh repositories.

Contents

• Why Gem Team?
• Features
• Comparison
• Core Concepts
• Workflow
• The Agent Team
• Installation
• Compatible Tools
• Configuration
• Operational Notes
• Contributing
• License
• Support

Features

Intelligent Workflow Engine

• Phase-based predictable pipeline: Init → Route → Plan → Execute → Output.
• Complexity-adaptive routing: TRIVIAL tasks get one-shot delegation. LOW gets in-memory planning. MEDIUM/HIGH get durable plans, validation gates, and DAG-based wave execution.
• Integration gates: Reviewer checks wave output before proceeding. MEDIUM gates on risk; HIGH gates every wave.
• Resumable plans: Plan IDs, file-based artifacts, and context envelopes make long tasks pause, inspect, and continue cleanly.

Specialist Agent Team

• 16 focused agents: Planner, Researcher, Implementer, Implementer-Mobile, Reviewer, Critic, Debugger, Browser Tester, Mobile Tester, Devops, Documentation Writer, Designer, Designer-Mobile, Code Simplifier, Skill Creator — plus the Orchestrator who coordinates them all.
• TDD by default: Implementers follow Red-Green-Refactor. Bug-fix mode requires debugger diagnosis before touching code.
• Diagnose-then-fix: Debugger diagnoses → Implementer fixes → Reviewer re-verifies. Enforced at planner, orchestrator, implementer, and reviewer levels.

Context & Knowledge Management

• Context envelope: Progressive cache shared across all agents. Tech stack, conventions, constraints, architecture snapshot, research digest, prior decisions — enriched after each wave.
• Three-tier memory: Repo (workspace-scoped), session (conversation-scoped), global (user-scoped). Confidence-gated persistence (≥0.85).
• Stable cache: High-confidence facts (≥0.90, stable, ≥3 uses) promoted to durable cache. Auto-eviction after 90 days unused.
• Reuse notes: Trusted file paths and patterns that agents skip re-verifying.
• Skill extraction: High-confidence workflows become reusable SKILL.md playbooks via gem-skill-creator.
• PRD management: Structured product requirements with acceptance criteria, decisions, and change history.

Quality & Verification

• Plan validation: Reviewer checks plan correctness, temporal paradoxes, wave ordering, and contract integrity.
• Critic review: Challenges assumptions, finds edge cases, flags over-engineering — for HIGH complexity and architecture-impacting changes.
• Per-wave integration checks: Reviewer verifies contracts, conflicts, and integration points after each wave.
• Security audits: OWASP scanning, secrets/PII detection, mobile 8-vector scan (keychain, cert pinning, deep links, biometric auth, network security).
• Accessibility audits: WCAG 2.1 AA contrast checks, ARIA labels, focus indicators, touch targets, reduced-motion support.
• Visual regression: Screenshot comparison with configurable thresholds.
• Configurable audit depth: none, basic, or full a11y scanning.

🔧 Testing

• E2E browser testing: Flow-based scenarios with setup, assertions, visual evidence, console/network capture.
• Mobile E2E testing: iOS + Android with Detox, Maestro, Appium. Gesture testing, lifecycle testing, push notifications, device farm support.
• Performance testing: Cold start TTI, memory profiling, frame rate analysis, bundle size tracking.
• Platform-specific testing: Safe areas, keyboard behaviors, system permissions, dark mode, haptics, back button, battery optimization.

Design

• UI/UX design system creation: Palettes, typography scales, spacing, shadows, design movements (brutalism, glassmorphism, minimalism, neo-brutalism, claymorphism, retro-futurism, maximalism).
• Mobile platform design: iOS HIG, Android Material 3, safe areas, dynamic island, touch targets (44pt/48dp), platform-select pattern.
• Accessibility-first: Contrast 4.5:1, touch targets, reduced-motion, semantic HTML/ARIA.
• Design output: 9-section DESIGN.md with tokens, component specs, responsive behavior, agent prompt guide.

DevOps & Deployment

• Infrastructure provisioning: Docker, Kubernetes, cloud (AWS/GCP/Azure).
• CI/CD pipeline management: PR → staging → smoke → production flows.
• Approval gates: Configurable per-environment approval requirements.
• Health checks: Endpoint verification, resource monitoring, rollback strategies (rolling, blue-green, canary).
• Mobile deployment: EAS Build/Update, Fastlane, TestFlight, Google Play phased rollouts.
• Idempotent operations: All ops designed to be safe to re-run.

Cost Control

• Model routing: Cheap models for routine work (implementer, docs). Strong models for planning, debugging, review, critique.
• Output hygiene: Agents limited to native tool flags, pipe truncation, maxResults on searches.
• Context reuse: Envelope filtered per-agent (only relevant sections).
• Budget controls: Researcher has max_searches, max_files_to_read, max_depth per task.

Learning & Reuse

• Persist high-confidence learnings: Facts, patterns, gotchas, failure modes, decisions ≥0.95 confidence automatically persisted.
• Batch delegation: Product decisions → PRD. Technical decisions → AGENTS.md/architecture docs. Patterns → memory/envelope. Workflows → skills.
• Git checkpointing: Optional wave-level commits on integration gate pass for clean audit trail and rollback diagnosis.

Comparison

gem-team is not trying to replace Copilot, Cursor, Claude Code, Cline, or Roo Code.

It focuses on the missing workflow layer:

• planning
• subagent delegation first policy for parallel work
• context envelope for avoiding repeated source reads
• reviewer/debugger loops
• specialist agents
• repeatable execution artifacts

Use gem-team when you want AI coding to follow an engineering process instead of a single chat prompt.

Vibe with confident, structured delivery and durable knowledge instead of ad-hoc one-off outputs.

Core Concepts

System-IQ multiplier

Gem Team wraps your chosen model with a disciplined delivery system: task classification, planning, delegation, verification, debugging, and learning. The goal is to improve the reliability of agentic software work without depending on a single long prompt.

Knowledge layers

Layer	Location	Purpose
PRD	docs/PRD.yaml	Product requirements and approved decisions.
AGENTS.md	AGENTS.md	Stable project conventions, rules, and agent instructions.
Plan artifacts	docs/plan/{plan_id}/	Per-task plans, context envelopes, task registries, evidence, and results.
Memory	Memory tool / configured backend	Durable facts, decisions, gotchas, patterns, and failure modes.
Skills	docs/skills/	Reusable procedures extracted from successful repeated workflows.
Derived docs	docs/knowledge/	Reference notes, external docs, summaries, and research outputs.

Workflow

Architecture Flow

Execution Model

Gem Team adapts workflow depth to task complexity:

• TRIVIAL: direct execution with a tiny checklist.
• LOW: lightweight in-memory planning and execution.
• MEDIUM/HIGH: durable planning, context envelope, validation, wave execution, and integration review.

The system batches independent work, serializes only true dependencies, and persists high-confidence learnings for future runs.

User Input
    ↓
Phase 0: Init & Clarify
    • Read provided context
    • Load config and relevant memory
    • Detect intent and plan state
    • Classify complexity
    • Ask only for blocking clarification
    ↓
Phase 1: Route
    • Continue existing plan
    • Revise existing plan
    • Start new task
    ↓
Phase 2: Plan
    • TRIVIAL → tiny checklist
    • LOW → lightweight in-memory plan
    • MEDIUM/HIGH → durable planner-generated plan
    • Validate higher-risk plans before execution
    ↓
Phase 3: Execute
    • Prepare context based on complexity
    • Run unblocked work in waves
    • Delegate tasks to suitable agents
    • Respect dependencies and conflicts
    • Review/integrate higher-risk waves
    ↓
Learn & Persist
    • Save reusable decisions, patterns, gotchas, and skills
    • Update memory, docs, PRD, AGENTS.md, or skills as appropriate
    ↓
Loop / Replan
    • Continue next wave
    • Replan if scope changes
    • Escalate if blocked
    ↓
Phase 4: Output
    • Present final status using configured output format

The Agent Team

Recommended model routing

Use a fast cost-efficient model as the default and reserve stronger reasoning models for tasks that need deeper analysis.

Role	Example model	Recommended use
Default agents	mimoi-2.5/deepseek-v4-flash	Routine implementation, documentation, research summaries, and simple checks.
Planner, Debugger, Critic, Reviewer	mimoi-2.5-pro/deepseek-v4-pro	Planning, root-cause analysis, compliance checks, critical review, and high-risk verification.

Replace these with equivalent models from your own provider if needed.

Core agents

Agent	Description
ORCHESTRATOR	Coordinates the workflow, delegates work, tracks plans, and enforces verification gates. Runs Phase 0–4 pipeline. Never executes work directly.
RESEARCHER	Explores codebase patterns, dependencies, architecture, and docs. Supports 5 modes (scan, deep, audit, trace, question) with budget controls.
PLANNER	Creates DAG-based execution plans with task decomposition, wave scheduling, dependency mapping, risk analysis, and acceptance criteria.
IMPLEMENTER	Implements features, fixes, and refactors using TDD (Red-Green-Refactor). Bug-fix mode requires debugger diagnosis. Surgical edits only.

Quality and review

Agent	Description
REVIEWER	Reviews implementation quality, security, maintainability, contracts, and test coverage. Plan validation (lightweight/full). Wave integration checks. OWASP + secrets + mobile 8-vector security scan. Accessibility audit (none/basic/full).
CRITIC	Challenges assumptions, finds edge cases, flags over-engineering or missed constraints. Evaluates decomposition, dependencies, complexity, coupling, and future-proofing. Offers alternatives, not just criticism.
DEBUGGER	Root-cause analysis, stack trace diagnosis, regression bisection, error reproduction. Prove-It pattern (reproduction test first). Never implements fixes.
BROWSER TESTER	E2E browser checks, UI flow validation, visual regression (screenshot comparison), console/network capture, a11y audit. Configurable thresholds.
CODE SIMPLIFIER	Removes dead code, reduces cyclomatic complexity, consolidates duplicates, improves naming. Preserves behavior — runs tests after each change. Chesterton's Fence principle.

Specialized agents

Agent	Description
DEVOPS	Infrastructure deployment, CI/CD pipelines, container management (Docker/K8s). Approval gates for prod. Health checks, rollback (rolling/blue-green/canary). Mobile deployment (EAS, Fastlane, TestFlight/Play Store).
DOCUMENTATION	Technical docs, READMEs, API docs, diagrams, walkthroughs. PRD authoring and maintenance. Context envelope updates. AGENTS.md management. Coverage matrices.
DESIGNER	UI/UX layouts, themes, color schemes, design systems. Create/validate modes. Design movements (brutalism, glassmorphism, minimalism, etc.). 9-section DESIGN.md output. WCAG 2.1 AA.
IMPLEMENTER-MOBILE	Mobile TDD for React Native, Expo, Flutter. Platform-specific code with Platform.select. SafeAreaView, FlatList, Reanimated. Bug-fix mode.
DESIGNER-MOBILE	Mobile UI/UX for iOS (HIG) and Android (Material 3). Safe areas, touch targets (44pt/48dp), dynamic island, platform-specific specs.
MOBILE TESTER	Mobile E2E with Detox, Maestro, Appium. iOS + Android. Gesture, lifecycle, push notification, device farm testing. Performance (cold start, memory, frame rate).
SKILL CREATOR	Extracts reusable SKILL.md files from high-confidence (≥0.95, ≥2 uses) patterns. Creates scripts, references, and cross-linked assets.

Installation

1. Install APM

# macOS / Linux
curl -sSL https://aka.ms/apm-unix | sh

# Windows PowerShell
irm https://aka.ms/apm-windows | iex

# Verify
apm --version

2. Install Gem Team

Project-scoped install, recommended for teams:

apm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf

Global user-scoped install, useful for personal use:

apm install -g mubaidr/gem-team

Pin a release for reproducible installs:

apm install mubaidr/gem-team#v1.20.0 --target copilot

3. Verify the install

apm list
apm view mubaidr/gem-team
apm audit

Tool-specific checks:

copilot plugin list   # GitHub Copilot CLI, if used
/plugin list          # Claude Code, inside Claude Code

Useful APM flags

# Preview without writing files
apm install mubaidr/gem-team --target copilot --dry-run

# Install only selected targets
apm install mubaidr/gem-team --target claude,cursor

# Install all supported harness targets
apm install mubaidr/gem-team --target all

# Exclude one target from auto-detection
apm install mubaidr/gem-team --exclude codex

# Reinstall from the existing apm.yml manifest
apm install

Compatible Tools

APM writes different files depending on the selected target and the primitives included in the package.

APM target	Tool / harness	Typical output
copilot	VS Code Copilot / GitHub Copilot CLI	.github/agents/, .github/instructions/, .github/prompts/, and VS Code MCP config when applicable.
claude	Claude Code	.claude/agents/, .claude/rules/, commands, skills, hooks, and MCP config when applicable.
cursor	Cursor	.cursor/agents/, .cursor/rules/, skills, commands, hooks, and MCP config when applicable.
opencode	OpenCode	.opencode/agents/, commands, skills, MCP, and compiled instructions.
codex	Codex CLI	.codex/agents/, AGENTS.md, and Codex config when applicable.
gemini	Gemini CLI	GEMINI.md, skills/instructions where supported, and Gemini config when applicable.
windsurf	Windsurf / Cascade	.windsurf/rules/, skills, commands, hooks, and MCP config where supported.

Some harnesses do not support every primitive. For example, not every tool has native agents, hooks, or project-scoped MCP. APM compiles or skips unsupported primitives according to the target.

Marketplace Installation

APM is the recommended installation path. Direct marketplace installs are optional and require this repository to publish the correct marketplace metadata for the target tool.

GitHub Copilot CLI

copilot plugin marketplace add mubaidr/gem-team
copilot plugin marketplace browse gem-team
copilot plugin install gem-team@gem-team

GitHub Copilot CLI also includes default marketplaces such as awesome-copilot; if Gem Team is published there, install it with:

copilot plugin install gem-team@awesome-copilot

Claude Code

/plugin marketplace add mubaidr/gem-team
/plugin
/plugin install gem-team@gem-team
/reload-plugins

Local Development

Clone the repository and install it into a test project:

git clone https://github.com/mubaidr/gem-team.git
cd gem-team
apm install . --target claude,cursor --dry-run

Then run a real install from the local path:

apm install /absolute/path/to/gem-team --target claude,cursor

For package authoring and release validation:

apm audit
apm compile --target copilot,claude,cursor --validate
apm pack

Configuration

Gem Team can be configured with .gem-team.yaml in your project root.

orchestrator:
  max_concurrent_agents: 2
  default_complexity_threshold: auto # auto | TRIVIAL | LOW | MEDIUM | HIGH
  git_commit_on_gate_pass: true

planning:
  enable_critic_for: [HIGH]

quality:
  visual_regression_enabled: true
  visual_diff_threshold: 0.95
  a11y_audit_level: basic # none | basic | full

devops:
  approval_required_for: [production]
  auto_rollback_on_failure: false

testing:
  screenshot_on_failure: true

Settings reference

Orchestrator

Setting	Type	Default	Description
orchestrator.max_concurrent_agents	number	2	Maximum parallel agent executions.
orchestrator.default_complexity_threshold	enum	auto	Force complexity routing: auto, TRIVIAL, LOW, MEDIUM, or HIGH.
orchestrator.git_commit_on_gate_pass	bool	true	Git commit wave output when integration gate passes.

Planning

Setting	Type	Default	Description
planning.enable_critic_for	enum[]	[HIGH]	Complexity levels that require critic validation.

Quality

Setting	Type	Default	Description
quality.visual_regression_enabled	boolean	true	Enable screenshot comparison checks.
quality.visual_diff_threshold	number	0.95	Visual comparison threshold from 0.0 to 1.0.
quality.a11y_audit_level	enum	basic	Accessibility audit depth: none, basic, or full.

DevOps

Setting	Type	Default	Description
devops.approval_required_for	enum[]	[production]	Environments that require explicit approval.
devops.auto_rollback_on_failure	boolean	false	Attempt rollback after deployment failure.

Testing

Setting	Type	Default	Description
testing.screenshot_on_failure	boolean	true	Capture screenshots when browser/UI tests fail.

A fully commented default file is available at .gem-team.yaml.

Operational Notes

• Prefer project-scoped installs for teams so apm.yml and apm.lock.yaml make the setup reproducible.
• Keep apm_modules/ out of git; it is an install cache.
• Pin releases with #vX.Y.Z for stable CI and team onboarding.
• Run apm audit before release and in CI.
• Review generated files before committing large updates.
• Treat DevOps, production deployment, data migration, and destructive operations as approval-gated tasks.
• Keep project rules in AGENTS.md; keep task-specific context in docs/plan/{plan_id}/.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Recommended contribution flow:

1. Open or pick an issue.
2. Create a focused branch.
3. Keep changes small and reviewable.
4. Add or update tests/docs where relevant.
5. Run validation before opening the PR.

License

Gem Team is licensed under the Apache License 2.0.

Support

If you encounter a bug or have a feature request, please open an issue.