meeks
91 lines
3.4 KiB
Markdown
91 lines
3.4 KiB
Markdown
# 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., `unknown-ai`) or other organizations.
|
|
- This filter is the single source of truth for repo scope — do not bypass it.
|