manual_slop/mma-orchestrator/SKILL.md

name, description

name	description
mma-orchestrator	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. Pre-Delegation Checkpoint: For dangerous or non-trivial changes, ALWAYS stage your changes (git add .) or commit before delegating to a Tier 3 Worker. If the worker fails or runs git restore, you will lose all prior AI iterations for that file if it wasn't staged/committed.
2. DO NOT perform large code writes yourself.
3. DO construct a single, highly specific prompt with a clear objective.
4. 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."
5. Handling Repeated Failures: If a Tier 3 Worker fails multiple times on the same task, it may lack the necessary capability. You must track failures and retry with --failure-count <N> (e.g., --failure-count 2). This tells mma_exec.py to escalate the sub-agent to a more powerful reasoning model (like gemini-3-flash).
6. 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, py_get_skeleton, or py_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 py_get_code_outline or get_tree to map out the structure of a file or project.
2. Use py_get_skeleton and py_get_imports to understand the interface, docstrings, and dependencies of modules.
3. Use py_find_usages to pinpoint where a function or class is called instead of searching the whole codebase.
4. Use py_check_syntax after making string replacements to ensure the file is still syntactically valid.
5. Only use read_file with start_line and end_line for specific implementation details once target areas are identified.
6. Tier 3 workers MUST NOT read the full content of unrelated files.

### 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):

{
  "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."
}

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