claw-email/AGENT.md

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.