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.