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.

---

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 with Fixes #<issue> in the body 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 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

• 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:
- 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. 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).
• Concise bullet points and explicit line breaks.
• No bracketed author/tool tags.