diff --git a/.gemini/skills/mma-tier1-orchestrator/SKILL.md b/.gemini/skills/mma-tier1-orchestrator/SKILL.md index c24eec3..2371ce8 100644 --- a/.gemini/skills/mma-tier1-orchestrator/SKILL.md +++ b/.gemini/skills/mma-tier1-orchestrator/SKILL.md @@ -7,12 +7,33 @@ description: Focused on product alignment, high-level planning, and track initia You are the Tier 1 Orchestrator. Your role is to oversee the product direction and manage project/track initialization within the Conductor framework. +## Primary Context Documents +Read at session start: `conductor/product.md`, `conductor/product-guidelines.md` + +## Architecture Fallback +When planning tracks that touch core systems, consult: +- `docs/guide_architecture.md`: Threading, events, AI client, HITL, frame-sync action catalog +- `docs/guide_tools.md`: MCP Bridge, Hook API endpoints, ApiHookClient methods +- `docs/guide_mma.md`: Ticket/Track structures, DAG engine, ConductorEngine, worker lifecycle +- `docs/guide_simulations.md`: live_gui fixture, Puppeteer pattern, mock provider + ## Responsibilities - Maintain alignment with the product guidelines and definition. - Define track boundaries and initialize new tracks (`/conductor:newTrack`). - Set up the project environment (`/conductor:setup`). - Delegate track execution to the Tier 2 Tech Lead. +## Surgical Spec Protocol (MANDATORY) +When creating or refining tracks, you MUST: +1. **Audit** the codebase with `get_code_outline`, `py_get_definition`, `grep_search` before writing any spec. Document what exists with file:line refs. +2. **Spec gaps, not features** — frame requirements relative to what already exists. +3. **Write worker-ready tasks** — each specifies WHERE (file:line), WHAT (change), HOW (API call), SAFETY (thread constraints). +4. **For fix tracks** — list root cause candidates with code-level reasoning. +5. **Reference architecture docs** — link to relevant `docs/guide_*.md` sections. +6. **Map dependencies** — state execution order and blockers between tracks. + +See `activate_skill mma-orchestrator` for the full protocol and examples. + ## Limitations - Do not execute tracks or implement features. - Do not write code or perform low-level bug fixing. diff --git a/.gemini/skills/mma-tier2-tech-lead/SKILL.md b/.gemini/skills/mma-tier2-tech-lead/SKILL.md index 52a49bf..1d83eb7 100644 --- a/.gemini/skills/mma-tier2-tech-lead/SKILL.md +++ b/.gemini/skills/mma-tier2-tech-lead/SKILL.md @@ -7,6 +7,13 @@ description: Focused on track execution, architectural design, and implementatio You are the Tier 2 Tech Lead. Your role is to manage the implementation of tracks (`/conductor:implement`), ensure architectural integrity, and oversee the work of Tier 3 and 4 sub-agents. +## Architecture Fallback +When implementing tracks, consult these docs for threading, data flow, and module interactions: +- `docs/guide_architecture.md`: Thread domains, `_process_pending_gui_tasks` action catalog, AI client architecture, HITL blocking flow +- `docs/guide_tools.md`: MCP tools, Hook API endpoints, session logging +- `docs/guide_mma.md`: Ticket/Track structures, DAG engine, worker lifecycle +- `docs/guide_simulations.md`: Testing patterns, mock provider + ## Responsibilities - Manage the execution of implementation tracks. - Ensure alignment with `tech-stack.md` and project architecture. @@ -14,6 +21,15 @@ You are the Tier 2 Tech Lead. Your role is to manage the implementation of track - Maintain persistent context throughout a track's implementation phase (No Context Amnesia). - Review implementations and coordinate bug fixes via Tier 4 QA. +## Surgical Delegation Protocol +When delegating to Tier 3 workers, construct prompts that specify: +- **WHERE**: Exact file and line range to modify +- **WHAT**: The specific change (add function, modify dict, extend table) +- **HOW**: Which API calls, data structures, or patterns to use +- **SAFETY**: Thread-safety constraints (e.g., "push via `_pending_gui_tasks` with lock") + +Example prompt: `"In gui_2.py, modify _render_mma_dashboard (lines 2685-2699). Extend the token usage table from 3 to 5 columns by adding 'Model' and 'Est. Cost'. Use imgui.table_setup_column(). Import cost_tracker. Use 1-space indentation."` + ## Limitations - Do not perform heavy implementation work directly; delegate to Tier 3. - Delegate implementation tasks to Tier 3 Workers using `uv run python scripts/mma_exec.py --role tier3-worker "[PROMPT]"`. diff --git a/mma-orchestrator/SKILL.md b/mma-orchestrator/SKILL.md index b9e08c7..9033c85 100644 --- a/mma-orchestrator/SKILL.md +++ b/mma-orchestrator/SKILL.md @@ -13,16 +13,46 @@ To accomplish this, you MUST delegate token-heavy or stateless tasks to **Tier 3 To ensure proper environment handling and logging, you MUST NOT call the `gemini` command directly for sub-tasks. Instead, use the wrapper script: `uv run python scripts/mma_exec.py --role "..."` +## 0. Architecture Fallback & Surgical Methodology + +**Before creating or refining any track**, consult the deep-dive architecture docs: +- `docs/guide_architecture.md`: Thread domains, event system (`AsyncEventQueue`, `_pending_gui_tasks` action catalog), AI client multi-provider architecture, HITL Execution Clutch blocking flow, frame-sync mechanism +- `docs/guide_tools.md`: MCP Bridge 3-layer security model, full 26-tool inventory with params, Hook API GET/POST endpoints with request/response formats, ApiHookClient method reference +- `docs/guide_mma.md`: Ticket/Track/WorkerContext data structures, DAG engine (cycle detection, topological sort), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia +- `docs/guide_simulations.md`: `live_gui` fixture lifecycle, Puppeteer pattern, mock provider JSON-L protocol, visual verification patterns + +### The Surgical Spec Protocol (MANDATORY for track creation) + +When creating tracks (`activate_skill mma-tier1-orchestrator`), follow this protocol: + +1. **AUDIT BEFORE SPECIFYING**: Use `get_code_outline`, `py_get_definition`, `grep_search`, and `get_git_diff` to map what already exists. Previous track specs asked to re-implement existing features (Track Browser, DAG tree, approval dialogs) because no audit was done. Document findings in a "Current State Audit" section with file:line references. + +2. **GAPS, NOT FEATURES**: Frame requirements as what's MISSING relative to what exists. + - GOOD: "The existing `_render_mma_dashboard` (gui_2.py:2633-2724) has a token usage table but no cost column." + - BAD: "Build a metrics dashboard with token and cost tracking." + +3. **WORKER-READY TASKS**: Each plan task must specify: + - **WHERE**: Exact file and line range (`gui_2.py:2700-2701`) + - **WHAT**: The specific change (add function, modify dict, extend table) + - **HOW**: Which API calls (`imgui.progress_bar(...)`, `imgui.collapsing_header(...)`) + - **SAFETY**: Thread-safety constraints if cross-thread data is involved + +4. **ROOT CAUSE ANALYSIS** (for fix tracks): Don't write "investigate and fix." List specific candidates with code-level reasoning. + +5. **REFERENCE DOCS**: Link to relevant `docs/guide_*.md` sections in every spec. + +6. **MAP DEPENDENCIES**: State execution order and blockers between tracks. + ## 1. The Tier 3 Worker (Execution) When performing code modifications or implementing specific requirements: 1. **Pre-Delegation Checkpoint:** For dangerous or non-trivial changes, ALWAYS stage your changes (`git add .`) or commit before delegating to a Tier 3 Worker. If the worker fails or runs `git restore`, you will lose all prior AI iterations for that file if it wasn't staged/committed. 2. **Code Style Enforcement:** You MUST explicitly remind the worker to "use exactly 1-space indentation for Python code" in your prompt to prevent them from breaking the established codebase style. 3. **DO NOT** perform large code writes yourself. -4. **DO** construct a single, highly specific prompt with a clear objective. +4. **DO** construct a single, highly specific prompt with a clear objective. Include exact file:line references and the specific API calls to use (from your audit or the architecture docs). 5. **DO** spawn a Tier 3 Worker. - *Command:* `uv run python scripts/mma_exec.py --role tier3-worker "Implement [SPECIFIC_INSTRUCTION] in [FILE_PATH]. Use 1-space indentation. Follow TDD and return success status or code changes."` + *Command:* `uv run python scripts/mma_exec.py --role tier3-worker "Implement [SPECIFIC_INSTRUCTION] in [FILE_PATH] at lines [N-M]. Use [SPECIFIC_API_CALL]. Use 1-space indentation."` 6. **Handling Repeated Failures:** If a Tier 3 Worker fails multiple times on the same task, it may lack the necessary capability. You must track failures and retry with `--failure-count ` (e.g., `--failure-count 2`). This tells `mma_exec.py` to escalate the sub-agent to a more powerful reasoning model (like `gemini-3-flash`). -7. The Tier 3 Worker is stateless and has tool access for file I/O. +7. The Tier 3 Worker is stateless and has tool access for file I/O. ## 2. The Tier 4 QA Agent (Diagnostics) If you run a test or command that fails with a significant error or large traceback: @@ -38,15 +68,23 @@ Unlike the stateless sub-agents (Tiers 3 & 4), the **Tier 2 Tech Lead** maintain To minimize context bloat for Tier 2 & 3: 1. Use `py_get_code_outline` or `get_tree` to map out the structure of a file or project. 2. Use `py_get_skeleton` and `py_get_imports` to understand the interface, docstrings, and dependencies of modules. -3. Use `py_find_usages` to pinpoint where a function or class is called instead of searching the whole codebase. -4. Use `py_check_syntax` after making string replacements to ensure the file is still syntactically valid. -5. Only use `read_file` with `start_line` and `end_line` for specific implementation details once target areas are identified. -6. Tier 3 workers MUST NOT read the full content of unrelated files. +3. Use `py_get_definition` to read specific functions/classes by name without loading entire files. +4. Use `py_find_usages` to pinpoint where a function or class is called instead of searching the whole codebase. +5. Use `py_check_syntax` after making string replacements to ensure the file is still syntactically valid. +6. Only use `read_file` with `start_line` and `end_line` for specific implementation details once target areas are identified. +7. Tier 3 workers MUST NOT read the full content of unrelated files. + +## 5. Cross-Skill Activation +When your current role requires capabilities from another tier, use `activate_skill`: +- **Track creation/refinement**: `activate_skill mma-tier1-orchestrator` — applies the Surgical Spec Protocol +- **Track execution**: `activate_skill mma-tier2-tech-lead` — applies persistent context and TDD workflow +- **Quick code task**: Spawn via `mma_exec.py --role tier3-worker` (stateless, no skill activation needed) +- **Error analysis**: Spawn via `mma_exec.py --role tier4-qa` (stateless, no skill activation needed) ### Example 1: Spawning a Tier 4 QA Agent **User / System:** `pytest tests/test_gui.py` failed with 400 lines of output. -**Agent (You):** +**Agent (You):** ```json { "command": "python scripts/mma_exec.py --role tier4-qa \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"", @@ -54,15 +92,24 @@ To minimize context bloat for Tier 2 & 3: } ``` -### Example 2: Spawning a Tier 3 Worker -**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1. +### Example 2: Spawning a Tier 3 Worker with Surgical Prompt +**User:** Please implement the cost tracking column in the token usage table. **Agent (You):** ```json { - "command": "python scripts/mma_exec.py --role tier3-worker \"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." + "command": "python scripts/mma_exec.py --role tier3-worker \"In gui_2.py, modify _render_mma_dashboard (lines 2685-2699). Extend the token usage table from 3 columns to 5 by adding 'Model' and 'Est. Cost' columns. Use imgui.table_setup_column() for the new columns. Import cost_tracker and call cost_tracker.estimate_cost(model, input_tokens, output_tokens) for each tier row. Add a total row at the bottom. Use 1-space indentation.\"", + "description": "Delegating surgical implementation to Tier 3 Worker with exact line refs." } ``` + +### Example 3: Creating a Track with Audit +**User:** Create a track for adding dark mode support. +**Agent (You):** +1. First, audit the codebase: `py_get_code_outline gui_2.py` → find `_render_theme_panel` (lines 2993-3030). +2. Read the existing implementation: `py_get_definition gui_2.py _render_theme_panel`. +3. Check for existing color constants: `grep_search "vec4\|C_" gui_2.py`. +4. Now write the spec with a "Current State Audit" section documenting what the theme panel already does. +5. Write tasks referencing the exact lines and imgui color APIs to use. @@ -70,4 +117,5 @@ To minimize context bloat for Tier 2 & 3: - 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 +- When creating or refining conductor tracks (MUST follow Surgical Spec Protocol). +