diff --git a/docs/guide_meta_boundary.md b/docs/guide_meta_boundary.md index 52fe3338..8c458024 100644 --- a/docs/guide_meta_boundary.md +++ b/docs/guide_meta_boundary.md @@ -13,11 +13,21 @@ 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`, `.gemini/`, `.claude/`. +- **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. -- **Safety Model**: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies or Claude Code's permissions). These agents have their own sandboxing and do *not* use the Application's GUI for approval unless explicitly hooked. +- **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). +### The Cross-Tool Abstractions + +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. +- **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. + ## The Inter-Domain Bridges: `cli_tool_bridge.py` & `claude_tool_bridge.py` To achieve true Human-In-The-Loop (HITL) safety while developing the app *with* external AI tools, the project provides "Bridge" scripts. - **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. @@ -25,6 +35,12 @@ To achieve true Human-In-The-Loop (HITL) safety while developing the app *with* - **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. +### Bridge Status (as of 2026-06-02) + +- `cli_tool_bridge.py` — **Active.** Primary toolchain is Gemini CLI. +- `claude_tool_bridge.py` — **Vestigial.** The project no longer uses Claude Code as a primary toolchain. The file is kept for backward compatibility with any external tooling that may still reference it. New meta-tooling work should target Gemini CLI (or OpenCode via the conductor convention), not Claude. +- An `opencode_bridge.py` is **not** present. OpenCode uses its own hook system (`.opencode/hooks.json`) and does not require an explicit bridge — the conductor convention is the bridge. + ## The Overlap & Entropy Vector: `mcp_client.py` `mcp_client.py` is the shared bridge. - It was originally written to give the Application's internal AI some read-only file context tools.