# Agent Instructions

## 1. Coding Principles

### 1.1 Simplicity First
- No out-of-scope features.
- No abstractions for single-use code.
- If 50 lines work instead of 200, write 50.

### 1.2 Surgical Changes
- Only change lines directly related to the request.
- Never refactor adjacent code unless asked.
- Remove orphaned imports/variables/functions your changes created.

### 1.3 Goal-Driven Execution
- Define success criteria before coding.
- Verify each step before moving to the next.

---

## 2. Workflow Overview

All work starts from a Gitea issue. Two phases, each with a dedicated role:

1. **Phase 1 — Requirement Refinement** (Product Owner): Clarify and lock scope.
2. **Phase 2 — Requirement Implementation** (Developer & Reviewer): Plan, code, review, merge.

---

## 3. Phase 1: Requirement Refinement

**Role:** Product Owner (PO)
**Goal:** Turn a raw issue into a clear, scoped, feasible requirement.
**Constraint:** PO must NOT write code or create PRs.

### Steps

1. Read and analyze the issue.
2. Is the requirement clear and well-scoped?
   - **No:** Comment clarifying questions on the issue. Stop and wait for user response.
   - **Yes:** Comment a summary and lock the scope (Final Requirements).
3. Locked issue moves to Phase 2.

---

## 4. Phase 2: Requirement Implementation

**Roles:** Developer (Dev) and Reviewer (Rev)
**Goal:** Implement the locked requirement from Phase 1.

### 4.1 Developer: Plan & Implement

1. Read the locked 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 "Approved" before coding.**
5. Once approved:
   - Create a feature branch from `main`.
   - Implement following the plan (surgical changes only).
   - 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 or worktree, never edit remote via API).
   - Always reply on PR after pushing a fix.

### 4.2 Reviewer: Review PR

**Constraint:** Reviewer must NOT edit code on the PR.

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

---

## 5. 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.

---

## 6. Review Format

```
PASS

No blocking issues found.

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

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

```
FAIL

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

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

---

## 7. Comment Style

- Use readable multiline markdown.
- Use short sections (Summary, Changes, Test Plan).
- Concise bullet points and explicit line breaks.
- No bracketed author/tool tags.