diff --git a/packages/junior-github/skills/github-code/SKILL.md b/packages/junior-github/skills/github-code/SKILL.md index 05e479c0..1a2be014 100644 --- a/packages/junior-github/skills/github-code/SKILL.md +++ b/packages/junior-github/skills/github-code/SKILL.md @@ -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 `` `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: + +``` +(): +``` + +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 +``` + +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 ` 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:** `(): ` — 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%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. diff --git a/packages/junior-github/skills/github-code/references/api-surface.md b/packages/junior-github/skills/github-code/references/api-surface.md index 7a3d1b9a..54282970 100644 --- a/packages/junior-github/skills/github-code/references/api-surface.md +++ b/packages/junior-github/skills/github-code/references/api-surface.md @@ -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]` |