Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-04-11 02:35:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

[gem-team] Introduce specialized skills and guidelines to agents (#1271)

Browse Source 
* feat(orchestrator): add Discuss Phase and PRD creation workflow

- Introduce Discuss Phase for medium/complex objectives, generating context‑aware options and logging architectural decisions
- Add PRD creation step after discussion, storing the PRD in docs/prd.yaml
- Refactor Phase 1 to pass task clarifications to researchers
- Update Phase 2 planning to include multi‑plan selection for complex tasks and verification with gem‑reviewer
- Enhance Phase 3 execution loop with wave integration checks and conflict filtering

* feat(gem-team): bump version to 1.3.3 and refine description with Discuss Phase and PRD compliance verification

* chore(release): bump marketplace version to 1.3.4

- Update `marketplace.json` version from `1.3.3` to `1.3.4`.
- Refine `gem-browser-tester.agent.md`:
  - Replace "UUIDs" typo with correct spelling.
  - Adjust wording and formatting for clarity.
  - Update JSON code fences to use ````jsonc````.
  - Modify workflow description to reference `AGENTS.md` when present.
- Refine `gem-devops.agent.md`:
  - Align expertise list formatting.
  - Standardize tool list syntax with back‑ticks.
  - Minor wording improvements.
- Increase retry attempts in `gem-browser-tester.agent.md` from 2 to 3 attempts.
- Minor typographical and formatting corrections across agent documentation.

* refactor: rename prd_path to project_prd_path in agent configurations

- Updated gem-orchestrator.agent.md to use `project_prd_path` instead of `prd_path` in task definitions and delegation logic.
- Updated gem-planner.agent.md to reference `project_prd_path` and clarify PRD reading.
- Updated gem-researcher.agent.md to use `project_prd_path` and adjust PRD consumption logic.
- Applied minor wording improvements and consistency fixes across the orchestrator, planner, and researcher documentation.

* feat(plugin): expand marketplace description, bump version to 1.4.0; revamp gem-browser-tester agent documentation with clearer role, expertise, and workflow specifications.

* chore: remove outdated plugin metadata fields from README.plugins.md and plugin.json

* feat(tooling): bump marketplace version to 1.5.0 and refine validation thresholds

- Update marketplace.json version from 1.4.0 to 1.5.0
- Adjust validation criteria in gem-browser-tester.agent.md to trigger additional tests when coverage < 0.85 or confidence < 0.85
- Refine accessibility compliance description, adding runtime validation and SPEC‑based accessibility notes- Add new gem-code-simplifier.agent.md documentation for code refactoring
- Update README and plugin metadata to reflect version change and new tooling

* docs: improve bug‑fix delegation description and delegation‑first guidance in gem‑orchestrator.agent.md

- Clarified the two‑step diagnostic‑then‑fix flow for bug fixes using gem‑debugger and gem‑implementer.
- Updated the “Delegation First” checklist to stress that **no** task, however small, should be performed directly by the orchestrator, emphasizing sub‑agent delegation and retry/escalation strategy.

* feat(gem-browser-tester): add flow testing support and refine workflow

- Update description to include “flow testing” and “user journey” among triggers.
- Expand expertise list to cover flow testing and visual regression.
- Revise knowledge sources and workflow to detail initialization, setup, flow execution, and teardown.
- Introduce comprehensive step types (navigate, interact, assert, branch, extract, wait, screenshot) with explicit wait strategies.
- Implement baseline screenshot comparison for visual regression.
- Restructure execution pattern to manage flow context and multi‑step user journeys.

* feat: add performance, design, responsive checks

* feat(styling): add priority-based styling hierarchy and validation rules

* feat: incorporate lint rule recommendations and update agent routing for ESLint rule handling

* chore(release): bump marketplace version to 1.5.4

* docs: Simplify readme

* chore: Add mobile specific agents and disable user invocation flags

* feat(architecture): add mobile agents and refactor diagram

* feat(readme): add recommended LLM column to agent team roles

* docs: Update readme

---------

Co-authored-by: Aaron Powell <me@aaron-powell.com>
This commit is contained in:
Muhammad Ubaid Raza
2026-04-09 07:17:20 +05:00
committed by GitHub
parent e1f966dd8c
commit 46bef1b61a
20 changed files with 2633 additions and 1588 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
plugins/gem-team/.github/plugin/plugin.json vendored
View File

@@ -11,26 +11,29 @@
"./agents/gem-debugger.md",
"./agents/gem-critic.md",
"./agents/gem-code-simplifier.md",
"./agents/gem-designer.md"
"./agents/gem-designer.md",
"./agents/gem-implementer-mobile.md",
"./agents/gem-designer-mobile.md",
"./agents/gem-mobile-tester.md"
],
"author": {
"name": "Awesome Copilot Community"
},
"description": "A modular, high-performance multi-agent orchestration framework for complex project execution, feature implementation, and automated verification.",
"description": "Multi-agent orchestration framework for spec-driven development and automated verification.",
"keywords": [
"multi-agent",
"orchestration",
"tdd",
"testing",
"e2e",
"devops",
"security-audit",
"dag-planning",
"compliance",
"code-review",
"prd",
"debugging",
"refactoring"
"mobile"
],
"license": "MIT",
"name": "gem-team",
"repository": "https://github.com/github/awesome-copilot",
"version": "1.5.0"
"version": "1.6.0"
}

429
plugins/gem-team/README.md
View File

@@ -1,55 +1,40 @@
# Gem Team
# 💎 Gem Team
> A modular, high-performance multi-agent orchestration framework for spec-driven development, feature implementation, and automated verification.
> Multi-agent orchestration framework for spec-driven development and automated verification.
[![Copilot Plugin](https://img.shields.io/badge/Plugin-Awesome%20Copilot-0078D4?style=flat-square&logo=microsoft)](https://awesome-copilot.github.com/plugins/#file=plugins%2Fgem-team)
![Version](https://img.shields.io/badge/Version-1.5.0-6366f1?style=flat-square)
![Version](https://img.shields.io/badge/Version-1.6.0-6366f1?style=flat-square)
---
## Why Gem Team?
## 🤔 Why Gem Team?
### Single-Agent Problems → Gem Team Solutions
| Problem | Solution |
|:--------|:---------|
| Context overload | **Specialized agents** with focused expertise |
| No specialization | **12 expert agents** with clear roles and zero overlap |
| Sequential bottlenecks | **DAG-based parallel execution** (≤4 agents simultaneously) |
| Missing verification | **TDD + mandatory verification gates** per agent |
| Intent misalignment | **Discuss phase** captures intent; **clarification tracking** in PRD |
| No audit trail | Persistent **`plan.yaml` and `PRD.yaml`** tracks every decision & outcome |
| Over-engineering | **Architectural gates** validate simplicity; **gem-critic** challenges assumptions |
| Untested accessibility | **WCAG spec validation** (designer) + **runtime checks** (browser tester) |
| Blind retries | **Diagnose-then-fix**: gem-debugger finds root cause, gem-implementer applies fix |
| Single-plan risk | Complex tasks get **3 planner variants** → best DAG selected automatically |
| Missed edge cases | **gem-critic** audits for logic gaps, boundary conditions, YAGNI violations |
| Slow manual workflows | **Magic keywords** (`autopilot`, `simplify`, `critique`, `debug`, `fast`) skip to what you need |
| Docs drift from code | **gem-documentation-writer** enforces code-documentation parity |
| Unsafe deployments | **Approval gates** block production/security changes until confirmed |
| Browser fragmentation | **Multi-browser testing** via Chrome MCP, Playwright, and Agent Browser |
| Broken contracts | **Contract verification** post-wave ensures dependent tasks integrate correctly |
### Why It Works
- **10x Faster** — Parallel execution eliminates bottlenecks
- **Higher Quality** — Specialized agents + TDD + verification gates = fewer bugs
- **Built-in Security** — OWASP scanning on critical tasks
- **Full Visibility** — Real-time status, clear approval gates
- **Resilient** — Pre-mortem analysis, failure handling, auto-replanning
- **Pattern Reuse** — Codebase pattern discovery prevents reinventing wheels
- **Self-Correcting** — All agents self-critique at 0.85 confidence threshold before returning results
- **Accessibility-First** — WCAG compliance validated at both spec and runtime layers
- **Smart Debugging** — Root-cause analysis with stack trace parsing, regression bisection, and confidence-scored fix recommendations
- **Safe DevOps** — Idempotent operations, health checks, and mandatory approval gates for production
- **Traceable** — Self-documenting IDs link requirements → tasks → tests → evidence
- **Decision-Focused** — Research outputs highlight blockers and decision points for planners
- **Rich Specification Creation** — PRD creation with user stories, IN/OUT of scope, acceptance criteria, and clarification tracking
- **Spec-Driven Development** — Specifications define the "what" before the "how", with multi-step refinement rather than one-shot code generation from prompts
- ⚡ **10x Faster** — Parallel execution with wave-based execution
- 🏆 **Higher Quality** — Specialized agents + TDD + verification gates + contract-first
- 🔒 **Built-in Security** — OWASP scanning, secrets/PII detection on critical tasks
- 👁️ **Full Visibility** — Real-time status, clear approval gates
- 🛡️ **Resilient** — Pre-mortem analysis, failure handling, auto-replanning
- ♻️ **Pattern Reuse** — Codebase pattern discovery prevents reinventing wheels
- 🪞 **Self-Correcting** — All agents self-critique at 0.85 confidence threshold
- 📋 **Source Verified** — Every factual claim cites its source; no guesswork
- ♿ **Accessibility-First** — WCAG compliance validated at spec and runtime layers
- 🔬 **Smart Debugging** — Root-cause analysis with stack trace parsing + confidence-scored fixes
- 🚀 **Safe DevOps** — Idempotent operations, health checks, mandatory approval gates
- 🔗 **Traceable** — Self-documenting IDs link requirements → tasks → tests → evidence
- 📚 **Knowledge-Driven** — Prioritized sources (PRD → codebase → AGENTS.md → Context7 → docs)
- 🛠️ **Skills & Guidelines** — Built-in skill & guidelines (web-design-guidelines)
- 📐 **Spec-Driven** — Multi-step refinement defines "what" before "how"
- 🌊 **Wave-Based** — Parallel agents with integration gates per wave
- 🗂️ **Multi-Plan** — Complex tasks: 3 planner variants → best DAG selected automatically
- 🩺 **Diagnose-then-Fix** — gem-debugger diagnoses → gem-implementer fixes → re-verifies
- ⚠️ **Pre-Mortem** — Failure modes identified BEFORE execution
- 💬 **Constructive Critique** — gem-critic challenges assumptions, finds edge cases
- 📝 **Contract-First** — Contract tests written before implementation
- 📱 **Mobile Agents** — Native mobile implementation (React Native, Flutter) + iOS/Android testing
---
## Installation
## 📦 Installation
```bash
# Using Copilot CLI
@@ -60,274 +45,170 @@ copilot plugin install gem-team@awesome-copilot
---
## Architecture
## 🏗️ Architecture
```mermaid
flowchart TB
subgraph USER["USER"]
goal["User Goal"]
end
flowchart
USER["User Goal"]
subgraph ORCH["ORCHESTRATOR"]
subgraph ORCH["Orchestrator"]
detect["Phase Detection"]
route["Route to agents"]
synthesize["Synthesize results"]
end
subgraph DISCUSS["Phase 1: Discuss"]
dir1["medium|complex only"]
intent["Intent capture"]
clar["Clarifications"]
subgraph PHASES
DISCUSS["🔹 Discuss"]
PRD["📋 PRD"]
RESEARCH["🔍 Research"]
PLANNING["📝 Planning"]
EXEC["⚙️ Execution"]
SUMMARY["📊 Summary"]
end
subgraph PRD["Phase 2: PRD Creation"]
stories["User stories"]
scope["IN/OUT of scope"]
criteria["Acceptance criteria"]
clar_tracking["Clarification tracking"]
end
DIAG["🔬 Diagnose-then-Fix"]
subgraph PHASE3["Phase 3: Research"]
focus["Focus areas (≤4∥)"]
res["gem-researcher"]
end
USER --> detect
subgraph PHASE4["Phase 4: Planning"]
dag["DAG + Pre-mortem"]
multi["3 variants (complex)"]
critic_plan["gem-critic"]
verify_plan["gem-reviewer"]
planner["gem-planner"]
end
subgraph EXEC["Phase 5: Execution"]
waves["Wave-based (1→n)"]
parallel["≤4 agents ∥"]
integ["Wave Integration"]
diag_fix["Diagnose-then-Fix Loop"]
end
subgraph AUTO["Auto-Invocations (post-wave)"]
auto_critic["gem-critic (complex)"]
auto_design["gem-designer (UI tasks)"]
end
subgraph WORKERS["Workers"]
impl["gem-implementer"]
test["gem-browser-tester"]
devops["gem-devops"]
docs["gem-documentation-writer"]
debug["gem-debugger"]
simplify["gem-code-simplifier"]
design["gem-designer"]
end
subgraph SUMMARY["Phase 6: Summary"]
status["Status report"]
prod_feedback["Production feedback"]
decision_log["Decision log"]
end
goal --> detect
detect --> |"No plan\n(medium|complex)"| DISCUSS
detect --> |"No plan\n(simple)"| PHASE3
detect --> |"Plan + pending"| EXEC
detect --> |"Plan + feedback"| PHASE4
detect --> |"All done"| SUMMARY
detect --> |"Magic keyword"| route
detect --> |"Simple"| RESEARCH
detect --> |"Medium|Complex"| DISCUSS
DISCUSS --> PRD
PRD --> PHASE3
PHASE3 --> PHASE4
PHASE4 --> |"Approved"| EXEC
PHASE4 --> |"Issues"| PHASE4
EXEC --> WORKERS
EXEC --> AUTO
EXEC --> |"Failure"| diag_fix
diag_fix --> |"Retry"| EXEC
EXEC --> |"Complete"| SUMMARY
SUMMARY --> |"Feedback"| PHASE4
PRD --> RESEARCH
RESEARCH --> PLANNING
PLANNING --> |"Approved"| EXEC
PLANNING --> |"Feedback"| PLANNING
EXEC --> |"Failure"| DIAG
DIAG --> EXEC
EXEC --> SUMMARY
PLANNING -.-> |"critique"| critic
PLANNING -.-> |"review"| reviewer
EXEC --> |"parallel ≤4"| agents
EXEC --> |"post-wave (complex)"| critic
```
---
## Core Workflow
## 🔄 Core Workflow
The Orchestrator follows a 6-phase workflow with automatic phase detection.
**Phase Flow:** User Goal → Orchestrator → Discuss (medium|complex) → PRD → Research → Planning → Execution → Summary
### Phase Detection
**Error Handling:** Diagnose-then-Fix loop (Debugger → Implementer → Re-verify)
| Condition | Action |
|:----------|:-------|
| No plan + simple | Research Phase (skip Discuss) |
| No plan + medium\|complex | Discuss Phase |
| Plan + pending tasks | Execution Loop |
**Orchestrator** auto-detects phase and routes accordingly.
| Condition | → Phase |
|:----------|:--------|
| No plan + simple | Research |
| No plan + medium\|complex | Discuss → PRD → Research |
| Plan + pending tasks | Execution |
| Plan + feedback | Planning |
| All tasks done | Summary |
| Magic keyword | Fast-track to specified agent/mode |
### Phase 1: Discuss (medium|complex only)
- **Identifies gray areas** → 2-4 context-aware options per question
- **Asks 3-5 targeted questions** → Architectural decisions → `AGENTS.md`
- **Task clarifications** captured for PRD creation
### Phase 2: PRD Creation
- **Creates** `docs/PRD.yaml` from Discuss Phase outputs
- **Includes:** user stories, IN SCOPE, OUT OF SCOPE, acceptance criteria
- **Tracks clarifications:** status (open/resolved/deferred) with owner assignment
### Phase 3: Research
- **Detects complexity** (simple/medium/complex)
- **Delegates to gem-researcher** (≤4 concurrent) per focus area
- **Output:** `docs/plan/{plan_id}/research_findings_{focus}.yaml`
### Phase 4: Planning
- **Complex:** 3 planner variants (a/b/c) → selects best
- **gem-reviewer** validates with architectural checks (simplicity, anti-abstraction, integration-first)
- **gem-critic** challenges assumptions
- **Planning history** tracks iteration passes for continuous improvement
- **Output:** `docs/plan/{plan_id}/plan.yaml` (DAG + waves)
### Phase 5: Execution
- **Executes in waves** (wave 1 first, wave 2 after)
- **≤4 agents parallel** per wave (6-8 with `fast`/`parallel` keyword)
- **TDD cycle:** Red → Green → Refactor → Verify
- **Contract-first:** Write contract tests before implementing tasks with dependencies
- **Wave integration:** get_errors → build → lint/typecheck/tests → contract verification
- **On failure:** gem-debugger diagnoses → root cause injected → gem-implementer retries (max 3)
- **Prototype support:** Wave 1 can include prototype tasks to validate architecture early
- **Auto-invocations:** gem-critic after each wave (complex); gem-designer validates UI tasks post-wave
### Phase 6: Summary
- **Decision log:** All key decisions with rationale (backward reference to requirements)
- **Production feedback:** How to verify in production, known limitations, rollback procedure
- **Presents** status, next steps
- **User feedback** → routes back to Planning
---
## The Agent Team
## 🤖 The Agent Team (Q2 2026 SOTA)
| Agent | Role | When to Use |
|:------|:-----|:------------|
| `gem-orchestrator` | **ORCHESTRATOR** | Coordinates multi-agent workflows, delegates tasks. Never executes directly. |
| `gem-researcher` | **RESEARCHER** | Research, explore, analyze code, find patterns, investigate dependencies. Decision-focused output with blockers highlighted. |
| `gem-planner` | **PLANNER** | Plan, design approach, break down work, estimate effort. Supports prototype tasks, planning passes, and multiple iterations. |
| `gem-implementer` | **IMPLEMENTER** | Implement, build, create, code, write, fix (TDD). Uses contract-first approach for tasks with dependencies. |
| `gem-browser-tester` | **BROWSER TESTER** | Test UI, browser tests, E2E, visual regression, accessibility. |
| `gem-devops` | **DEVOPS** | Deploy, configure infrastructure, CI/CD, containers. |
| `gem-reviewer` | **REVIEWER** | Review, audit, security scan, compliance. Never modifies. Performs architectural checks and contract verification. |
| `gem-documentation-writer` | **DOCUMENTATION** | Document, write docs, README, API docs, diagrams. |
| `gem-debugger` | **DEBUGGER** | Debug, diagnose, root cause analysis, trace errors. Never fixes. |
| `gem-critic` | **CRITIC** | Critique, challenge assumptions, edge cases, over-engineering. |
| `gem-code-simplifier` | **SIMPLIFIER** | Simplify, refactor, dead code removal, reduce complexity. |
| `gem-designer` | **DESIGNER** | Design UI, create themes, layouts, validate accessibility. |
| Role | Description | Output | Recommended LLM |
|:-----|:------------|:-------|:---------------|
| 🎯 **ORCHESTRATOR** (`gem-orchestrator`) | The team lead: Orchestrates research, planning, implementation, and verification | 📋 PRD, plan.yaml | **Closed:** GPT-5.4, Gemini 3.1 Pro, Claude Sonnet 4.6<br>**Open:** GLM-5, Kimi K2.5, Qwen3.5 |
| 🔍 **RESEARCHER** (`gem-researcher`) | Codebase exploration — patterns, dependencies, architecture discovery | 🔍 findings | **Closed:** Gemini 3.1 Pro, GPT-5.4, Claude Sonnet 4.6<br>**Open:** GLM-5, Qwen3.5-9B, DeepSeek-V3.2 |
| 📋 **PLANNER** (`gem-planner`) | DAG-based execution plans — task decomposition, wave scheduling, risk analysis | 📄 plan.yaml | **Closed:** Gemini 3.1 Pro, Claude Sonnet 4.6, GPT-5.4<br>**Open:** Kimi K2.5, GLM-5, Qwen3.5 |
| 🔧 **IMPLEMENTER** (`gem-implementer`) | TDD code implementation — features, bugs, refactoring. Never reviews own work | 💻 code | **Closed:** Claude Opus 4.6, GPT-5.4, Gemini 3.1 Pro<br>**Open:** DeepSeek-V3.2, GLM-5, Qwen3-Coder-Next |
| 🧪 **BROWSER TESTER** (`gem-browser-tester`) | E2E browser testing, UI/UX validation, visual regression with Playwright | 🧪 evidence | **Closed:** GPT-5.4, Claude Sonnet 4.6, Gemini 3.1 Flash<br>**Open:** Llama 4 Maverick, Qwen3.5-Flash, MiniMax M2.7 |
| 🚀 **DEVOPS** (`gem-devops`) | Infrastructure deployment, CI/CD pipelines, container management | 🌍 infra | **Closed:** GPT-5.4, Gemini 3.1 Pro, Claude Sonnet 4.6<br>**Open:** DeepSeek-V3.2, GLM-5, Qwen3.5 |
| 🛡️ **REVIEWER** (`gem-reviewer`) | Security auditing, code review, OWASP scanning, PRD compliance verification | 📊 review report | **Closed:** Claude Opus 4.6, GPT-5.4, Gemini 3.1 Pro<br>**Open:** Kimi K2.5, GLM-5, DeepSeek-V3.2 |
| 📝 **DOCUMENTATION** (`gem-documentation-writer`) | Technical documentation, README files, API docs, diagrams, walkthroughs | 📝 docs | **Closed:** Claude Sonnet 4.6, Gemini 3.1 Flash, GPT-5.4 Mini<br>**Open:** Llama 4 Scout, Qwen3.5-9B, MiniMax M2.7 |
| 🔬 **DEBUGGER** (`gem-debugger`) | Root-cause analysis, stack trace diagnosis, regression bisection, error reproduction | 🔬 diagnosis | **Closed:** Gemini 3.1 Pro (Retrieval King), Claude Opus 4.6, GPT-5.4<br>**Open:** DeepSeek-V3.2, GLM-5, Qwen3-Coder-Next |
| 🎯 **CRITIC** (`gem-critic`) | Challenges assumptions, finds edge cases, spots over-engineering and logic gaps | 💬 critique | **Closed:** Claude Sonnet 4.6, GPT-5.4, Gemini 3.1 Pro<br>**Open:** Kimi K2.5, GLM-5, Qwen3.5 |
| ✂️ **SIMPLIFIER** (`gem-code-simplifier`) | Refactoring specialist — removes dead code, reduces complexity, consolidates duplicates | ✂️ change log | **Closed:** Claude Opus 4.6, GPT-5.4, Gemini 3.1 Pro<br>**Open:** DeepSeek-V3.2, GLM-5, Qwen3-Coder-Next |
| 🎨 **DESIGNER** (`gem-designer`) | UI/UX design specialist — layouts, themes, color schemes, design systems, accessibility | 🎨 DESIGN.md | **Closed:** GPT-5.4, Gemini 3.1 Pro, Claude Sonnet 4.6<br>**Open:** Qwen3.5, GLM-5, MiniMax M2.7 |
| 📱 **IMPLEMENTER-MOBILE** (`gem-implementer-mobile`) | Mobile implementation — React Native, Expo, Flutter with TDD | 💻 code | **Closed:** Claude Opus 4.6, GPT-5.4, Gemini 3.1 Pro<br>**Open:** DeepSeek-V3.2, GLM-5, Qwen3-Coder-Next |
| 📱 **DESIGNER-MOBILE** (`gem-designer-mobile`) | Mobile UI/UX specialist — HIG, Material Design, safe areas, touch targets | 🎨 DESIGN.md | **Closed:** GPT-5.4, Gemini 3.1 Pro, Claude Sonnet 4.6<br>**Open:** Qwen3.5, GLM-5, MiniMax M2.7 |
| 📱 **MOBILE TESTER** (`gem-mobile-tester`) | Mobile E2E testing — Detox, Maestro, iOS/Android simulators | 🧪 evidence | **Closed:** GPT-5.4, Claude Sonnet 4.6, Gemini 3.1 Flash<br>**Open:** Llama 4 Maverick, Qwen3.5-Flash, MiniMax M2.7 |
### Agent File Skeleton
Each `.agent.md` file follows this structure:
```
--- # Frontmatter: description, name, triggers
# Role # One-line identity
# Expertise # Core competencies
# Knowledge Sources # Prioritized reference list
# Workflow # Step-by-step execution phases
## 1. Initialize # Setup and context gathering
## 2. Analyze/Execute # Role-specific work
## N. Self-Critique # Confidence check (≥0.85)
## N+1. Handle Failure # Retry/escalate logic
## N+2. Output # JSON deliverable format
# Input Format # Expected JSON schema
# Output Format # Return JSON schema
# Rules
## Execution # Tool usage, batching, error handling
## Constitutional # IF-THEN decision rules
## Anti-Patterns # Behaviors to avoid
## Anti-Rationalization # Excuse → Rebuttal table
## Directives # Non-negotiable commands
```
All agents share: Execution rules, Constitutional rules, Anti-Patterns, and Directives sections. Anti-Rationalization tables are present in 5 agents (implementer, planner, reviewer, designer, browser-tester). Role-specific sections (Workflow, Expertise, Knowledge Sources) vary by agent.
---
## Key Features
## 📚 Knowledge Sources
| Feature | Description |
|:--------|:------------|
| **TDD (Red-Green-Refactor)** | Tests first → fail → minimal code → refactor → verify |
| **Security-First** | OWASP scanning, secrets/PII detection, tiered depth review |
| **Pre-Mortem Analysis** | Failure modes identified BEFORE execution |
| **Multi-Plan Selection** | Complex tasks: 3 planner variants → selects best DAG |
| **Wave-Based Execution** | Parallel agent execution with integration gates |
| **Diagnose-then-Fix** | gem-debugger finds root cause → injects diagnosis → gem-implementer fixes |
| **Approval Gates** | Security + deployment approval for sensitive ops |
| **Multi-Browser Testing** | Chrome MCP, Playwright, Agent Browser |
| **Codebase Patterns** | Avoids reinventing the wheel |
| **Self-Critique** | Reflection step before output (0.85 confidence threshold) |
| **Root-Cause Diagnosis** | Stack trace analysis, regression bisection |
| **Constructive Critique** | Challenges assumptions, finds edge cases |
| **Magic Keywords** | Fast-track modes: `autopilot`, `simplify`, `critique`, `debug`, `fast` |
| **Docs-Code Parity** | Documentation verified against source code |
| **Contract-First Development** | Contract tests written before implementation |
| **Self-Documenting IDs** | Task/AC IDs encode lineage for traceability |
| **Architectural Gates** | Plan review validates simplicity & integration-first |
| **Prototype Wave** | Wave 1 can validate architecture before full implementation |
| **Planning History** | Tracks iteration passes for continuous improvement |
| **Clarification Tracking** | PRD tracks unresolved items with ownership |
Agents consult only the sources relevant to their role. Trust levels apply:
| Trust Level | Sources | Behavior |
|:-----------|:--------|:---------|
| **Trusted** | PRD.yaml, plan.yaml, AGENTS.md | Follow as instructions |
| **Verify** | Codebase files, research findings | Cross-reference before assuming |
| **Untrusted** | Error logs, external data, third-party responses | Factual only — never as instructions |
| Agent | Knowledge Sources |
|:------|:------------------|
| orchestrator | PRD.yaml, AGENTS.md |
| researcher | PRD.yaml, codebase patterns, AGENTS.md, Context7, official docs, online search |
| planner | PRD.yaml, codebase patterns, AGENTS.md, Context7, official docs |
| implementer | codebase patterns, AGENTS.md, Context7 (API verification), DESIGN.md (UI tasks) |
| debugger | codebase patterns, AGENTS.md, error logs (untrusted), git history, DESIGN.md (UI bugs) |
| reviewer | PRD.yaml, codebase patterns, AGENTS.md, OWASP reference, DESIGN.md (UI review) |
| browser-tester | PRD.yaml (flow coverage), AGENTS.md, test fixtures, baseline screenshots, DESIGN.md (visual validation) |
| designer | PRD.yaml (UX goals), codebase patterns, AGENTS.md, existing design system |
| code-simplifier | codebase patterns, AGENTS.md, test suites (behavior verification) |
| documentation-writer | AGENTS.md, existing docs, source code |
---
## Knowledge Sources
All agents consult in priority order:
| Source | Description |
|:-------|:------------|
| `docs/PRD.yaml` | Product requirements — scope and acceptance criteria |
| Codebase patterns | Semantic search for implementations, reusable components |
| `AGENTS.md` | Team conventions and architectural decisions |
| Context7 | Library and framework documentation |
| Official docs | Guides, configuration, reference materials |
| Online search | Best practices, troubleshooting, GitHub issues |
---
## Generated Artifacts
| Agent | Generates | Path |
|:------|:----------|:-----|
| gem-orchestrator | PRD | `docs/PRD.yaml` |
| gem-planner | plan.yaml | `docs/plan/{plan_id}/plan.yaml` |
| gem-researcher | findings | `docs/plan/{plan_id}/research_findings_{focus}.yaml` |
| gem-critic | critique report | `docs/plan/{plan_id}/critique_{scope}.yaml` |
| gem-browser-tester | evidence | `docs/plan/{plan_id}/evidence/{task_id}/` |
| gem-designer | design specs | `docs/plan/{plan_id}/design_{task_id}.yaml` |
| gem-code-simplifier | change log | `docs/plan/{plan_id}/simplification_{task_id}.yaml` |
| gem-debugger | diagnosis | `docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml` |
| gem-documentation-writer | docs | `docs/` (README, API docs, walkthroughs) |
---
## Agent Protocol
### Core Rules
- Output ONLY requested deliverable (code: code ONLY)
- Think-Before-Action via internal `<thought>` block
- Batch independent operations; context-efficient reads (≤200 lines)
- Agent-specific `verification` criteria from plan.yaml
- Self-critique: agents reflect on output before returning results
- Knowledge sources: agents consult prioritized references (PRD → codebase → AGENTS.md → Context7 → docs → online)
### Verification by Agent
| Agent | Verification |
|:------|:-------------|
| Implementer | get_errors → typecheck → unit tests → contract tests (if applicable) |
| Debugger | reproduce → stack trace → root cause → fix recommendations |
| Critic | assumption audit → edge case discovery → over-engineering detection → logic gap analysis |
| Browser Tester | validation matrix → console → network → accessibility |
| Reviewer (task) | OWASP scan → code quality → logic → task_completion_check → coverage_status |
| Reviewer (plan) | coverage → atomicity → deps → PRD alignment → architectural_checks |
| Reviewer (wave) | get_errors → build → lint → typecheck → tests → contract_checks |
| DevOps | deployment → health checks → idempotency |
| Doc Writer | completeness → code parity → formatting |
| Simplifier | tests pass → behavior preserved → get_errors |
| Designer | accessibility → visual hierarchy → responsive → design system compliance |
| Researcher | decision_blockers → research_blockers → coverage → confidence |
---
## Contributing
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
## 📄 License
This project is licensed under the MIT License.
## Support
## 💬 Support
If you encounter any issues or have questions, please [open an issue](https://github.com/mubaidr/gem-team/issues) on GitHub.
---
## 📋 Changelog
### 1.6.0 (April 8, 2026)
**New:**
- Mobile agents — build, design, and test iOS/Android apps with gem-implementer-mobile, gem-designer-mobile, gem-mobile-tester
**Improved:**
- Concise agent descriptions — one-liners that quickly communicate what each agent does
- Unified agent table — clean overview of all 15 agents with roles and outputs
### 1.5.4
**Bug Fixes:**
- Fixed AGENTS.md pattern extraction logic for semantic search integration