manual_slop/docs/guide_meta_boundary.md

Meta-Boundary & Tooling Architecture

The Core Confusion

This repository contains two distinct architectural domains that share similar concepts. It is very easy for an AI agent (or human) to confuse the two and cause "feature bleed" or safety bypasses.

1. The Application (manual_slop): The Dear PyGui application being developed. This is the product.
2. The Meta-Tooling: The scripts, CLI wrappers, and MCP servers used by the human developer (and their external AI assistants like Gemini CLI or Claude Code) to build the Application.

Domain 1: The Application (manual_slop)

• Primary Files: gui_2.py, ai_client.py, multi_agent_conductor.py, dag_engine.py.
• Purpose: A local GUI for orchestrating AI. It manages its own internal AI sessions, tracks, and tickets.
• Safety Model: Strict Human-In-The-Loop (HITL). Any script or mutating action generated by the Application's internal AI must be approved by the human via a GUI modal (pre_tool_callback).
• 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.
• 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.
• 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.

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.
• It was later expanded heavily with AST mutation tools (py_update_definition, set_file_slice) specifically so the Meta-Tooling (Gemini CLI) could perform surgical edits on the codebase.

The Danger: Because mcp_client.py is shared, an AI working on the Application might accidentally expose these new Meta-Tooling mutation tools to the Application's internal AI without wiring them into the Application's strict GUI approval modal. This causes a critical safety bypass where the Application's AI can silently mutate files.

Guidelines for Future Tiers

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