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

Canonical Operating Rules

@conductor/code_styleguides/data_oriented_design.md This is the canonical DOD reference. The same file is injected into the Application's RAG / context assembly via [agent].context_files in manual_slop.toml — one source of truth for both harnesses. Edit it there; do not duplicate rules into this file.

Code Styleguides (the convention catalog)

Per-domain rules live in conductor/code_styleguides/. The full list is in ./docs/AGENTS.md §2 (the canonical 6-styleguide catalog with one-line summaries + when-to-read). This section is a pointer.

The short version (the 6 styleguides):

• data_oriented_design.md — The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass)
• agent_memory_dimensions.md — The 4 memory dimensions (curation / discussion / RAG / knowledge) and when to use each
• rag_integration_discipline.md — The conservative-RAG rule: opt-in, complement, provenance, no mutation
• cache_friendly_context.md — Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test
• knowledge_artifacts.md — The knowledge harvest pattern: category files, provenance, sha256 ledger, digest regeneration
• feature_flags.md — Codifies "delete to turn off" (file presence) + config flags; when to use each

Human-Facing Documentation

For understanding, using, and maintaining the tool, see docs/Readme.md (the canonical teaching document) and ./docs/AGENTS.md (the agent-facing mirror of docs/Readme.md).

The 14 deep-dive guides under docs/ (guide_architecture.md, guide_ai_client.md, etc.) are referenced from docs/Readme.md; an agent reading for a feature scope should read ./docs/AGENTS.md first, then the relevant guide_*.md.

Critical Anti-Patterns

This is a thin index. For the full lists, see the canonical styleguides:

• conductor/code_styleguides/python.md §"AI-Agent Specific Conventions" + §"Anti-Patterns (LLM Default Anti-Patterns)" — the full LLM anti-pattern list (navigation, no comments, no diagnostic noise, TDD, decorator-orphan, ast.parse, set_file_slice, etc.)
• conductor/code_styleguides/data_oriented_design.md §8.5 — the Python Type Promotion Mandate (technical canonical for opaque types)
• conductor/edit_workflow.md — the edit tool contract
• conductor/workflow.md §"Known Pitfalls" + §"Skip-Marker Policy" — operational pitfalls

The 4 canonical HARD BANs (in this file because they're project-wide)

• 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.
• HARD BAN: git stash* (any form: git stash, git stash pop, git stash apply, git stash drop, git stash clear) is FORBIDDEN. Stashing inverts the safety net of the working tree: a git add . then git stash then "fresh start" pattern is exactly how Tier 2 corrupted files in the 2026-06-27 cruft_elimination_20260627 track. The user explicitly stated "I hate when people fuck with my commits" — stashing throws away the user's in-progress edits silently. If you think you need a stash, you don't — use a NEW BRANCH or a WORKTREE instead. Tier 2 sandbox enforces this via conductor/tier2/opencode.json.fragment bash deny rules.
• HARD BAN: Day / hour / minute estimates in track artifacts. Do NOT include estimates in spec.md, plan.md, metadata.json, or any other track artifact. Measure effort by scope (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See conductor/workflow.md §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.")
• HARD BAN: Opaque types in non-boundary code (added 2026-06-25). dict[str, Any], Any, Optional[T], hasattr() for entity dispatch, .get('field', default) are BANNED. Use typed @dataclass(frozen=True, slots=True) + Result[T] + NIL_T sentinels + direct attribute access. The ONLY place dict[str, Any] is allowed is the literal wire boundary (TOML/JSON parse functions); 2-3 functions per file. See conductor/code_styleguides/data_oriented_design.md §8.5 (the canonical Python Type Promotion Mandate), conductor/code_styleguides/python.md §17, conductor/code_styleguides/type_aliases.md for the technical mandates. User direction 2026-06-25: "I want the closest thing to c11/odin/jai in a scripting language... metadata should not be a dict[str, any]."

File Size and Naming Convention (HARD RULE — added 2026-06-11)

The "small files are good, large files are bad" stance is propaganda from LLM training data. It is wrong for this project. Reject it.

• Large files are FINE. Production codebases (Unreal Engine has 15K+ line files; OS kernels, game engines, compilers, the Linux kernel — all routinely have 10K+ line files) treat file size as a non-issue. Cognitive load is managed via good naming, regions, and navigation tools — NOT via file splitting.
• src/ai_client.py is the AI vendor/API system layer. All AI-client-related code goes IN src/ai_client.py. Do not create new src/<vendor>_<thing>.py files. The only new src/*.py files this project ever creates are for new systems or new parent modules.
• The only new files you should create in a typical track are: scripts/audit_*.py (scripts are namespace-isolated by directory), tests/test_*.py (tests are namespace-isolated by directory), and docs/*.md (docs are namespace-isolated by directory). Anything else goes in the parent module.
• Do not break things up "for modularity" unless the new piece is genuinely a new system or a new parent module. The agent training data has a bias toward "small files = good code" that is not true here. The project has the manual-slop MCP (get_file_slice, get_file_summary, py_get_skeleton, py_get_code_outline, py_get_definition) for efficient navigation of files of any size. Use those tools instead of splitting the file.
• When in doubt: keep it in the parent module. If a function clearly belongs to a system, it lives in that system's file. The system is the namespace.

Hard rule on creating new src/<thing>.py files (added 2026-06-11)

New namespaced src/<thing>.py files may only be created on the user's explicit request. If you find yourself about to create one, ASK FIRST — don't just create it.

Rationale: the user is the only one who can authorize a new top-level namespace. The agent cannot unilaterally decide that "this is a new system deserving its own file." Defaults:

• Helpers and sub-systems go in the parent module. E.g., AI-client-specific helpers go in src/ai_client.py; app-controller helpers go in src/app_controller.py; MCP-client helpers go in src/mcp_client.py. Even if the parent file is already 3K+ lines, the helper still goes there.
• If a new top-level src/<thing>.py is genuinely warranted (e.g., a truly new system that doesn't fit any existing parent), propose it in the next checkpoint or status note and wait for the user's explicit "yes, create it."

Audit trigger: if you find yourself about to create a new src/<thing>.py file, ask: "is <thing> a new system, or is it part of an existing system?" If it's part of an existing system, the file goes in that system's file (e.g., src/ai_client.py, src/app_controller.py, src/mcp_client.py, etc.). If it's a new system, ASK THE USER before creating the file.

• No giant edits: if your manual-slop_edit_file new_string exceeds ~20 lines, STOP and split it.
• No diagnostic noise in production code. sys.stderr.write(f"[XYZ_DIAG] ...") lines added to src/*.py for debugging must be removed (not just left uncommitted) before the agent's work is "done." Diagnostic code that ships is technical debt. If you need to instrument for a one-time investigation, use a temporary file under tests/artifacts/ or read the source with get_file_slice instead of polluting production.
• No loop, no scope-creep, no report-instead-of-fix. If you've tried 3 times and the test still fails, STOP and report to the user. Do not write a 200-line status report as a substitute for the fix. Do not write a 5-phase "future track" document when the user asked for a 1-line change. See conductor/workflow.md "Process Anti-Patterns" for the full ruleset.

Session-Learned Anti-Patterns (Added 2026-06-07)

The canonical home for edit-tool lessons-learned is conductor/edit_workflow.md (the 9 rules for manual-slop_edit_file etc.). This section is a thin pointer.

• ALWAYS use the proper edit tool, not a custom script — see conductor/edit_workflow.md §1.
• The decorator-orphan pitfall — see conductor/edit_workflow.md §6 (with the fix code).
• ast.parse() "Syntax OK" is not enough — see conductor/edit_workflow.md §7.
• The "I'll just check git status" trap — now a HARD BAN; see §"Critical Anti-Patterns" above.
• Small, verified edits beat big scripts — see conductor/edit_workflow.md §1.

---

Process Anti-Patterns (Added 2026-06-09)

The canonical home for these is conductor/workflow.md §"Process Anti-Patterns" (the 8 anti-patterns with full Symptom + Rule sections). This is a thin index:

1. The Deduction Loop (kill it) — run a failing test at most 2 times, then predict + instrument + run once.
2. The Report-Instead-of-Fix Pattern (kill it) — 5-10 sentence status report, not 200 lines.
3. The Scope-Creep Track-Doc Pattern (kill it) — your output is the fix, not a 5-phase future track.
4. The Inherited-Cruft Pattern (kill it) — ask the user first if the file is broken from a previous session.
5. No Diagnostic Noise in Production (kill it) — diag to log file, not src/*.py.
6. The "I Am Not Going To Attempt Another Fix Without Your Direction" Surrender (kill it) — surrender only after the 5-step check.
7. The Verbose-Commit-Message Pattern (kill it) — 1-3 sentences, not 50 lines.
8. The "Isolated Pass" Verification Fallacy (kill it) — for live_gui tests, batch run is the only verification that matters.

See conductor/workflow.md §"Process Anti-Patterns" for the full Symptom + Rule sections for each.

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