feat(conductor): Consolidate MMA implementation into single multi-phase track and draft Agent Skill

MMA_Support/mma_tiered_orchestrator_skill.md

@@ -0,0 +1,62 @@
+# Skill: MMA Tiered Orchestrator
+
+## Description
+This skill enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) directly within the Gemini CLI using Token Firewalling and sub-agent task delegation. It teaches the CLI how to act as a Tier 1/2 Orchestrator, dispatching stateless tasks to cheaper models using shell commands, thereby preventing massive error traces or heavy coding contexts from polluting the primary prompt context.
+
+<instructions>
+# 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`.
+
+## 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:* `gemini ask "Modify [FILE_PATH] to implement [SPECIFIC_INSTRUCTION]. Only write the code, no pleasantries." --model gemini-1.5-flash`
+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:* `gemini ask "Summarize this stack trace into a 20-word fix: [PASTE_SNIPPET_OF_STDERR_HERE]" --model gemini-1.5-flash`
+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.
+</instructions>
+
+<examples>
+### 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": "gemini ask "Summarize this stack trace into a 20-word fix: [snip first 30 lines...]" --model gemini-1.5-flash",
+  "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": "gemini ask "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." --model gemini-1.5-flash",
+  "description": "Delegating implementation to a Tier 3 Worker."
+}
+```
+</examples>
+
+<triggers>
+- 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.
+</triggers>

conductor/tracks.md

@@ -34,26 +34,5 @@ This file tracks all major tracks for the project. Each track has its own detail
 *Link: [./tracks/gui_sim_extension_20260224/](./tracks/gui_sim_extension_20260224/)*
 ---
 
-- [ ] **Track: The Memory Foundations (AST Parser)**
+- [ ] **Track: MMA Core Engine Implementation**
-*Link: [./tracks/mma_the_memory_foundations_ast_parser_20260224/](./tracks/mma_the_memory_foundations_ast_parser_20260224/)*
+*Link: [./tracks/mma_core_engine_20260224/](./tracks/mma_core_engine_20260224/)*
-
----
-
-- [ ] **Track: State Machine & Data Structures**
-*Link: [./tracks/mma_state_machine_data_structures_20260224/](./tracks/mma_state_machine_data_structures_20260224/)*
-
----
-
-- [ ] **Track: The Linear Orchestrator & Execution Clutch**
-*Link: [./tracks/mma_the_linear_orchestrator_execution_clutch_20260224/](./tracks/mma_the_linear_orchestrator_execution_clutch_20260224/)*
-
----
-
-- [ ] **Track: Tier 4 QA Interception**
-*Link: [./tracks/mma_tier_4_qa_interception_20260224/](./tracks/mma_tier_4_qa_interception_20260224/)*
-
----
-
-- [ ] **Track: UI Decoupling & Tier 1/2 Routing (The Final Boss)**
-*Link: [./tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/](./tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/)*
-

conductor/tracks/mma_core_engine_20260224/index.md

@@ -0,0 +1,8 @@
+# MMA Core Engine Implementation
+
+This track implements the 5 Core Epics defined during the MMA Architecture Evaluation.
+
+### Navigation
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Original Architecture Proposal / Meta-Track](../mma_implementation_20260224/index.md)

conductor/tracks/mma_core_engine_20260224/metadata.json

@@ -0,0 +1,6 @@
+{
+  "id": "mma_core_engine_20260224",
+  "title": "MMA Core Engine Implementation",
+  "status": "planning",
+  "created_at": "2026-02-24T00:00:00.000000"
+}

conductor/tracks/mma_core_engine_20260224/plan.md

@@ -0,0 +1,48 @@
+# Implementation Plan: MMA Core Engine Implementation
+
+## Phase 1: Track 1 - The Memory Foundations (AST Parser)
+- [ ] Task: Dependency Setup
+    - [ ] Add `tree-sitter` and `tree-sitter-python` to `pyproject.toml` / `requirements.txt`
+- [ ] Task: Core Parser Class
+    - [ ] Create `ASTParser` in `file_cache.py`
+- [ ] Task: Skeleton View Extraction
+    - [ ] Write query to extract `function_definition` and `class_definition`
+    - [ ] Replace bodies with `pass`, keep type hints and signatures
+- [ ] Task: Curated View Extraction
+    - [ ] Keep class structures, module docstrings
+    - [ ] Preserve `@core_logic` or `# [HOT]` function bodies, hide others
+
+## Phase 2: Track 2 - State Machine & Data Structures
+- [ ] Task: The Dataclasses
+    - [ ] Create `models.py` defining `Ticket` and `Track`
+- [ ] Task: Worker Context Definition
+    - [ ] Define `WorkerContext` holding `Ticket` ID, model config, and ephemeral messages
+- [ ] Task: State Mutator Methods
+    - [ ] Implement `ticket.mark_blocked()`, `ticket.mark_complete()`, `track.get_executable_tickets()`
+
+## Phase 3: Track 3 - The Linear Orchestrator & Execution Clutch
+- [ ] Task: The Engine Core
+    - [ ] Create `multi_agent_conductor.py` containing `ConductorEngine` and `run_worker_lifecycle`
+- [ ] Task: Context Injection
+    - [ ] Format context strings using `file_cache.py` target AST views
+- [ ] Task: The HITL Execution Clutch
+    - [ ] Before executing `write_file`/`shell_runner.py` tools in step-mode, prompt user for confirmation
+    - [ ] Provide functionality to mutate the history JSON before resuming execution
+
+## Phase 4: Track 4 - Tier 4 QA Interception
+- [ ] Task: The Interceptor Loop
+    - [ ] Catch `subprocess.run()` execution errors inside `shell_runner.py`
+- [ ] Task: Tier 4 Instantiation
+    - [ ] Make a secondary API call to `default_cheap` model passing `stderr` and snippet
+- [ ] Task: Payload Formatting
+    - [ ] Inject the 20-word fix summary into the Tier 3 worker history
+
+## Phase 5: Track 5 - UI Decoupling & Tier 1/2 Routing (The Final Boss)
+- [ ] Task: The Event Bus
+    - [ ] Implement an `asyncio.Queue` linking GUI actions to the backend engine
+- [ ] Task: Tier 1 & 2 System Prompts
+    - [ ] Create structured system prompts for Epic routing and Ticket creation
+- [ ] Task: The Dispatcher Loop
+    - [ ] Read Tier 2 JSON flat-lists, construct Tickets, execute Stub resolution paths
+- [ ] Task: UI Component Update
+    - [ ] Refactor `gui_2.py` to push `UserRequestEvent` instead of blocking on API generation

conductor/tracks/mma_core_engine_20260224/spec.md

@@ -0,0 +1,36 @@
+# Specification: MMA Core Engine Implementation
+
+## 1. Overview
+This track consolidates the implementation of the 4-Tier Hierarchical Multi-Model Architecture into the `manual_slop` codebase. The architecture transitions the current monolithic single-agent loop into a compartmentalized, token-efficient, and fully debuggable state machine.
+
+## 2. Functional Requirements
+
+### Phase 1: The Memory Foundations (AST Parser)
+- Integrate `tree-sitter` and `tree-sitter-python` into `pyproject.toml` / `requirements.txt`.
+- Implement `ASTParser` in `file_cache.py` to extract strict memory views (Skeleton View, Curated View).
+- Strip function bodies from dependencies while preserving `@core_logic` or `# [HOT]` logic for the target modules.
+
+### Phase 2: State Machine & Data Structures
+- Create `models.py` incorporating strict Pydantic/Dataclass schemas for `Ticket`, `Track`, and `WorkerContext`.
+- Enforce rigid state mutators governing dependencies between tickets (e.g., locking execution until a stub generation ticket completes).
+
+### Phase 3: The Linear Orchestrator & Execution Clutch
+- Build `multi_agent_conductor.py` and a `ConductorEngine` dispatcher loop.
+- Embed the "Execution Clutch" allowing developers to pause, review, and manually rewrite payloads (JSON history mutation) before applying changes to the local filesystem.
+
+### Phase 4: Tier 4 QA Interception
+- Augment `shell_runner.py` with try/except wrappers capturing process errors (`stderr`).
+- Rather than feeding raw stack traces to an expensive model, instantly forward them to a stateless `default_cheap` sub-agent for a 20-word summarization that is subsequently injected into the primary worker's context.
+
+### Phase 5: UI Decoupling & Tier 1/2 Routing (The Final Boss)
+- Disconnect `gui_2.py` from direct LLM inference requests.
+- Bind the GUI to a synchronous or `asyncio.Queue` Event Bus managed by the Orchestrator, allowing dynamic tracking of parallel worker executions without thread-locking the interface.
+
+## 3. Acceptance Criteria
+- [ ] A 1000-line script can be successfully parsed into a 100-line AST Skeleton.
+- [ ] Tickets properly block and resolve depending on stub-generation dependencies.
+- [ ] Shell errors are compressed into >50-token hints using the cheap utility model.
+- [ ] The GUI remains responsive during multi-model generation phases.
+
+## 4. Meta-Track Reference
+For the original rationale, API formatting recommendations (e.g., Godot ECS schemas vs Nested JSON), and strict token firewall workflows, refer back to the architectural planning meta-track: `conductor/tracks/mma_implementation_20260224/`.

conductor/tracks/mma_state_machine_data_structures_20260224/metadata.json

@@ -1,6 +0,0 @@
-{
-  "id": "mma_state_machine_data_structures_20260224",
-  "title": "State Machine & Data Structures",
-  "status": "planning",
-  "created_at": "2026-02-24T22:44:11.756941"
-}

conductor/tracks/mma_state_machine_data_structures_20260224/plan.md

@@ -1,7 +0,0 @@
-# Implementation Plan: State Machine & Data Structures
-
-- [ ] Task: Create \	ests/test_models.py\.
-- [ ] Task: Write failing tests that instantiate \Track\, \Ticket\, and \WorkerContext\ with various valid and invalid schemas.
-- [ ] Task: Write tests that assert state transitions (e.g., from \pending\ to \locked\, from \step_paused\ to \completed\) correctly update internal flags and dependencies.
-- [ ] Task: **Red Phase:** Tests fail because \models.py\ classes are undefined or lack transition methods.
-- [ ] Task: **Green Phase:** Implement the dataclasses and state mutators.

conductor/tracks/mma_state_machine_data_structures_20260224/spec.md

@@ -1,5 +0,0 @@
-# Specification: State Machine & Data Structures
-
-## Goal
-Define the rigid Python objects (Pydantic/Dataclasses) that AI agents will pass to each other, enforcing structured data over loose chat strings.
-

conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/metadata.json

@@ -1,6 +0,0 @@
-{
-  "id": "mma_the_linear_orchestrator_execution_clutch_20260224",
-  "title": "The Linear Orchestrator & Execution Clutch",
-  "status": "planning",
-  "created_at": "2026-02-24T22:44:11.757962"
-}

conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/plan.md

@@ -1,8 +0,0 @@
-# Implementation Plan: The Linear Orchestrator & Execution Clutch
-
-- [ ] Task: Create \	ests/test_conductor.py\.
-- [ ] Task: Write tests that mock the AI client response (e.g., returning a mock tool call like \write_file\).
-- [ ] Task: Test that \
-- [ ] Task: Test that execution pauses (waits for a simulated human signal) when the \	rust_level\ dictates.
-- [ ] Task: **Red Phase:** Failure occurs because \multi_agent_conductor.py\ lacks the lifecycle execution loop.
-- [ ] Task: **Green Phase:** Implement the \ConductorEngine\ core execution block.

conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/spec.md

@@ -1,5 +0,0 @@
-# Specification: The Linear Orchestrator & Execution Clutch
-
-## Goal
-Build the synchronous, debuggable core loop that runs a single Tier 3 Worker and pauses for human approval.
-

conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/metadata.json

@@ -1,6 +0,0 @@
-{
-  "id": "mma_the_memory_foundations_ast_parser_20260224",
-  "title": "The Memory Foundations (AST Parser)",
-  "status": "planning",
-  "created_at": "2026-02-24T22:44:11.755925"
-}

conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/plan.md

@@ -1,7 +0,0 @@
-# Implementation Plan: The Memory Foundations (AST Parser)
-
-- [ ] Task: Create `tests/test_file_cache_ast.py`.
-- [ ] Task: Define mock Python source files containing various structures (classes, functions, docstrings, `@core_logic` decorators, `# [HOT]` comments).
-- [ ] Task: Write failing tests that instantiate `ASTParser` and assert that `get_skeleton_view()` and `get_curated_view()` return the precisely filtered strings.
-- [ ] Task: **Red Phase:** Ensure tests fail because `ASTParser` does not exist.
-- [ ] Task: **Green Phase:** Implement the tree-sitter logic iteratively until strings match exactly.

conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/spec.md

@@ -1,5 +0,0 @@
-# Specification: The Memory Foundations (AST Parser)
-
-## Goal
-Build the engine that prevents token-bloat by turning massive source files into curated memory views.
-

conductor/tracks/mma_tier_4_qa_interception_20260224/metadata.json

@@ -1,6 +0,0 @@
-{
-  "id": "mma_tier_4_qa_interception_20260224",
-  "title": "Tier 4 QA Interception",
-  "status": "planning",
-  "created_at": "2026-02-24T22:44:11.758965"
-}

conductor/tracks/mma_tier_4_qa_interception_20260224/plan.md

@@ -1,8 +0,0 @@
-# Implementation Plan: Tier 4 QA Interception
-
-- [ ] Task: Create \	ests/test_shell_runner.py\.
-- [ ] Task: Write tests that mock a local execution failure (e.g., returning a mock 3000-line Python stack trace).
-- [ ] Task: Test that the error is intercepted and passed to a mock Tier 4 agent.
-- [ ] Task: Test that the output is compressed into a 20-word fix before returning.
-- [ ] Task: **Red Phase:** Fails because no interception loop exists in \shell_runner.py\.
-- [ ] Task: **Green Phase:** Implement the try/except logic handling \subprocess.run()\ with \

conductor/tracks/mma_tier_4_qa_interception_20260224/spec.md

@@ -1,5 +0,0 @@
-# Specification: Tier 4 QA Interception
-
-## Goal
-Stop error traces from destroying the Worker's token window by routing crashes through a cheap, stateless translator.
-

conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/metadata.json

@@ -1,6 +0,0 @@
-{
-  "id": "mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224",
-  "title": "UI Decoupling & Tier 1/2 Routing (The Final Boss)",
-  "status": "planning",
-  "created_at": "2026-02-24T22:44:11.759465"
-}

conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/plan.md

@@ -1,7 +0,0 @@
-# Implementation Plan: UI Decoupling & Tier 1/2 Routing (The Final Boss)
-
-- [ ] Task: Create \	ests/test_gui_decoupling.py\.
-- [ ] Task: Write tests that instantiate a mocked GUI instance listening to an \syncio.Queue\.
-- [ ] Task: Mock pushing \TrackStateUpdated\ and \TicketStarted\ events into the queue and ensure the GUI updates its view state rather than calling LLM endpoints directly.
-- [ ] Task: **Red Phase:** Failure occurs because \gui_2.py\ is tightly coupled with \i_client.py\ logic.
-- [ ] Task: **Green Phase:** Implement the \AgentBus\ messaging system linking \multi_agent_conductor.py\ to \gui_2.py\.

conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/spec.md

@@ -1,5 +0,0 @@
-# Specification: UI Decoupling & Tier 1/2 Routing (The Final Boss)
-
-## Goal
-Bring the whole system online by letting Tier 1 and Tier 2 generate Tickets dynamically, managed via an asynchronous Event Bus.
-