---
name: mma-orchestrator
description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation.
---

# MMA Token Firewall & Tiered Delegation Protocol

You are operating within the MMA Framework, acting as either the **Tier 1 Orchestrator** (for setup/init) or the **Tier 2 Tech Lead** (for execution). Your context window is extremely valuable and must be protected from token bloat (such as raw, repetitive code edits, trial-and-error histories, or massive stack traces).

To accomplish this, you MUST delegate token-heavy or stateless tasks to **Tier 3 Workers** or **Tier 4 QA Agents** by spawning secondary Gemini CLI instances via `run_shell_command`.

**CRITICAL Prerequisite:**
To ensure proper environment handling and logging, you MUST NOT call the `gemini` command directly for sub-tasks. Instead, use the wrapper script:
`uv run python scripts/mma_exec.py --role <Role> "..."`

## 1. The Tier 3 Worker (Execution)
When performing code modifications or implementing specific requirements:
1. **DO NOT** perform large code writes yourself.
2. **DO** construct a single, highly specific prompt with a clear objective.
3. **DO** spawn a Tier 3 Worker.
   *Command:* `uv run python scripts/mma_exec.py --role tier3-worker "Implement [SPECIFIC_INSTRUCTION] in [FILE_PATH]. Follow TDD and return success status or code changes."`
4. The Tier 3 Worker is stateless and has tool access for file I/O. 

## 2. The Tier 4 QA Agent (Diagnostics)
If you run a test or command that fails with a significant error or large traceback:
1. **DO NOT** analyze the raw logs in your own context window.
2. **DO** spawn a stateless Tier 4 agent to diagnose the failure.
3. *Command:* `uv run python scripts/mma_exec.py --role tier4-qa "Analyze this failure and summarize the root cause: [LOG_DATA]"`
4. **Mandatory Research-First Protocol:** Avoid direct `read_file` calls for any file over 50 lines. Use `get_file_summary`, `get_python_skeleton`, or `get_code_outline` first to identify relevant sections. Use `git diff` to understand changes.

## 3. Persistent Tech Lead Memory (Tier 2)
Unlike the stateless sub-agents (Tiers 3 & 4), the **Tier 2 Tech Lead** maintains persistent context throughout the implementation of a track. Do NOT apply "Context Amnesia" to your own session during track implementation. You are responsible for the continuity of the technical strategy.

## 4. AST Skeleton & Outline Views
To minimize context bloat for Tier 2 & 3:
1. Use `get_code_outline` to map out the structure of a file.
2. Use `get_python_skeleton` to understand the interface and docstrings of dependencies.
3. Only use `read_file` with `start_line` and `end_line` for specific implementation details once target areas are identified.
4. Tier 3 workers MUST NOT read the full content of unrelated files.

<examples>
### Example 1: Spawning a Tier 4 QA Agent
**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output.
**Agent (You):** 
```json
{
  "command": "python scripts/mma_exec.py --role tier4-qa \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"",
  "description": "Spawning Tier 4 QA to compress error trace statelessly."
}
```

### Example 2: Spawning a Tier 3 Worker
**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1.
**Agent (You):**
```json
{
  "command": "python scripts/mma_exec.py --role tier3-worker \"Read file_cache.py and implement the ASTParser class using tree-sitter. Ensure you preserve docstrings but strip function bodies. Output the updated code.\"",
  "description": "Delegating implementation to a Tier 3 Worker."
}
```
</examples>

<triggers>
- When asked to write large amounts of boilerplate or repetitive code (Coding > 50 lines).
- When encountering a large error trace from a shell execution (Errors > 100 lines).
- When explicitly instructed to act as a "Tech Lead" or "Orchestrator".
- When managing complex, multi-file Track implementations.
</triggers>