Private
Public Access
ed
6f4832b6a7
The mma-orchestrator skill is what the meta-tooling Tier 1/2 agents load. The previous version was entirely built around the deprecated scripts/mma_exec.py / claude_mma_exec.py bridge scripts — every example used 'uv run python scripts/mma_exec.py --role tierN-X ...' which was deprecated 2026-06-27 in favor of the OpenCode Task tool. Rewrote the skill to use the OpenCode Task tool's subagent_type parameter (tier3-worker / tier4-qa / tier1-orchestrator / tier2-tech-lead) as the canonical mechanism, with explicit deprecation notes for mma_exec.py. Also updated: tool count (26 -> 45, now in src/mcp_tool_specs.py); data locations (Ticket/Track/WorkerContext now in src/mma.py; the src/models.py shim note). The 8 mma_exec.py invocation examples in the previous version would have caused Tier 2 Tech Lead agents to literally invoke deprecated scripts. This is the highest-impact drift of the session — the user explicitly said the deprecated invocation was wrong, and this skill is what loaded the wrong pattern into agent context.
122 lines
9.7 KiB
Markdown
122 lines
9.7 KiB
Markdown
---
|
|
name: mma-orchestrator
|
|
description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within the Manual Slop meta-tooling environment using Token Firewalling and sub-agent task delegation via the OpenCode Task tool.
|
|
---
|
|
|
|
# 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** via the **OpenCode Task tool** (subagent invocation with the `subagent_type` parameter). The canonical mechanism is the OpenCode Task tool; the legacy `scripts/mma_exec.py` / `scripts/claude_mma_exec.py` bridge scripts are **DEPRECATED for meta-tooling sub-agent delegation as of 2026-06-27** (see `conductor/workflow.md` §"Conductor Token Firewalling" + `docs/guide_meta_boundary.md`). The Application-domain WorkerPool at `src/multi_agent_conductor.py:run_worker_lifecycle` uses its own internal subprocess template — that is NOT the meta-tooling mechanism and is also unrelated to the OpenCode Task tool.
|
|
|
|
## 0. Architecture Fallback & Surgical Methodology
|
|
|
|
**Before creating or refining any track**, consult the deep-dive architecture docs:
|
|
- `docs/guide_architecture.md`: Thread domains, event system (`AsyncEventQueue`, `_pending_gui_tasks` action catalog), AI client multi-provider architecture, HITL Execution Clutch blocking flow, frame-sync mechanism
|
|
- `docs/guide_tools.md`: MCP Bridge 3-layer security model, full 45-tool inventory (now in `src/mcp_tool_specs.py`) with params, Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference
|
|
- `docs/guide_mma.md`: Ticket/Track/WorkerContext data structures (now in `src/mma.py`; moved out of `src/models.py`), DAG engine (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia
|
|
- `docs/guide_simulations.md`: `live_gui` fixture lifecycle, Puppeteer pattern, mock provider JSON-L protocol, visual verification patterns
|
|
|
|
### The Surgical Spec Protocol (MANDATORY for track creation)
|
|
|
|
When creating tracks (`activate_skill mma-tier1-orchestrator`), follow this protocol:
|
|
|
|
1. **AUDIT BEFORE SPECIFYING**: Use `py_get_code_outline`, `py_get_definition`, `py_find_usages`, and `get_git_diff` to map what already exists. Previous track specs asked to re-implement existing features (Track Browser, DAG tree, approval dialogs) because no audit was done. Document findings in a "Current State Audit" section with file:line references.
|
|
|
|
2. **GAPS, NOT FEATURES**: Frame requirements as what's MISSING relative to what exists.
|
|
- GOOD: "The existing `_render_mma_dashboard` (gui_2.py ~line 2633-2724) has a token usage table but no cost column."
|
|
- BAD: "Build a metrics dashboard with token and cost tracking."
|
|
|
|
3. **WORKER-READY TASKS**: Each plan task must specify:
|
|
- **WHERE**: Exact file and line range (`gui_2.py:2700-2701`)
|
|
- **WHAT**: The specific change (add function, modify dict, extend table)
|
|
- **HOW**: Which API calls (`imgui.progress_bar(...)`, `imgui.collapsing_header(...)`)
|
|
- **SAFETY**: Thread-safety constraints if cross-thread data is involved
|
|
|
|
4. **ROOT CAUSE ANALYSIS** (for fix tracks): Don't write "investigate and fix." List specific candidates with code-level reasoning.
|
|
|
|
5. **REFERENCE DOCS**: Link to relevant `docs/guide_*.md` sections in every spec.
|
|
|
|
6. **MAP DEPENDENCIES**: State execution order and blockers between tracks.
|
|
|
|
## 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. **Code Style Enforcement:** You MUST explicitly remind the worker to "use exactly 1-space indentation for Python code" in your prompt to prevent them from breaking the established codebase style.
|
|
3. **DO NOT** perform large code writes yourself.
|
|
4. **DO** construct a single, highly specific prompt with a clear objective. Include exact file:line references and the specific API calls to use (from your audit or the architecture docs).
|
|
5. **DO** spawn a Tier 3 Worker via the OpenCode Task tool with `subagent_type: "tier3-worker"` and a surgical prompt specifying WHERE/WHAT/HOW/SAFETY/COMMIT structure. The Task tool invokes the `.opencode/agents/tier3-worker.md` sub-agent prompt which carries the tier-specific operating constraints.
|
|
6. **Handling Repeated Failures:** If a Tier 3 Worker fails multiple times on the same task, it may lack the necessary capability. Re-dispatch with a more capable model tier (e.g., request a higher-capability model in the prompt). The OpenCode Task tool's sub-agent contracts are stateless — failures show up as the returned task result, not as in-band escalation flags.
|
|
7. 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. **Spawn via the OpenCode Task tool** with `subagent_type: "tier4-qa"` and a prompt structured as "DO NOT fix — provide root cause analysis only: [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 `get_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_get_definition` to read specific functions/classes by name without loading entire files.
|
|
4. Use `py_find_usages` to pinpoint where a function or class is called instead of searching the whole codebase.
|
|
5. Use `py_check_syntax` after making string replacements to ensure the file is still syntactically valid.
|
|
6. Only use `read_file` with `start_line` and `end_line` for specific implementation details once target areas are identified.
|
|
7. Tier 3 workers MUST NOT read the full content of unrelated files.
|
|
|
|
## 5. Cross-Skill Activation
|
|
When your current role requires capabilities from another tier, use `activate_skill`:
|
|
- **Track creation/refinement**: `activate_skill mma-tier1-orchestrator` — applies the Surgical Spec Protocol
|
|
- **Track execution**: `activate_skill mma-tier2-tech-lead` — applies persistent context and TDD workflow
|
|
- **Quick code task**: Spawn via the OpenCode Task tool with `subagent_type: "tier3-worker"` (stateless, no skill activation needed)
|
|
- **Error analysis**: Spawn via the OpenCode Task tool with `subagent_type: "tier4-qa"` (stateless, no skill activation needed)
|
|
|
|
<examples>
|
|
### Example 1: Spawning a Tier 4 QA Agent
|
|
**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output.
|
|
**Agent (You):**
|
|
```python
|
|
# OpenCode Task tool invocation (subagent_type="tier4-qa", not a shell command)
|
|
prompt = ("DO NOT fix — provide root cause analysis only. "
|
|
"Summarize this stack trace into a 20-word fix: "
|
|
"<snip first 30 lines of the traceback> "
|
|
"Inputs: [the relevant test + file paths]")
|
|
```
|
|
|
|
### Example 2: Spawning a Tier 3 Worker with Surgical Prompt
|
|
**User:** Please implement the cost tracking column in the token usage table.
|
|
**Agent (You):**
|
|
```python
|
|
# OpenCode Task tool invocation (subagent_type="tier3-worker")
|
|
prompt = ("In gui_2.py, modify _render_mma_dashboard (lines ~2685-2699). "
|
|
"Extend the token usage table from 3 columns to 5 by adding "
|
|
"'Model' and 'Est. Cost' columns. Use imgui.table_setup_column() "
|
|
"for the new columns. Import cost_tracker and call "
|
|
"cost_tracker.estimate_cost(model, input_tokens, output_tokens) "
|
|
"for each tier row. Add a total row at the bottom. "
|
|
"Use 1-space indentation.")
|
|
```
|
|
|
|
### Example 3: Creating a Track with Audit
|
|
**User:** Create a track for adding dark mode support.
|
|
**Agent (You):**
|
|
1. First, audit the codebase: `py_get_code_outline gui_2.py` → find `_render_theme_panel`.
|
|
2. Read the existing implementation: `py_get_definition gui_2.py _render_theme_panel`.
|
|
3. Check for existing color constants: `py_find_usages src/gui_2.py C_LBL`.
|
|
4. Now write the spec with a "Current State Audit" section documenting what the theme panel already does.
|
|
5. Write tasks referencing the exact lines and imgui color APIs to use.
|
|
</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.
|
|
- When creating or refining conductor tracks (MUST follow Surgical Spec Protocol).
|
|
</triggers>
|
|
</body</content> |