From 216c058fa832314d991cd3a239944d8a4eb42a91 Mon Sep 17 00:00:00 2001 From: apstndb <803393+apstndb@users.noreply.github.com> Date: Sun, 22 Feb 2026 15:19:35 +0900 Subject: [PATCH 1/3] docs(dev): clarify Gemini review/summary request timing in CLAUDE.md Clarify when to use --request-review and --request-summary flags: - PR creation: auto-triggered, do not use these flags - After additional commits: use --request-review for new review - --request-summary: only right before merge Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4d873802..a20d23ee 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,7 +34,7 @@ spanner-mycli is a personal fork of spanner-cli, an interactive CLI for Google C 2. **Resolve conflicts with origin/main** - ensure branch can merge cleanly 3. **Never push/commit directly to main branch** - always use feature branches + PRs 4. **Squash merge only** - enforced via Repository Ruleset -5. **PR merge process**: Use `go tool gh-helper reviews wait` before merging (**DO NOT** use `--request-review`). Request `/gemini summary` only if additional commits were pushed after initial review. +5. **PR merge process**: Use `go tool gh-helper reviews wait` before merging. Gemini review and summary are auto-triggered on PR creation — do NOT use `--request-review` or `--request-summary` at that point. After additional commits: use `--request-review` to get a new review. Use `--request-summary` only right before merge to update the summary. 6. **Squash merge commits**: MUST include descriptive summary of PR changes 7. **GitHub comment editing**: NEVER use `gh pr comment --edit-last` - always specify exact comment ID 8. **GitHub checks must pass**: All CI checks MUST pass before merging. Always investigate failures - never assume they are transient. From 450ef938d07f702af8a41670ca2eef96e1595495 Mon Sep 17 00:00:00 2001 From: apstndb <803393+apstndb@users.noreply.github.com> Date: Sun, 22 Feb 2026 15:20:12 +0900 Subject: [PATCH 2/3] docs(dev): update and add Claude Code skills - release-prep: rewrite for tag-based goreleaser workflow with PR range analysis - review-cycle: clarify Gemini review vs summary distinction, remove auto --request-review - start-issue: add new skill for starting work on GitHub issues with worktree setup Co-Authored-By: Claude Opus 4.6 --- .claude/commands/release-prep.md | 63 +++++++++++++++++++++++++------- .claude/commands/review-cycle.md | 9 ++++- .claude/commands/start-issue.md | 33 +++++++++++++++++ 3 files changed, 89 insertions(+), 16 deletions(-) create mode 100644 .claude/commands/start-issue.md diff --git a/.claude/commands/release-prep.md b/.claude/commands/release-prep.md index 055d5aca..e42be809 100644 --- a/.claude/commands/release-prep.md +++ b/.claude/commands/release-prep.md @@ -1,45 +1,80 @@ --- name: Release Prep -description: Analyze and prepare a milestone for release -arguments: "" +description: Analyze and prepare a new release by pushing a tag (goreleaser creates the release) +arguments: " (e.g. v0.26.0)" --- # Release Preparation -Prepare release for milestone **$ARGUMENTS**. +Prepare release **$ARGUMENTS**. ## Steps -1. Analyze PRs for proper release notes categorization: +1. Fetch latest state and derive PR range to analyze: ```bash -go tool gh-helper releases analyze --milestone $ARGUMENTS +git fetch origin main +LAST_TAG=$(gh api repos/apstndb/spanner-mycli/releases/latest --jq '.tag_name') +PR_NUMS=$(git log ${LAST_TAG}..origin/main --oneline | grep -oE '\(#[0-9]+\)' | grep -oE '[0-9]+' | sort -n) +FIRST_PR=$(echo "$PR_NUMS" | head -1) +LAST_PR=$(echo "$PR_NUMS" | tail -1) +echo "PR range: ${FIRST_PR}-${LAST_PR}" ``` -2. Review the analysis output for: +2. Analyze PRs merged since the last release tag: +```bash +go tool gh-helper releases analyze --pr-range ${FIRST_PR}-${LAST_PR} +``` + +3. Review the analysis output for: - PRs missing classification labels (`bug`, `enhancement`, `breaking-change`) - - PRs that should have `ignore-for-release` label (dev-docs only changes) + - PRs that should have `ignore-for-release` label (dev-docs only, test-only changes) - Inconsistent labeling patterns -3. Fix missing labels based on analysis: +4. Fix missing labels based on analysis: ```bash # Add classification labels to unlabeled PRs go tool gh-helper labels add enhancement --items -# Mark dev-docs-only PRs +# Mark dev-docs-only or test-only PRs go tool gh-helper labels add ignore-for-release --items ``` -4. Re-analyze to verify all PRs are properly labeled: +5. Re-analyze to verify all PRs are properly labeled: ```bash -go tool gh-helper releases analyze --milestone $ARGUMENTS +go tool gh-helper releases analyze --pr-range ${FIRST_PR}-${LAST_PR} +# Confirm: readyForRelease: true ``` -5. Generate draft release notes: +6. Push the release tag to origin/main HEAD (goreleaser will create the draft release automatically): ```bash -gh release create $ARGUMENTS --generate-notes --draft +git fetch origin main +git tag $ARGUMENTS origin/main +git push origin $ARGUMENTS ``` -6. Review the draft release notes and report any issues found. +7. Wait for the goreleaser workflow to complete and review the draft release: +```bash +gh run watch --repo apstndb/spanner-mycli +gh release view $ARGUMENTS --repo apstndb/spanner-mycli +``` + +8. Enhance the release notes before publishing: + - For spanemuboost bump PRs, look up the emulator version and add it as a sub-bullet: + ```bash + # Replace with the spanemuboost version from the PR + gh api "repos/apstndb/spanemuboost/contents/spanemuboost.go?ref=" -q '.content' | base64 -d | grep DefaultEmulatorImage + ``` + - For major new features, add an actual output example as a sub-bullet + - Update the release notes via: + ```bash + gh release edit $ARGUMENTS --repo apstndb/spanner-mycli --notes "..." + ``` + +9. Publish the release: +```bash +gh release edit $ARGUMENTS --repo apstndb/spanner-mycli --draft=false +gh release view $ARGUMENTS --repo apstndb/spanner-mycli --json isDraft,url +``` **Label → Release notes mapping:** - `breaking-change` → "Breaking Changes" diff --git a/.claude/commands/review-cycle.md b/.claude/commands/review-cycle.md index d7365729..49850849 100644 --- a/.claude/commands/review-cycle.md +++ b/.claude/commands/review-cycle.md @@ -7,8 +7,13 @@ description: Wait for Gemini review and check feedback Please execute the following steps: -1. Wait for Gemini review (request if needed): -!go tool gh-helper reviews wait --request-review +1. Wait for Gemini code review: +!go tool gh-helper reviews wait + +**IMPORTANT**: `/gemini summary` and `/gemini review` are DIFFERENT commands. +- `/gemini summary` generates a "Summary of Changes" — this is posted **automatically** on PR creation. Never request it manually. +- `/gemini review` triggers an **inline code review** — this is also automatic but may take several minutes for large PRs. +- If the wait times out without a review, **wait longer or request `/gemini review`** (NOT `/gemini summary`). 2. Check for unresolved threads: !go tool gh-helper reviews fetch --unresolved-only diff --git a/.claude/commands/start-issue.md b/.claude/commands/start-issue.md new file mode 100644 index 00000000..8909e660 --- /dev/null +++ b/.claude/commands/start-issue.md @@ -0,0 +1,33 @@ +--- +allowed-tools: Bash, mcp__github__issue_read, mcp__Phantom__phantom_create_worktree +description: Start working on a GitHub issue by fetching latest state and creating a worktree +arguments: "" +--- + +## Context + +You are starting work on issue #$ARGUMENTS in the spanner-mycli repository. + +## Your task + +1. Fetch the latest state from origin: + ```bash + git fetch origin + ``` + +2. Read the issue details to understand the task: + - Use `mcp__github__issue_read` with method `get` for issue #$ARGUMENTS + - Also check sub-issues: `go tool gh-helper issues show $ARGUMENTS --include-sub` + +3. Derive a descriptive worktree name from the issue title: + - Format: `issue-{N}-{slug}` (e.g., `issue-483-read-lock-mode`) + - Slug: lowercase, hyphens only, strip conventional prefixes (`feat:`, `fix:`, `chore:`, etc.) + - Keep it concise (3-5 meaningful words max) + +4. Create the worktree: + - Use `mcp__Phantom__phantom_create_worktree` with `name=issue-{N}-{slug}` and `baseBranch=origin/main` + +5. Report: + - The issue title and summary + - The worktree path and branch name created + - Key implementation points to address From df849a0863e9b2881e20f8ba621c8c64772335f5 Mon Sep 17 00:00:00 2001 From: apstndb <803393+apstndb@users.noreply.github.com> Date: Sun, 22 Feb 2026 15:23:53 +0900 Subject: [PATCH 3/3] docs(dev): sync Gemini workflow in issue-management.md Update dev-docs/issue-management.md to reflect the same review/summary timing rules added to CLAUDE.md: auto-triggered on PR creation, --request-review after additional commits, --request-summary before merge. Co-Authored-By: Claude Opus 4.6 --- dev-docs/issue-management.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/dev-docs/issue-management.md b/dev-docs/issue-management.md index 4963e007..10ec41c3 100644 --- a/dev-docs/issue-management.md +++ b/dev-docs/issue-management.md @@ -42,20 +42,24 @@ go tool gh-helper threads resolve # Batch resolve threads **Gemini Review Workflow:** ```bash -# 1. Create PR (Gemini automatically reviews initial creation) +# 1. Create PR (Gemini automatically reviews and summarizes) gh pr create --title "feat: new feature" --body "Description" -# 2. Wait for automatic Gemini review (initial PR only) +# 2. Wait for automatic Gemini review (initial PR only — no flags needed) go tool gh-helper reviews wait --timeout 15m -# 3. For subsequent pushes: ALWAYS request Gemini review +# 3. After additional commits: request a new review git add && git commit -m "fix: address feedback" && git push go tool gh-helper reviews wait --request-review --timeout 15m + +# 4. Right before merge: update summary if additional commits were pushed +go tool gh-helper reviews wait --request-summary --timeout 15m ``` **Gemini Review Rules:** -- ✅ Initial PR creation: Automatic review (no flag needed) -- ✅ All subsequent pushes: MUST use `--request-review` flag +- ✅ Initial PR creation: Review and summary are auto-triggered (no flags needed) +- ✅ After additional commits: Use `--request-review` for a new review +- ✅ Right before merge: Use `--request-summary` to update the summary - ✅ Always wait for review completion before proceeding ## Issue Management