### Gem Team Configuration Example

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Example of a `.gem-team.yaml` file demonstrating configuration for orchestrator, planning, quality, devops, and testing.

```yaml
orchestrator:
  max_concurrent_agents: 2
  default_complexity_threshold: auto # auto | TRIVIAL | LOW | MEDIUM | HIGH
  git_commit_on_gate_pass: true

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
```

--------------------------------

### Install All Supported Harness Targets

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Install Gem Team for all supported harness targets using the 'all' keyword.

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

--------------------------------

### Gem-Team Configuration Example

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/00-START-HERE.md

Example of a .gem-team.yaml configuration file. Customize settings for orchestrator, planning, quality, devops, and testing.

```yaml
# .gem-team.yaml in project root

orchestrator:
  max_concurrent_agents: 2          # Parallel execution limit
  default_complexity_threshold: auto # auto or force level
  git_commit_on_gate_pass: true      # Auto-commit per wave

planning:
  enable_critic_for: [HIGH]          # Which levels get critique

quality:
  a11y_audit_level: basic            # none | basic | full
  visual_regression_enabled: true
  visual_diff_threshold: 0.95        # Screenshot tolerance

devops:
  approval_required_for: [production]
  auto_rollback_on_failure: false

testing:
  screenshot_on_failure: true
```

--------------------------------

### Install Gem Team from an Alternative Marketplace

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

If Gem Team is published to an alternative marketplace like 'awesome-copilot', use this command for installation.

```bash
copilot plugin install gem-team@awesome-copilot
```

--------------------------------

### Install APM on Windows

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Use this PowerShell command to install APM on Windows systems.

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

--------------------------------

### Perform a Real Install from Local Path

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

After cloning, use this command to perform a full installation of Gem Team from its local path.

```bash
apm install /absolute/path/to/gem-team --target claude,cursor
```

--------------------------------

### Install APM on Windows PowerShell

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Installs the APM tool on Windows systems using PowerShell. This command fetches and executes the installation script.

```powershell
irm https://aka.ms/apm-windows | iex
```

--------------------------------

### Install APM on macOS/Linux

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Installs the APM tool on macOS and Linux systems using a curl command. Ensure you have curl installed.

```bash
curl -sSL https://aka.ms/apm-unix | sh
```

--------------------------------

### Verify Gem Team Installation

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Commands to verify the Gem Team installation and check its status.

```bash
apm list
```

```bash
apm view mubaidr/gem-team
```

```bash
apm audit
```

--------------------------------

### Global User-Scoped Gem Team Install

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Install Gem Team globally for personal use.

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

--------------------------------

### Install APM on macOS/Linux

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Use this command to install APM on macOS and Linux systems.

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

--------------------------------

### Verify APM Installation

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Checks the installed version of APM to confirm successful installation. Run this command after installing APM.

```bash
apm --version
```

--------------------------------

### Preview Install Without Writing Files

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Use the --dry-run flag to preview the installation of Gem Team without modifying files. Specify the target tool.

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

--------------------------------

### Gem Team Project Configuration Example

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/README.md

Example YAML configuration for Gem Team, covering orchestrator, planning, quality, devops, and testing settings.

```yaml
orchestrator:
  max_concurrent_agents: 2
  default_complexity_threshold: auto
  git_commit_on_gate_pass: true

planning:
  enable_critic_for: [HIGH]

quality:
  a11y_audit_level: basic
  visual_regression_enabled: true

devops:
  approval_required_for: [production]

testing:
  screenshot_on_failure: true

```

--------------------------------

### Clone and Install Gem Team Locally for Development

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Clone the Gem Team repository and install it into a test project for local development and testing.

```bash
git clone https://github.com/mubaidr/gem-team.git
cd gem-team
apm install . --target claude,cursor --dry-run
```

--------------------------------

### Install Gem Team for Multiple Targets

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Installs the Gem Team project into your current project for a specified list of targets. Ensure APM is installed and configured.

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

--------------------------------

### Debugger Agent Example Input

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/6-remaining-agents.md

Provides an example of the input JSON structure for the Debugger Agent, including error context.

```json
{
  "error_context": {
    "message": "Cannot read property 'id' of undefined",
    "stack": "at validateToken (src/middleware/auth.ts:52)",
    "failing_test": "should reject expired tokens"
  }
}
```

--------------------------------

### Install Gem Team for a Single Target

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Installs the Gem Team project into your current project for a single specified target. Use this for targeted installations.

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

--------------------------------

### Install Only Selected Targets

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Install Gem Team for specific targets by listing them with the --target flag.

```bash
apm install mubaidr/gem-team --target claude,cursor
```

--------------------------------

### Task Acceptance Criteria Example

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/3-implementer.md

Example of defining task acceptance criteria in a YAML format for feature implementation.

```yaml
task_id: email-validation
acceptance_criteria:
  - "Email format validated before save"
  - "Invalid emails rejected with 400"
  - "Valid emails accepted (RFC 5322 subset)"
verification:
  command: "npm test -- email.validation"
  expected: "All tests pass"
```

--------------------------------

### Orchestrate Task / Start Workflow

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/10-api-endpoints.md

This is the primary entry point for initiating tasks within the Gem Team framework. It allows users to start new tasks by providing an objective or to resume an existing task using a plan ID. Optional context and configuration overrides can also be provided.

```APIDOC
## Orchestrate Task / Start Workflow

### Description
This operation serves as the main entry point for initiating and managing tasks within the Gem Team framework. Users can define a new task by specifying an objective or resume a previously interrupted task by providing its `plan_id`. It also supports passing optional error context and configuration overrides.

### Function Signature
`orchestrator(objective, plan_id?)`

### Request Schema
```typescript
interface OrchestrationRequest {
  objective: string                  // Task description or objective
  plan_id?: string                   // Optional: resume existing plan
  
  // Optional context
  error_context?: {
    message: string
    stack?: string
    failing_test?: string
  }
  
  // Optional configuration override
  config_overrides?: Partial<GemTeamConfig>
}
```

### Response Schema
```typescript
interface OrchestrationResponse {
  plan_id: string                    // Generated or resumed plan ID
  complexity: ComplexityLevel        // TRIVIAL | LOW | MEDIUM | HIGH
  phase: "0" | "1" | "2" | "3" | "4" // Current phase
  status: PlanStatus                 // Current status
  
  message: string                    // Human-readable status
  
  // If Phase 4
  result?: {
    tasks_completed: number
    tasks_failed: number
    blocked_tasks: string[]
    artifacts: string[]              // Paths to generated files
  }
  
  // If needs clarification
  clarification_needed?: {
    question: string
    options?: string[]
  }
}
```

### Error Responses
- `400 BadRequest` — Invalid objective, ambiguous requirements
- `404 NotFound` — Plan ID provided but plan.yaml not found
- `409 Conflict` — Cannot classify complexity; conflicting context
- `503 ServiceUnavailable` — Planner/Implementer service unavailable

### Example Usage
```typescript
// Start new task
const response = await gem_team.orchestrate({
  objective: "Add JWT authentication to REST API"
});
// Returns: plan_id = "20250623-add-api-auth"

// Resume existing task
const response = await gem_team.orchestrate({
  objective: "Continue authentication setup",
  plan_id: "20250623-add-api-auth"
});
// Resumes from Wave 1 if in progress
```
```

--------------------------------

### Install Gem Team via GitHub Copilot CLI Marketplace

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Use this command to add the Gem Team plugin from its GitHub repository to your GitHub Copilot CLI.

```bash
copilot plugin marketplace add mubaidr/gem-team
copilot plugin marketplace browse gem-team
copilot plugin install gem-team@gem-team
```

--------------------------------

### Gem-Team Workflow Example: Adding Authentication to API

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/00-START-HERE.md

Illustrates a Gem-Team workflow for adding JWT authentication to a REST API. Includes user input, phase breakdown, and output summary.

```text
Objective: Add JWT authentication to REST API
```

```text
Complexity: MEDIUM (integration risk, cross-domain)
Load config, memory, tech_stack
```

```text
Delegate to Planner
Planner creates 2-wave plan:
  - Wave 1: Middleware + login endpoint (parallel)
  - Wave 2: Secure existing endpoints
```

```text
Wave 1: Delegate to 2 Implementers (parallel)
  - Task 1: JWT middleware (TDD)
  - Task 2: /login endpoint (TDD)
Integration gate: Reviewer verifies no secrets, contracts satisfied
Auto-commit: `20250623-add-api-auth_wave-1`
Wave 2: Delegate to 1 Implementer
  - Task 1: Apply middleware to endpoints (TDD)
Final integration gate: Reviewer full check
Auto-commit: `20250623-add-api-auth_wave-2`
```

```text
Plan Status

Plan: 20250623-add-api-auth | Add JWT authentication to REST API

Progress: 3/3 tasks completed (100%)

Waves: Wave 1 (2/2) | Wave 2 (1/1)

Next: Complete ✓
```

--------------------------------

### Install Gem Team via Claude Code Marketplace

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Commands to add, install, and manage the Gem Team plugin within the Claude Code environment.

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

--------------------------------

### Pin Gem Team Release Install

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Install a specific release of Gem Team for reproducible builds. Specify the target tool.

```bash
apm install mubaidr/gem-team#v1.20.0 --target copilot
```

--------------------------------

### Install Gem Team with APM

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/README.md

Use the Agent Package Manager (APM) to install Gem Team and specify target tools.

```bash
apm install mubaidr/gem-team --target copilot,claude,cursor,...
```

--------------------------------

### Debugger Agent Example Output

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/6-remaining-agents.md

Illustrates the expected JSON output from the Debugger Agent after analyzing an error, including root cause and fix suggestions.

```json
{
  "status": "completed",
  "root_cause": "Token expiry check missing; only signature validated. Expired tokens pass validation.",
  "error_location": "src/middleware/auth.ts:52",
  "proof_of_concept_test": "const expired = generateJWT({exp: Date.now() - 3600000}); expect(() => validateToken(expired)).toThrow();",
  "proposed_fix_location": "src/middleware/auth.ts:validateToken()",
  "regression_risk": "low",
  "related_code": [
    "test/auth.test.ts:validateToken",
    "src/config/jwt.ts:generateJWT"
  ]
}
```

--------------------------------

### Tool-Specific Verification

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Verify installations for specific tools like GitHub Copilot CLI or Claude Code.

```bash
copilot plugin list   # GitHub Copilot CLI, if used
```

```bash
/plugin list          # Claude Code, inside Claude Code
```

--------------------------------

### Start or Resume Task Orchestration

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/10-api-endpoints.md

Initiates a new task or resumes an existing one by providing an objective and an optional plan ID. Use this as the primary entry point for orchestrating tasks.

```typescript
const response = await gem_team.orchestrate({
  objective: "Add JWT authentication to REST API"
});
// Returns: plan_id = "20250623-add-api-auth"
```

```typescript
const response = await gem_team.orchestrate({
  objective: "Continue authentication setup",
  plan_id: "20250623-add-api-auth"
});
// Resumes from Wave 1 if in progress
```

--------------------------------

### Green Phase: Minimal Passing Code Example

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/3-implementer.md

Write the minimal amount of code required to pass all tests. Focus on surgical changes only, preserving code reviewability.

```typescript
export function validateCredentials(email, password) {
  return database.users.findOne({ email, password });
}
```

--------------------------------

### Red Phase: Failing Test Example

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/3-implementer.md

Create or update tests for new behavior, including edge cases and error scenarios. Tests should initially fail.

```typescript
describe('User authentication', () => {
  it('should return 401 for invalid credentials', () => {
    // Test setup and assertion that currently fails
  });
});
```

--------------------------------

### Verify Feature Implementation

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/3-implementer.md

Command to run tests and verify the implementation, showing expected output.

```bash
npm test -- email.validation
# ✓ All tests pass
# Coverage: 95%
```

--------------------------------

### Invoke Gem-Team with GitHub Copilot CLI

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/10-api-endpoints.md

Initiate Gem-Team tasks using the GitHub Copilot CLI by providing a descriptive objective.

```bash
copilot gem-team "Your objective here"
```

--------------------------------

### Fast Development Configuration

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/7-configuration.md

This configuration prioritizes speed for rapid prototyping and development. It minimizes checks and approvals to accelerate iteration cycles.

```yaml
orchestrator:
  max_concurrent_agents: 4
  default_complexity_threshold: LOW
  git_commit_on_gate_pass: false

planning:
  enable_critic_for: []  # No critic, save cost

quality:
  a11y_audit_level: none  # Skip a11y for speed
  visual_regression_enabled: false

devops:
  approval_required_for: []  # No approval gates
  auto_rollback_on_failure: false

testing:
  screenshot_on_failure: false
```

--------------------------------

### Exclude Target from Auto-Detection

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Use the --exclude flag to prevent Gem Team from installing for a specific target.

```bash
apm install mubaidr/gem-team --exclude codex
```

--------------------------------

### Run Authentication Middleware Tests

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/3-implementer.md

Execute tests for the authentication middleware to verify the fix for token expiry and ensure no regressions.

```bash
npm test -- auth.middleware
# ✓ All tests pass
# ✓ Proof-of-concept test now passes
# ✓ No regressions in other auth tests
```

--------------------------------

### Agent Definition File Structure

Source: https://github.com/mubaidr/gem-team/blob/main/CONTRIBUTING.md

Defines the structure for agent configuration files. This includes frontmatter for metadata, sections for role, knowledge sources, workflow, output format, and rules.

```txt
---
# Role / # Expertise
# Knowledge Sources
# Workflow
# Output Format
# Rules
---
```

--------------------------------

### Complete Gem Team Configuration Structure

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/7-configuration.md

This snippet shows the full structure of the .gem-team.yaml file, including all available configuration options for orchestrator behavior, planning, quality, devops, and testing.

```yaml
# ═══════════════════════════════════════════════════════════
# ORCHESTRATOR BEHAVIOR
# ═══════════════════════════════════════════════════════════
orchestrator:
  # Maximum number of agents that can run in parallel
  # Higher = faster execution, but more API requests/rate limit usage
  # Default: 2
  max_concurrent_agents: 2

  # Force all tasks to this complexity level
  # Options: auto | TRIVIAL | LOW | MEDIUM | HIGH
  # auto = let orchestrator decide based on actual task scope
  # TRIVIAL/LOW = faster, fewer planning steps
  # MEDIUM/HIGH = more thorough planning, review gates, critic validation
  # Default: auto
  default_complexity_threshold: auto

  # Git commit wave output on integration gate pass
  # Creates clean audit trail per wave with message {plan_id}_wave-{n}
  # Skip if your CI/CD handles commits differently
  # Default: true
  git_commit_on_gate_pass: true

# ═══════════════════════════════════════════════════════════
# PLANNING & WORKFLOW
# ═══════════════════════════════════════════════════════════
planning:
  # Run gem-critic (challenge assumptions, find edge cases) for these complexities
  # Options: TRIVIAL | LOW | MEDIUM | HIGH
  # Critic adds cost but improves plan quality for risky changes
  # Default: [HIGH]
  enable_critic_for: [HIGH]

# ═══════════════════════════════════════════════════════════
# QUALITY & VERIFICATION
# ═══════════════════════════════════════════════════════════
quality:
  # Enable visual regression testing (screenshot comparison)
  # Requires browser tester to save baselines first
  # Default: true
  visual_regression_enabled: true

  # Screenshot difference threshold
  # 0.99 = very strict (catch tiny changes)
  # 0.95 = balanced (catch visible changes, ignore aliasing)
  # 0.90 = lenient (catch major layout changes only)
  # Default: 0.95
  visual_diff_threshold: 0.95

  # Accessibility audit depth (used by browser-tester and reviewer)
  # none = skip a11y checks
  # basic = check contrast, touch targets, ARIA labels
  # full = comprehensive WCAG 2.1 AA audit (slower)
  # Default: basic
  a11y_audit_level: basic

# ═══════════════════════════════════════════════════════════
# DEVOPS & DEPLOYMENT
# ═══════════════════════════════════════════════════════════
devops:
  # Require explicit approval for these environments before deploying
  # Options: dev | staging | production
  # Empty array = no approval required (not recommended for production)
  # Default: [production]
  approval_required_for: [production]

  # Automatically attempt rollback on deployment failure
  # Executes rollback plan per strategy (rolling, blue-green, canary)
  # Set to false if you prefer manual intervention
  # Default: false
  auto_rollback_on_failure: false

# ═══════════════════════════════════════════════════════════
# TESTING
# ═══════════════════════════════════════════════════════════
testing:
  # Capture screenshots when UI tests fail
  # Helps debug visual issues
  # Default: true
  screenshot_on_failure: true

```

--------------------------------

### Bash: Search for Authentication Patterns

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/5-researcher.md

Use grep to find TypeScript files containing 'Bearer' token or 'Authorization' header patterns. Limits results to the first 10.

```bash
grep -r "Bearer.*token\|Authorization.*header" --include="*.ts" | head -10
```

--------------------------------

### Package Authoring and Release Validation Commands

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Commands for auditing, compiling with validation, and packing the Gem Team package for release.

```bash
apm audit
apm compile --target copilot,claude,cursor --validate
apm pack
```

--------------------------------

### Bash: Search for Authentication-Related Files

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/5-researcher.md

Use grep to find files containing 'auth' and related keywords in TypeScript files. Limits results to the first 20.

```bash
grep -r "auth" --include="*.ts" -l | grep -E "(middleware|routes|auth)" | head -20
```

--------------------------------

### Implement Operation

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/README.md

Executes a given task definition, modifying files and running tests to ensure successful implementation.

```APIDOC
## Implement

### Description
Executes a specific task, including modifying relevant files and verifying changes with tests.

### Method
Not specified (delegated operation)

### Endpoint
Not specified (delegated operation)

### Parameters
#### Input
- **task_definition** (any) - Required - The definition of the task to be implemented.

#### Output
- **files modified** (list) - A list of files that were modified.
- **tests passed** (boolean) - Indicates whether all associated tests passed.
```

--------------------------------

### Reinstall from APM Manifest

Source: https://github.com/mubaidr/gem-team/blob/main/README.md

Reinstall Gem Team using the existing apm.yml manifest file for reproducible configurations.

```bash
apm install
```

--------------------------------

### Create Plan Operation

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/README.md

Generates a plan based on a given objective and context, outputting the plan in YAML format along with the context envelope.

```APIDOC
## Create Plan

### Description
Generates a detailed plan for achieving a specific objective, utilizing provided context.

### Method
Not specified (delegated operation)

### Endpoint
Not specified (delegated operation)

### Parameters
#### Input
- **objective** (any) - Required - The objective to create a plan for.
- **context** (any) - Required - The context to inform plan creation.

#### Output
- **plan.yaml** (file) - The generated plan in YAML format.
- **context_envelope.json** (file) - The context envelope associated with the plan.
```

--------------------------------

### Set Environment Variables for Configuration

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/7-configuration.md

Configure Gem-Team settings by exporting environment variables. These variables override values set in `.gem-team.yaml`.

```bash
export GEM_TEAM_ORCHESTRATOR_MAX_CONCURRENT_AGENTS=4
export GEM_TEAM_QUALITY_A11Y_AUDIT_LEVEL=full
```

--------------------------------

### Bash: Search for Middleware Registration

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/5-researcher.md

Use grep to find TypeScript files related to app.use, middleware, or express.Router. Limits results to the first 20.

```bash
grep -r "app\.use\|middleware\|express\.Router" --include="*.ts" | head -20
```

--------------------------------

### Deploy Operation

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/README.md

Handles the deployment process based on the specified environment and strategy, reporting the deployment status.

```APIDOC
## Deploy

### Description
Manages the deployment of the system or application to a specified environment using a defined strategy.

### Method
Not specified (delegated operation)

### Endpoint
Not specified (delegated operation)

### Parameters
#### Input
- **environment** (string) - Required - The target deployment environment.
- **strategy** (string) - Required - The deployment strategy to be used.

#### Output
- **deployment status** (string) - The status of the deployment process.
```

--------------------------------

### Orchestrator Agent Argument Hint

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/1-orchestrator.md

Use this hint to describe your objective or task when interacting with the Orchestrator Agent. Include the plan_id if you are resuming a previous workflow.

```text
Describe your objective or task. Include plan_id if resuming.
```

--------------------------------

### Bash: Search for POST Login Endpoints

Source: https://github.com/mubaidr/gem-team/blob/main/_autodocs/5-researcher.md

Use grep to find TypeScript files containing POST requests to login endpoints. Limits results to the first 10.

```bash
grep -r "POST.*login\|/login" --include="*.ts" | head -10
```