# Project Zuza Agent Guide

## First Rule

- Do not put word-bound, domain-word, or prompt-language behavior rules inside runtime code. Words belong in prompts, tool instructions, schemas, and docs. Code should enforce structural contracts, typed fields, validation, persistence, ordering, and generic transport only.

Project Zuza runs as a Flask application backed by LM Studio and local Python tool runtimes. The active runtime is the universal Zuza loop in `main.py`.

## Core Contract

- `self.md` is the base identity prompt and is used as the system instruction for the LM Studio SDK main chat.
- Later loop passes use the persisted SDK chat context/checkpoints plus a compact structured packet.
- The runtime uses one configured LM Studio model.
- Tools and senses are discovered from disk and executed locally by Project Zuza.
- Enabled tool and skill instructions are loaded into the main loop context.

## Loop Packet

Each pass receives:

- original and latest user message
- current plan state
- last pass output
- latest memory context
- available tool and skill catalogs
- full enabled tool and skill instructions
- fresh sense snapshots

The model returns one JSON object with:

- `schema_version`
- `review`
- `plan_patch`
- `memory_updates`
- `memory_request`
- `next_action`

## Persistence

Keep these persisted surfaces working:

- `messages`
- `operations`
- `attachments`
- `memory_entries`
- `memory_tags`
- `agent_tasks`
- `agent_task_steps`
- `agent_passes`

The right-side plan panel, files tab, SSE stream, and reconnect snapshot must stay authoritative from persisted state.

## Tool Boundary

- Core discovers `description.md`, `instruction.md`, `schema.json`, and optional `runtime.json`.
- Core validates tool input against the discovered schema before execution.
- Tool-specific state, screenshots, cleanup, and hooks live inside the tool package.
- Core must not hardcode behavior for a specific tool.

## Engineering Rules

- Prefer structural state and typed fields over text heuristics.
- Keep the chat UI driven by authoritative operation snapshots plus ordered stream deltas.
- Preserve task files and visible trace ordering.
- Do not store user-task outputs in source directories by default; use `artifacts/` unless the task is project implementation work.