claw-email/AGENT.md

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

### 2.1 Definition of Done

A change is done only when all of the following are true:

- The issue has locked **Final Requirements** with verifiable acceptance criteria.
- The implementation stays within approved scope; unrelated refactors are not allowed.
- Behavior, contract, or config changes have relevant tests added or updated, or the change record explains why tests were not added.
- Validation passes with fresh output: `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`.
- `README.md` and `.env.example` and related documents are updated when config, endpoint, or runtime behavior changes.
- A new ADR is added in `docs/adr/**` when the change introduces a durable architecture, contract, behavior, or workflow decision.
- The implementation evidence is posted on the issue and reflected in the PR body:
  - what changed
  - what tests were run
  - whether any refactor was included
  - whether docs or ADRs were added or not needed
  - risks or follow-ups
- After merge, the linked issue is verified closed.

---

## 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, verification criteria, and any docs/ADR impact.
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).
   - Update `README.md` and `.env.example` if config, endpoint, or runtime behavior changes.
   - If the change locks in a durable decision, write/update an ADR in `docs/adr/**`.
   - Run validation: `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`.
   - Post an implementation summary comment on the issue with sections: `Summary`, `Changes`, `Test Plan`, `Refactor`, `Docs/ADR`, `Risks/Follow-ups`.
   - Create PR with the same evidence in the body plus `Fixes #<issue>` so Gitea auto-closes the issue on merge.
   - After merge, verify the issue is closed. If not (e.g. missing keyword), close it manually with a summary comment.
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, review history, and PR discussion comments.
3. Validate in worktree if needed (`.worktrees/pr-<number>`, run `gofmt -l .`, `go test ./...`, `go vet ./...`, `staticcheck ./...`).
4. Check for scope creep — FAIL if PR contains unrelated changes or refactoring.
5. Verify the repo Definition of Done:
   - relevant tests exist for behavior/config changes
   - docs and `.env.example` were updated when required
   - ADR exists when a durable decision was introduced
   - the issue comment and PR body contain the required implementation evidence
6. Write verdict — start with **PASS** or **FAIL**.
7. Post review proactively if verdict is clear:
   - `PASS` → `APPROVED`
   - `FAIL` → `REQUEST_CHANGES`
   - Non-blocking note → `COMMENT`

---

## 5. Gitea Tools

- Always use Gitea MCP tools in this project.
- Scope: read PR/issue, list comments, post replies, create/edit PRs, reviews.
- Use `tea` CLI only as fallback when MCP is unavailable.
- Local CLI tools (`git`, `go`, `rg`) are fine for local validation.

---

## 6. Review Format

```
PASS

No blocking issues found.

Validation:
- gofmt -l .: OK
- go test ./...: OK
- go vet ./...: OK
- staticcheck ./...: OK

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

```
FAIL

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

Validation:
- <list only the commands you actually ran and their result>
```

---

## 7. Documentation Rules

- Durable architecture or behavior decisions belong in `docs/adr/**`.
- `docs/superpowers/**` is for agent execution artifacts and must not be merged as part of product implementation PRs.
- If a PR needs a lasting technical rationale, author an ADR in `docs/adr/` instead.
- Reviewers should treat temporary plan/spec docs as scope creep, but accept ADRs that directly document the accepted behavior of the change.

---

## 8. Comment Style

- Use readable multiline markdown.
- Use short sections (`Summary`, `Changes`, `Test Plan`).
- Implementation completion comments should also include `Refactor`, `Docs/ADR`, and `Risks/Follow-ups`.
- Concise bullet points and explicit line breaks.
- No bracketed author/tool tags.