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
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