diff --git a/MMA_Support/mma_tiered_orchestrator_skill.md b/MMA_Support/mma_tiered_orchestrator_skill.md new file mode 100644 index 0000000..c4cc0ae --- /dev/null +++ b/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. + + +# 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. + + + +### 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." +} +``` + + + +- 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. + \ No newline at end of file diff --git a/conductor/tracks.md b/conductor/tracks.md index 50c70d1..bd7cdc5 100644 --- a/conductor/tracks.md +++ b/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)** -*Link: [./tracks/mma_the_memory_foundations_ast_parser_20260224/](./tracks/mma_the_memory_foundations_ast_parser_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/)* - +- [ ] **Track: MMA Core Engine Implementation** +*Link: [./tracks/mma_core_engine_20260224/](./tracks/mma_core_engine_20260224/)* diff --git a/conductor/tracks/mma_core_engine_20260224/index.md b/conductor/tracks/mma_core_engine_20260224/index.md new file mode 100644 index 0000000..1403b30 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/conductor/tracks/mma_core_engine_20260224/metadata.json b/conductor/tracks/mma_core_engine_20260224/metadata.json new file mode 100644 index 0000000..b08a27f --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/conductor/tracks/mma_core_engine_20260224/plan.md b/conductor/tracks/mma_core_engine_20260224/plan.md new file mode 100644 index 0000000..8b4c11c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/conductor/tracks/mma_core_engine_20260224/spec.md b/conductor/tracks/mma_core_engine_20260224/spec.md new file mode 100644 index 0000000..4720153 --- /dev/null +++ b/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/`. \ No newline at end of file diff --git a/conductor/tracks/mma_state_machine_data_structures_20260224/metadata.json b/conductor/tracks/mma_state_machine_data_structures_20260224/metadata.json deleted file mode 100644 index 42b2c1a..0000000 --- a/conductor/tracks/mma_state_machine_data_structures_20260224/metadata.json +++ /dev/null @@ -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" -} \ No newline at end of file diff --git a/conductor/tracks/mma_state_machine_data_structures_20260224/plan.md b/conductor/tracks/mma_state_machine_data_structures_20260224/plan.md deleted file mode 100644 index abc1983..0000000 --- a/conductor/tracks/mma_state_machine_data_structures_20260224/plan.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/conductor/tracks/mma_state_machine_data_structures_20260224/spec.md b/conductor/tracks/mma_state_machine_data_structures_20260224/spec.md deleted file mode 100644 index 19c96fc..0000000 --- a/conductor/tracks/mma_state_machine_data_structures_20260224/spec.md +++ /dev/null @@ -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. - diff --git a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/metadata.json b/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/metadata.json deleted file mode 100644 index c2c148c..0000000 --- a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/metadata.json +++ /dev/null @@ -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" -} \ No newline at end of file diff --git a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/plan.md b/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/plan.md deleted file mode 100644 index 5023a9a..0000000 --- a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/plan.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/spec.md b/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/spec.md deleted file mode 100644 index 9561aab..0000000 --- a/conductor/tracks/mma_the_linear_orchestrator_execution_clutch_20260224/spec.md +++ /dev/null @@ -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. - diff --git a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/metadata.json b/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/metadata.json deleted file mode 100644 index 5a77218..0000000 --- a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/metadata.json +++ /dev/null @@ -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" -} \ No newline at end of file diff --git a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/plan.md b/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/plan.md deleted file mode 100644 index 6392d79..0000000 --- a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/plan.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/spec.md b/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/spec.md deleted file mode 100644 index 00f6705..0000000 --- a/conductor/tracks/mma_the_memory_foundations_ast_parser_20260224/spec.md +++ /dev/null @@ -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. - diff --git a/conductor/tracks/mma_tier_4_qa_interception_20260224/metadata.json b/conductor/tracks/mma_tier_4_qa_interception_20260224/metadata.json deleted file mode 100644 index 951e656..0000000 --- a/conductor/tracks/mma_tier_4_qa_interception_20260224/metadata.json +++ /dev/null @@ -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" -} \ No newline at end of file diff --git a/conductor/tracks/mma_tier_4_qa_interception_20260224/plan.md b/conductor/tracks/mma_tier_4_qa_interception_20260224/plan.md deleted file mode 100644 index c8e7dbe..0000000 --- a/conductor/tracks/mma_tier_4_qa_interception_20260224/plan.md +++ /dev/null @@ -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 \ \ No newline at end of file diff --git a/conductor/tracks/mma_tier_4_qa_interception_20260224/spec.md b/conductor/tracks/mma_tier_4_qa_interception_20260224/spec.md deleted file mode 100644 index f03aec8..0000000 --- a/conductor/tracks/mma_tier_4_qa_interception_20260224/spec.md +++ /dev/null @@ -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. - diff --git a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/metadata.json b/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/metadata.json deleted file mode 100644 index 7805ca1..0000000 --- a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/metadata.json +++ /dev/null @@ -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" -} \ No newline at end of file diff --git a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/plan.md b/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/plan.md deleted file mode 100644 index 3d9cac7..0000000 --- a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/plan.md +++ /dev/null @@ -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\. \ No newline at end of file diff --git a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/spec.md b/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/spec.md deleted file mode 100644 index e74079b..0000000 --- a/conductor/tracks/mma_ui_decoupling_tier_1_2_routing_the_final_boss_20260224/spec.md +++ /dev/null @@ -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. -