# Agent Instructions

Behavioral guidelines for AI agents working on this project.

## 1. Coding Principles

### Simplicity First

- No features beyond what was asked.
- No abstractions for single-use code.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

### Surgical Changes

- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- Remove imports/variables/functions that YOUR changes made unused.
- Every changed line should trace directly to the user's request.

### Goal-Driven Execution

- Define success criteria before coding.
- For multi-step tasks, state a plan with verification at each step.
- Verify each step before moving to the next.

## 2. Roles

| Role                    | Responsibility                                           |
| ----------------------- | -------------------------------------------------------- |
| **Product Owner** | Validate and clarify issues. Do NOT implement.           |
| **Developer**     | Plan, implement, own PRs until merged.                   |
| **Reviewer**      | Review PRs against issue requirements. Do NOT implement. |

## 3. Issue-Driven Workflow

All work starts from a Gitea issue. The flow through roles:

```
Issue created
     │
     ▼
┌──────────────────────┐
│  Product Owner        │  Validate & clarify
│  → comment on issue   │
└──────────┬───────────┘
           │ issue validated
           ▼
┌──────────────────────┐
│  Developer            │  Plan & implement
│  → comment plan       │
│  → branch → code      │
│  → PR → fix feedback  │
└──────────┬───────────┘
           │ PR ready
           ▼
┌──────────────────────┐
│  Reviewer             │  Review PR
│  → check vs issue     │
│  → validate → verdict │
└──────────────────────┘
```

### 3.1 Product Owner: Validate & Clarify

**Trigger:** Issue is created or assigned.

1. Read the issue.
2. Analyze: is the requirement clear, feasible, and well-scoped?
3. If unclear: ask clarifying questions as a comment on the issue.
4. If reasonable: summarize understanding, confirm scope, update issue with refined requirements.
5. **Do NOT implement** — only validate and clarify.

### 3.2 Developer: Plan & Implement

**Trigger:** Issue is validated (Product Owner done).

1. Read the issue and any clarification comments.
2. Read relevant code to understand current state.
3. Write an implementation plan — list steps, files to change, risks.
4. **Comment the plan on the issue** — wait for approval before coding.
5. Once approved:
   - Create a feature branch from `main`.
   - Implement following the plan.
   - Run validation (`go test ./...`, `go vet ./...`, `gofmt -l .`).
   - Create PR referencing the issue.
6. **Own the PR until merged:**
   - Monitor for review feedback.
   - Fix feedback on the correct branch (checkout/worktree, never edit remote via API).
   - Always reply on PR after pushing a fix.

### 3.3 Reviewer: Review PR

**Trigger:** PR is created or updated.

1. Re-read the original issue — verify PR addresses the actual requirement.
2. Read PR diff and discussion history.
3. Validate in worktree if needed (`.worktrees/pr-<number>`, run `go test`, `go vet`, `gofmt`).
4. Write verdict — start with **PASS** or **FAIL**.
5. Post review proactively if verdict is clear:
   - `PASS` → `APPROVED`
   - `FAIL` → `REQUEST_CHANGES`
   - Non-blocking note → `COMMENT`

## 4. Gitea Tools

- If git remote contains `git.thuanle.me`, ALWAYS use Gitea MCP tools.
- Scope: read PR/issue, list comments, post replies, create/edit PRs, reviews.
- Use `tea` CLI only as fallback when MCP is unavailable.
- Do not use `gh` for Gitea repositories.
- Local CLI tools (`git`, `go`, `rg`) are fine for local validation.

## 5. Review Format

```
PASS

No blocking issues found.

Validation:
- go test ./...
- go vet ./...

Non-blocking:
- <optional note>
```

```
FAIL

1. [High] <issue with path:line and impact>
2. [Medium] <issue with path:line and impact>

Validation:
- go test ./...
```

## 6. Comment Style

- Prioritize clear presentation over compact text.
- Write as readable multiline markdown.
- Use short sections when useful (Summary, Changes, Test Plan).
- Concise bullet points and explicit line breaks.