diff --git a/MMA_Support/Architecture_Recommendation.md b/MMA_Support/Architecture_Recommendation.md index 830e276..d82975e 100644 --- a/MMA_Support/Architecture_Recommendation.md +++ b/MMA_Support/Architecture_Recommendation.md @@ -1,45 +1,45 @@ -# MMA Hierarchical Delegation: Recommended Architecture - -## 1. Overview -The Multi-Model Architecture (MMA) utilizes a 4-Tier hierarchy to ensure token efficiency and structural integrity. The primary agent (Conductor) acts as the Tier 2 Tech Lead, delegating specific, stateless tasks to Tier 3 (Workers) and Tier 4 (Utility) agents. - -## 2. Agent Roles & Responsibilities - -### Tier 2: The Conductor (Tech Lead) -- **Role:** Orchestrator of the project lifecycle via the Conductor framework. -- **Context:** High-reasoning, long-term memory of project goals and specifications. -- **Key Tool:** `mma-orchestrator` skill (Strategy). -- **Delegation Logic:** Identifies tasks that would bloat the primary context (large code blocks, massive error traces) and spawns sub-agents. - -### Tier 3: The Worker (Contributor) -- **Role:** Stateless code generator. -- **Context:** Isolated. Sees only the target file and the specific ticket. -- **Protocol:** Receives a "Worker" system prompt. Outputs clean code or diffs. -- **Invocation:** `.\scripts un_subagent.ps1 -Role Worker -Prompt "..."` - -### Tier 4: The Utility (QA/Compressor) -- **Role:** Stateless translator and summarizer. -- **Context:** Minimal. Sees only the error trace or snippet. -- **Protocol:** Receives a "QA" system prompt. Outputs compressed findings (max 50 tokens). -- **Invocation:** `.\scripts un_subagent.ps1 -Role QA -Prompt "..."` - -## 3. Invocation Protocol - -### Step 1: Detection -Tier 2 detects a delegation trigger: -- Coding task > 50 lines. -- Error trace > 100 lines. - -### Step 2: Spawning -Tier 2 calls the delegation script: -```powershell -.\scripts un_subagent.ps1 -Role -Prompt "Specific instructions..." -``` - -### Step 3: Integration -Tier 2 receives the sub-agent's response. -- **If Worker:** Tier 2 applies the code changes (using `replace` or `write_file`) and verifies. -- **If QA:** Tier 2 uses the compressed error to inform the next fix attempt or passes it to a Worker. - -## 4. System Prompt Management -The `run_subagent.ps1` script should be updated to maintain a library of role-specific system prompts, ensuring that Tier 3/4 agents remain focused and tool-free (to prevent nested complexity). +# MMA Hierarchical Delegation: Recommended Architecture + +## 1. Overview +The Multi-Model Architecture (MMA) utilizes a 4-Tier hierarchy to ensure token efficiency and structural integrity. The primary agent (Conductor) acts as the Tier 2 Tech Lead, delegating specific, stateless tasks to Tier 3 (Workers) and Tier 4 (Utility) agents. + +## 2. Agent Roles & Responsibilities + +### Tier 2: The Conductor (Tech Lead) +- **Role:** Orchestrator of the project lifecycle via the Conductor framework. +- **Context:** High-reasoning, long-term memory of project goals and specifications. +- **Key Tool:** `mma-orchestrator` skill (Strategy). +- **Delegation Logic:** Identifies tasks that would bloat the primary context (large code blocks, massive error traces) and spawns sub-agents. + +### Tier 3: The Worker (Contributor) +- **Role:** Stateless code generator. +- **Context:** Isolated. Sees only the target file and the specific ticket. +- **Protocol:** Receives a "Worker" system prompt. Outputs clean code or diffs. +- **Invocation:** `.\scripts\run_subagent.ps1 -Role Worker -Prompt "..."` + +### Tier 4: The Utility (QA/Compressor) +- **Role:** Stateless translator and summarizer. +- **Context:** Minimal. Sees only the error trace or snippet. +- **Protocol:** Receives a "QA" system prompt. Outputs compressed findings (max 50 tokens). +- **Invocation:** `.\scripts\run_subagent.ps1 -Role QA -Prompt "..."` + +## 3. Invocation Protocol + +### Step 1: Detection +Tier 2 detects a delegation trigger: +- Coding task > 50 lines. +- Error trace > 100 lines. + +### Step 2: Spawning +Tier 2 calls the delegation script: +```powershell +.\scripts\run_subagent.ps1 -Role -Prompt "Specific instructions..." +``` + +### Step 3: Integration +Tier 2 receives the sub-agent's response. +- **If Worker:** Tier 2 applies the code changes (using `replace` or `write_file`) and verifies. +- **If QA:** Tier 2 uses the compressed error to inform the next fix attempt or passes it to a Worker. + +## 4. System Prompt Management +The `run_subagent.ps1` script should be updated to maintain a library of role-specific system prompts, ensuring that Tier 3/4 agents remain focused and tool-free (to prevent nested complexity). diff --git a/mma-orchestrator/SKILL.md b/mma-orchestrator/SKILL.md index 3f99c03..1c1a90d 100644 --- a/mma-orchestrator/SKILL.md +++ b/mma-orchestrator/SKILL.md @@ -1,64 +1,64 @@ ---- -name: mma-orchestrator -description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation. ---- - -# MMA Token Firewall & Tiered Delegation Protocol - -You are operating as a Tier 1 Product Manager or Tier 2 Tech Lead within the MMA Framework. 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 Contributors" or "Tier 4 QA Agents" by spawning secondary Gemini CLI instances via `run_shell_command`. - -**CRITICAL Prerequisite:** -To avoid hanging the CLI and ensure proper environment authentication, you MUST NOT call the `gemini` command directly. Instead, you MUST use the wrapper script: -`.\scripts un_subagent.ps1 -Prompt "..."` - -## 1. The Tier 3 Worker (Heads-Down Coding) -When you need to perform a significant code modification (e.g., refactoring a 500-line script, writing a massive class, or implementing a predefined spec): -1. **DO NOT** attempt to write or use `replace`/`write_file` yourself. Your history will bloat. -2. **DO** construct a single, highly specific prompt. -3. **DO** spawn a sub-agent using `run_shell_command` pointing to the target file. - *Command:* `.\scripts un_subagent.ps1 -Prompt "Modify [FILE_PATH] to implement [SPECIFIC_INSTRUCTION]. Only write the code, no pleasantries."` -4. If you need the sub-agent to automatically apply changes instead of just returning the text, use `gemini run` or pipe the output appropriately. However, the best method is to let the sub-agent modify the code and return "Done." - -## 2. The Tier 4 QA Agent (Error Translation) -If you run a local test (e.g., `npm test`, `pytest`, `go run`) via `run_shell_command` and it fails with a massive traceback (e.g., 200+ lines of `stderr`): -1. **DO NOT** analyze the raw `stderr` in your own context window. -2. **DO** immediately spawn a stateless Tier 4 agent to compress the error. -3. *Command:* `.\scripts un_subagent.ps1 -Prompt "Summarize this stack trace into a 20-word fix: [PASTE_SNIPPET_OF_STDERR_HERE]"` -4. Use the 20-word fix returned by the Tier 4 agent to inform your next architectural decision or pass it to the Tier 3 worker. - -## 3. Context Amnesia (Phase Checkpoints) -When you complete a major Phase or Track within the `conductor` workflow: -1. Stage your changes and commit them. -2. Draft a comprehensive summary of the state changes in a Git Note attached to the commit. -3. Treat the checkpoint as a "Memory Wipe." Actively disregard previous conversational turns and trial-and-error histories. Rely exclusively on the newly generated Git Note and the physical state of the files on disk for your next Phase. - - -### Example 1: Spawning a Tier 4 QA Agent -**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output. -**Agent (You):** -```json -{ - "command": ".\scripts un_subagent.ps1 -Prompt "Summarize this stack trace into a 20-word fix: [snip first 30 lines...]"", - "description": "Spawning Tier 4 QA to compress error trace statelessly." -} -``` - -### Example 2: Spawning a Tier 3 Worker -**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1. -**Agent (You):** -```json -{ - "command": ".\scripts un_subagent.ps1 -Prompt "Read file_cache.py and implement the ASTParser class using tree-sitter. Ensure you preserve docstrings but strip function bodies. Output the updated code or edit the file directly."", - "description": "Delegating implementation to a Tier 3 Worker." -} -``` - - - -- When asked to write large amounts of boilerplate or repetitive code. -- When encountering a large error trace from a shell execution. -- When explicitly instructed to act as a "Tech Lead" or "Orchestrator". -- When managing complex, multi-file Track implementations. - +--- +name: mma-orchestrator +description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation. +--- + +# MMA Token Firewall & Tiered Delegation Protocol + +You are operating as a Tier 1 Product Manager or Tier 2 Tech Lead within the MMA Framework. 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 Contributors" or "Tier 4 QA Agents" by spawning secondary Gemini CLI instances via `run_shell_command`. + +**CRITICAL Prerequisite:** +To avoid hanging the CLI and ensure proper environment authentication, you MUST NOT call the `gemini` command directly. Instead, you MUST use the wrapper script: +`.\scripts\run_subagent.ps1 -Role -Prompt "..."` + +## 1. The Tier 3 Worker (Heads-Down Coding) +When you need to perform a significant code modification (e.g., refactoring a 50-line+ script, writing a massive class, or implementing a predefined spec): +1. **DO NOT** attempt to write or use `replace`/`write_file` yourself. Your history will bloat. +2. **DO** construct a single, highly specific prompt. +3. **DO** spawn a sub-agent using `run_shell_command` pointing to the target file. + *Command:* `.\scripts\run_subagent.ps1 -Role Worker -Prompt "Read [FILE_PATH] and modify it to implement [SPECIFIC_INSTRUCTION]. Only write the code, no pleasantries."` +4. The Tier 3 Worker is stateless and has no tool access. You must take the clean code it returns and apply it to the file system using your own `replace` or `write_file` tools. + +## 2. The Tier 4 QA Agent (Error Translation) +If you run a local test (e.g., `npm test`, `pytest`, `go run`) via `run_shell_command` and it fails with a massive traceback (e.g., 100+ lines of `stderr`): +1. **DO NOT** analyze the raw `stderr` in your own context window. +2. **DO** immediately spawn a stateless Tier 4 agent to compress the error. +3. *Command:* `.\scripts\run_subagent.ps1 -Role QA -Prompt "Summarize this stack trace into a 20-word fix: [PASTE_SNIPPET_OF_STDERR_HERE]"` +4. Use the 20-word fix returned by the Tier 4 agent to inform your next architectural decision or pass it to the Tier 3 worker. + +## 3. Context Amnesia (Phase Checkpoints) +When you complete a major Phase or Track within the `conductor` workflow: +1. Stage your changes and commit them. +2. Draft a comprehensive summary of the state changes in a Git Note attached to the commit. +3. Treat the checkpoint as a "Memory Wipe." Actively disregard previous conversational turns and trial-and-error histories. Rely exclusively on the newly generated Git Note and the physical state of the files on disk for your next Phase. + + +### Example 1: Spawning a Tier 4 QA Agent +**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output. +**Agent (You):** +```json +{ + "command": ".\\scripts\\run_subagent.ps1 -Role QA -Prompt \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"", + "description": "Spawning Tier 4 QA to compress error trace statelessly." +} +``` + +### Example 2: Spawning a Tier 3 Worker +**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1. +**Agent (You):** +```json +{ + "command": ".\\scripts\\run_subagent.ps1 -Role Worker -Prompt \"Read file_cache.py and implement the ASTParser class using tree-sitter. Ensure you preserve docstrings but strip function bodies. Output the updated code.\"", + "description": "Delegating implementation to a Tier 3 Worker." +} +``` + + + +- 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. + \ No newline at end of file