docs: add AGENT.md workflow and local skills
- AGENT.md: role-based issue-driven workflow (PO → Dev → Reviewer) - CLAUDE.md: points to AGENT.md - .codex/skills/: validate-issue, do-task, review-pr with phase gates Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.7
@@ -1,109 +1,86 @@
|
||||
# Agent Instructions
|
||||
|
||||
Behavioral guidelines for AI agents working on this project.
|
||||
|
||||
## 1. Coding Principles
|
||||
|
||||
### Simplicity First
|
||||
|
||||
- No features beyond what was asked.
|
||||
### 1.1 Simplicity First
|
||||
- No out-of-scope features.
|
||||
- No abstractions for single-use code.
|
||||
- No error handling for impossible scenarios.
|
||||
- If you write 200 lines and it could be 50, rewrite it.
|
||||
- If 50 lines work instead of 200, write 50.
|
||||
|
||||
### 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
|
||||
### 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.
|
||||
- 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. |
|
||||
## 2. Workflow Overview
|
||||
|
||||
## 3. Issue-Driven Workflow
|
||||
All work starts from a Gitea issue. Two phases, each with a dedicated role:
|
||||
|
||||
All work starts from a Gitea issue. The flow through roles:
|
||||
1. **Phase 1 — Requirement Refinement** (Product Owner): Clarify and lock scope.
|
||||
2. **Phase 2 — Requirement Implementation** (Developer & Reviewer): Plan, code, review, merge.
|
||||
|
||||
```
|
||||
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
|
||||
## 3. Phase 1: Requirement Refinement
|
||||
|
||||
**Trigger:** Issue is created or assigned.
|
||||
**Role:** Product Owner (PO)
|
||||
**Goal:** Turn a raw issue into a clear, scoped, feasible requirement.
|
||||
**Constraint:** PO must NOT write code or create PRs.
|
||||
|
||||
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.
|
||||
### Steps
|
||||
|
||||
### 3.2 Developer: Plan & Implement
|
||||
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.
|
||||
|
||||
**Trigger:** Issue is validated (Product Owner done).
|
||||
---
|
||||
|
||||
1. Read the issue and any clarification comments.
|
||||
## 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 approval before coding.
|
||||
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.
|
||||
- Run validation (`go test ./...`, `go vet ./...`, `gofmt -l .`).
|
||||
- Implement following the plan (surgical changes only).
|
||||
- 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).
|
||||
- Fix feedback on the correct branch (checkout or worktree, never edit remote via API).
|
||||
- Always reply on PR after pushing a fix.
|
||||
|
||||
### 3.3 Reviewer: Review PR
|
||||
### 4.2 Reviewer: Review PR
|
||||
|
||||
**Trigger:** PR is created or updated.
|
||||
**Constraint:** Reviewer must NOT edit code on the PR.
|
||||
|
||||
1. Re-read the original issue — verify PR addresses the actual requirement.
|
||||
1. Re-read the original issue — verify PR addresses the locked 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:
|
||||
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`
|
||||
|
||||
## 4. Gitea Tools
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -111,7 +88,9 @@ Issue created
|
||||
- Do not use `gh` for Gitea repositories.
|
||||
- Local CLI tools (`git`, `go`, `rg`) are fine for local validation.
|
||||
|
||||
## 5. Review Format
|
||||
---
|
||||
|
||||
## 6. Review Format
|
||||
|
||||
```
|
||||
PASS
|
||||
@@ -119,8 +98,8 @@ PASS
|
||||
No blocking issues found.
|
||||
|
||||
Validation:
|
||||
- go test ./...
|
||||
- go vet ./...
|
||||
- go test ./...: OK
|
||||
- go vet ./...: OK
|
||||
|
||||
Non-blocking:
|
||||
- <optional note>
|
||||
@@ -133,12 +112,14 @@ FAIL
|
||||
2. [Medium] <issue with path:line and impact>
|
||||
|
||||
Validation:
|
||||
- go test ./...
|
||||
- go test ./...: OK
|
||||
```
|
||||
|
||||
## 6. Comment Style
|
||||
---
|
||||
|
||||
- Prioritize clear presentation over compact text.
|
||||
- Write as readable multiline markdown.
|
||||
- Use short sections when useful (Summary, Changes, Test Plan).
|
||||
## 7. 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.
|
||||
|
||||
Reference in New Issue
Block a user