manual_slop/AGENTS.md

# 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_<date>.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/<track_id>/state.toml` to see `current_phase`; read `conductor/tracks/<track_id>/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/<track_id>/` 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).