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

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

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.

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.

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

• 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.

• 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.

• 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.

• 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.

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.

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.

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

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

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

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

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

# Verify
apm --version

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

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

# 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

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

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.

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.

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

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

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

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

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

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

• 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}/.

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.

Gem Team is licensed under the Apache License 2.0.

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