Skip to content

Commit da402f3

Browse files
jescaladajescalada
authored
Merge pull request #1411 from jescalada/add-claude-md
feat: improve agentic AI development flow and guidelines
2 parents 3186da2 + 693d62b commit da402f3

20 files changed

Lines changed: 959 additions & 2 deletions

File tree

‎.agents/skills/address-review/SKILL.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
name: address-review
3+
description: Address review comments on a GitHub pull request
4+
---
5+
6+
Address review comments on a GitHub pull request.
7+
8+
Read `AGENTS.md` first. It is the canonical project guide for this repository.
9+
10+
The argument is a PR number (e.g. `/address-review 98`). If no number is given, ask the user.
11+
12+
## Phase 1: Fetch and display comments
13+
14+
1. Save the current branch name: `git rev-parse --abbrev-ref HEAD`
15+
2. Checkout the PR branch: `gh pr checkout <number> --detach`
16+
3. Fetch review data (pick one):
17+
18+
**REST (simple):** Lists inline review comments; it does **not** include per-thread `resolved` status, so you cannot rely on it alone to skip resolved threads.
19+
20+
```
21+
gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
22+
```
23+
24+
**GraphQL (for filtering resolved threads):** Returns `reviewThreads` with `isResolved`, `isOutdated`, paths/lines, and nested comments—use this when step 5 must honor “already resolved.” Paginate with `cursor` (use `null` or omit for the first page; then pass `reviewThreads.pageInfo.endCursor` while `hasNextPage` is true).
25+
26+
```
27+
gh api graphql -f query='
28+
query($owner:String!, $repo:String!, $number:Int!, $cursor:String) {
29+
repository(owner:$owner, name:$repo) {
30+
pullRequest(number:$number) {
31+
reviewThreads(first:100, after:$cursor) {
32+
pageInfo { hasNextPage endCursor }
33+
nodes {
34+
isResolved
35+
isOutdated
36+
path
37+
line
38+
originalLine
39+
comments(first:100) {
40+
nodes {
41+
databaseId
42+
body
43+
author { login }
44+
createdAt
45+
url
46+
}
47+
}
48+
}
49+
}
50+
}
51+
}
52+
}' -F owner={owner} -F repo={repo} -F number=<number> -F cursor=<cursor>
53+
```
54+
55+
First page: pass JSON `null` for `cursor` (see `gh help api` / your shell for how `gh` expects null). Later pages: set `cursor` to the previous response’s `reviewThreads.pageInfo.endCursor` until `hasNextPage` is false.
56+
57+
4. Group comments by file. For each comment, extract: `id`, `path`, `line` (or `original_line`), `body`, `user.login`, `in_reply_to_id` (to detect threads). If you used GraphQL, map `databaseId` to `id` and thread fields as needed.
58+
5. Filter out threads that are already resolved (when using GraphQL method).
59+
6. Present a numbered summary to the programmer:
60+
61+
```
62+
PR #<number> — <n> unaddressed review comments
63+
64+
1. <file>:<line> — @<author>: <first 80 chars of comment>
65+
2. <file>:<line> — @<author>: <first 80 chars of comment>
66+
...
67+
```
68+
69+
If there are no unaddressed comments, say so and return to the original branch.
70+
71+
## Phase 2: Walk through each comment
72+
73+
For each comment in order, show:
74+
75+
- The full comment body
76+
- The file path and line number
77+
- The relevant code context (read ~10 lines around the commented line from the actual file)
78+
- The author who left the comment
79+
80+
Then ask the programmer what to do using AskUserQuestion with these options:
81+
82+
- **Fix** — Make a code change to address the comment. After the programmer picks this, analyze the comment and the surrounding code, propose a fix, and apply it with Edit. Show the programmer what changed and confirm before moving to the next comment.
83+
- **Reply** — Draft a reply to the comment. Write a concise, human-sounding response (see tone rules below). Show the exact text to the programmer. They can modify it. Queue the reply for posting in Phase 3.
84+
- **Skip** — Move to the next comment without action.
85+
86+
If the programmer chooses Fix, apply the change and move on. If they choose Reply, queue it. Track all code changes and queued replies separately.
87+
88+
## Phase 3: Commit, push, and post replies
89+
90+
After walking through all comments:
91+
92+
**Code changes:**
93+
If any code fixes were made, run the /commit skill to create a commit with the changes, then push:
94+
95+
```
96+
git push
97+
```
98+
99+
**Replies:**
100+
If there are queued replies, show all of them in a final summary:
101+
102+
```
103+
Queued replies:
104+
105+
1. <file>:<line> — reply to @<author>:
106+
"<reply text>"
107+
108+
2. <file>:<line> — reply to @<author>:
109+
"<reply text>"
110+
```
111+
112+
Ask the programmer for final confirmation before posting. They can modify any reply text at this point.
113+
114+
Post each reply as a separate API call:
115+
116+
```
117+
gh api repos/{owner}/{repo}/pulls/<number>/comments/<comment_id>/replies \
118+
--method POST \
119+
-f body="<reply text>"
120+
```
121+
122+
After all replies are posted, return to the original branch:
123+
124+
```
125+
git checkout <original-branch>
126+
```
127+
128+
## Reply tone and style
129+
130+
Follow these rules strictly when drafting replies:
131+
132+
- Write as a human developer, not an AI. Never mention AI, automation, or tools.
133+
- No markdown headings (#, ##, ###) in replies. Plain text and inline formatting only.
134+
- Keep replies concise — 1-3 sentences. Get to the point.
135+
- Conversational, collaborative tone: "good catch, fixed in the latest push", "I think this is fine because...", "yeah, updated this to use X instead"
136+
- Be direct but not dismissive. If you disagree with a comment, explain briefly why.
137+
- No bullet lists. Keep it flowing as natural text.
138+
- No emojis.
139+
- The programmer gets final say on every reply before it is posted.
140+
141+
## Rules
142+
143+
- Never post anything to GitHub without explicit programmer confirmation
144+
- Never modify code without programmer approval
145+
- Show exact reply text before queuing it
146+
- The programmer can modify any reply at any point
147+
- Always checkout with `--detach` to avoid creating local branches
148+
- Never push while in detached state. Before any push, explicitly checkout the target branch after programmer confirmation
149+
- After everything is done, return to the original branch
150+
- No emojis in any output
151+
- No markdown headings in any output or posted content
152+
- If an API call fails, show the error and ask the programmer how to proceed
153+
154+
$ARGUMENTS

‎.agents/skills/commit/SKILL.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
name: commit
3+
description: Create a conventional commit for the current staged/unstaged changes
4+
---
5+
6+
Create a git commit for the current staged/unstaged changes using Conventional Commits.
7+
8+
Read `AGENTS.md` first. It is the canonical project guide for this repository.
9+
10+
Rules:
11+
12+
1. Run `git status` and `git diff` to understand what changed
13+
2. Stage relevant files (prefer specific files over `git add -A`)
14+
3. Write a commit message following Conventional Commits format
15+
4. Use `--signoff` to sign off using the committer's git config (do NOT hardcode any name/email)
16+
5. Do NOT add Co-Authored-By or any other trailers beyond Signed-off-by
17+
6. If there are no changes, say so and stop
18+
19+
Commit format:
20+
21+
```
22+
<type>[optional scope]: <description>
23+
```
24+
25+
Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
26+
27+
Scope (optional): a noun describing the affected area in parentheses.
28+
Common scopes: config, api, proxy, db, e2e, docker, ci.
29+
30+
Subject line rules:
31+
32+
- Imperative mood ("add", not "added" or "adds")
33+
- Do NOT capitalize the first letter after the type prefix
34+
- Do NOT end with a period
35+
- Keep under 72 characters total
36+
37+
For breaking changes, add `!` after the type/scope:
38+
39+
```
40+
feat(config)!: rename queue config key
41+
```
42+
43+
Examples of good messages:
44+
45+
- "feat(api): add support for rejection reason"
46+
- "fix(config): handle invalid regex on commitConfig"
47+
- "refactor(ts): remove any/as usages in push-actions"
48+
- "test(proxy): add tests for Git hosts other than GitHub"
49+
- "docs: update architecture diagram in Architecture.md"
50+
- "build: bump express to 5.2.1"
51+
- "chore: remove unused import in services/push.ts"
52+
53+
Commit command:
54+
55+
```
56+
git commit --signoff -m "<type>[scope]: <description>"
57+
```
58+
59+
Do NOT:
60+
61+
- Use long multi-line messages for simple changes
62+
- Add Co-Authored-By trailers
63+
- Use past tense ("added", "fixed")
64+
- Hardcode any author name or email
65+
- Omit the type prefix

‎.agents/skills/docs/SKILL.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
name: docs
3+
description: Update existing project documentation to reflect the current state of the branch
4+
---
5+
6+
Update existing project documentation to reflect the current state of the branch.
7+
8+
Read `AGENTS.md` first. It is the canonical project guide for this repository.
9+
10+
Steps:
11+
12+
1. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what changed on this branch
13+
2. Read the changed files to understand what was added, removed, or modified
14+
3. Read the current documentation files: `README.md`, `docs/Architecture.md`, `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`
15+
4. Identify documentation that is now outdated or missing based on the branch changes
16+
5. Apply minimal, targeted edits to bring docs in line with the code
17+
18+
What to update:
19+
20+
- **Architecture.md** — new push actions, configuration parameters, plugins, build steps, authentiction methods
21+
- **README.md** — project description, features list, usage examples
22+
- **AGENTS.md** — canonical project architecture, invariants, testing commands, and AI-agent workflow guidance
23+
- **CLAUDE.md** — Claude-specific entry point that should remain aligned with `AGENTS.md`
24+
- **.github/copilot-instructions.md** — short Copilot-compatible summary of the highest-priority repo rules
25+
26+
Principles:
27+
28+
- **Minimal changes only.** Do not rewrite sections that are already accurate. Edit the smallest possible region.
29+
- **Capture important information.** New commands, config keys, classes, architecture changes, and breaking changes must be documented.
30+
- **Keep it concise.** Prefer inline descriptions over new subsections. Use tables and bullet points. Avoid verbose prose.
31+
- **Match existing style.** Follow the formatting, tone, and structure already in each file. Do not add headings, sections, or patterns that don't already exist.
32+
- **One edit per concern.** If a section needs updating, make one focused edit rather than rewriting the whole section.
33+
- **Skip trivial changes.** Internal refactors, renames, or implementation details that don't affect the public interface do not need doc updates.
34+
35+
After editing, report what was updated:
36+
37+
- List each file edited and a one-line description of the change
38+
- If no docs needed updating, say "Documentation is up to date" and stop
39+
40+
Do NOT:
41+
42+
- Create new documentation files
43+
- Add sections or headings that don't already exist
44+
- Rewrite large blocks of text when a small edit suffices
45+
- Document internal implementation details
46+
- Add emojis, badges, or decorative elements
47+
- Update docs for changes that don't affect user-facing behavior

‎.agents/skills/implement/SKILL.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
name: implement
3+
description: Implement a GitHub issue end-to-end: fetch, plan, code with approval, commit incrementally, and generate a PR summary
4+
---
5+
6+
Implement a GitHub issue end-to-end: fetch the issue, plan, code with approval, commit incrementally, and generate a PR summary.
7+
8+
Read `AGENTS.md` first. It is the canonical project guide for this repository.
9+
10+
The argument is an issue number (e.g. `/implement 42`) or a full GitHub URL (e.g. `/implement https://github.com/finos/git-proxy/issues/42`). If no argument is given, ask the user.
11+
12+
## Phase 1: Fetch issue
13+
14+
1. Parse the argument:
15+
- If it is a full URL like `https://github.com/{owner}/{repo}/issues/{number}`, extract `{owner}/{repo}` and `{number}`.
16+
- If it is just a number, use the current repo (run `gh repo view --json nameWithOwner -q .nameWithOwner` to get it).
17+
2. Fetch issue details:
18+
```
19+
gh issue view <number> --repo <owner/repo> --json title,body,labels,assignees,comments
20+
```
21+
3. Display a summary to the programmer:
22+
- Issue number and title
23+
- Labels (if any)
24+
- Body (truncated to ~40 lines if longer)
25+
- Number of comments and any noteworthy discussion points
26+
4. Ask the programmer to confirm this is the right issue before proceeding. Use AskUserQuestion with options: "Proceed", "Show full issue body", "Cancel".
27+
28+
## Phase 2: Branch setup
29+
30+
1. List all configured remotes: `git remote -v`
31+
2. If there is more than one remote, ask the programmer which remote to use as upstream using AskUserQuestion (list the remote names as options).
32+
If there is only one remote, use it automatically.
33+
3. Fetch and update main from the chosen remote:
34+
```
35+
git fetch <remote>
36+
git checkout main
37+
git pull <remote> main
38+
```
39+
4. Create a new branch from main. The branch name must follow this convention:
40+
- Format: `<type>/<short-slug>` where `<type>` is a Conventional Commits type (`feat`, `fix`, `refactor`, `docs`, `chore`, etc.) and `<short-slug>` is a kebab-case summary derived from the issue title (3-5 words max).
41+
- Examples: `feat/dynamic-allocation-support`, `fix/event-watcher-reconnect`, `refactor/pod-spec-converter`
42+
- Pick the type based on the issue labels and description (e.g. a bug report maps to `fix/`, a feature request to `feat/`).
43+
```
44+
git checkout -b <type>/<short-slug>
45+
```
46+
5. Confirm to the programmer: "Created branch `<branch-name>` from `<remote>/main`."
47+
48+
## Phase 3: Plan
49+
50+
1. Based on the issue description, explore the codebase to understand the relevant code paths. Use subagents to search for files, classes, and patterns referenced in or implied by the issue.
51+
2. Create an implementation plan with numbered steps. Each step should be a logical, committable unit of work. The plan must include:
52+
- A 1-2 sentence summary of the issue
53+
- Numbered steps, where each step has a title, a description of what to change, and the affected file paths
54+
3. Save the plan to `plans/implement-<issue-number>.md` using this format:
55+
56+
```
57+
## Issue #<number>: <title>
58+
59+
<1-2 sentence summary of what the issue asks for>
60+
61+
## Steps
62+
63+
1. <step title>
64+
- <what to change and where>
65+
- Files: <path/to/file.ts>
66+
67+
2. <step title>
68+
- <what to change and where>
69+
- Files: <path/to/file.ts, path/to/other.ts>
70+
```
71+
72+
4. Show the full plan to the programmer for approval.
73+
5. Ask the programmer using AskUserQuestion with options: "Approve plan", "Modify plan", "Cancel".
74+
6. If the programmer wants modifications, iterate on the plan until approved.
75+
76+
## Phase 4: Execute step by step
77+
78+
For each step in the approved plan:
79+
80+
1. Announce the step: "Step <n>/<total>: <step title>"
81+
2. Make the code changes for that step
82+
3. If the step involves logic changes, run tests (`npm run test`) and show the result
83+
4. Show the programmer a brief summary of what changed (key files and the nature of the change)
84+
5. Ask the programmer using AskUserQuestion with options: "Commit this step", "Revise changes", "Skip this step", "Stop here".
85+
6. If the programmer picks "Commit this step", run the /commit skill to commit the changes
86+
7. If the programmer picks "Revise changes", iterate until they are satisfied
87+
8. If the programmer picks "Skip this step", move to the next step without committing
88+
9. If the programmer picks "Stop here", skip all remaining steps and jump to Phase 5
89+
90+
After each commit, briefly confirm the commit was made and move to the next step.
91+
92+
## Phase 5: Summary
93+
94+
1. After all steps are complete (or the programmer stops early):
95+
- Run the /summary skill to generate a PR description based on all commits made during this session
96+
- Show the summary to the programmer
97+
2. Do NOT create a PR or push. Just present the summary for the programmer to use when they are ready.
98+
3. If no commits were made (e.g. the programmer cancelled early), skip the summary and say so.
99+
100+
## Rules
101+
102+
- Never make code changes without programmer approval
103+
- Always show what changed after each step before committing
104+
- The programmer can modify, skip, reorder, or stop steps at any point
105+
- Save the plan file before starting execution so the programmer has a reference
106+
- Each commit should be a logical unit (one step = one commit, unless the step is trivial)
107+
- If the issue is from a different repo (not the current one), fetch it via the full URL but make changes in the current repo
108+
- No emojis in any output
109+
- Do not create a PR or push to remote — only local commits and a summary
110+
- If a step requires running tests, run them and show results before committing
111+
- Use subagents for codebase exploration and code changes; keep the main flow focused on coordination and programmer interaction
112+
113+
$ARGUMENTS

0 commit comments

Comments
 (0)