Gem Team Framework

Gem Team transforms AI coding from single-prompt outputs into a coordinated engineering pipeline that plans, builds, reviews, and learns. It provides a workflow designed to enforce software engineering best practices through agents and skills.

Key capabilities include:

• Quality by default: Automatic TDD, acceptance checks, and risk-based reviews.
• Smart & efficient: Scoped handoffs and high cache-hit rates to keep token costs proportional to new work.
• Resumable plans: Uses persistent plan IDs and plan.yaml for MEDIUM/HIGH complexity work, allowing you to pause, resume, or extend tasks without losing context.
• Failure classification: Automatically routes failures to the appropriate agent instead of simple retries.
• Tool compatibility: Works with Copilot, Claude, Cursor, Codex, Gemini, or Windsurf.
• Continuous learning: Converts stable patterns into reusable skills and uses confidence-gated memory.

The Orchestrator is the central coordinator of the Gem Team workflow (Phases 0-4). It does not execute specialist work directly; instead, it delegates tasks to agents defined in .apm/agents/ and manages the following:

• Workflow Coordination: Delegates work, tracks state, and enforces verification gates.
• Error Classification: Classifies failures into specific categories (e.g., retry, fixable, replan, flaky, regression, platform-specific, test-bug) to route them to the correct agent.
• Context Propagation: Passes typed handoff outputs into handoff.relevant_context of dependent tasks so discoveries persist across agent instances.
• Memory Management: Promotes stable research findings to repo memory and injects relevant memory into planning context.
• Resilience: Applies relational invariant fallbacks to infer intent and fill safe defaults when agent outputs miss conditional fields, preventing valid work from being rejected.

The Gem Team Orchestrator follows a structured five-phase lifecycle to transform AI coding requests into engineering outcomes. The Orchestrator itself does not perform specialist work (like coding or testing) but instead acts as a router, planner, and synthesizer, delegating tasks to specialized agents.

The Five Phases:

1. Init & Clarify (Phase 0): Classifies the request, validates the plan_id, normalizes intent (e.g., execute, debug, research), and assigns complexity (TRIVIAL to HIGH).
2. Route (Phase 1): Determines the path based on state. For example, research goes to gem-researcher, while new_task or extend goes to the Planning phase.
3. Planning (Phase 2): Generates or reuses a plan. Complexity dictates depth: TRIVIAL/LOW tasks use a direct specialist path, while MEDIUM/HIGH tasks use gem-planner and persistent plan_ids.
4. Execution (Phase 3): Executes work using an ordered 'wave' system. Tasks are collected, scheduled (respecting concurrency limits), delegated to specialists, and gated by reviewers if necessary.
5. Output (Phase 4): Returns a structured report containing the Plan ID, objective, progress metrics, and next steps.

Gem Team organizes information across six distinct layers to separate requirements, instructions, task state, and long-term learning. Understanding these layers is critical for knowing where to place documentation or where to look for context.

Key Constraints:

• Plan Isolation: Every workflow receives a unique plan_id. Persistent plan artifacts store workflow state, but they do not contain project knowledge. New plans do not automatically inherit data from previous plans.
• Stable vs. Ephemeral: AGENTS.md and repository memory are for stable knowledge. They should not be used to store task status or temporary assumptions.

To prevent infinite loops and ensure stability, the Orchestrator enforces guardrails on the planning process. Replans are intended to revise execution details (like waves or routing) without changing the user's immutable baseline objective.

Key Constraints:

• Lineage: Every replan tracks its revision and replan_count. The system defaults to a maximum of two replans.
• Scope: The Planner can revise waves, handoffs, and validation, but it cannot change the baseline objective/criteria or decide if a budget is exhausted.
• Escalation: Empty or repetitive replans will trigger an escalation rather than continuing to loop.
• Invalidation: Any change to waves, handoffs, or criteria automatically invalidates affected results and stale snapshots.
• Revision Types:
  • needs_revision: Revises a plan or context.
  • needs_retry: Retries execution within its allowed cap.
• Planner Usage: Planner revision is limited via the planner_revision_used flag.

Gem Team operates as a multi-stage pipeline rather than a single request-response loop. The workflow follows these stages:

1. Understand & Plan: Clarifies intent and selects the appropriate approach.
2. Execute & Verify: Builds using TDD, verifies every task, and reviews risky boundaries.
3. Learn & Improve: Saves patterns, skills, and decisions for future use.
4. Done: Provides a status report and reusable knowledge.

The system is powered by Agent definitions and packaged skills. The Orchestrator is the central component that routes work, manages context scoping, and enforces verification gates.

Your Request
    ↓
Understand & Plan     ← Clarify intent, pick the right approach
    ↓
Execute & Verify      ← Build with TDD, verify every task, review risky boundaries
    ↓
Learn & Improve       ← Save patterns, skills, decisions for next time
    ↓
Done                  ← Status report + reusable knowledge

Every MEDIUM or HIGH task is designed to be resumable. The system generates a persistent plan ID and a plan.yaml file for every task. This allows work to be paused, resumed, or extended without losing context.

Key behaviors for resumable tasks:

• Exact plan IDs: Continuation requires the exact ID; the system does not use fuzzy matching.
• Ordered waves: Tasks progress in waves where each wave must complete before the next begins. Evidence is carried forward through scoped handoffs.
• Parallel execution: Independent tasks run in parallel within waves, but overlapping ownership is serialized to prevent conflicts.
• Bounded replans: Replans revise execution details but do not change the user's goal. A maximum of two replans is allowed to prevent infinite loops.
• Relational invariant fallbacks: If an agent output violates a conditional requirement, the Orchestrator attempts to infer intent and fill the gap rather than rejecting the work.