From 6f4832b6a730b7e206bfb30f279adca5a14435cb Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 2 Jul 2026 20:42:48 -0400 Subject: [PATCH] docs(skill): rewrite mma-orchestrator SKILL.md for OpenCode Task tool MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- mma-orchestrator/SKILL.md | 59 ++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/mma-orchestrator/SKILL.md b/mma-orchestrator/SKILL.md index 9033c85f..6bffc4a9 100644 --- a/mma-orchestrator/SKILL.md +++ b/mma-orchestrator/SKILL.md @@ -1,34 +1,30 @@ --- name: mma-orchestrator -description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation. +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** 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 "..."` +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 26-tool inventory with params, Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference -- `docs/guide_mma.md`: Ticket/Track/WorkerContext data structures, DAG engine (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia +- `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 `get_code_outline`, `py_get_definition`, `grep_search`, 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. +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:2633-2724) has a token usage table but no cost column." + - 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: @@ -49,17 +45,16 @@ When performing code modifications or implementing specific requirements: 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. - *Command:* `uv run python scripts/mma_exec.py --role tier3-worker "Implement [SPECIFIC_INSTRUCTION] in [FILE_PATH] at lines [N-M]. Use [SPECIFIC_API_CALL]. Use 1-space indentation."` -6. **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 ` (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`). +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. *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. **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. @@ -78,36 +73,41 @@ To minimize context bloat for Tier 2 & 3: 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 `mma_exec.py --role tier3-worker` (stateless, no skill activation needed) -- **Error analysis**: Spawn via `mma_exec.py --role tier4-qa` (stateless, no skill activation needed) +- **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) ### 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." -} +```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: " + " " + "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):** -```json -{ - "command": "python scripts/mma_exec.py --role tier3-worker \"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.\"", - "description": "Delegating surgical implementation to Tier 3 Worker with exact line refs." -} +```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` (lines 2993-3030). +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: `grep_search "vec4\|C_" gui_2.py`. +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. @@ -119,3 +119,4 @@ When your current role requires capabilities from another tier, use `activate_sk - When managing complex, multi-file Track implementations. - When creating or refining conductor tracks (MUST follow Surgical Spec Protocol). + \ No newline at end of file