docs(meta-boundary): clarify OpenCode Task tool is current meta-tooling sub-agent mechanism (mma_exec deprecated)

2026-06-25 21:33:55 -04:00
parent c8726c5173
commit 1e3155c596
1 changed files with 6 additions and 6 deletions
@@ -13,8 +13,8 @@ This repository contains two distinct architectural domains that share similar c
 - **Internal Tooling Control**: The tools available to the Application's internal AI are defined strictly by `manual_slop.toml` (`[agent.tools]`).

 ## Domain 2: The Meta-Tooling
- **Primary Files**: `scripts/mma_exec.py`, `scripts/claude_mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `mma-orchestrator/SKILL.md`, `.agents/skills/*/SKILL.md`, `.gemini/`, `.claude/`, `.opencode/`.
- **Purpose**: The external AI agents (you, reading this) used to write the code for the Application.
+- **Primary Files (UPDATED 2026-06-27)**: The legacy `scripts/mma_exec.py` and `scripts/claude_mma_exec.py` are **DEPRECATED** for sub-agent delegation. The current sub-agent mechanism is the **OpenCode Task tool** (`.opencode/agents/*` tier prompts; subagent invocation via the `subagent_type` parameter). The remaining meta-tooling files: `scripts/tool_call.py`, `scripts/mcp_server.py`, `mma-orchestrator/SKILL.md`, `.agents/skills/*/SKILL.md`, `.gemini/`, `.claude/`, `.opencode/`.
+- **Purpose**: The external AI agents (you, reading this) used to write the code for the Application. Sub-agent delegation (Tier 2 → Tier 3, Tier 2 → Tier 4) goes through the OpenCode Task tool.
 - **Safety Model**: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies, Claude Code's permissions, or OpenCode's hook system). These agents have their own sandboxing and do *not* use the Application's GUI for approval unless explicitly hooked.
 - **Tooling Control**: These external agents use `mcp_client.py` natively to investigate and modify the `manual_slop` codebase (e.g., using `set_file_slice` to fix a bug).

@@ -22,8 +22,8 @@ This repository contains two distinct architectural domains that share similar c

 The Meta-Tooling domain is itself split by which external agent consumes it:

- **Gemini CLI** (the primary toolchain as of 2026-06-02): Uses the **conductor extension** which reads `./conductor/` for task tracking, workflow, and product context. Skills are activated via `activate_skill`.
- **OpenCode** (secondary): Uses **superpowers** or the conductor convention directly. Skills live in `.agents/skills/` and are activated by name.
+- **Gemini CLI** (the primary toolchain as of 2026-06-02): Uses the **conductor extension** which reads `./conductor/` for task tracking, workflow, and product context. Skills are activated via `activate_skill`. The legacy `scripts/mma_exec.py` was Gemini CLI's primary sub-agent bridge; it is now DEPRECATED in favor of the OpenCode Task tool.
+- **OpenCode** (secondary, growing primary as of 2026-06-27): Uses the **OpenCode Task tool** for sub-agent delegation (with `subagent_type: "tier3-worker"` / `"tier4-qa"` / etc.) and the `.opencode/agents/*` tier prompts. Skills live in `.agents/skills/` and are activated by name. This is the canonical meta-tooling sub-agent mechanism now.
 - **Claude Code** (legacy, no longer primary): Uses the original `.claude/commands/*.md` slash command inventory. The `claude_mma_exec.py` script may be vestigial.

 **The conductor system in `./conductor/` is the cross-tool abstraction.** Both Gemini CLI and OpenCode consume `conductor/workflow.md`, `conductor/product.md`, `conductor/tech-stack.md`, and `conductor/tracks.md`. Track implementation follows the TDD protocol documented in `conductor/workflow.md` regardless of which external agent is doing the work.
@@ -33,7 +33,7 @@ To achieve true Human-In-The-Loop (HITL) safety while developing the app *with*
 - **How they work**: These scripts (`cli_tool_bridge.py` for Gemini CLI, `claude_tool_bridge.py` for Claude) intercept the tool execution requests from the external AI.
 - **The Hook Server**: They instantiate an `ApiHookClient` and send an HTTP request to `http://127.0.0.1:8999` (the Application's local API Hook Server).
 - **The Result**: The `manual_slop` GUI intercepts this network request and pops open a modal asking the human developer if they approve the action requested by the *external* Meta-Tooling agent.
- **Environment Context**: These bridges check the `GEMINI_CLI_HOOK_CONTEXT` or `CLAUDE_CLI_HOOK_CONTEXT` environment variables. If the variable is set to `mma_headless` (which happens during `mma_exec.py` sub-agent execution), the bridge automatically **allows** the execution to prevent sub-agents from blocking the main thread waiting for human GUI clicks.
+- **Environment Context**: These bridges check the `GEMINI_CLI_HOOK_CONTEXT` or `CLAUDE_CLI_HOOK_CONTEXT` environment variables. If the variable is set to `mma_headless` (which happens during legacy `mma_exec.py` sub-agent execution — DEPRECATED in favor of the OpenCode Task tool), the bridge automatically **allows** the execution to prevent sub-agents from blocking the main thread waiting for human GUI clicks.

 ### Bridge Status (as of 2026-06-02)

@@ -53,5 +53,5 @@ When you are implementing a Track, you must ask yourself:
 > *"Am I modifying the Application's behavior, or am I modifying the Meta-Tooling used to build it?"*

 1. **If adding a tool to `mcp_client.py`**: You must clarify if it is for the Meta-Tooling (us) or the Application (them). If it is for the Application, it MUST be gated behind `manual_slop.toml` toggles and wired to the GUI's `pre_tool_callback` for approval.
-2. **If editing `mma_exec.py`**: You are modifying the Meta-Tooling. The changes here affect how *you* (or your Tier 3 workers) operate. Ensure you respect token limits (Context Amnesia) and do not leak massive Application files into your own context window.
+2. **If editing `mma_exec.py`** (legacy): You are modifying the **Meta-Tooling** (the bridge script). The changes here affect how *you* (or your Tier 3 workers) operate. However, `mma_exec.py` is **DEPRECATED** as of 2026-06-27 in favor of the OpenCode Task tool. New meta-tooling work should target `.opencode/agents/*` (the tier prompts) and the OpenCode Task tool invocation, not `mma_exec.py`. Ensure you respect token limits (Context Amnesia) and do not leak massive Application files into your own context window.
 3. **If editing `gui_2.py` or `ai_client.py`**: You are modifying the Application. Do not assume your external tool capabilities (like automatic file modification) apply here. Follow the Application's strict UX rules.