manual_slop/mma-orchestrator/SKILL.md

name, description

name	description
mma-orchestrator	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)

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

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

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