manual_slop/conductor/product.md

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: Threading model, event system, AI client, HITL mechanism
• 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: MCP Bridge, Hook API, ApiHookClient, shell runner
• docs/guide_mma.md: 4-tier orchestration, DAG engine, worker lifecycle
• 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.
  • Tier 2 (Tech Lead): Technical oversight and track execution (/conductor:implement) using gemini-2.5-flash. Maintains persistent context throughout implementation.
  • Tier 3 (Worker): Surgical code implementation and TDD using gemini-2.5-flash or deepseek-v3. Operates statelessly with tool access and dependency skeletons.
  • Tier 4 (QA): Error analysis and diagnostics using gemini-2.5-flash or deepseek-v3. Operates statelessly with tool access.
  • MMA Delegation Engine: Route tasks, ensuring role-scoped context and detailed observability via timestamped sub-agent logs. Supports dynamic ticket creation and dependency resolution via an automated Dispatcher Loop.
  • MMA Observability Dashboard: A high-density control center within the GUI for monitoring and managing the 4-Tier architecture.
    • Track Browser: Real-time visualization of all implementation tracks with status indicators and progress bars.
    • Hierarchical Task DAG: An interactive, tree-based visualizer for the active track's task dependencies, featuring color-coded state tracking (Ready, Running, Blocked, Done) and manual retry/skip overrides.
    • Strategy Visualization: Dedicated real-time output streams for Tier 1 (Strategic Planning) and Tier 2/3 (Execution) agents, allowing the user to follow the agent's reasoning chains alongside the task DAG.
  • Track-Scoped State Management: Segregates discussion history and task progress into per-track state files (e.g., conductor/tracks/<track_id>/state.toml). This prevents global context pollution and ensures the Tech Lead session is isolated to the specific track's objective.
  • Native DAG Execution Engine: Employs a Python-based Directed Acyclic Graph (DAG) engine to manage complex task dependencies, supporting automated topological sorting and robust cycle detection.
  • Programmable Execution State Machine: Governing the transition between "Auto-Queue" (autonomous worker spawning) and "Step Mode" (explicit manual approval for each task transition).
  • Role-Scoped Documentation: Automated mapping of foundational documents to specific tiers to prevent token bloat and maintain high-signal context.
  • Tiered Context Scoping: Employs optimized context subsets for each tier. Tiers 1 & 2 receive strategic documents and full history, while Tier 3/4 workers receive task-specific "Focus Files" and automated AST dependency skeletons.
  • Worker Spawn Interceptor: A mandatory security gate that intercepts every sub-agent launch. Provides a GUI modal allowing the user to review, modify, or reject the worker's prompt and file context before it is sent to the API.
• Strict Memory Siloing: Employs tree-sitter AST-based interface extraction (Skeleton View, Curated View) and "Context Amnesia" to provide workers only with the absolute minimum context required, preventing hallucination loops.
• Explicit Execution Control: All AI-generated PowerShell scripts require explicit human confirmation via interactive UI dialogs before execution, supported by a global "Linear Execution Clutch" for deterministic debugging.
• Asynchronous Event-Driven Architecture: Uses an AsyncEventQueue to link GUI actions to the backend engine, ensuring the interface remains fully responsive during multi-model generation and parallel worker execution.
• Automated Tier 4 QA: Integrates real-time error interception in the shell runner, automatically forwarding technical failures to cheap sub-agents for 20-word diagnostic summaries injected back into the worker history.
• Detailed History Management: Rich discussion history with branching, timestamping, and specific git commit linkage per conversation.
• In-Depth Toolset Access: MCP-like file exploration, URL fetching, search, and dynamic context aggregation embedded within a multi-viewport Dear PyGui/ImGui interface.
• Integrated Workspace: A consolidated Hub-based layout (Context, AI Settings, Discussion, Operations) designed for expert multi-monitor workflows.
• Session Analysis: Ability to load and visualize historical session logs with a dedicated tinted "Prior Session" viewing mode.
• Structured Log Taxonomy: Automated session-based log organization into logs/sessions/, logs/agents/, and logs/errors/. Includes a dedicated GUI panel for monitoring and manual whitelisting. Features an intelligent heuristic-based pruner that automatically cleans up insignificant logs older than 24 hours while preserving valuable sessions.
• Clean Project Root: Enforces a "Cruft-Free Root" policy by redirecting all temporary test data, configurations, and AI-generated artifacts to tests/artifacts/.
• Performance Diagnostics: Built-in telemetry for FPS, Frame Time, and CPU usage, with a dedicated Diagnostics Panel and AI API hooks for performance analysis.
• Automated UX Verification: A robust IPC mechanism via API hooks and a modular simulation suite allows for human-like simulation walkthroughs and automated regression testing of the full GUI lifecycle across multiple specialized scenarios.
• Headless Backend Service: Optional headless mode allowing the core AI and tool execution logic to run as a decoupled REST API service (FastAPI), optimized for Docker and server-side environments (e.g., Unraid).
• Remote Confirmation Protocol: A non-blocking, ID-based challenge/response mechanism for approving AI actions via the REST API, enabling remote "Human-in-the-Loop" safety.
• Gemini CLI Integration: Allows using the gemini CLI as a headless backend provider. This enables leveraging Gemini subscriptions with advanced features like persistent sessions, while maintaining full "Human-in-the-Loop" safety through a dedicated bridge for synchronous tool call approvals within the Manual Slop GUI. Now features full functional parity with the direct API, including accurate token estimation, safety settings, and robust system instruction handling.