136 lines
4.1 KiB
Markdown
136 lines
4.1 KiB
Markdown
# 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
|
|
|
|
- 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.
|
|
|
|
---
|
|
|
|
## 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.
|