diff --git a/conductor/workflow.md b/conductor/workflow.md index ff9f4258..a3d9ef29 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -334,25 +334,39 @@ A task is complete when: To emulate the 4-Tier MMA Architecture within the standard Conductor extension without requiring a custom fork, adhere to these strict workflow policies: +### 0. The Domain Distinction (CRITICAL โ€” added 2026-06-27) + +This doc describes **META-TOOLING** โ€” the AI agent orchestration layer used by Conductor agents to coordinate their own work. It is **NOT** the Application domain (the manual-slop GUI app being built). + +| Domain | What it does | Tools | +|---|---|---| +| **META-TOOLING** (this doc) | AI agent orchestration: sub-agent delegation, model switching, doc reading, file editing of THIS repo | OpenCode Task tool (sub-agent delegation), `.opencode/agents/*` (tier prompts), `manual-slop_*` MCP tools (file I/O on this repo), the canonical docs (AGENTS.md, conductor/code_styleguides/*.md) | +| **APPLICATION** (separate) | The manual-slop GUI app the agents are building: gui_2.py, ai_client.py, the MMA *engine* (multi_agent_conductor.py, dag_engine.py), the app's MCP tools (mcp_client.py's `read_file`, `search_files`, etc.) | Documented in `docs/guide_*.md` (especially `docs/guide_meta_boundary.md`) | + +**When you see "sub-agent" or "Task tool" in this doc, it means META-TOOLING sub-agent delegation** (Tier 2 dispatching Tier 3 / Tier 4 to do work on this repo). It is **distinct from** the manual-slop app's `multi_agent_conductor.py` MMA engine, which is the APPLICATION-domain feature that runs inside the running GUI app. + ### 1. Active Model Switching (Simulating the 4 Tiers) +**UPDATED 2026-06-27:** The legacy `mma_exec.py` / `claude_mma_exec.py` bridge scripts are DEPRECATED. All tiered **META-TOOLING** sub-agent delegation now goes through the **OpenCode Task tool** (subagent invocation via the `subagent_type` parameter). This is in the meta-tooling domain (per ยง0); it does not affect the application's MMA engine. + - **Mandatory Skill Activation:** As the very first step of any MMA-driven process, including track initialization and implementation phases, the agent MUST activate the `mma-orchestrator` skill (`activate_skill mma-orchestrator`) and their corresponding role's specific tier skill. This is crucial for enforcing the 4-Tier token firewall. -- **The MMA Bridge (`mma_exec.py`):** All tiered delegation is routed through `uv python scripts/mma_exec.py`. This script acts as the primary bridge, managing model selection, context injection, and logging. +- **The Sub-Agent Bridge (OpenCode Task tool):** All meta-tooling tiered delegation is now via the OpenCode Task tool with the appropriate `subagent_type`. This is the canonical META-TOOLING mechanism; it replaces the legacy `mma_exec.py` invocation. (The application-domain MMA engine in `src/multi_agent_conductor.py` is unchanged and is documented in `docs/guide_multi_agent_conductor.md`.) - **Model Tiers:** - **Tier 1 (Strategic/Orchestration):** `gemini-3.1-pro-preview`. Focused on product alignment, setup (`/conductor:setup`), and track initialization (`/conductor:newTrack`). - **Tier 2 (Architectural/Tech Lead):** `gemini-3-flash-preview`. Focused on architectural design and track execution (`/conductor:implement`). **Note:** Tier 2 maintains persistent memory throughout a track's implementation. - **Tier 3 (Execution/Worker):** `gemini-2.5-flash-lite`. Used for surgical code implementation and test generation. Operates statelessly (Context Amnesia) but has access to file I/O tools. - **Tier 4 (Utility/QA):** `gemini-2.5-flash-lite`. Used for log summarization and error analysis. Operates statelessly (Context Amnesia) but has access to diagnostic tools. -- **Tiered Delegation Protocol:** - - **Tier 3 Worker:** `uv run python scripts/mma_exec.py --role tier3-worker "[PROMPT]"` - - **Tier 4 QA Agent:** `uv run python scripts/mma_exec.py --role tier4-qa "[PROMPT]"` -- **Observability:** All hierarchical interactions are recorded in `logs/mma_delegation.log` and detailed sub-agent logs are saved to `logs/agents/`. +- **Tiered Delegation Protocol (OpenCode Task tool):** + - **Tier 3 Worker:** invoke the Task tool with `subagent_type: "tier3-worker"`, providing a surgical prompt with WHERE/WHAT/HOW/SAFETY/COMMIT structure. **DO NOT** use `python scripts/mma_exec.py --role tier3-worker` (deprecated). + - **Tier 4 QA Agent:** invoke the Task tool with `subagent_type: "tier4-qa"`, providing the error output + an explicit instruction "DO NOT fix โ€” provide root cause analysis only". + - **Tier 1 Orchestrator:** invoke the Task tool with `subagent_type: "tier1-orchestrator"` for track planning tasks. +- **Observability:** All hierarchical interactions are recorded in `logs/mma_delegation.log` and detailed sub-agent logs are saved to `logs/agents/`. (These logs are populated by the OpenCode Task tool's logging layer.) ### 2. Context Management and Token Firewalling -- **Context Amnesia (Tiers 3 & 4):** `mma_exec.py` enforces "Context Amnesia" by executing sub-agents in a stateless manner. Each call starts with a clean slate, receiving only the strictly necessary documents and prompts. +- **Context Amnesia (Tiers 3 & 4):** The OpenCode Task tool enforces "Context Amnesia" by executing sub-agents in a stateless manner. Each call starts with a clean slate, receiving only the strictly necessary documents and prompts. - **Persistent Memory (Tier 2):** The Tier 2 Tech Lead does NOT use Context Amnesia during track implementation to ensure continuity of technical strategy. -- **AST Skeleton Views:** For Tier 3 implementation, `mma_exec.py` automatically generates "AST Skeleton Views" of project dependencies. This provides the worker model with the interface-level structure (function signatures, docstrings) of imported modules without the full source code, maximizing the signal-to-noise ratio in the context window. +- **AST Skeleton Views:** For Tier 3 implementation, the OpenCode Task tool + the `manual-slop_py_get_skeleton` MCP tool provides "AST Skeleton Views" of project dependencies. This provides the worker model with the interface-level structure (function signatures, docstrings) of imported modules without the full source code, maximizing the signal-to-noise ratio in the context window. ### 3. Phase Checkpoints (The Final Defense)