Skip to content

ref(github-code): Add edit workflow, verification, and on-behalf-of attribution #392

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dcramer merged 1 commit into from
May 21, 2026
+147 −59
Merged

ref(github-code): Add edit workflow, verification, and on-behalf-of attribution #392

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 140 additions & 58 deletions packages/junior-github/skills/github-code/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,90 +6,172 @@ allowed-tools: bash

# GitHub Code Operations

Repository checkout, source-code investigation, and pull request operations via `gh` CLI.
Use `gh` and `git` for repository checkout, source investigation, code changes, commits, and pull requests.

## Reference loading
## References

| Operation | Load |
| ------------- | -------------------------------------------------------------------------------------- |
| Any operation | [references/api-surface.md](references/api-surface.md) |
| On failure | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
| Need | Load |
| ---- | ---- |
| Command syntax, permissions, config | [references/api-surface.md](references/api-surface.md) |
| Failed commands, auth errors | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |

## Core rules

- Resolve the target repo: explicit request wins, then `github.repo` config. Run `jr-rpc config get github.repo` standalone — never chain with `cd`, pipes, `gh`, or `git`.
- Keep `--repo owner/repo` explicit on all `gh` commands; use `git -C PATH` for local repos.
- Do not treat this skill's files or `/skills/...` as target repository source.
- Read repo-local instructions (`AGENTS.md`, `.github/AGENTS.md`, nested equivalents) before editing. When repo, task-specific, and skill instructions conflict, follow the narrower rule.
- Do not overwrite or revert unrelated user changes.
- Do not guess architecture, upstream intent, or feedback validity without reading the relevant code, comments, or failing output.
- Do not claim checks ran unless they did. Do not declare a fix complete without running the chosen check or stating why no credible check was available.
- Stop on: missing repo access, ambiguous target, destructive op without confirmation, or unresolved auth failure.

## Workflow

### 1. Resolve operation and target
### 1. Resolve target and state

- Determine whether the task is `clone`, `source-code investigation`, a pull request inspection (`view`, `list`, `diff`, `checks`), or a pull request mutation (`create`, `update`, `close`, `merge`).
- Resolve repository from the requested action: explicit target wins; otherwise use `<configuration>` `github.repo`. If absent, run standalone `jr-rpc config get github.repo`.
- Preserve non-target GitHub references when they materially support the work.
- Run `jr-rpc config get github.repo` as its own bash command. Do not combine it with `cd`, `&&`, pipes, or any `gh` or `git` command.
- After resolving a configured repo, pass it explicitly to the next `gh` command with `--repo owner/repo`; do not rely on implicit GitHub CLI repository discovery.
- Resolve the pull request number for operations targeting an existing PR.
- Keep `--repo owner/repo` explicit on `gh` commands so the command itself targets the intended repository, not a stale default.
Identify `owner/repo`, local checkout path, default branch, and current branch.

### 2. Execute by operation type
For edit operations, also check:

**Clone** → shallow clone path below.
**Source-code investigation** → source-code path below.
**Pull request inspection** → inspection path below.
**Pull request mutation** → mutation path below.
- current branch and uncommitted changes
- package manager, build tool, monorepo structure
- relevant test/lint/typecheck commands
- repo-local instructions that override this skill

---
Choose a validation path before editing:

### Clone path
- changed-file or package-scoped checks before broad suites
- targeted tests before full runs
- repo-native scripts, fixtures, playgrounds, or smoke checks before one-off scaffolding

- Default to a shallow clone; deepen incrementally only when the task needs history.
- Use exact command forms from [references/api-surface.md](references/api-surface.md).
- After cloning, check for `AGENTS.md` in the repo root (and `.github/AGENTS.md`) before making edits. Treat discovered instructions as hard constraints.
- Report the local directory and whether the clone is shallow or full.
For risky, user-visible, or long-running changes, capture a baseline before editing. If the baseline already fails, record it as pre-existing.

---
Prefer existing local checkouts over cloning. Default to shallow clones.

### Source-code investigation path
### 2. Investigate before editing

- Use for questions like "where is this implemented?", "how does this workflow work in code?", "is there already logic for X?", or "verify this from the repo."
- If the current workspace already contains the target repository, inspect local files directly before cloning.
- Do not treat this skill's `SKILL.md`, bundled references, or `/vercel/sandbox/skills/...` as target repository source code. If no checkout of the target repo is present, inspect the configured GitHub repository by cloning it shallowly or reading files through `gh` before answering.
- Prefer the narrowest deterministic evidence: local file search, exact file reads, targeted clone inspection, existing issues/PRs, tests.
- Cite repository evidence in the reply: file paths, symbols, issue/PR numbers, or commit references when known.
- If evidence is incomplete, say what is unknown instead of guessing.
Before changing code, establish:

---
- where the behavior lives
- what the current vs. requested behavior is
- root cause or gap the change addresses
- what smallest check can prove the result

Rules:

- Prefer narrow evidence: file reads, grep, tests, existing issues/PRs, command output.
- Read referenced issues, PRs, specs, policies, designs, or incidents when the task points to them.
- For product copy, docs, design, or UI work, inspect the real product/project context before inventing wording or layout.
- Before editing a bug, know the failure shape: what breaks, where, and under what condition.
- After a failed fix attempt or strong correction, stop patching symptoms — re-read the evidence and restate the root cause before editing again.
- If the task is investigation-only, answer from evidence without editing.

### 3. Edit safely

- Smallest coherent change that satisfies the request.
- Follow repo-local style, patterns, and API boundaries.
- Keep interfaces, exports, config, and public surfaces no broader than the requirement needs.
- When the change touches related call sites or representations, remove duplication or split logic introduced by the change before finalizing.
- No drive-by refactors or speculative cleanup.
- Do not optimize only for passing tests; solve the requested behavior.
- After meaningful edits, run the smallest relevant repo-real check.
- On check failure, inspect root cause before patching again.

For multi-step or risky work, keep a compact checklist of intent, touched files, verification state, next step, and blockers.

For non-obvious architecture, security-sensitive, concurrency, or repeated-failure work, pause after investigation with evidence, risks, and a proposed plan before pushing ahead.

### 4. Verify before packaging

Before committing and creating a PR for code, config, or docs-as-code changes:

- Run the chosen validation path. Separate pre-existing failures from regressions.
- For docs or instruction-only changes, do a content consistency review instead of claiming automated validation.
- If no credible check exists, say so explicitly.

### 5. Commit

Default format when the repo does not specify otherwise:

```
<type>(<scope>): <Subject>
```

Types: `feat`, `fix`, `ref`, `docs`, `test`, `build`, `ci`, `chore`. Imperative present tense, no trailing period, no agent/tool branding. Keep lines under 100 characters.

### Pull request inspection path
Body only when it helps reviewers understand _why_.

- Use read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md); skip branch resolution and push logic.
- When inspecting PR comments or feedback, query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{number}/comments` and `.../reviews`). Bot review feedback lives in the review comments API, not conversation comments.
- Return canonical PR URL, PR number when available, target repository, and the fields the user asked to inspect.
- If the PR cannot be resolved, report the exact not-found or auth failure and stop.
Footer order: `Fixes`/`Refs` lines, then `Co-authored-by` trailers.

#### On-behalf-of commits

If the commit is authored by a bot and a human requested the work, add a trailer:

```
Co-authored-by: Full Name <email>
```

Resolve name and email from evidence — requester context, Slack profile (`slackUserLookup`), GitHub profile, or repo commit history. If email cannot be confirmed, use `Full Name <noreply>` and note the gap in the PR body.

### 6. Create or update PR

Before creating:

1. Changes committed on a non-default branch.
2. Push the branch explicitly: `git push -u origin BRANCH`.
3. Create with explicit targeting: `gh pr create --repo owner/repo --head BRANCH ...`.

Defaults:

- Draft PRs unless the user or repo says otherwise.
- Reuse an existing PR for the branch; only open a new one when explicitly asked or the work is materially distinct.
- After new commits, re-evaluate title and body against the current diff.

**Title:** `<type>(<scope>): <Subject>` — same rules as commits, no agent branding.

**Body:**

- Reviewer-facing prose, not diff narration.
- What changed and why; what was verified; what remains unverified or risky.
- Issue references when relevant.
- No checkbox boilerplate, no PII or customer data in public repos.

**Footers** (in order):

1. Issue references (`Fixes #N`, `Refs SENTRY-N`), if any.
2. `Action taken on behalf of Full Name.` — when on-behalf-of.
3. Session link — when `gen_ai.conversation.id` is available:

```
---
[View Session in Sentry](https://sentry.sentry.io/traces/?project=4510944073809921&query=gen_ai.conversation.id%3A%22<url-encoded conversation id>%22)
```

**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning reviewers or the requester. Skip assignment when the handle cannot be confirmed.

### 7. Report result

Return: repo, branch, PR URL/number (when applicable), checks run with results, pre-existing failures if any, checks not run and why.

### Pull request mutation path
On failure, report the exact command and error. Do not claim success from partial state.

#### 3. Resolve mutation inputs
Before finishing, reconcile any plan or checklist stated earlier — mark items as done, blocked, or cancelled.

- For PR creation credential/order questions, explicitly answer that repository context comes first, then `git push` pushes the branch with GitHub remote write access, then `gh pr create` runs against the pushed branch with pull-request permissions.
- For PR creation, resolve the base branch (explicit user request wins; otherwise repository default).
- Resolve the head branch from the current checkout or user request.
- If the head branch may not exist on the remote yet, push it explicitly before PR creation.
## Operation-specific notes

#### 4. Execute
**Clone** — shallow by default; deepen only when history is needed. Read repo instructions after cloning, before editing.

- Run `git push` first so `gh pr create` does not trigger hidden push/fork behavior; then `gh pr create --repo owner/repo --head BRANCH ...`.
- If `git push` returns 401/403 or another auth/permission error, verify the command is targeting the right repository and retry once. If it still fails, report the exact command failure and the GitHub App installation/permission remediation.
- Treat `gh pr merge` as a contents mutation and keep repository context explicit.
**Source investigation** — use local files first, otherwise clone shallowly or use `gh`. Cite evidence: file paths, symbols, PRs, issues, command output.

#### 5. Report result
**PR inspection** — read-only `gh pr` and `gh api` commands. Query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{n}/comments` and `.../reviews`).

- Return canonical PR URL, PR number when available, target repository, and applied changes.
- If PR creation fails after explicit push + explicit repo scoping, report the exact auth or validation failure and stop.
**PR mutation** — push before create. Retry once on auth failure after verifying repo targeting. Treat merge, close-with-delete, and force-push as confirmation-required. No admin mutations.

## Guardrails

- Require explicit confirmation only for destructive merges or force operations.
- Answer source-code questions from repository evidence, not product framing or generic memory.
- Default to shallow clones; do not use a full clone unless the task requires repository history or the user asks for it.
- If repository or installation access is missing, stop and return a concrete remediation message.
- GitHub App auth is host-managed; do not ask the user to reconnect a GitHub account.
- Do not execute repository admin mutations.
- Default shallow clones; deepen only when needed.
- Confirm before destructive merges or force operations.
- Answer source questions from repo evidence, not product framing or memory.
- GitHub App auth is host-managed; do not ask users to reconnect accounts.
- Stop and return concrete remediation on missing access or permissions.
8 changes: 7 additions & 1 deletion packages/junior-github/skills/github-code/references/api-surface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,14 @@ Treat explicit repo flags as command-targeting safety rails, not as a credential
| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1` |
| Deepen shallow clone | `git -C DIRECTORY fetch --depth=N origin` |
| Convert shallow clone to full | `git -C DIRECTORY fetch --unshallow` |
| Check branch | `git -C DIRECTORY branch --show-current` |
| Check worktree state | `git -C DIRECTORY status --short --branch` |
| View commit log against base | `git -C DIRECTORY log BASE..HEAD --oneline` |
| Diff against base | `git -C DIRECTORY diff BASE...HEAD` |
| Create branch | `git -C DIRECTORY checkout -b BRANCH` |
| Stage and commit | `git -C DIRECTORY add -A && git -C DIRECTORY commit -m "message"` |
| Push branch before PR creation | `git -C DIRECTORY push -u origin BRANCH` |
| Create pull request | `gh pr create --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH` |
| Create pull request (draft) | `gh pr create --draft --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH` |
| Update pull request | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
| Close pull request | `gh pr close NUMBER --repo owner/repo` |
| Merge pull request | `gh pr merge NUMBER --repo owner/repo [--merge \| --squash \| --rebase]` |
Expand Down
Loading