# Gem Team

**Turn AI coding into an engineering process.**

> Agent definitions that enforce good software engineering: optimizing cost, time, and quality.

<p align="center">
  <a href="https://mubaidr.github.io/gem-team/"><b>Visit Homepage</b></a>
</p>

<br/>

<p align="center">
  <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>

## The Problem

Current AI coding is often one-off and ad-hoc. You get code, but you don't get a repeatable process. This leads to inconsistent quality, wasted tokens, and a lack of long-term learning.

## The Solution

Gem Team wraps your AI with a disciplined engineering delivery system. It enforces good software engineering practices automatically, so you get better results with less effort.

## Why Gem Team?

- **Quality by Default**: TDD and acceptance checks always apply; reviews and security audits run when risk requires them. No more "vibe coding" that breaks in production.
- **Smart & Efficient**: Optimized for fewer tokens and lower costs. Progressive context management prevents bloat and keeps your AI focused.
- **Works With Your Tools**: Seamless integration with Copilot, Claude, Cursor, Codex, Gemini, and Windsurf. Use your preferred environment.
- **Learns & Improves**: Remembers what works and extracts reusable skills. Your AI gets smarter and more efficient over time.

### Intelligent Model Routing

Gem Team automatically uses the right model for each kind of work:

- **Premium models** handle planning, debugging, and review where deeper reasoning matters.
- **Explore models** handle research, implementation, testing, documentation, and other bounded tasks efficiently.
- **Configurable tiers** let you choose the models and providers that fit your budget and workflow.

This gives you stronger verification where it matters without paying the highest model cost for every task. Configure it once in `.gem-team.yaml`:

```yaml
model_routing:
  enabled: true
  tiers:
    premium: "your-strong-model (provider)"
    explore: "your-fast-model (provider)"
```

**TL;DR:** Gem Team turns AI coding into a structured, repeatable engineering process with built-in quality, efficiency, and learning.

## Quick Start

Install [APM](https://microsoft.github.io/apm/) first:

```bash
# 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:

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

Or install for one target only:

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

Install globally for personal use:

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

APM records the resolved commit in `apm.lock.yaml`. Repeating `apm install`
replays that lockfile; it does not silently upgrade an existing installation.
Refresh Gem Team explicitly when desired:

```bash
# Project-scoped installation
apm update mubaidr/gem-team --yes

# Global installation
apm update -g mubaidr/gem-team --yes
```

To check for an update to the APM CLI itself, use `apm self-update --check`.

For reproducible environments, pin a release tag:

```bash
apm install 'mubaidr/gem-team#gem-team-v<version>' --target copilot
```

Replace `<version>` with a published version from the
[GitHub Releases](https://github.com/mubaidr/gem-team/releases) page.

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.
>
> Direct Git installs use the canonical sources in `.apm/`. Maintainers do not
> need to commit `build/`; release archives and checksums are generated and
> attached automatically to each GitHub Release.

## The Process

Gem Team uses a structured workflow to turn AI coding into a reliable engineering process:

1. **Route**: Classify the request from supplied evidence and select only the workflow depth it needs.
2. **Plan**: Use an in-memory DAG for TRIVIAL/LOW work or a persistent, planner-confirmed DAG for MEDIUM/HIGH work.
3. **Build**: Execute every DAG through the same dependency-aware loop, using TDD and specialist agents.
4. **Verify**: Check every task and run reviewer integration checks only when changed-scope risk requires them.
5. **Learn**: Promote only stable, high-confidence patterns after successful execution.

## Features

- **Risk-Based Quality Gates**: TDD and deterministic verification always apply; specialist reviews and audits run when the plan or changed scope requires them.
- **Effortless Context**: Progressive context management prevents bloat and keeps your AI focused.
- **Smart Routing**: Tasks are automatically routed to the right agents based on complexity.
- **Reusable Knowledge**: High-confidence patterns and skills are extracted and reused for future tasks.
- **Cost Efficiency**: Model routing and output hygiene ensure you only use the tokens you need.

## How it Works

Gem Team installs a set of specialized agents that work together under the guidance of an Orchestrator. This team follows a disciplined workflow that includes planning, implementation, verification, and learning.

- **Specialist Agents**: Dedicated agents for planning, research, implementation, review, and more.
- **Orchestration**: One DAG loop coordinates dependencies, parallel work, bounded retries, and final acceptance checks at every complexity level.
- **Context Management**: Execution agents receive an authoritative `task_definition`; constraints, evidence, and dependency outputs travel through its canonical `handoff`. Planner and reviewer use dedicated handoff contracts, and every delegate receives only a role-scoped configuration snapshot.

### Agent Roles

| Role                | Description                                                                               |
| :------------------ | :---------------------------------------------------------------------------------------- |
| **Orchestrator**    | Coordinates the workflow and ensures all tasks are completed correctly.                   |
| **Planner**         | Creates bounded DAG plans: milestones, routing, dependencies, waves, risks, and criteria. |
| **Implementer**     | Writes the code using TDD and best practices.                                             |
| **Reviewer**        | Reviews plans; provides read-only critique for ideas and challenges.                      |
| **Debugger**        | Diagnoses bugs with root-cause analysis (never implements fixes).                         |
| **Researcher**      | Explores the codebase and finds the best patterns to use.                                 |
| **Designer**        | Creates UI/UX designs, layouts, and design systems.                                       |
| **Tester**          | Runs E2E browser tests and visual regression.                                             |
| **Tester Mobile**   | Runs mobile E2E tests on iOS/Android simulators.                                          |
| **DevOps**          | Manages deployments, CI/CD, and infrastructure with approval gates.                       |
| **Documentation**   | Writes technical docs, API references, and walkthroughs.                                  |
| **Code Simplifier** | Refactors code to reduce complexity and remove dead code.                                 |
| **Skill Creator**   | Extracts reusable patterns into packaged agent skills.                                    |

## Compatible Tools

Gem Team works with your favorite AI coding tools:

| Tool         | Harness             | Description                          |
| :----------- | :------------------ | :----------------------------------- |
| **Copilot**  | `.github/agents/`   | VS Code Copilot / GitHub Copilot CLI |
| **Claude**   | `.claude/agents/`   | Claude Code                          |
| **Cursor**   | `.cursor/agents/`   | Cursor                               |
| **OpenCode** | `.opencode/agents/` | OpenCode                             |
| **Codex**    | `.codex/agents/`    | Codex CLI                            |
| **Gemini**   | `GEMINI.md`         | Gemini CLI                           |
| **Windsurf** | `.windsurf/rules/`  | Windsurf / Cascade                   |

## Configuration

Gem Team is designed to work out of the box with smart defaults. You can customize behavior by editing the `AGENTS.md` file or specific agent definitions in the `.apm/agents/` directory.

### Reviewer and critic modes

`gem-reviewer` uses three independent axes:

- `review_mode`: `standard`, `high`, or `critic` controls review intensity.
- `review_target`: `plan`, `task`, `code`, `decision`, `docs`, `config`, or `integration` selects what is reviewed.
- `review_scope`: `changed`, `affected`, or `full` limits the evidence breadth.

TRIVIAL/LOW work does not invoke the planner or reviewer during planning.
MEDIUM/HIGH work receives one pre-execution plan review: standard for MEDIUM,
high for HIGH or high-risk work, and critic for architecture, breaking-change,
or cross-domain signals. Later integration review is risk-triggered, not a
routine wave gate.

Discussion is answered directly. A requested evaluation or decision becomes a
read-only challenge with `review_mode: critic`, `review_target: decision`, and
`review_scope: full`. Critic mode does not mutate files or claim implementation.
Its subject and context are passed through `handoff`:

```yaml
review_mode: critic
review_target: decision
review_scope: full
handoff:
  critic_subject:
    objective: string
    proposal: string
    constraints: string[]
    alternatives: string[]
    evidence: string[]
    decision_needed: string
  critic_context:
    audience: string
    time_horizon: string
    success_criteria: string[]
    known_unknowns: string[]
```

## Learn More

- [Documentation](https://mubaidr.github.io/gem-team/)
- [Contributing](https://mubaidr.github.io/gem-team/5.resources/2.contributing.html)
- [License](LICENSE)

## Support

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