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 - CORRECT 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
HARD BAN: git restore, git checkout -- <file>, git reset are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST.
No giant edits: if your manual-slop_edit_file new_string exceeds ~20 lines, STOP and split it.

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 (now a HARD BAN, see Critical list above)

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. This trap has now caused irrecoverable data loss twice in one session — the ban is enforced above.

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:

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.
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.
Check git log --oneline -20 to see what has been committed; the most recent commits in conductor/tracks/<track_id>/ are the latest work.
Run the audit scripts (scripts/audit_main_thread_imports.py, scripts/audit_weak_types.py) to see the current state of the codebase.
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).

6.0 KiB Raw Blame History