From 17dcb9fbf3a88f02f787d941a23b94a0d6855dd2 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 2 Jun 2026 20:45:21 -0400 Subject: [PATCH] docs(agents): rewrite as thin pointer document; defer to skill files and conductor docs --- AGENTS.md | 136 ++++++++++-------------------------------------------- 1 file changed, 24 insertions(+), 112 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6f09027a..51bb165c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,123 +1,35 @@ -# Manual Slop - OpenCode Configuration +# AGENTS.md -## MCP TOOL PARAMETERS - CRITICAL -- **ALWAYS use snake_case**: `old_string`, `new_string`, `replace_all` -- **NEVER use camelCase**: `oldString`, `newString`, `replaceAll` +## What This Is -## Project Overview +Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution. -**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. +## The Conductor Convention -## Main Technologies +All AI agents consuming this project must read `./conductor/workflow.md` and treat `./conductor/tracks.md` as the task registry. Track implementation follows the TDD protocol documented in `conductor/workflow.md` with per-file atomic commits and git notes. -- **Language:** Python 3.11+ -- **Package Management:** `uv` -- **GUI Framework:** ImGui Bundle (`imgui-bundle`) -- **AI SDKs:** `google-genai` (Gemini), `anthropic` -- **Configuration:** TOML (`tomli-w`) +## Guidance for AI Agents -## Architecture +Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here: -- **`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) +- **Operational workflow:** `conductor/workflow.md` +- **Code style and process:** `conductor/product-guidelines.md` +- **Tech stack and constraints:** `conductor/tech-stack.md` +- **Product context:** `conductor/product.md` +- **MMA orchestrator role:** `mma-orchestrator/SKILL.md` +- **Tier 1 (Orchestrator):** `.agents/skills/mma-tier1-orchestrator/SKILL.md` +- **Tier 2 (Tech Lead):** `.agents/skills/mma-tier2-tech-lead/SKILL.md` +- **Tier 3 (Worker):** `.agents/skills/mma-tier3-worker/SKILL.md` +- **Tier 4 (QA):** `.agents/skills/mma-tier4-qa/SKILL.md` -## Critical Context (Read First) +## Human-Facing Documentation -- **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 +For understanding, using, and maintaining the tool, see `docs/Readme.md` and the 14 deep-dive guides it indexes. -## Environment +## Critical Anti-Patterns -- 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 ./condcutor/tracks.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 -- **docs/guide_meta_boundary.md**: Clarification of ai agent tools making the application vs the application itself. - -## Development Workflow - -1. Run `/conductor-setup` to load session context -2. Pick active track from `./condcutor/tracks.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 +- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary` +- Do not modify the tech stack without updating `conductor/tech-stack.md` first +- Do not skip TDD — write failing tests before implementation +- Do not batch commits — commit per-task for atomic rollback +- Do not add comments to source code; documentation lives in `/docs`