manual_slop/AGENTS.md

Manual Slop - OpenCode Configuration

Project Overview

Manual Slop is a local GUI application designed as an experimental, "manual" AI coding assistant. It allows users to curate and send context (files, screenshots, and discussion history) to AI APIs (Gemini and Anthropic). The AI can then execute PowerShell scripts within the project directory to modify files, requiring explicit user confirmation before execution.

Main Technologies

• Language: Python 3.11+
• Package Management: uv
• GUI Framework: Dear PyGui (dearpygui), ImGui Bundle (imgui-bundle)
• AI SDKs: google-genai (Gemini), anthropic
• Configuration: TOML (tomli-w)

Architecture

• gui_legacy.py: Main entry point and Dear PyGui application logic
• ai_client.py: Unified wrapper for Gemini and Anthropic APIs
• aggregate.py: Builds file_items context
• mcp_client.py: Implements MCP-like tools (26 tools)
• shell_runner.py: Sandboxed subprocess wrapper for PowerShell
• project_manager.py: Per-project TOML configurations
• session_logger.py: Timestamped logging (JSON-L)

Critical Context (Read First)

• Tech Stack: Python 3.11+, Dear PyGui / ImGui, FastAPI, Uvicorn
• Main File: gui_2.py (primary GUI), ai_client.py (multi-provider LLM abstraction)
• Core Mechanic: GUI orchestrator for LLM-driven coding with 4-tier MMA architecture
• Key Integration: Gemini API, Anthropic API, DeepSeek, Gemini CLI (headless), MCP tools
• Platform Support: Windows (PowerShell)
• DO NOT: Read full files >50 lines without using py_get_skeleton or get_file_summary first

Environment

• Shell: PowerShell (pwsh) on Windows
• Do NOT use bash-specific syntax (use PowerShell equivalents)
• Use uv run for all Python execution
• Path separators: forward slashes work in PowerShell

Session Startup Checklist

At the start of each session:

1. Check TASKS.md - look for IN_PROGRESS or BLOCKED tracks
2. Review recent JOURNAL.md entries - scan last 2-3 entries for context
3. Run /conductor-setup - load full context
4. Run /conductor-status - get overview

Conductor System

The project uses a spec-driven track system in conductor/:

• Tracks: conductor/tracks/{name}_{YYYYMMDD}/ - spec.md, plan.md, metadata.json
• Workflow: conductor/workflow.md - full task lifecycle and TDD protocol
• Tech Stack: conductor/tech-stack.md - technology constraints
• Product: conductor/product.md - product vision and guidelines

MMA 4-Tier Architecture

Tier 1: Orchestrator   - product alignment, epic -> tracks
Tier 2: Tech Lead      - track -> tickets (DAG), architectural oversight
Tier 3: Worker         - stateless TDD implementation per ticket
Tier 4: QA             - stateless error analysis, no fixes

Architecture Fallback

When uncertain about threading, event flow, data structures, or module interactions, consult:

• docs/guide_architecture.md: Thread domains, event system, AI client, HITL mechanism
• docs/guide_tools.md: MCP Bridge security, 26-tool inventory, Hook API endpoints
• docs/guide_mma.md: Ticket/Track data structures, DAG engine, ConductorEngine
• docs/guide_simulations.md: live_gui fixture, Puppeteer pattern, verification

Development Workflow

1. Run /conductor-setup to load session context
2. Pick active track from TASKS.md or /conductor-status
3. Run /conductor-implement to resume track execution
4. Follow TDD: Red (failing tests) -> Green (pass) -> Refactor
5. Delegate implementation to Tier 3 Workers, errors to Tier 4 QA
6. On phase completion: run /conductor-verify for checkpoint

Anti-Patterns (Avoid These)

• Don't read full large files - use py_get_skeleton, get_file_summary, py_get_code_outline first
• Don't implement directly as Tier 2 - delegate to Tier 3 Workers
• Don't skip TDD - write failing tests before implementation
• Don't modify tech stack silently - update conductor/tech-stack.md BEFORE implementing
• Don't skip phase verification - run /conductor-verify when all tasks in a phase are [x]
• Don't mix track work - stay focused on one track at a time

Code Style

• IMPORTANT: DO NOT ADD ANY COMMENTS unless asked
• Use 1-space indentation for Python code
• Use type hints where appropriate

Code Style

• IMPORTANT: DO NOT ADD ANY COMMENTS unless asked
• Use 1-space indentation for Python code
• Use type hints where appropriate
• Internal methods/variables prefixed with underscore

CRITICAL: Native Edit Tool Destroys Indentation

The native Edit tool DESTROYS 1-space indentation and converts to 4-space.

NEVER use native edit tool on Python files.

Instead, use Manual Slop MCP tools:

• manual-slop_py_update_definition - Replace function/class
• manual-slop_set_file_slice - Replace line range
• manual-slop_py_set_signature - Replace signature only

Or use Python subprocess with newline='' to preserve line endings:

python -c "
with open('file.py', 'r', encoding='utf-8', newline='') as f:
    content = f.read()
content = content.replace(old, new)
with open('file.py', 'w', encoding='utf-8', newline='') as f:
    f.write(content)
"

Quality Gates