feat: improve agentic AI development flow and guidelines

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

@@ -0,0 +1,119 @@
+---
+name: address-review
+description: Address review comments on a GitHub pull request
+---
+
+Address review comments on a GitHub pull request.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+The argument is a PR number (e.g. `/address-review 98`). If no number is given, ask the user.
+
+## Phase 1: Fetch and display comments
+
+1. Save the current branch name: `git rev-parse --abbrev-ref HEAD`
+2. Checkout the PR branch: `gh pr checkout <number> --detach`
+3. Fetch all review comments:
+
+```
+gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
+```
+
+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).
+5. Filter out threads that are already resolved or where the last message is from the PR author (likely already addressed).
+6. Present a numbered summary to the programmer:
+
+```
+PR #<number> — <n> unaddressed review comments
+
+ 1. <file>:<line> — @<author>: <first 80 chars of comment>
+ 2. <file>:<line> — @<author>: <first 80 chars of comment>
+ ...
+```
+
+If there are no unaddressed comments, say so and return to the original branch.
+
+## Phase 2: Walk through each comment
+
+For each comment in order, show:
+
+- The full comment body
+- The file path and line number
+- The relevant code context (read ~10 lines around the commented line from the actual file)
+- The author who left the comment
+
+Then ask the programmer what to do using AskUserQuestion with these options:
+
+- **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.
+- **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.
+- **Skip** — Move to the next comment without action.
+
+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.
+
+## Phase 3: Commit, push, and post replies
+
+After walking through all comments:
+
+**Code changes:**
+If any code fixes were made, run the /commit skill to create a commit with the changes, then push:
+
+```
+git push
+```
+
+**Replies:**
+If there are queued replies, show all of them in a final summary:
+
+```
+Queued replies:
+
+1. <file>:<line> — reply to @<author>:
+   "<reply text>"
+
+2. <file>:<line> — reply to @<author>:
+   "<reply text>"
+```
+
+Ask the programmer for final confirmation before posting. They can modify any reply text at this point.
+
+Post each reply as a separate API call:
+
+```
+gh api repos/{owner}/{repo}/pulls/<number>/comments/<comment_id>/replies \
+  --method POST \
+  -f body="<reply text>"
+```
+
+After all replies are posted, return to the original branch:
+
+```
+git checkout <original-branch>
+```
+
+## Reply tone and style
+
+Follow these rules strictly when drafting replies:
+
+- Write as a human developer, not an AI. Never mention AI, automation, or tools.
+- No markdown headings (#, ##, ###) in replies. Plain text and inline formatting only.
+- Keep replies concise — 1-3 sentences. Get to the point.
+- Conversational, collaborative tone: "good catch, fixed in the latest push", "I think this is fine because...", "yeah, updated this to use X instead"
+- Be direct but not dismissive. If you disagree with a comment, explain briefly why.
+- No bullet lists. Keep it flowing as natural text.
+- No emojis.
+- The programmer gets final say on every reply before it is posted.
+
+## Rules
+
+- Never post anything to GitHub without explicit programmer confirmation
+- Never modify code without programmer approval
+- Show exact reply text before queuing it
+- The programmer can modify any reply at any point
+- Always checkout with `--detach` to avoid creating local branches
+- Never push while in detached state. Before any push, explicitly checkout the target branch after programmer confirmation
+- After everything is done, return to the original branch
+- No emojis in any output
+- No markdown headings in any output or posted content
+- If an API call fails, show the error and ask the programmer how to proceed
+
+$ARGUMENTS

.agents/skills/commit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: commit
+description: Create a conventional commit for the current staged/unstaged changes
+---
+
+Create a git commit for the current staged/unstaged changes using Conventional Commits.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+Rules:
+
+1. Run `git status` and `git diff` to understand what changed
+2. Stage relevant files (prefer specific files over `git add -A`)
+3. Write a commit message following Conventional Commits format
+4. Use `--signoff` to sign off using the committer's git config (do NOT hardcode any name/email)
+5. Do NOT add Co-Authored-By or any other trailers beyond Signed-off-by
+6. If there are no changes, say so and stop
+
+Commit format:
+
+```
+<type>[optional scope]: <description>
+```
+
+Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore
+
+Scope (optional): a noun describing the affected area in parentheses.
+Common scopes: config, api, proxy, db, e2e, docker, ci.
+
+Subject line rules:
+
+- Imperative mood ("add", not "added" or "adds")
+- Do NOT capitalize the first letter after the type prefix
+- Do NOT end with a period
+- Keep under 72 characters total
+
+For breaking changes, add `!` after the type/scope:
+
+```
+feat(config)!: rename queue config key
+```
+
+Examples of good messages:
+
+- "feat(api): add support for rejection reason"
+- "fix(config): handle invalid regex on commitConfig"
+- "refactor(ts): remove any/as usages in push-actions"
+- "test(proxy): add tests for Git hosts other than GitHub"
+- "docs: update architecture diagram in Architecture.md"
+- "build: bump express to 5.2.1"
+- "chore: remove unused import in services/push.ts"
+
+Commit command:
+
+```
+git commit --signoff -m "<type>[scope]: <description>"
+```
+
+Do NOT:
+
+- Use long multi-line messages for simple changes
+- Add Co-Authored-By trailers
+- Use past tense ("added", "fixed")
+- Hardcode any author name or email
+- Omit the type prefix

.agents/skills/docs/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: docs
+description: Update existing project documentation to reflect the current state of the branch
+---
+
+Update existing project documentation to reflect the current state of the branch.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+Steps:
+
+1. Run `git diff main...HEAD --stat` and `git log main..HEAD --oneline` to understand what changed on this branch
+2. Read the changed files to understand what was added, removed, or modified
+3. Read the current documentation files: `README.md`, `docs/Architecture.md`, `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`
+4. Identify documentation that is now outdated or missing based on the branch changes
+5. Apply minimal, targeted edits to bring docs in line with the code
+
+What to update:
+
+- **Architecture.md** — new push actions, configuration parameters, plugins, build steps, authentiction methods
+- **README.md** — project description, features list, usage examples
+- **AGENTS.md** — canonical project architecture, invariants, testing commands, and AI-agent workflow guidance
+- **CLAUDE.md** — Claude-specific entry point that should remain aligned with `AGENTS.md`
+- **.github/copilot-instructions.md** — short Copilot-compatible summary of the highest-priority repo rules
+
+Principles:
+
+- **Minimal changes only.** Do not rewrite sections that are already accurate. Edit the smallest possible region.
+- **Capture important information.** New commands, config keys, classes, architecture changes, and breaking changes must be documented.
+- **Keep it concise.** Prefer inline descriptions over new subsections. Use tables and bullet points. Avoid verbose prose.
+- **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.
+- **One edit per concern.** If a section needs updating, make one focused edit rather than rewriting the whole section.
+- **Skip trivial changes.** Internal refactors, renames, or implementation details that don't affect the public interface do not need doc updates.
+
+After editing, report what was updated:
+
+- List each file edited and a one-line description of the change
+- If no docs needed updating, say "Documentation is up to date" and stop
+
+Do NOT:
+
+- Create new documentation files
+- Add sections or headings that don't already exist
+- Rewrite large blocks of text when a small edit suffices
+- Document internal implementation details
+- Add emojis, badges, or decorative elements
+- Update docs for changes that don't affect user-facing behavior

.agents/skills/implement/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: implement
+description: Implement a GitHub issue end-to-end: fetch, plan, code with approval, commit incrementally, and generate a PR summary
+---
+
+Implement a GitHub issue end-to-end: fetch the issue, plan, code with approval, commit incrementally, and generate a PR summary.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+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.
+
+## Phase 1: Fetch issue
+
+1. Parse the argument:
+   - If it is a full URL like `https://github.com/{owner}/{repo}/issues/{number}`, extract `{owner}/{repo}` and `{number}`.
+   - If it is just a number, use the current repo (run `gh repo view --json nameWithOwner -q .nameWithOwner` to get it).
+2. Fetch issue details:
+   ```
+   gh issue view <number> --repo <owner/repo> --json title,body,labels,assignees,comments
+   ```
+3. Display a summary to the programmer:
+   - Issue number and title
+   - Labels (if any)
+   - Body (truncated to ~40 lines if longer)
+   - Number of comments and any noteworthy discussion points
+4. Ask the programmer to confirm this is the right issue before proceeding. Use AskUserQuestion with options: "Proceed", "Show full issue body", "Cancel".
+
+## Phase 2: Branch setup
+
+1. List all configured remotes: `git remote -v`
+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).
+   If there is only one remote, use it automatically.
+3. Fetch and update main from the chosen remote:
+   ```
+   git fetch <remote>
+   git checkout main
+   git pull <remote> main
+   ```
+4. Create a new branch from main. The branch name must follow this convention:
+   - 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).
+   - Examples: `feat/dynamic-allocation-support`, `fix/event-watcher-reconnect`, `refactor/pod-spec-converter`
+   - Pick the type based on the issue labels and description (e.g. a bug report maps to `fix/`, a feature request to `feat/`).
+   ```
+   git checkout -b <type>/<short-slug>
+   ```
+5. Confirm to the programmer: "Created branch `<branch-name>` from `<remote>/main`."
+
+## Phase 3: Plan
+
+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.
+2. Create an implementation plan with numbered steps. Each step should be a logical, committable unit of work. The plan must include:
+   - A 1-2 sentence summary of the issue
+   - Numbered steps, where each step has a title, a description of what to change, and the affected file paths
+3. Save the plan to `plans/implement-<issue-number>.md` using this format:
+
+   ```
+   ## Issue #<number>: <title>
+
+   <1-2 sentence summary of what the issue asks for>
+
+   ## Steps
+
+   1. <step title>
+      - <what to change and where>
+      - Files: <path/to/file.ts>
+
+   2. <step title>
+      - <what to change and where>
+      - Files: <path/to/file.ts, path/to/other.ts>
+   ```
+
+4. Show the full plan to the programmer for approval.
+5. Ask the programmer using AskUserQuestion with options: "Approve plan", "Modify plan", "Cancel".
+6. If the programmer wants modifications, iterate on the plan until approved.
+
+## Phase 4: Execute step by step
+
+For each step in the approved plan:
+
+1. Announce the step: "Step <n>/<total>: <step title>"
+2. Make the code changes for that step
+3. If the step involves logic changes, run tests (`npm run test`) and show the result
+4. Show the programmer a brief summary of what changed (key files and the nature of the change)
+5. Ask the programmer using AskUserQuestion with options: "Commit this step", "Revise changes", "Skip this step", "Stop here".
+6. If the programmer picks "Commit this step", run the /commit skill to commit the changes
+7. If the programmer picks "Revise changes", iterate until they are satisfied
+8. If the programmer picks "Skip this step", move to the next step without committing
+9. If the programmer picks "Stop here", skip all remaining steps and jump to Phase 5
+
+After each commit, briefly confirm the commit was made and move to the next step.
+
+## Phase 5: Summary
+
+1. After all steps are complete (or the programmer stops early):
+   - Run the /summary skill to generate a PR description based on all commits made during this session
+   - Show the summary to the programmer
+2. Do NOT create a PR or push. Just present the summary for the programmer to use when they are ready.
+3. If no commits were made (e.g. the programmer cancelled early), skip the summary and say so.
+
+## Rules
+
+- Never make code changes without programmer approval
+- Always show what changed after each step before committing
+- The programmer can modify, skip, reorder, or stop steps at any point
+- Save the plan file before starting execution so the programmer has a reference
+- Each commit should be a logical unit (one step = one commit, unless the step is trivial)
+- 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
+- No emojis in any output
+- Do not create a PR or push to remote — only local commits and a summary
+- If a step requires running tests, run them and show results before committing
+- Use subagents for codebase exploration and code changes; keep the main flow focused on coordination and programmer interaction
+
+$ARGUMENTS

.agents/skills/issue/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: issue
+description: Create a GitHub issue markdown file from a bug report, feature request, or discussion context
+---
+
+Create a GitHub issue markdown file from the details provided by the user.
+
+Read `AGENTS.md` first. It is the canonical project guide for this repository.
+
+The user will describe a bug, feature request, or discussion context (e.g. Slack conversations, error logs, reproduction steps). Your job is to turn that into a well-structured issue and save it to `plans/`.
+
+Steps:
+
+1. Read the user's input to understand the problem, who reported it, and any logs or reproduction steps provided
+2. Investigate the codebase to identify relevant code paths, pinpoint where the issue likely originates, and gather context that would help a contributor understand the problem
+3. Write a concise GitHub issue markdown file and save it to `plans/issue-<short-slug>.md`
+
+Issue format:
+
+- Start with `## <title>` as the first line (this becomes the GitHub issue title)
+- `### Problem` — 2-3 sentences explaining the issue and its impact
+- `### Steps to Reproduce` — numbered list (if applicable)
+- `### Expected Behavior` — 1-2 sentences
+- `### Actual Behavior` — include relevant log snippets in code blocks, keep them short (trim stack traces to the key lines)
+- `### Potential Root Cause` — based on your codebase investigation, explain where the issue likely lives. Link to source code using upstream GitHub URLs: `https://github.com/finos/git-proxy/blob/main/...#L<start>-L<end>`.
+- `### Affected Files` — table with file links and one-line role descriptions
+- `### Additional Context` — bullet points for version info, related code paths, or anything else useful
+
+Style rules:
+
+- Keep it concise — the whole issue should be under 80 lines
+- Use code blocks sparingly — only for key log lines and small code snippets
+- Do not propose fixes or implementation approaches
+- Do not add Labels, Description, or Title as separate sections — the `##` heading is the title
+- Write for a contributor who knows the project but hasn't seen this specific bug
+- No emojis
+
+$ARGUMENTS