thuanle/claw-email
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add AGENT.md workflow and local skills

Browse Source 
- 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:
thuanle
2026-04-28 00:00:41 +07:00
co-authored by Claude Opus 4.7
parent 8be84cc396
commit 248a5bdbcd
7 changed files with 501 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.codex/skills/do-task/SKILL.codex.md
+53
View File
@@ -0,0 +1,53 @@
---
name: do-task
description: Use when handling a Gitea issue/task end-to-end, including validation, planning, implementation, PR creation, and review-feedback iteration.
---
# Do Task
## Overview
Process a single Gitea issue from analysis to merge-ready PR with explicit decision gates. Prefer Gitea MCP tools for all issue/PR actions.
## Workflow
1. **Load issue**
- Read issue by ID from Gitea.
- Extract: problem, expected behavior, impact, acceptance checks.
2. **Validate technical correctness**
- Verify against current code/docs/tests.
- Decide:
- **Valid issue** -> continue to planning.
- **Not valid / out of scope** -> comment rationale on issue and stop.
3. **If valid: plan and comment**
- Create implementation plan using Superpowers planning flow.
- Post summary plan to the issue before coding.
4. **Implement**
- Use Superpowers execution flow (TDD + verification before completion).
- Keep changes scoped strictly to issue requirements.
5. **Create PR**
- Open PR from feature branch.
- PR description must include:
- Summary of changes
- Test evidence (exact commands)
- `Fixes #<issue-id>` (or `Closes #<issue-id>`)
- Add reviewer: `codex`.
6. **Review feedback loop**
- Read all feedback.
- For each item:
- If technically valid -> implement + re-test + reply.
- If not valid -> reply with concise technical reasoning.
- Do not blindly accept external feedback without verification.
## Required Rules
- Use Gitea MCP tools first for issue/PR/review operations.
- Do not use `tea` or other CLI Gitea clients unless MCP is unavailable.
- Never claim completion without fresh verification output.
## Quick Command Pattern
- Invoke as: `/do-task <issue-id>`
- Example: `/do-task 12`
.codex/skills/do-task/SKILL.md
+80
View File
@@ -0,0 +1,80 @@
---
name: do-task
description: Phase 2 skill. Use when issue scope is locked by Product Owner (Phase 1 done). Plan, implement, create PR, and own it until merged as Developer.
---
# Do Task
**Phase:** 2 — Requirement Implementation
**Role:** Developer
## When to invoke
- User says: "implement issue #X", "/do-task #X"
- Phase 1 is complete (issue has a "Final Requirements" comment from PO).
## Prerequisite
- Issue must have a **Final Requirements** comment locked by PO. If not found, stop and tell the user to run `/validate-issue` first.
## Workflow
1. **Load issue**
- Read issue: `mcp__gitea__.issue_read` (`method: "get"`).
- Read comments, find the **Final Requirements** comment: `mcp__gitea__.issue_read` (`method: "get_comments"`).
- If Final Requirements not found → stop, tell user to validate issue first.
2. **Read codebase**
- Use `mcp__gitea__.get_file_contents`, `mcp__gitea__.get_repository_tree` to understand current state.
- Identify files and functions that need to change.
3. **Write plan and post on issue**
- List implementation steps with verification criteria.
- List files to change.
- Flag risks or tradeoffs.
- Post plan as comment: `mcp__gitea__.issue_write` (`method: "add_comment"`).
- **Wait for "Approved" before coding.** Stop here.
4. **Implement** (only after plan is approved)
- Create feature branch from `main`:
```
git checkout main && git pull origin main
git checkout -b feat/<short-description>
```
- If currently on another branch, use worktree:
```
git worktree add .worktrees/<branch-name> main
```
- Implement following the plan (surgical changes only).
- Run validation:
```
gofmt -l .
go vet ./...
go test ./...
```
5. **Create PR**
- Use `mcp__gitea__.pull_request_write` (`method: "create"`).
- PR body must include:
- Summary of changes
- Test evidence (exact commands and output)
- `Fixes #<issue-id>`
- Add reviewer.
6. **Own the PR until merged**
- Monitor for review feedback: `mcp__gitea__.pull_request_read` (`method: "get_reviews"`, `get_review_comments`).
- When feedback arrives:
- Checkout the PR branch (or use worktree if on another branch).
- Fix code locally, commit, push.
- Reply on PR: `mcp__gitea__.pull_request_review_write` (`method: "create"`, `state: "COMMENT"`) explaining what was fixed.
- Never edit remote files directly via API.
- After reviewer approves (APPROVED), merge the PR if user confirms.
## Rules
- Use Gitea MCP tools for all issue/PR operations.
- Never edit remote files directly — always work on local branch.
- Never claim completion without fresh verification output.
- Keep changes strictly scoped to the approved plan.
## Next skill
After PR is created, the user invokes `/review-pr <pr-number>` on the Reviewer agent.
.codex/skills/review-pr/SKILL.codex.md
+133
View File
@@ -0,0 +1,133 @@
---
name: review-pr
description: Review pull requests in Gitea repositories using Gitea MCP for server-side PR metadata, comments, reviews, diffs, workflow state, and PR comments. Use local CLI tools such as git and test runners only for local repository inspection and validation. Use when the user asks to "Review PR", "review pull request", "check PR", "recheck PR after updates", or "post review comment". Inspect PR metadata and discussion, compare the PR head against its base branch, produce a clear PASS/FAIL verdict, and optionally post the result back to the PR.
---
# Review PR
## Local Preference
For repositories on `git.thuanle.me`, prefer the `mcp__gitea__` tools for Gitea-hosted pull request metadata, comments, reviews, server-side diffs, repository contents, branches, commits, workflow runs, and PR comments. Do not use `tea` or other command-line Gitea API clients unless the user explicitly asks for them or the MCP tools are unavailable for the required Gitea operation. Other local CLI tools such as `git`, `go`, `rg`, test runners, and formatters are OK for local repository inspection and validation.
## Workflow
Follow this sequence:
1. Identify the PR and current repo context.
- Use the current repository when the user is already inside it.
- If the user gives only a PR number and the repo context is ambiguous, ask a short clarifying question.
- Do not ask follow-up questions when the repository, PR, and requested reviewer action are already clear.
- If the user has already given a standing instruction earlier in the same thread such as "if you're confident, post it", carry that instruction forward for later re-reviews until the user changes it.
- Read the PR first with `mcp__gitea__.pull_request_read` using `method: "get"`, and read issue comments with `mcp__gitea__.issue_read` using `method: "get_comments"`.
- Read reviews with `mcp__gitea__.pull_request_read` using `method: "get_reviews"` when review state matters.
- Note the PR status exactly. If it is already merged or closed, say so explicitly before continuing.
2. Read the review history before judging the latest update.
- Find the latest blocking review comments first.
- If the author says they addressed feedback in a follow-up commit, focus on the new commits after that discussion.
- Still sanity-check the current full PR diff before concluding `PASS`.
3. Compare against the real base branch.
- Use PR metadata from MCP as the source of truth for base/head refs and SHAs.
- Prefer the PR base branch from MCP metadata; use `main` only when the base branch is not obvious from PR metadata.
4. Inspect the code changes.
- Use `mcp__gitea__.pull_request_read` with `method: "get_diff"` to read the PR diff.
- Use `mcp__gitea__.get_file_contents`, `mcp__gitea__.get_repository_tree`, and commit/branch MCP reads for surrounding context.
- If the user asks for a re-review after updates, optionally diff the latest fix commit range as a helper view, but do not skip the full PR sanity check.
5. Validate behavior where it matters.
- Prefer an isolated worktree when validation should run on the PR snapshot instead of the currently checked out branch.
- Use a repository-local worktree under `.worktrees/` by default, for example `git worktree add .worktrees/pr-<pr> origin/<head>`. Before creating it, run `git worktree list` and confirm the repo-local `.worktrees/` path.
- For `/Users/tm/working/thuanle/crypto/crypto-price-bot`, PR validation worktrees must be under `.worktrees/pr-<pr>` from the repository root. Do not use `/tmp` for this repo; if `.worktrees/` is unavailable, stop and ask the user before using any fallback path.
- Run validation commands inside that worktree.
- Remove it afterward with `git worktree remove .worktrees/pr-<pr>` when it is no longer needed.
- For other repositories, if `git worktree add` fails because the environment blocks writes to `.git/worktrees`, fall back to exporting a temporary snapshot for validation and say that you used the fallback.
- Run repo-appropriate checks when feasible.
- Prefer targeted checks first, then broader validation such as `go test ./...` and `go vet ./...` in Go repositories.
- Say explicitly when validation could not be run.
6. Write the verdict for the user.
- Start with `PASS` or `FAIL`.
- For `FAIL`, list blocking findings first, ordered by severity.
- Include file and line references whenever possible.
- Explain the concrete behavior impact, not style preferences.
- For `PASS`, say that no blocking issues were found and then add any non-blocking notes.
7. Post a review result proactively by default.
- When acting as a reviewer, prefer an official PR review over a plain issue comment if the result should affect PR state.
- Default stance: if the verdict is clear and you are confident in it, post the review without waiting for another prompt from the user.
- If the user has already asked you to post the result, or has given a standing instruction such as "if you're confident, post it", treat that as continuing authority for later re-reviews in the same thread unless the user revokes or narrows it.
- Ask the user only when there is a real ambiguity you cannot safely resolve, such as unclear repo/PR context, unclear whether they explicitly want a local-only verdict instead of a posted review, or a materially uncertain finding.
- If the user explicitly asks for a local verdict only, do not post.
- Use `mcp__gitea__.pull_request_review_write` for review posting.
- For normal review results, prefer a single `create` call with the final `state` and `body`. This is the default path for `PASS`, `FAIL`, and neutral review comments.
- Use `submit` only when you intentionally need a multi-step pending review flow, such as staging a pending review first and finalizing it later.
- Never send the same review narrative through both `create` and `submit`; that is a process bug and can surface as duplicate review content in the UI.
- Map the verdict to review state:
- `PASS` -> `APPROVED`
- `FAIL` -> `REQUEST_CHANGES`
- neutral/non-blocking note only -> `COMMENT`
- Use `mcp__gitea__.issue_write` with `method: "add_comment"` only for plain discussion comments that should not change PR review status.
- Do not add bracketed author/tool tags such as `[codex]`.
- Start directly with the review result or author response, depending on your role in the thread.
- Keep the review/comment concise and direct.
- Mention the validation commands you actually ran when posting review results.
## Command Patterns
Use these MCP operations directly:
- `mcp__gitea__.pull_request_read` with `method: "get"`
- `mcp__gitea__.pull_request_read` with `method: "get_diff"`
- `mcp__gitea__.pull_request_read` with `method: "get_reviews"`
- `mcp__gitea__.pull_request_read` with `method: "get_review_comments"` when a specific review thread is needed
- `mcp__gitea__.issue_read` with `method: "get_comments"`
- `mcp__gitea__.get_file_contents`
- `mcp__gitea__.get_repository_tree`
- `mcp__gitea__.get_commit`
- `mcp__gitea__.actions_run_read` for workflow status and logs
- `mcp__gitea__.pull_request_review_write` with `method: "create"` for the normal one-shot final review path
- Set the final `state` on `create`
- Put the final review text on `create`
- `mcp__gitea__.pull_request_review_write` with `method: "submit"` only when finishing an intentionally pending review
- `mcp__gitea__.issue_write` with `method: "add_comment"` when posting a plain PR comment
Do not use `tea` for Gitea PR review unless the user explicitly requests it or MCP cannot provide the needed data. Local CLI usage such as `git diff`, `git worktree`, and test commands remains acceptable when it materially improves local validation.
## Comment Template
Use this structure when posting a review result:
```text
PASS
No blocking issues found in the latest update.
Validation:
- <command 1>
- <command 2>
Non-blocking note:
- <optional note>
```
```text
FAIL
1. [High] <blocking issue with path:line and impact>
2. [Medium] <blocking issue with path:line and impact>
Validation:
- <command 1>
- <command 2>
```
When acting as a reviewer and the user asks to approve/reject or otherwise post the result, also submit the matching official review state:
- `PASS` -> `APPROVED`
- `FAIL` -> `REQUEST_CHANGES`
- neutral note only -> `COMMENT`
When responding as the PR author rather than reviewer, do not use `PASS`/`FAIL`; write a concise author response that explains what feedback was addressed and which validation ran.
Do not add filler. Keep the review specific, technical, and actionable.
.codex/skills/review-pr/SKILL.md
+110
View File
@@ -0,0 +1,110 @@
---
name: review-pr
description: Phase 2 skill. Use when a PR is created or updated. Review PR against locked issue requirements and post verdict as Reviewer. Do NOT edit code on the PR.
---
# Review PR
**Phase:** 2 — Requirement Implementation
**Role:** Reviewer
## When to invoke
- User says: "review PR #X", "check PR #X", "/review-pr #X"
- A PR is created or updated and needs review.
## Prerequisite
- PR exists on Gitea.
- The referenced issue has a **Final Requirements** comment from PO (Phase 1 done).
## Workflow
1. **Load PR and issue**
- Read PR: `mcp__gitea__.pull_request_read` (`method: "get"`).
- Identify the linked issue from PR body (`Fixes #<id>` or `Closes #<id>`).
- Read issue comments, find the **Final Requirements** comment: `mcp__gitea__.issue_read` (`method: "get_comments"`).
- Read existing reviews: `mcp__gitea__.pull_request_read` (`method: "get_reviews"`).
- If PR is already merged or closed, say so and stop.
2. **Read review history** (for re-reviews)
- Get review comments: `mcp__gitea__.pull_request_read` (`method: "get_review_comments"`).
- If author addressed feedback in a follow-up commit, focus on new commits but still sanity-check the full diff.
3. **Get the diff**
- Use `mcp__gitea__.pull_request_read` (`method: "get_diff"`).
- Use `mcp__gitea__.get_file_contents` for surrounding context when needed.
4. **Validate locally** (when needed)
- Create worktree:
```
git worktree add .worktrees/pr-<number> origin/<head-branch>
```
- Run checks:
```
gofmt -l .
go vet ./...
go test ./...
```
- Remove worktree when done:
```
git worktree remove .worktrees/pr-<number>
```
5. **Evaluate**
- Does PR address **all** Final Requirements from the issue?
- Does PR contain unrelated changes or refactoring? → FAIL immediately.
- Code correctness, style, test coverage.
6. **Write verdict**
- Start with **PASS** or **FAIL**.
- Include file:line references for findings.
- Explain concrete impact, not style preferences.
7. **Post review**
- Post proactively if verdict is clear.
- Use `mcp__gitea__.pull_request_review_write` (`method: "create"`):
- `PASS` → `state: "APPROVED"`
- `FAIL` → `state: "REQUEST_CHANGES"`
- Non-blocking note → `state: "COMMENT"`
- For plain discussion (not changing review state): `mcp__gitea__.issue_write` (`method: "add_comment"`).
## Review Format
### PASS
```
PASS
No blocking issues found.
Validation:
- gofmt -l .: OK
- go vet ./...: OK
- go test ./...: OK
Non-blocking:
- <optional note>
```
### FAIL
```
FAIL
1. [High] <issue with path:line and impact>
2. [Medium] <issue with path:line and impact>
Validation:
- go test ./...: FAIL (<details>)
```
## Rules
- Use Gitea MCP tools for all PR/review operations.
- Do NOT edit code on the PR.
- FAIL if PR contains unrelated changes or scope creep.
- Post review proactively if verdict is clear.
- Mention validation commands you actually ran.
- No bracketed author/tool tags.
## What happens next
- **PASS (APPROVED):** Developer merges the PR.
- **FAIL (REQUEST_CHANGES):** Developer fixes feedback, then user re-invokes `/review-pr` on this PR.
.codex/skills/validate-issue/SKILL.md
+65
View File
@@ -0,0 +1,65 @@
---
name: validate-issue
description: Phase 1 skill. Use when a Gitea issue is created or updated and needs requirement validation. Analyze, clarify, and lock scope as Product Owner. Do NOT implement.
---
# Validate Issue
**Phase:** 1 — Requirement Refinement
**Role:** Product Owner
## When to invoke
- User says: "check issue #X", "validate issue #X", "/validate-issue #X"
- A new issue is created or an existing issue is updated with new information.
## Prerequisite
- Issue exists on Gitea.
## Workflow
1. **Load issue**
- Read issue: `mcp__gitea__.issue_read` (`method: "get"`).
- Read comments: `mcp__gitea__.issue_read` (`method: "get_comments"`).
2. **Analyze**
- Is the problem statement clear?
- Is the scope well-defined or too broad?
- Is it technically feasible?
- If needed, read relevant code: `mcp__gitea__.get_file_contents`.
3. **Decide**
- **Unclear or incomplete:**
- Post clarifying questions: `mcp__gitea__.issue_write` (`method: "add_comment"`).
- Stop. Wait for user to respond, then re-run this skill.
- **Clear and feasible:**
- Post Final Requirements (see format below).
- This locks the scope and signals Phase 2 can begin.
## Final Requirements format
```
## Final Requirements
**Summary:** <one-line summary>
**Scope:**
- <requirement 1>
- <requirement 2>
**Out of scope:**
- <explicitly excluded items>
**Acceptance criteria:**
- <verifiable check 1>
- <verifiable check 2>
```
## Rules
- Use Gitea MCP tools for all operations.
- Do NOT write code, create branches, or create PRs.
- Do NOT proceed to Phase 2 — that is a separate skill.
## Next skill
After Final Requirements are posted, the user invokes `/do-task <issue-id>` on the Developer agent.
AGENT.md
+58 -77
View File
@@ -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.
CLAUDE.md
+2
View File
@@ -1,3 +1,5 @@
# CLAUDE.md
See [AGENT.md](AGENT.md) for full project instructions and workflow.
Agent skills are stored in `.codex/skills`