docs: consolidate project instructions into AGENT.md

Move behavioral guidelines, role-based workflow, and Gitea tooling
instructions into AGENT.md. CLAUDE.md now references AGENT.md.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

AGENT.md

@@ -0,0 +1,144 @@
+# 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.

CLAUDE.md

@@ -1,70 +1,3 @@
 # CLAUDE.md
 
-Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+See [AGENT.md](AGENT.md) for full project instructions and workflow.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
-
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-
-- 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.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
----
-
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.