# AGENTS.md ## What This Is 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. ## The Conductor Convention 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. ## Guidance for AI Agents Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here: - **MUST READ TO DE-RETARD EDIT WORKFLOW** `conductor/edit_workflow.md` - **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` ## Human-Facing Documentation For understanding, using, and maintaining the tool, see `docs/Readme.md` and the 14 deep-dive guides it indexes. ## Critical Anti-Patterns - 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` - Do not use `set_file_slice` for multi-line content; it's literal line replacement by design (see `conductor/edit_workflow.md`) - Do not use `git restore` while a user is mid-conversation without first confirming the desired state ## Session-Learned Anti-Patterns (Added 2026-06-07) These burned the most time in a recent startup_speedup session. The rules below are short because the rules above (and `conductor/edit_workflow.md`) are the source of truth. ### 1. ALWAYS use the proper edit tool, not a custom script - For Python source edits, use `manual-slop_edit_file` with `old_string`/`new_string`. **Do NOT** write a standalone Python script that does file-level replacements. - Custom scripts fail silently on: wrong indent in `new_content`, wrong EOL (CRLF vs LF) in `old_string` searches, wrong exact-string match (whitespace drift). - When a script fails, debug the actual error message. Do not dismiss it and try a different approach. ### 2. The decorator-orphan pitfall When inserting new methods **before an existing `@property` def**, your script will leave the `@property` decorator on the line above your new methods. The decorator then accidentally decorates YOUR new method (which is no longer a property, breaking any subsequent `@your_method.setter` calls). The file passes `ast.parse()` but blows up at import time. The fix: anchor on the **def line that has the `@property` ABOVE it**, and replace the pair `@property\n def foo(...)` with `@property\n def your_new(...)\n ...\n def foo(...)` — keeping the decorator attached to its original method. Or anchor on a different non-decorated landmark (e.g. `self._init_actions()`). ### 3. `ast.parse()` "Syntax OK" is not enough `ast.parse()` only catches syntax errors. Semantic errors (wrong decorator targets, wrong class attribute, missing `self`, etc.) are NOT caught. After a multi-line edit, ALWAYS: - Import the module - Instantiate the class - Call the new method in the way it's expected to be called (e.g. `ctrl.foo_ts` vs `ctrl.foo_ts()` for properties vs methods) ### 4. The "I'll just check git status" trap If you suspect you might have lost work, the worst move is to run `git status` / `git restore` while a frantic user is watching. Pause, read the actual file, and admit what state you're in. The user knows their state better than you do. ### 5. Small, verified edits beat big scripts `conductor/edit_workflow.md` says it explicitly: 3-10 lines at a time, verify after each, repeat. If you find yourself writing a 200-line Python script to do an edit, you're doing it wrong. Use the MCP tools. ## Compaction Recovery If you're a new agent picking up a session that was compacted (or a previous agent ran out of context), follow this recovery path: 1. **Read the most recent `docs/reports/PLANNING_DIGEST_.md`** if one exists. It indexes the planning artifacts and explains the design decisions behind the active tracks. 2. **For each in-flight track**, read `conductor/tracks//state.toml` to see `current_phase`; read `conductor/tracks//plan.md` for the task breakdown. 3. **Check `git log --oneline -20`** to see what has been committed; the most recent commits in `conductor/tracks//` are the latest work. 4. **Run the audit scripts** (`scripts/audit_main_thread_imports.py`, `scripts/audit_weak_types.py`) to see the current state of the codebase. 5. **Resume from the next unchecked task** in `state.toml`. The per-task commit discipline means each commit is a safe rollback point. The track's `metadata.json` has a `verification_criteria` field — this is the definition of "done" for the track. If all the criteria are checked, the track is complete. For deeper recovery, see `conductor/workflow.md` "Compaction Recovery" (the same pattern, but workflow-level).