{"id":38948516,"url":"https://github.com/mubaidr/gem-team","last_synced_at":"2026-06-09T15:00:31.265Z","repository":{"id":332076413,"uuid":"1132659940","full_name":"mubaidr/gem-team","owner":"mubaidr","description":"Self-Learning Multi-agent orchestration framework for spec-driven development and automated verification.","archived":false,"fork":false,"pushed_at":"2026-06-06T22:32:13.000Z","size":1870,"stargazers_count":141,"open_issues_count":1,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-07T00:12:55.180Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mubaidr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":"mubaidr","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":"mubaidr","lfx_crowdfunding":null,"polar":"mubaidr","buy_me_a_coffee":"mubaidr","thanks_dev":null,"custom":null}},"created_at":"2026-01-12T09:20:28.000Z","updated_at":"2026-06-06T22:32:05.000Z","dependencies_parsed_at":"2026-02-11T19:01:53.097Z","dependency_job_id":null,"html_url":"https://github.com/mubaidr/gem-team","commit_stats":null,"previous_names":["mubaidr/gem-team"],"tags_count":48,"template":false,"template_full_name":null,"purl":"pkg:github/mubaidr/gem-team","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mubaidr%2Fgem-team","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mubaidr%2Fgem-team/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mubaidr%2Fgem-team/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mubaidr%2Fgem-team/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mubaidr","download_url":"https://codeload.github.com/mubaidr/gem-team/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mubaidr%2Fgem-team/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34112225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-01-17T16:06:52.968Z","updated_at":"2026-06-09T15:00:31.253Z","avatar_url":"https://github.com/mubaidr.png","language":null,"funding_links":["https://opencollective.com/mubaidr","https://issuehunt.io/r/mubaidr","https://polar.sh/mubaidr","https://buymeacoffee.com/mubaidr"],"categories":[],"sub_categories":[],"readme":"# Gem Team\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/APM-mubaidr/gem--team-blue?style=flat-square\" alt=\"APM package: mubaidr/gem-team\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/v/release/mubaidr/gem-team?style=flat-square\u0026color=important\" alt=\"Latest release\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square\" alt=\"Apache-2.0 license\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square\" alt=\"Pull requests welcome\"\u003e\n\u003c/p\u003e\n\nTurn AI coding into an orchestrated loop: plan, build, review, debug.\n\n\u003e Spec-driven multi-agent orchestration for software development, verification, debugging, and reusable project knowledge.\n\n**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.\n\n## Quick Start\n\nInstall [APM](https://microsoft.github.io/apm/) first:\n\n```bash\n# macOS / Linux\ncurl -sSL https://aka.ms/apm-unix | sh\n\n# Windows PowerShell\nirm https://aka.ms/apm-windows | iex\n\n# Verify\napm --version\n```\n\nInstall Gem Team into your current project:\n\n```bash\napm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf\n```\n\nOr install for one target only:\n\n```bash\napm install mubaidr/gem-team --target copilot\n```\n\nAfter 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/`.\n\n\u003e APM can auto-detect targets from existing harness directories, but explicit `--target` is recommended for predictable installs and fresh repositories.\n\n## Contents\n\n- [Why Gem Team?](#why-gem-team)\n- [Comparison](#comparison)\n- [Core Concepts](#core-concepts)\n- [Workflow](#workflow)\n- [The Agent Team](#the-agent-team)\n- [Installation](#installation)\n- [Compatible Tools](#compatible-tools)\n- [Configuration](#configuration)\n- [Operational Notes](#operational-notes)\n- [Contributing](#contributing)\n- [License](#license)\n- [Support](#support)\n\n## Why Gem Team?\n\n### Better delivery flow\n\n- **Spec-driven execution** — turns goals into scoped plans, tasks, checks, and evidence.\n- **Wave-based execution** — runs independent work in parallel while serializing true dependencies.\n- **Verification loops** — uses reviewers, testers, critics, and debuggers before final output.\n- **Resumable plans** — plan IDs, task artifacts, and context files make long tasks easier to pause, inspect, and continue.\n\n### Better code quality\n\n- **Specialist agents** — planning, implementation, debugging, review, testing, documentation, design, and DevOps are handled by focused roles.\n- **Pattern reuse** — researchers inspect the codebase first so agents follow existing architecture instead of inventing new patterns.\n- **Contract-first mindset** — encourages requirements, API contracts, tests, and acceptance criteria before implementation.\n- **Security-aware reviews** — reviewer and DevOps roles check for common security, secrets, PII, and deployment risks.\n\n### Better context management\n\n- **Context envelope** — stores the active project summary, constraints, architecture notes, task registry, prior decisions, and reusable findings.\n- **File-based knowledge** — important outputs are written to durable files instead of being trapped in a single chat turn.\n- **Skill extraction** — high-confidence repeated workflows can become reusable `SKILL.md` playbooks.\n- **Memory discipline** — durable learnings are persisted only when useful and sufficiently reliable.\n\n### Better cost control\n\n- **Model routing** — routine agents can use a fast cost-efficient model while planner, debugger, critic, and reviewer roles can use stronger reasoning models.\n- **Reduced redundant reading** — the context envelope and research digest prevent repeated source reads.\n- **Concise agent outputs** — agents are instructed to return actionable artifacts rather than verbose commentary.\n\n## Comparison\n\ngem-team is not trying to replace Copilot, Cursor, Claude Code, Cline, or Roo Code.\n\nIt focuses on the missing workflow layer:\n\n- planning\n- subagent delegation first policy for parallel work\n- context envelope for avoiding repeated source reads\n- reviewer/debugger loops\n- specialist agents\n- repeatable execution artifacts\n\nUse gem-team when you want AI coding to follow an engineering process instead of a single chat prompt.\n\nVibe with confident, structured delivery and durable knowledge instead of ad-hoc one-off outputs.\n\n## Core Concepts\n\n### System-IQ multiplier\n\nGem 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.\n\n### Knowledge layers\n\n| Layer              | Location                         | Purpose                                                                    |\n| :----------------- | :------------------------------- | :------------------------------------------------------------------------- |\n| **PRD**            | `docs/PRD.yaml`                  | Product requirements and approved decisions.                               |\n| **AGENTS.md**      | `AGENTS.md`                      | Stable project conventions, rules, and agent instructions.                 |\n| **Plan artifacts** | `docs/plan/{plan_id}/`           | Per-task plans, context envelopes, task registries, evidence, and results. |\n| **Memory**         | Memory tool / configured backend | Durable facts, decisions, gotchas, patterns, and failure modes.            |\n| **Skills**         | `docs/skills/`                   | Reusable procedures extracted from successful repeated workflows.          |\n| **Derived docs**   | `docs/knowledge/`                | Reference notes, external docs, summaries, and research outputs.           |\n\n## Workflow\n\n### Architecture Flow\n\n### Execution Model\n\nGem Team adapts workflow depth to task complexity:\n\n- **TRIVIAL:** direct execution with a tiny checklist.\n- **LOW:** lightweight in-memory planning and execution.\n- **MEDIUM/HIGH:** durable planning, context envelope, validation, wave execution, and integration review.\n\nThe system batches independent work, serializes only true dependencies, and persists high-confidence learnings for future runs.\n\n```text\nUser Input\n    ↓\nPhase 0: Init \u0026 Clarify\n    • Read provided context\n    • Load config and relevant memory\n    • Detect intent and plan state\n    • Classify complexity\n    • Ask only for blocking clarification\n    ↓\nPhase 1: Route\n    • Continue existing plan\n    • Revise existing plan\n    • Start new task\n    ↓\nPhase 2: Plan\n    • TRIVIAL → tiny checklist\n    • LOW → lightweight in-memory plan\n    • MEDIUM/HIGH → durable planner-generated plan\n    • Validate higher-risk plans before execution\n    ↓\nPhase 3: Execute\n    • Prepare context based on complexity\n    • Run unblocked work in waves\n    • Delegate tasks to suitable agents\n    • Respect dependencies and conflicts\n    • Review/integrate higher-risk waves\n    ↓\nLearn \u0026 Persist\n    • Save reusable decisions, patterns, gotchas, and skills\n    • Update memory, docs, PRD, AGENTS.md, or skills as appropriate\n    ↓\nLoop / Replan\n    • Continue next wave\n    • Replan if scope changes\n    • Escalate if blocked\n    ↓\nPhase 4: Output\n    • Present final status using configured output format\n```\n\n## The Agent Team\n\n### Recommended model routing\n\nUse a fast cost-efficient model as the default and reserve stronger reasoning models for tasks that need deeper analysis.\n\n| Role                                    | Example model                   | Recommended use                                                                                |\n| :-------------------------------------- | :------------------------------ | :--------------------------------------------------------------------------------------------- |\n| **Default agents**                      | `mimoi-2.5/deepseek-v4-flash`   | Routine implementation, documentation, research summaries, and simple checks.                  |\n| **Planner, Debugger, Critic, Reviewer** | `mimoi-2.5-pro/deepseek-v4-pro` | Planning, root-cause analysis, compliance checks, critical review, and high-risk verification. |\n\nReplace these with equivalent models from your own provider if needed.\n\n### Core agents\n\n| Agent            | Description                                                                              |\n| :--------------- | :--------------------------------------------------------------------------------------- |\n| **ORCHESTRATOR** | Coordinates the workflow, delegates work, tracks plans, and enforces verification gates. |\n| **RESEARCHER**   | Explores the codebase, dependencies, architecture, existing patterns, and relevant docs. |\n| **PLANNER**      | Creates DAG-based execution plans, task waves, risk notes, and acceptance criteria.      |\n| **IMPLEMENTER**  | Implements features, fixes, refactors, and tests according to the approved plan.         |\n\n### Quality and review\n\n| Agent               | Description                                                                                 |\n| :------------------ | :------------------------------------------------------------------------------------------ |\n| **REVIEWER**        | Reviews implementation quality, security, maintainability, contracts, and test coverage.    |\n| **CRITIC**          | Challenges assumptions, finds edge cases, and flags over-engineering or missed constraints. |\n| **DEBUGGER**        | Performs root-cause analysis, regression tracing, and targeted fix planning.                |\n| **BROWSER TESTER**  | Runs browser/E2E checks, validates UI behavior, and captures visual evidence.               |\n| **CODE SIMPLIFIER** | Removes dead code, reduces complexity, and improves maintainability.                        |\n\n### Specialized agents\n\n| Agent                  | Description                                                                                   |\n| :--------------------- | :-------------------------------------------------------------------------------------------- |\n| **DEVOPS**             | Handles deployment, CI/CD, infrastructure, containers, health checks, and rollback planning.  |\n| **DOCUMENTATION**      | Writes technical docs, READMEs, API docs, diagrams, and plan artifacts.                       |\n| **DESIGNER**           | Produces UI/UX guidance, layouts, interaction notes, visual polish, and accessibility checks. |\n| **IMPLEMENTER-MOBILE** | Implements native mobile work for React Native, Expo, Flutter, iOS, or Android.               |\n| **DESIGNER-MOBILE**    | Reviews mobile UX using platform conventions, safe areas, and accessibility requirements.     |\n| **MOBILE TESTER**      | Runs mobile E2E and device testing workflows such as Detox, Maestro, iOS, or Android checks.  |\n| **SKILL CREATOR**      | Extracts reusable `SKILL.md` files from repeated high-confidence workflows.                   |\n\n## Installation\n\n### 1. Install APM\n\n```bash\n# macOS / Linux\ncurl -sSL https://aka.ms/apm-unix | sh\n\n# Windows PowerShell\nirm https://aka.ms/apm-windows | iex\n\n# Verify\napm --version\n```\n\n### 2. Install Gem Team\n\nProject-scoped install, recommended for teams:\n\n```bash\napm install mubaidr/gem-team --target copilot,claude,cursor,opencode,codex,gemini,windsurf\n```\n\nGlobal user-scoped install, useful for personal use:\n\n```bash\napm install -g mubaidr/gem-team\n```\n\nPin a release for reproducible installs:\n\n```bash\napm install mubaidr/gem-team#v1.20.0 --target copilot\n```\n\n### 3. Verify the install\n\n```bash\napm list\napm view mubaidr/gem-team\napm audit\n```\n\nTool-specific checks:\n\n```bash\ncopilot plugin list   # GitHub Copilot CLI, if used\n/plugin list          # Claude Code, inside Claude Code\n```\n\n### Useful APM flags\n\n```bash\n# Preview without writing files\napm install mubaidr/gem-team --target copilot --dry-run\n\n# Install only selected targets\napm install mubaidr/gem-team --target claude,cursor\n\n# Install all supported harness targets\napm install mubaidr/gem-team --target all\n\n# Exclude one target from auto-detection\napm install mubaidr/gem-team --exclude codex\n\n# Reinstall from the existing apm.yml manifest\napm install\n```\n\n## Compatible Tools\n\nAPM writes different files depending on the selected target and the primitives included in the package.\n\n| APM target | Tool / harness                       | Typical output                                                                                          |\n| :--------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------ |\n| `copilot`  | VS Code Copilot / GitHub Copilot CLI | `.github/agents/`, `.github/instructions/`, `.github/prompts/`, and VS Code MCP config when applicable. |\n| `claude`   | Claude Code                          | `.claude/agents/`, `.claude/rules/`, commands, skills, hooks, and MCP config when applicable.           |\n| `cursor`   | Cursor                               | `.cursor/agents/`, `.cursor/rules/`, skills, commands, hooks, and MCP config when applicable.           |\n| `opencode` | OpenCode                             | `.opencode/agents/`, commands, skills, MCP, and compiled instructions.                                  |\n| `codex`    | Codex CLI                            | `.codex/agents/`, `AGENTS.md`, and Codex config when applicable.                                        |\n| `gemini`   | Gemini CLI                           | `GEMINI.md`, skills/instructions where supported, and Gemini config when applicable.                    |\n| `windsurf` | Windsurf / Cascade                   | `.windsurf/rules/`, skills, commands, hooks, and MCP config where supported.                            |\n\n\u003e 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.\n\n## Marketplace Installation\n\nAPM is the recommended installation path. Direct marketplace installs are optional and require this repository to publish the correct marketplace metadata for the target tool.\n\n### GitHub Copilot CLI\n\n```bash\ncopilot plugin marketplace add mubaidr/gem-team\ncopilot plugin marketplace browse gem-team\ncopilot plugin install gem-team@gem-team\n```\n\nGitHub Copilot CLI also includes default marketplaces such as `awesome-copilot`; if Gem Team is published there, install it with:\n\n```bash\ncopilot plugin install gem-team@awesome-copilot\n```\n\n### Claude Code\n\n```bash\n/plugin marketplace add mubaidr/gem-team\n/plugin\n/plugin install gem-team@gem-team\n/reload-plugins\n```\n\n## Local Development\n\nClone the repository and install it into a test project:\n\n```bash\ngit clone https://github.com/mubaidr/gem-team.git\ncd gem-team\napm install . --target claude,cursor --dry-run\n```\n\nThen run a real install from the local path:\n\n```bash\napm install /absolute/path/to/gem-team --target claude,cursor\n```\n\nFor package authoring and release validation:\n\n```bash\napm audit\napm compile --target copilot,claude,cursor --validate\napm pack\n```\n\n## Configuration\n\nGem Team can be configured with `.gem-team.yaml` in your project root.\n\n```yaml\norchestrator:\n  max_concurrent_agents: 2\n  default_complexity_threshold: auto # auto | TRIVIAL | LOW | MEDIUM | HIGH\n\nplanning:\n  enable_critic_for: [HIGH]\n\nquality:\n  visual_regression_enabled: true\n  visual_diff_threshold: 0.95\n  a11y_audit_level: basic # none | basic | full\n\ndevops:\n  approval_required_for: [production]\n  auto_rollback_on_failure: false\n\ntesting:\n  screenshot_on_failure: true\n```\n\n### Settings reference\n\n#### Orchestrator\n\n| Setting                                     | Type   | Default | Description                                                              |\n| :------------------------------------------ | :----- | :------ | :----------------------------------------------------------------------- |\n| `orchestrator.max_concurrent_agents`        | number | `2`     | Maximum parallel agent executions.                                       |\n| `orchestrator.default_complexity_threshold` | enum   | `auto`  | Force complexity routing: `auto`, `TRIVIAL`, `LOW`, `MEDIUM`, or `HIGH`. |\n\n#### Planning\n\n| Setting                      | Type   | Default  | Description                                       |\n| :--------------------------- | :----- | :------- | :------------------------------------------------ |\n| `planning.enable_critic_for` | enum[] | `[HIGH]` | Complexity levels that require critic validation. |\n\n#### Quality\n\n| Setting                             | Type    | Default | Description                                            |\n| :---------------------------------- | :------ | :------ | :----------------------------------------------------- |\n| `quality.visual_regression_enabled` | boolean | `true`  | Enable screenshot comparison checks.                   |\n| `quality.visual_diff_threshold`     | number  | `0.95`  | Visual comparison threshold from `0.0` to `1.0`.       |\n| `quality.a11y_audit_level`          | enum    | `basic` | Accessibility audit depth: `none`, `basic`, or `full`. |\n\n#### DevOps\n\n| Setting                           | Type    | Default        | Description                                  |\n| :-------------------------------- | :------ | :------------- | :------------------------------------------- |\n| `devops.approval_required_for`    | enum[]  | `[production]` | Environments that require explicit approval. |\n| `devops.auto_rollback_on_failure` | boolean | `false`        | Attempt rollback after deployment failure.   |\n\n#### Testing\n\n| Setting                         | Type    | Default | Description                                     |\n| :------------------------------ | :------ | :------ | :---------------------------------------------- |\n| `testing.screenshot_on_failure` | boolean | `true`  | Capture screenshots when browser/UI tests fail. |\n\nA fully commented default file is available at [`.gem-team.yaml`](.gem-team.yaml).\n\n## Operational Notes\n\n- Prefer project-scoped installs for teams so `apm.yml` and `apm.lock.yaml` make the setup reproducible.\n- Keep `apm_modules/` out of git; it is an install cache.\n- Pin releases with `#vX.Y.Z` for stable CI and team onboarding.\n- Run `apm audit` before release and in CI.\n- Review generated files before committing large updates.\n- Treat DevOps, production deployment, data migration, and destructive operations as approval-gated tasks.\n- Keep project rules in `AGENTS.md`; keep task-specific context in `docs/plan/{plan_id}/`.\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.\n\nRecommended contribution flow:\n\n1. Open or pick an issue.\n2. Create a focused branch.\n3. Keep changes small and reviewable.\n4. Add or update tests/docs where relevant.\n5. Run validation before opening the PR.\n\n## License\n\nGem Team is licensed under the [Apache License 2.0](./LICENSE).\n\n## Support\n\nIf you encounter a bug or have a feature request, please [open an issue](https://github.com/mubaidr/gem-team/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmubaidr%2Fgem-team","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmubaidr%2Fgem-team","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmubaidr%2Fgem-team/lists"}