Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-06-13 19:34:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(deps, docs): bump marketplace version to 1.46.0 (#1877)

Browse Source 
* chore(deps, docs): bump marketplace version to 1.46.0

- Refine execution priority guidance in agent documentation
- Imrpvoe discovery guidance
- Improve context cache guidance
- Add script usage guidelines to agent documentation
- Simplify agent input references

* feat: bump marketplace version to 1.47.0 and enhance agent workflows

- Add Bug‑Fix Mode with validation gate for `debugger_diagnosis` tasks
- Expand allowed task types to include `research`
- Reduce subagent concurrency limit from 4 to 2
- Update design validation handling for flagged tasks
- Update marketplace plugin version reference to 1.47.0

* chore: bump marketplace version to 1.48.0 and refine agent context envelope workflow documentation

- Enhance the Init section in gem-browser-tester.agent.md, gem-code-simplifier.agent.md, and gem-critic.agent.md with detailed context envelope handling, active context treatment, and reuse_notes trust/verification logic.
- Add explicit steps for safe assumption, verification before use, and controlled re‑reading of context notes.

* chore: refine verification of symbol usages before modifying shared components

* chore(marketplace): bump version to 1.50.0; refactor(gem-browser-tester): simplify workflow steps

* chore(docs): simplify Phase 0 task classification and streamline initialization

* chore: Merges teps for batching

* feat: Enhcanc esuport for trivial/ low complex tasks

* chore: bump version to 1.56.0 and add config settings for visual regression, devops approvals, and orchestrator complexity

* chore: fix toc links

* chore: Remove emojis from headings

* chore: Update readme

* chore: Enforce orchestration

* chore: clarify orchestrator role and bump version to 1.59.0

* chore: bump version to 1.61.0 and refine agent documentation
This commit is contained in:
Muhammad Ubaid Raza
2026-06-10 09:34:29 +05:00
committed by GitHub
parent 21e2d9f0d6
commit 33c3ac8935
19 changed files with 1279 additions and 1504 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/gem-team/.github/plugin/plugin.json
Vendored
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "gem-team",
"version": "1.42.0",
"version": "1.61.0",
"description": "Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.",
"author": {
"name": "mubaidr",
plugins/gem-team/README.md
+322 -271
View File
@@ -1,400 +1,451 @@
<p align="center">
<svg width="120" height="120" viewBox="0 0 36 36" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Gem Team Logo">
<g fill="none" fill-rule="evenodd">
<path fill="#BDDDF4" d="M13 3H7l-7 9h10z"/>
<path fill="#5DADEC" d="M36 12l-7-9h-6l3 9z"/>
<path fill="#4289C1" d="M26 12h10L18 33z"/>
<path fill="#8CCAF7" d="M10 12H0l18 21zm3-9l-3 9h16l-3-9z"/>
<path fill="#5DADEC" d="M18 33l-8-21h16z"/>
</g>
</svg>
</p>
# Gem Team
<p align="center">
<img src="https://img.shields.io/badge/APM-mubaidr/gem--team-blue?style=flat-square" alt="APM">
<img src="https://img.shields.io/github/v/release/mubaidr/gem-team?style=flat-square&color=important" alt="Version">
<img src="https://img.shields.io/badge/License-Apache%202.0-green?style=flat-square" alt="License">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome">
<img src="https://img.shields.io/badge/Maintained%3F-yes-green?style=flat-square" alt="Maintained">
<img src="https://img.shields.io/badge/APM-mubaidr/gem--team-blue?style=flat-square" alt="APM package: mubaidr/gem-team">
<img src="https://img.shields.io/github/v/release/mubaidr/gem-team?style=flat-square&color=important" alt="Latest release">
<img src="https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square" alt="Apache-2.0 license">
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="Pull requests welcome">
</p>
Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.
Turn AI coding into an orchestrated loop: plan, build, review, debug.
> **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.
> Spec-driven multi-agent orchestration for software development, verification, debugging, and reusable project knowledge.
> **Recommended Models:** Use a cost-efficient fast model as the default, and a stronger reasoning model for planner/debugger/critical review agents, e.g. `default=deepseek-v4-flash`, `planner,debugger,critic/reviewer=deepseek-v4-pro`. This gives you **80-90%** cost savings without sacrificing quality on complex tasks.
**TL;DR:** Gem Team installs a coordinated set of specialist AI agents for planning, implementation, review, debugging, testing, documentation, design, DevOps, and skill extraction. It is designed for structured software delivery: clarify the goal, discover existing patterns, plan the work, execute in controlled waves, verify results, and persist useful learnings.
> **Crafted from years of personal experience** — This framework is shaped by real-world usage patterns, battle-tested and refined through countless hours of hands-on development workflows.
## Quick Start
## 🚀 Quick Start
Install [APM](https://microsoft.github.io/apm/) first:
```bash
apm install -g mubaidr/gem-team
# macOS / Linux
curl -sSL https://aka.ms/apm-unix | sh
# Windows PowerShell
irm https://aka.ms/apm-windows | iex
# Verify
apm --version
```
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.
Install Gem Team into your current project:
See [all supported installation options](#installation) below.
```bash
apm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf
```
---
Or install for one target only:
## 📚 Contents
```bash
apm install mubaidr/gem-team --target copilot
```
- [🚀 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)
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.
## 🎯 Why Gem Team?
## Contents
### Performance
- [Why Gem Team?](#why-gem-team)
- [Comparison](#comparison)
- [Core Concepts](#core-concepts)
- [Workflow](#workflow)
- [The Agent Team](#the-agent-team)
- [Installation](#installation)
- [Compatible Tools](#compatible-tools)
- [Configuration](#configuration)
- [Operational Notes](#operational-notes)
- [Contributing](#contributing)
- [License](#license)
- [Support](#support)
- **4x Faster** — Parallel execution with wave-based execution
- **Pattern Reuse** — Codebase pattern discovery prevents reinventing wheels
## Why Gem Team?
### Quality & Security
### Better delivery flow
- **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
- **Spec-driven execution** — turns goals into scoped plans, tasks, checks, and evidence.
- **Wave-based execution** — runs independent work in parallel while serializing true dependencies.
- **Verification loops** — uses reviewers, testers, critics, and debuggers before final output.
- **Resumable plans** — plan IDs, task artifacts, and context files make long tasks easier to pause, inspect, and continue.
### Intelligence
### Better code quality
- **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
- **Specialist agents** — planning, implementation, debugging, review, testing, documentation, design, and DevOps are handled by focused roles.
- **Pattern reuse** — researchers inspect the codebase first so agents follow existing architecture instead of inventing new patterns.
- **Contract-first mindset** — encourages requirements, API contracts, tests, and acceptance criteria before implementation.
- **Security-aware reviews** — reviewer and DevOps roles check for common security, secrets, PII, and deployment risks.
### Process
### Better context management
- **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)
- **Context envelope** — stores the active project summary, constraints, architecture notes, task registry, prior decisions, and reusable findings.
- **File-based knowledge** — important outputs are written to durable files instead of being trapped in a single chat turn.
- **Skill extraction** — high-confidence repeated workflows can become reusable `SKILL.md` playbooks.
- **Memory discipline** — durable learnings are persisted only when useful and sufficiently reliable.
### Token Efficiency
### Better cost control
Optimized for reduced LLM token consumption without quality loss:
- **Model routing** — routine agents can use a fast cost-efficient model while planner, debugger, critic, and reviewer roles can use stronger reasoning models.
- **Reduced redundant reading** — the context envelope and research digest prevent repeated source reads.
- **Concise agent outputs** — agents are instructed to return actionable artifacts rather than verbose commentary.
- **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
## Comparison
### Design
gem-team is not trying to replace Copilot, Cursor, Claude Code, Cline, or Roo Code.
- **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
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
## 🧠 Core Concepts
Use gem-team when you want AI coding to follow an engineering process instead of a single chat prompt.
### The "System-IQ" Multiplier
Vibe with confident, structured delivery and durable knowledge instead of ad-hoc one-off outputs.
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.
## Core Concepts
### Knowledge Layers
### System-IQ multiplier
| Type | Storage | 1-liner |
| :--------------- | :---------------- | :------------------------------------------------------------------------------------------------------- |
| **PRD** | `docs/PRD.yaml` | Product requirements spec — drives agent planning, implementation, and verification |
| **AGENTS.md** | `AGENTS.md` | Static conventions, rules, and agent definitions (requires approval) |
| **Memory** | memory tool | Facts, preferences, research, diagnoses, decisions, patterns — self-validated and reused across sessions |
| **Skills** | `docs/skills/` | Reusable procedures with code examples, extracted from high-confidence patterns |
| **Derived Docs** | `docs/knowledge/` | Online documentation, LLM-generated text, and reference materials |
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
Agents build these knowledge layers over time while working with you, capturing patterns, decisions, and learnings that improve future execution.
| 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. |
## 🏗️ Architecture
## 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.
```text
User Goal
↓
Orchestrator
User Input
↓
Phase 0: Init & Clarify
• Generate/load plan_id
• Read memory, detect effort (LOW/MEDIUM/HIGH)
• Route to appropriate path
• Read provided context
• Load config and relevant memory
• Detect intent and plan state
• Classify complexity
• Ask only for blocking clarification
↓
Phase 1: Route
• Routing matrix based on effort, task type, and context
• Continue existing plan
• Revise existing plan
• Start new task
↓
Phase 2: Planning
• Delegate to planner
• Validation: MEDIUM (reviewer) / HIGH (reviewer+critic)
• Loop on failure (max 3x)
• Present for approval if HIGH
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: Execution Loop
Pre-Wave: Check memory for failure_modes/gotchas → add guards
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
↓
┌─ Wave Execution ──────────────┐
│ • Delegate tasks (≤4 concurrent)│
└─────────────┬─────────────────┘
↓
┌─ Integration Check ──────────┐
│ • Reviewer(wave) │
│ • UI: Designer(validate) │
│ • If fail: Debugger → retry │
└─────────────┬─────────────────┘
↓
┌─ Phase 4: Persist Learnings ─┐
│ • Collect & merge learnings │
│ • Memory (deduped) │
│ • Context Envelope update │
│ • Conventions → AGENTS.md │
│ • Decisions → PRD │
│ • Skills extraction │
└─────────────┬─────────────────┘
↓
Next wave? → No → Phase 5
│Yes
└─────────────────┘
Learn & Persist
• Save reusable decisions, patterns, gotchas, and skills
• Update memory, docs, PRD, AGENTS.md, or skills as appropriate
↓
Phase 5: Output
• Present final status
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
## 👥 The Agent Team
### Recommended model routing
### Core Agents
Use a fast cost-efficient model as the default and reserve stronger reasoning models for tasks that need deeper analysis.
| Agent | Description | Sources |
| :--------------- | :------------------------------------------------------------------------------- | :----------------------------- |
| **ORCHESTRATOR** | The team lead: Orchestrates research, planning, implementation, and verification | PRD, AGENTS.md |
| **RESEARCHER** | Codebase exploration — patterns, dependencies, architecture discovery | PRD, codebase, AGENTS.md, docs |
| **PLANNER** | DAG-based execution plans — task decomposition, wave scheduling, risk analysis | PRD, codebase, AGENTS.md |
| **IMPLEMENTER** | TDD code implementation — features, bugs, refactoring. Never reviews own work | codebase, AGENTS.md, DESIGN.md |
| 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. |
### Quality & Review
Replace these with equivalent models from your own provider if needed.
| Role | Description | Sources |
| :----------------- | :------------------------------------------------------------------------------- | :------------------------------- |
| **REVIEWER** | **Zero- Hallucination Filter** — Security auditing, code review, OWASP scanning | PRD, codebase, AGENTS.md, OWASP |
| **CRITIC** | Challenges assumptions, finds edge cases, spots over- engineering and logic gaps | PRD, codebase, AGENTS.md |
| **DEBUGGER** | Root-cause analysis, stack trace diagnosis, regression bisection | codebase, AGENTS.md, git history |
| **BROWSER TESTER** | E2E browser testing, UI/UX validation, visual regression | PRD, AGENTS.md, fixtures |
| **SIMPLIFIER** | Refactoring specialist — removes dead code, reduces complexity | codebase, AGENTS.md, tests |
### Core agents
### Skill Management
| Agent | Description |
| :--------------- | :--------------------------------------------------------------------------------------- |
| **ORCHESTRATOR** | Coordinates the workflow, delegates work, tracks plans, and enforces verification gates. |
| **RESEARCHER** | Explores the codebase, dependencies, architecture, existing patterns, and relevant docs. |
| **PLANNER** | Creates DAG-based execution plans, task waves, risk notes, and acceptance criteria. |
| **IMPLEMENTER** | Implements features, fixes, refactors, and tests according to the approved plan. |
| Role | Description | Sources |
| :---------------- | :---------------------------------------------------------------------------------- | :----------------------------------- |
| **SKILL CREATOR** | Pattern-to-skill extraction — creates SKILL.md files from high-confidence learnings | AGENTS.md, Memory patterns, SKILL.md |
### Quality and review
### Specialized
| Agent | Description |
| :------------------ | :------------------------------------------------------------------------------------------ |
| **REVIEWER** | Reviews implementation quality, security, maintainability, contracts, and test coverage. |
| **CRITIC** | Challenges assumptions, finds edge cases, and flags over-engineering or missed constraints. |
| **DEBUGGER** | Performs root-cause analysis, regression tracing, and targeted fix planning. |
| **BROWSER TESTER** | Runs browser/E2E checks, validates UI behavior, and captures visual evidence. |
| **CODE SIMPLIFIER** | Removes dead code, reduces complexity, and improves maintainability. |
| Role | Description | Sources |
| :--------------------- | :--------------------------------------------------------------- | :----------------------- |
| **DEVOPS** | Infrastructure deployment, CI/CD pipelines, container management | AGENTS.md, infra configs |
| **DOCUMENTATION** | Technical documentation, README files, API docs, diagrams | AGENTS.md, source code |
| **DESIGNER** | UI/UX design — layouts, themes, color schemes, accessibility | PRD, codebase, AGENTS.md |
| **IMPLEMENTER-MOBILE** | Mobile implementation — React Native, Expo, Flutter | codebase, AGENTS.md |
| **DESIGNER-MOBILE** | Mobile UI/UX — HIG, Material Design, safe areas | PRD, codebase, AGENTS.md |
| **MOBILE TESTER** | Mobile E2E testing — Detox, Maestro, iOS/Android | PRD, AGENTS.md |
### Specialized agents
---
| Agent | Description |
| :--------------------- | :-------------------------------------------------------------------------------------------- |
| **DEVOPS** | Handles deployment, CI/CD, infrastructure, containers, health checks, and rollback planning. |
| **DOCUMENTATION** | Writes technical docs, READMEs, API docs, diagrams, and plan artifacts. |
| **DESIGNER** | Produces UI/UX guidance, layouts, interaction notes, visual polish, and accessibility checks. |
| **IMPLEMENTER-MOBILE** | Implements native mobile work for React Native, Expo, Flutter, iOS, or Android. |
| **DESIGNER-MOBILE** | Reviews mobile UX using platform conventions, safe areas, and accessibility requirements. |
| **MOBILE TESTER** | Runs mobile E2E and device testing workflows such as Detox, Maestro, iOS, or Android checks. |
| **SKILL CREATOR** | Extracts reusable `SKILL.md` files from repeated high-confidence workflows. |
## 📦 Installation
## Installation
### Install APM First
If you don't have APM installed, install it first:
### 1. Install APM
```bash
# macOS/Linux
curl -fsSL https://microsoft.github.io/apm/install.sh | sh
# macOS / Linux
curl -sSL https://aka.ms/apm-unix | sh
# Windows (PowerShell)
irm https://microsoft.github.io/apm/install.ps1 | iex
# Windows PowerShell
irm https://aka.ms/apm-windows | iex
# Or via npm
npm install -g @microsoft/apm
# Verify
apm --version
```
**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.
### 2. Install Gem Team
[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:
Project-scoped install, recommended for teams:
```bash
apm install mubaidr/gem-team
apm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf
```
#### Useful Flags
Global user-scoped install, useful for personal use:
```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
Pin a release for reproducible installs:
```bash
apm install mubaidr/gem-team#v1.20.0 --target copilot
```
### 3. Verify the install
```bash
apm list
apm view mubaidr/gem-team
apm audit
```
Tool-specific checks:
```bash
copilot plugin list # GitHub Copilot CLI, if used
/plugin list # Claude Code, inside Claude Code
```
### Useful APM flags
```bash
# 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
```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)
GitHub Copilot CLI also includes default marketplaces such as `awesome-copilot`; if Gem Team is published there, install it with:
```bash
copilot plugin install gem-team@awesome-copilot
```
#### Claude Code
### Claude Code
```bash
# Add marketplace
/plugin marketplace add mubaidr/gem-team
# Browse
/plugin
# Install
/plugin install gem-team@gem-team
/reload-plugins
```
#### Cursor IDE
## Local Development
```bash
apm marketplace add mubaidr/gem-team
apm install gem-team@gem-team
```
---
### Local / Manual Installation
For development, testing, or offline use.
Clone the repository and install it into a test project:
```bash
git clone https://github.com/mubaidr/gem-team.git
cd gem-team
apm install . --target claude,cursor --dry-run
```
#### Claude Code
Then run a real install from the local path:
```bash
claude --plugin-dir .
# Or: /plugin marketplace add ./
apm install /absolute/path/to/gem-team --target claude,cursor
```
#### Cursor IDE
For package authoring and release validation:
```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 ../..
apm audit
apm compile --target copilot,claude,cursor --validate
apm pack
```
#### GitHub Copilot CLI
## Configuration
```bash
copilot plugin marketplace add /absolute/path/to/gem-team
copilot plugin install gem-team@gem-team
Gem Team can be configured with `.gem-team.yaml` in your project root.
```yaml
orchestrator:
max_concurrent_agents: 2
default_complexity_threshold: auto # auto | TRIVIAL | LOW | MEDIUM | HIGH
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
```
#### Any Tool (Manual Copy)
### Settings reference
```bash
cp -r .apm/agents <destination>
# Destinations:
# VS Code / Copilot CLI → ~/.copilot/
# Claude Code → ~/.claude/plugins/
# Cursor → .cursor/rules/
# OpenCode → .opencode/plugins/
```
#### 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`. |
### Verification
#### Planning
After installation, confirm your setup:
| Setting | Type | Default | Description |
| :--------------------------- | :----- | :------- | :------------------------------------------------ |
| `planning.enable_critic_for` | enum[] | `[HIGH]` | Complexity levels that require critic validation. |
```bash
# Preview which tools APM detects
apm targets
#### Quality
# List installed packages
apm list
| 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`. |
# View package details
apm view gem-team
#### DevOps
# Tool-specific checks
copilot plugin list # GitHub Copilot CLI
/plugin list # Claude Code
```
| 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. |
## 🤝 Contributing
#### Testing
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.
| Setting | Type | Default | Description |
| :------------------------------ | :------ | :------ | :---------------------------------------------- |
| `testing.screenshot_on_failure` | boolean | `true` | Capture screenshots when browser/UI tests fail. |
## 📄 License
A fully commented default file is available at [`.gem-team.yaml`](.gem-team.yaml).
This project is licensed under the Apache License 2.0.
## Operational Notes
## 💬 Support
- 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}/`.
If you encounter any issues or have questions, please [open an issue](https://github.com/mubaidr/gem-team/issues) on GitHub.
## Contributing
Contributions are welcome. Please read [CONTRIBUTING.md](./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](./LICENSE).
## Support
If you encounter a bug or have a feature request, please [open an issue](https://github.com/mubaidr/gem-team/issues).