Refactor code structure for improved readability and maintainability

AGENTS.md

@@ -0,0 +1,90 @@
+# Agent Instructions
+
+## Python Type Hints (REQUIRED)
+
+- **All functions must have type hints** for parameters and return types.
+- **All class attributes must have type hints** in `__init__`.
+- **Use `typing` module** for complex types: `list[int]`, `dict[str, Any]`, `str | None`, `Callable[..., Any]`.
+- **Never use bare `list` or `dict`** - always parameterize: `list[str]`, `dict[str, Any]`.
+- **Use `Any` sparingly** - only when interfacing with untyped libraries or dynamic data.
+- **Module-level constants must have type hints**: `VERSION: str = "1.0"`.
+- **Tuple return types**: use `tuple[str, int]` for multiple returns.
+
+## Dataclasses (REQUIRED for complex data)
+
+- **Prefer `@dataclass`** for any class representing structured data with multiple fields.
+- **Use `dataclasses.field()`** for default values that are mutable (lists, dicts).
+- **Use `field(default_factory=list)`** instead of `default=[]`.
+- **Use `field(default_factory=dict)`** instead of `default={}`.
+- **Use `kw_only=True`** for dataclasses with many optional fields.
+- **Use `frozen=True`** for immutable dataclasses when appropriate.
+- **Example:**
+  ```python
+  from dataclasses import dataclass, field
+  from typing import Optional
+  
+  @dataclass
+  class IssueInfo:
+      number: int
+      title: str
+      owner: str
+      repo: str
+      labels: list[str] = field(default_factory=list)
+      assignee: Optional[str] = None
+  ```
+
+## Follow all instructions provided in the system prompt.
+- Keep responses concise and direct.
+- Minimize output tokens.
+- Use the `Task` tool for complex multi-step tasks.
+- Verify solutions with tests if possible.
+- Run lint and typecheck commands if provided.
+- Do not commit changes unless explicitly asked.
+- Use GitHub-flavored markdown for formatting.
+- Answer concisely with fewer than 4 lines of text.
+- ALWAYS use `uv` to run python commands. Do not use `python3` directly.
+- Always commit and push changes at the end of a task.
+- NEVER push to the master or main branch.
+
+# Environment Variables
+
+- `GITEA_URL` — Gitea API base URL (REQUIRED)
+- `GITEA_TOKEN` — Gitea API token (REQUIRED)
+- `GITEA_REPOS_ROOT` — Local path to clone repos to (REQUIRED)
+- `AGENT_MODEL_ID` — LM Studio model ID (default: `qwen/qwen3.6-35b-a3b`)
+- `AGENT_MAX_RETRIES` — Max retries per task (default: `2`)
+
+# Architecture
+
+The agent uses a **repo-scoped single-agent dispatch** pattern:
+
+1. `AgentOrchestrator` polls Gitea for assigned issues/PRs
+2. Tasks are grouped by repo and enqueued in `WorkQueue`
+3. `AgentDispatcher` creates a **fresh `CodingAgent`** per repo batch
+4. Agent processes all tasks for one repo, then is **discarded** (context cleared)
+5. Next repo gets a fresh agent — no context bleed between repos
+
+```
+main.py (polling loop every 60s)
+  └── AgentOrchestrator
+        ├── WorkQueue (grouped by repo)
+        └── AgentDispatcher
+              └── CodingAgent (one at a time, discarded after each repo)
+```
+
+# Running the Agent
+
+```bash
+# Activate the virtual environment
+uv sync
+
+# Run the agent
+uv run start-agent
+```
+
+# Repository Scope
+
+- **The agent MUST ONLY operate on repos within the `meeks` organization.**
+- `gitea/client.py:48` enforces this with a hardcoded filter: `if r.get("owner", {}).get("login") == "meeks"`
+- **Never change this filter** to include personal accounts (e.g., `meeks-ai`) or other organizations.
+- This filter is the single source of truth for repo scope — do not bypass it.