From d575ebb4710c1b8cd3adadf0a5e8c3b350b5b2fd Mon Sep 17 00:00:00 2001 From: Ed_ Date: Fri, 6 Mar 2026 10:18:16 -0500 Subject: [PATCH] adjustments --- conductor/code_styleguides/python.md | 10 ++- conductor/product-guidelines.md | 2 + conductor/product.md | 5 ++ .../tracks/ux_sim_test_20260305/metadata.json | 8 -- conductor/tracks/ux_sim_test_20260305/plan.md | 3 - conductor/tracks/ux_sim_test_20260305/spec.md | 5 -- conductor/workflow.md | 75 ++----------------- 7 files changed, 21 insertions(+), 87 deletions(-) delete mode 100644 conductor/tracks/ux_sim_test_20260305/metadata.json delete mode 100644 conductor/tracks/ux_sim_test_20260305/plan.md delete mode 100644 conductor/tracks/ux_sim_test_20260305/spec.md diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index b82c566..a6ebf27 100644 --- a/conductor/code_styleguides/python.md +++ b/conductor/code_styleguides/python.md @@ -5,6 +5,7 @@ These deviate from PEP 8 / Google style to minimize token consumption when code is processed by AI agents, while preserving readability for human review. ## 1. Indentation and Whitespace + - **Indentation:** 1 space per level. No tabs. - **Continuation lines:** 1 space relative to the opening construct. - **Blank lines:** Zero blank lines between function/method definitions within a class. One blank line between top-level definitions only when separating logically distinct sections. @@ -12,6 +13,7 @@ is processed by AI agents, while preserving readability for human review. - **Rationale:** 1-space indentation reduces token count by ~40% compared to 4-space on deeply nested GUI code, with no loss of structural clarity for AST-based tools. ## 2. Type Annotations + - **All functions and methods** must have return type annotations. - **All parameters** (except `self`/`cls`) must have type annotations. - **Module-level and class-level variables** must have type annotations. @@ -20,18 +22,21 @@ is processed by AI agents, while preserving readability for human review. - **DearPyGui / ImGui callbacks:** Use `sender: Any, app_data: Any` for framework callbacks where the types are runtime-determined. ## 3. Imports + - Use `from __future__ import annotations` at the top of every module. - Group imports: stdlib, third-party, local — separated by a blank line. - Use `from typing import Any, Optional, Callable` etc. for type-only imports. - Prefer `from x import Y` for specific symbols over `import x` when only one or two names are used. ## 4. Naming + - **snake_case** for modules, functions, methods, variables. - **PascalCase** for classes. - **ALL_CAPS** for module-level constants. - **Single leading underscore** (`_name`) for internal/private members. ## 5. Docstrings + - Required on classes and non-trivial public functions. - Use `"""triple double quotes"""`. - One-line summary is sufficient for simple methods. @@ -48,17 +53,18 @@ is processed by AI agents, while preserving readability for human review. - Prefer `if x is None:` over `if not x:` when testing for None specifically. ## 8. AI-Agent Specific Conventions + - **No redundant comments.** Do not add comments that restate what the code does. Only comment on *why* when non-obvious. - **No empty `__init__.py` files.** - **Minimal blank lines.** Token-efficient density is preferred over visual padding. - **Short variable names are acceptable** in tight scopes (loop vars, lambdas). Use descriptive names for module-level and class attributes. ## 9. Line Length + - Soft limit: 120 characters. - Hard limit: None — let the formatter handle wrapping if needed. - Rationale: 80-char limits cause excessive line continuations that waste tokens. ## 10. Main Guard -- All executable files should have `if __name__ == "__main__":` calling `main()`. -**BE CONSISTENT.** When editing existing code, match the style already present in the file. +- All executable files should have `if __name__ == "__main__":` calling `main()`. diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 0aa340e..a7f1d6b 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -21,7 +21,9 @@ - **Strict State Management:** There must be a rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should *never* hang during AI communication or script execution. Use lock-protected queues and events for synchronization. - **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability. - **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages. + ## AI-Optimized Compact Style + - **Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures. - **Newlines:** Maximum **one (1)** blank line between top-level definitions. **Zero (0)** blank lines within function or method bodies. - **Type Hinting:** Mandatory, strict type hints for all parameters, return types, and global variables to ensure high-signal context for AI agents. diff --git a/conductor/product.md b/conductor/product.md index 66576f6..a66e704 100644 --- a/conductor/product.md +++ b/conductor/product.md @@ -1,10 +1,13 @@ # Product Guide: Manual Slop ## Vision + To serve as an expert-level utility for personal developer use on small projects, providing full, manual control over vendor API metrics, agent capabilities, and context memory usage. ## Architecture Reference + For deep implementation details when planning or implementing tracks, consult `docs/` (last updated: 08e003a): + - **[docs/guide_architecture.md](../docs/guide_architecture.md):** Threading model, event system, AI client, HITL mechanism - **[docs/guide_meta_boundary.md](../docs/guide_meta_boundary.md):** The critical distinction between the Application's Strict-HITL environment and the Meta-Tooling environment used to build it. - **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge, Hook API, ApiHookClient, shell runner @@ -12,11 +15,13 @@ For deep implementation details when planning or implementing tracks, consult `d - **[docs/guide_simulations.md](../docs/guide_simulations.md):** Test framework, mock provider, verification patterns ## Primary Use Cases + - **Full Control over Vendor APIs:** Exposing detailed API metrics and configuring deep agent capabilities directly within the GUI. - **Context & Memory Management:** Better visualization and management of token usage and context memory, allowing developers to optimize prompt limits manually. - **Manual "Vibe Coding" Assistant:** Serving as an auxiliary, multi-provider assistant that natively interacts with the codebase via sandboxed PowerShell scripts and MCP-like file tools, emphasizing manual developer oversight and explicit confirmation. ## Key Features + - **Multi-Provider Integration:** Supports Gemini, Anthropic, and DeepSeek with seamless switching. - **4-Tier Hierarchical Multi-Model Architecture:** Orchestrates an intelligent cascade of specialized models to isolate cognitive loads and minimize token burn. - **Tier 1 (Orchestrator):** Strategic product alignment, setup (`/conductor:setup`), and track initialization (`/conductor:newTrack`) using `gemini-3.1-pro-preview`. diff --git a/conductor/tracks/ux_sim_test_20260305/metadata.json b/conductor/tracks/ux_sim_test_20260305/metadata.json deleted file mode 100644 index 127365d..0000000 --- a/conductor/tracks/ux_sim_test_20260305/metadata.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "id": "ux_sim_test_20260305", - "title": "UX_SIM_TEST", - "description": "Simulation testing for GUI UX", - "type": "feature", - "status": "new", - "progress": 0.0 -} \ No newline at end of file diff --git a/conductor/tracks/ux_sim_test_20260305/plan.md b/conductor/tracks/ux_sim_test_20260305/plan.md deleted file mode 100644 index 5f17e2c..0000000 --- a/conductor/tracks/ux_sim_test_20260305/plan.md +++ /dev/null @@ -1,3 +0,0 @@ -# Implementation Plan: UX_SIM_TEST - -- [ ] Task 1: Initialize diff --git a/conductor/tracks/ux_sim_test_20260305/spec.md b/conductor/tracks/ux_sim_test_20260305/spec.md deleted file mode 100644 index 6b42dbd..0000000 --- a/conductor/tracks/ux_sim_test_20260305/spec.md +++ /dev/null @@ -1,5 +0,0 @@ -# Specification: UX_SIM_TEST - -Type: feature - -Description: Simulation testing for GUI UX diff --git a/conductor/workflow.md b/conductor/workflow.md index 4dd0aab..2364eb2 100644 --- a/conductor/workflow.md +++ b/conductor/workflow.md @@ -34,8 +34,6 @@ with open('file.py', 'w', encoding='utf-8', newline='') as f: ## Guiding Principles -## Guiding Principles - 1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md` 2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation 3. **Test-Driven Development:** Write unit tests before implementing functionality @@ -360,93 +358,32 @@ A task is complete when: 8. Changes committed with proper message 9. Git note with task summary attached to the commit -## Emergency Procedures - -### Critical Bug in Production - -1. Create hotfix branch from main -2. Write failing test for bug -3. Implement minimal fix -4. Test thoroughly including mobile -5. Deploy immediately -6. Document in plan.md - -### Data Loss - -1. Stop all write operations -2. Restore from latest backup -3. Verify data integrity -4. Document incident -5. Update backup procedures - -### Security Breach - -1. Rotate all secrets immediately -2. Review access logs -3. Patch vulnerability -4. Notify affected users (if any) -5. Document and update security procedures - -## Deployment Workflow - -### Pre-Deployment Checklist - -- [ ] All tests passing -- [ ] Coverage >80% -- [ ] No linting errors -- [ ] Mobile testing complete -- [ ] Environment variables configured -- [ ] Database migrations ready -- [ ] Backup created - -### Deployment Steps - -1. Merge feature branch to main -2. Tag release with version -3. Push to deployment service -4. Run database migrations -5. Verify deployment -6. Test critical paths -7. Monitor for errors - -### Post-Deployment - -1. Monitor analytics -2. Check error logs -3. Gather user feedback -4. Plan next iteration - -## Continuous Improvement - -- Review workflow weekly -- Update based on pain points -- Document lessons learned -- Optimize for user happiness -- Keep things simple and maintainable - ## Conductor Token Firewalling & Model Switching Strategy To emulate the 4-Tier MMA Architecture within the standard Conductor extension without requiring a custom fork, adhere to these strict workflow policies: ### 1. Active Model Switching (Simulating the 4 Tiers) + - **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`). This is crucial for enforcing the 4-Tier token firewall. -- **The MMA Bridge (`mma_exec.py`):** All tiered delegation is routed through `python scripts/mma_exec.py`. This script acts as the primary bridge, managing model selection, context injection, and logging. +- **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. - **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:** `python scripts/mma_exec.py --role tier3-worker "[PROMPT]"` - - **Tier 4 QA Agent:** `python scripts/mma_exec.py --role tier4-qa "[PROMPT]"` + - **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/`. ### 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. - **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. ### 3. Phase Checkpoints (The Final Defense) + - The **Phase Completion Verification and Checkpointing Protocol** is the project's primary defense against token bloat. - When a Phase is marked complete and a checkpoint commit is created, the AI Agent must actively interpret this as a **"Context Wipe"** signal. It should summarize the outcome in its git notes and move forward treating the checkpoint as absolute truth, deliberately dropping earlier conversational history. - **MMA Phase Memory Wipe:** After completing a major Phase, use the Tier 1/2 Orchestrator's perspective to consolidate state into Git Notes and then disregard previous trial-and-error histories.