From 2188d090091ec017045296fc2cb74939a33caf33 Mon Sep 17 00:00:00 2001 From: Keith Guerin Date: Tue, 24 Mar 2026 15:48:25 -0700 Subject: [PATCH] feat(ux-extension): address feedback and fix build errors --- package-lock.json | 34 +--- packages/cli/src/acp/fileSystemService.ts | 2 +- packages/extensions/ux-extension/WELCOME.md | 6 +- .../skills/_ux_finish-pr/SKILL.md | 7 +- pr-workflow-improvements.md | 70 +++++++ worktrees-discussion.md | 192 ++++++++++++++++++ 6 files changed, 275 insertions(+), 36 deletions(-) create mode 100644 pr-workflow-improvements.md create mode 100644 worktrees-discussion.md diff --git a/package-lock.json b/package-lock.json index ff6b8fee23..b70dc1413b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -486,8 +486,7 @@ "version": "2.11.0", "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-2.11.0.tgz", "integrity": "sha512-sBXGT13cpmPR5BMgHE6UEEfEaShh5Ror6rfN3yEK5si7QVrtZg8LEPQb0VVhiLRUslD2yLnXtnRzG035J/mZXQ==", - "license": "(Apache-2.0 AND BSD-3-Clause)", - "peer": true + "license": "(Apache-2.0 AND BSD-3-Clause)" }, "node_modules/@bundled-es-modules/cookie": { "version": "2.0.1", @@ -1490,7 +1489,6 @@ "resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.13.4.tgz", "integrity": "sha512-GsFaMXCkMqkKIvwCQjCrwH+GHbPKBjhwo/8ZuUkWHqbI73Kky9I+pQltrlT0+MWpedCoosda53lgjYfyEPgxBg==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@grpc/proto-loader": "^0.7.13", "@js-sdsl/ordered-map": "^4.4.2" @@ -2197,7 +2195,6 @@ "integrity": "sha512-t54CUOsFMappY1Jbzb7fetWeO0n6K0k/4+/ZpkS+3Joz8I4VcvY9OiEBFRYISqaI2fq5sCiPtAjRDOzVYG8m+Q==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@octokit/auth-token": "^6.0.0", "@octokit/graphql": "^9.0.2", @@ -2378,7 +2375,6 @@ "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz", "integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==", "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=8.0.0" } @@ -2428,7 +2424,6 @@ "resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.5.0.tgz", "integrity": "sha512-ka4H8OM6+DlUhSAZpONu0cPBtPPTQKxbxVzC4CzVx5+K4JnroJVBtDzLAMx4/3CDTJXRvVFhpFjtl4SaiTNoyQ==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, @@ -2803,7 +2798,6 @@ "resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.5.0.tgz", "integrity": "sha512-F8W52ApePshpoSrfsSk1H2yJn9aKjCrbpQF1M9Qii0GHzbfVeFUB+rc3X4aggyZD8x9Gu3Slua+s6krmq6Dt8g==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/semantic-conventions": "^1.29.0" @@ -2837,7 +2831,6 @@ "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-metrics/-/sdk-metrics-2.5.0.tgz", "integrity": "sha512-BeJLtU+f5Gf905cJX9vXFQorAr6TAfK3SPvTFqP+scfIpDQEJfRaGJWta7sJgP+m4dNtBf9y3yvBKVAZZtJQVA==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/resources": "2.5.0" @@ -2892,7 +2885,6 @@ "resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.5.0.tgz", "integrity": "sha512-VzRf8LzotASEyNDUxTdaJ9IRJ1/h692WyArDBInf5puLCjxbICD6XkHgpuudis56EndyS7LYFmtTMny6UABNdQ==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@opentelemetry/core": "2.5.0", "@opentelemetry/resources": "2.5.0", @@ -4129,7 +4121,6 @@ "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "csstype": "^3.0.2" } @@ -4404,7 +4395,6 @@ "integrity": "sha512-6sMvZePQrnZH2/cJkwRpkT7DxoAWh+g6+GFRK6bV3YQo7ogi3SX5rgF6099r5Q53Ma5qeT7LGmOmuIutF4t3lA==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.35.0", "@typescript-eslint/types": "8.35.0", @@ -5278,7 +5268,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -7413,8 +7402,7 @@ "version": "0.0.1581282", "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1581282.tgz", "integrity": "sha512-nv7iKtNZQshSW2hKzYNr46nM/Cfh5SEvE2oV0/SEGgc9XupIY5ggf84Cz8eJIkBce7S3bmTAauFD6aysMpnqsQ==", - "license": "BSD-3-Clause", - "peer": true + "license": "BSD-3-Clause" }, "node_modules/dezalgo": { "version": "1.0.4", @@ -7998,7 +7986,6 @@ "integrity": "sha512-GsGizj2Y1rCWDu6XoEekL3RLilp0voSePurjZIkxL3wlm5o5EC9VpgaP7lrCvjnkuLvzFBQWB3vWB3K5KQTveQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", "@eslint-community/regexpp": "^4.12.1", @@ -8516,7 +8503,6 @@ "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", "license": "MIT", - "peer": true, "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", @@ -9829,7 +9815,6 @@ "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz", "integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==", "license": "MIT", - "peer": true, "engines": { "node": ">=16.9.0" } @@ -10108,7 +10093,6 @@ "resolved": "https://registry.npmjs.org/@jrichman/ink/-/ink-6.4.11.tgz", "integrity": "sha512-93LQlzT7vvZ1XJcmOMwN4s+6W334QegendeHOMnEJBlhnpIzr8bws6/aOEHG8ZCuVD/vNeeea5m1msHIdAY6ig==", "license": "MIT", - "peer": true, "dependencies": { "@alcalzone/ansi-tokenize": "^0.2.1", "ansi-escapes": "^7.0.0", @@ -13866,7 +13850,6 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz", "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -13877,7 +13860,6 @@ "integrity": "sha512-ePrwPfxAnB+7hgnEr8vpKxL9cmnp7F322t8oqcPshbIQQhDKgFDW4tjhF2wjVbdXF9O/nyuy3sQWd9JGpiLPvA==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "shell-quote": "^1.6.1", "ws": "^7" @@ -16027,7 +16009,6 @@ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "license": "MIT", - "peer": true, "engines": { "node": ">=12" }, @@ -16250,8 +16231,7 @@ "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "license": "0BSD", - "peer": true + "license": "0BSD" }, "node_modules/tsx": { "version": "4.20.3", @@ -16259,7 +16239,6 @@ "integrity": "sha512-qjbnuR9Tr+FJOMBqJCW5ehvIo/buZq7vH7qD7JziU98h6l3qGy0a/yPFjwO+y0/T7GFpNgNAvEcPPVfyT8rrPQ==", "devOptional": true, "license": "MIT", - "peer": true, "dependencies": { "esbuild": "~0.25.0", "get-tsconfig": "^4.7.5" @@ -16425,7 +16404,6 @@ "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -16648,7 +16626,6 @@ "resolved": "https://registry.npmjs.org/vite/-/vite-7.2.2.tgz", "integrity": "sha512-BxAKBWmIbrDgrokdGZH1IgkIk/5mMHDreLDmCJ0qpyJaAteP8NvMhkwr/ZCQNqNH97bw/dANTE9PDzqwJghfMQ==", "license": "MIT", - "peer": true, "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.5.0", @@ -16762,7 +16739,6 @@ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "license": "MIT", - "peer": true, "engines": { "node": ">=12" }, @@ -16775,7 +16751,6 @@ "resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.4.tgz", "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==", "license": "MIT", - "peer": true, "dependencies": { "@types/chai": "^5.2.2", "@vitest/expect": "3.2.4", @@ -17423,7 +17398,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } @@ -17867,7 +17841,6 @@ "resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.14.3.tgz", "integrity": "sha512-Iq8QQQ/7X3Sac15oB6p0FmUg/klxQvXLeileoqrTRGJYLV+/9tubbr9ipz0GKHjmXVsgFPo/+W+2cA8eNcR+XA==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@grpc/proto-loader": "^0.8.0", "@js-sdsl/ordered-map": "^4.4.2" @@ -17971,7 +17944,6 @@ "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "license": "MIT", - "peer": true, "engines": { "node": ">=12" }, diff --git a/packages/cli/src/acp/fileSystemService.ts b/packages/cli/src/acp/fileSystemService.ts index 1d3c8ad0b8..02b9d68195 100644 --- a/packages/cli/src/acp/fileSystemService.ts +++ b/packages/cli/src/acp/fileSystemService.ts @@ -14,7 +14,7 @@ export class AcpFileSystemService implements FileSystemService { constructor( private readonly connection: acp.AgentSideConnection, private readonly sessionId: string, - private readonly capabilities: acp.FileSystemCapability, + private readonly capabilities: acp.FileSystemCapabilities, private readonly fallback: FileSystemService, ) {} diff --git a/packages/extensions/ux-extension/WELCOME.md b/packages/extensions/ux-extension/WELCOME.md index daade17b2f..6e2f4b1493 100644 --- a/packages/extensions/ux-extension/WELCOME.md +++ b/packages/extensions/ux-extension/WELCOME.md @@ -50,8 +50,10 @@ When you're happy, just say "I'm ready to submit." I'll run the structural integrity. 3. **Snapshots**: Fixes snapshots for CI using a neutral environment. 4. **Preflight**: Runs the full `preflight` suite. -5. **Commit Strategy**: Squashes your main feature into one commit, but keeps - review-fix commits separate to keep the diffs manageable for reviewers. +5. **Commit Strategy**: Squashes your main feature and ALL previous review + fixes into one commit, but keeps only the **very last** round of code review + comments as separate commits. This keeps the diffs manageable and fast for + reviewers (30 seconds vs. 10 minutes). ### **Phase 5: Handling Feedback** diff --git a/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md b/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md index c88bd0e1fa..ff5822970a 100644 --- a/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md +++ b/packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md @@ -48,8 +48,11 @@ You are a senior co-author assistant. Your goal is to ensure this PR passes CI o - **Diff Verification**: After reverting, run `git diff origin/main...HEAD` on the specific reverted files to ensure their diff is completely empty. ### 7. Final Submission -- **Commit Strategy**: Squash commits for the main feature into a single Conventional Commit (e.g., `feat(ui): ...`), BUT keep code review fixes as separate commits. Do not squash review fixes into the main feature commit; reviewing the entire diff repeatedly is brutal for reviewers. +- **Commit Strategy**: Maintain a **Two-Tier** commit history to optimize for reviewer speed (30s vs 10m): + 1. **Tier 1 (Base)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature and all *previously addressed* review cycles. + 2. **Tier 2 (Latest)**: Separate, granular commits addressing only the **very last** round of reviewer feedback. + - **Action**: Use `git rebase -i` or `git reset --soft` to squash all older review-fix commits into the Tier 1 base. Ensure only the commits from the current (latest) review cycle remain as separate entries. - **Push**: `git push origin HEAD --force-with-lease`. -- **Link**: Provide the GitHub PR link. +- **Link**: You MUST provide the full, clickable GitHub PR link (e.g., `https://github.com/google-gemini/gemini-cli/pull/23487`) as the final output of this skill. This allows the user to immediately verify the update. **Note**: If any step fails, do NOT claim completion. Fix the issue and restart from Step 1. diff --git a/pr-workflow-improvements.md b/pr-workflow-improvements.md new file mode 100644 index 0000000000..846efef852 --- /dev/null +++ b/pr-workflow-improvements.md @@ -0,0 +1,70 @@ +# PR Workflow Improvements: Lessons Learned & Skill Updates + +During a recent PR review cycle, we encountered two significant workflow issues +that resulted in wasted review cycles, polluted diffs, and unnecessary churn. To +prevent these from recurring, we need to update our standard operating +procedures, specifically within the `_ux_finish-pr` skill. + +## Problem 1: Blindspots in Fetching Reviewer Feedback + +### The Issue + +When instructed to address reviewer feedback, the agent relied on high-level PR +summaries (`gh pr view`) and top-level comments. It completely failed to fetch +or parse **inline, file-specific review comments**. As a result, critical +feedback (like removing unsafe type casts, fixing hardcoded arrays, and +reverting specific lines of code) was ignored. Furthermore, the agent did not +directly reply to the reviewer's comments to confirm resolution, leaving the +reviewer in the dark. + +### The Solution for `_ux_finish-pr` + +The skill must be updated to strictly mandate the retrieval and addressing of +_all_ review comments, especially inline ones. + +**Proposed Skill Additions:** + +- **Mandatory Comprehensive Fetching:** Require the use of `gh api graphql` or + advanced `gh pr view` parsing to explicitly extract _inline_ review comments, + which are often nested inside review objects and missed by basic commands. +- **Checklist Execution:** Mandate that the agent enumerates every single + comment from the reviewer and explicitly verifies its resolution against the + codebase. +- **Direct Engagement:** Require the agent to use the GitHub API to post a + direct reply to _every_ addressed inline comment (e.g., "Done. Extracted to a + helper.") to provide the reviewer with a clear audit trail. + +--- + +## Problem 2: Git Base-State & Branch Management Errors + +### The Issue + +When the reviewer requested that specific configuration files be reverted to +their pre-PR state to remove them from the diff, the agent executed +`git checkout origin/main -- `. Because `origin/main` had advanced with +new commits since the PR was originally branched, this action accidentally +pulled in _unrelated_ recent changes from `main`. This polluted the PR's diff, +causing it to include changes that had nothing to do with the feature, violating +the principle of atomic commits. + +### The Solution for `_ux_finish-pr` + +The skill must be updated to enforce strict Git merge-base practices when +reverting or referencing the original state of a PR. + +**Proposed Skill Additions:** + +- **Merge-Base Awareness:** Explicitly forbid blindly checking out files from + the tip of `origin/main` when attempting to restore a file's pre-PR state. +- **Safe File Reversion Protocol:** Instruct the agent to always find the true + branch point using `git merge-base` when reverting files to strip them from a + PR: + ```bash + BASE_SHA=$(git merge-base origin/main HEAD) + git checkout $BASE_SHA -- + ``` +- **Diff Verification:** Add a mandatory validation step where the agent runs + `git diff origin/main...HEAD` on the specific reverted files to ensure their + diff is completely empty, confirming they have been successfully excised from + the PR. diff --git a/worktrees-discussion.md b/worktrees-discussion.md new file mode 100644 index 0000000000..376b615376 --- /dev/null +++ b/worktrees-discussion.md @@ -0,0 +1,192 @@ +# Gemini CLI Git Worktrees Discussion Transcript + +## Overview + +This document captures a discussion regarding the new experimental native Git +Worktree support in the Gemini CLI and whether it makes the custom +`_ux_git-worktree` skill obsolete for the UX team. + +### Skill Information + +**Path:** `packages/extensions/ux-extension/skills/_ux_git-worktree/SKILL.md` + +**High-Level Description:** The `_ux_git-worktree` skill manages a specific +"Base Folder Strategy" for the engineering team. Rather than nesting worktrees +inside a hidden `.gemini` folder, it enforces that all functional work occurs in +sibling sub-directories (e.g., `main/`, `feature-name/`). It automates creating +new task branches, checking out GitHub PRs into semantically named folders +(e.g., `pr-123-fix-core-bug`), and automatically running `npm install` to ensure +the isolated environment is immediately ready for development. It also handles +macOS sandbox pathing requirements. + +--- + +## Discussion Transcript + +**User:** Take a look at this new feature of Gemini CLI, and let me know if you +think it makes our git-worktree skill obsolete. +https://geminicli.com/docs/cli/git-worktrees/ + +**Gemini CLI:** Based on the documentation for the new native Git Worktree +feature and the specific rules defined in your `_ux_git-worktree` skill, **no, +it does not make your custom skill obsolete.** + +While the new native feature is great for general-purpose isolation, your +`_ux_git-worktree` skill enforces highly specific, project-tailored workflows +that the native feature doesn't cover out-of-the-box: + +1. **Directory Structure (The "Base Folder" Strategy):** The native CLI creates + worktrees hidden away in `.gemini/worktrees/`. Your skill strictly enforces + that worktrees must be **sibling directories** to `main/` (e.g., + `../feature-name/`). +2. **Semantic PR Checkouts:** Your skill uses a custom `worktree-manager.sh` + script to automatically fetch PR titles and create human-readable, semantic + directory names (like `pr-123-fix-core-bug`). The native CLI does not + integrate with GitHub PRs in this way. +3. **Mandatory Environment Setup:** Your skill enforces a mandatory + `npm install` immediately after a worktree is created to ensure the + environment is ready for development. +4. **macOS Sandbox Management:** Because your worktrees live outside the + immediate repository container as sibling folders, your skill includes + specific logic to ensure the primary `../main/.git` path is added to the + trusted environment to bypass macOS sandbox restrictions. + +**Recommendation:** The native `--worktree` flag is an excellent feature for +standard use cases, but for the rigorous, standardized workflows required by the +UX Extension in this repository, you should continue using your custom +`_ux_git-worktree` skill to maintain compliance with the "Base Folder" +architecture. + +**User:** Let's back up a step. My goal is for the UX team that uses this +extension to be able to use git worktrees following the standard team convention +(i.e. the whole eng team will use this worktrees feature). We don't want to +duplicate or recreate the feature with our skill, nor do we want to diverge from +standard team practice. The exception is that I'd like the UX team (and end +users potentially) to be able to create and use worktrees with natural language. + +Let's take a user-journey approach to designing the experience. Start by +creating a list of the use-cases/journeys that users will want to do with +worktrees. My current behavior is: + +1. I want to create a new worktree to work on a new feature. I have a name in + mind, and I want to start from main. Its nice that I can use gemini cli + interactive mode and say 'new worktree called blahblah' and i dont have to + remember a specific syntax, but also the startup time maybe means I should + just learn the syntax. It seems simple. Its convenient that it runs npm + install to save me a step, but not critical. +2. I want to create a new worktree by cloning someone's branch/PR to my local + machine. Its easy for me to run gemini cli interactive mode and say 'create a + new worktree from http://PRURL and call it blahblah. Again, the npm install + is convenient. In this case Im not sure how to do this in noninteractive + mode. +3. I want to see all the worktrees ive created locally, and its handy i can look + at my folders, becuase it basically represents a list of my projects/features + im working on. Im not sure how this could be done in noninteractive mode, so + I would worry about losing my work in progress. its kind of confusing if my + worktrees are in gemini's hidden folder. It would be great if there was a way + to see my worktrees within gemini cli interactive and non interactive mode. + +So as a worktree novice, and someone who has not tested this experimental +feature still, I may be misunderstanding things. Would you please create a list +of use-cases that includes mine, as well as any key ones im missing? Under each +use-case, identify whether its supported by the experimental feature in both +interactive and noninteractive modes. + +**Gemini CLI:** This is a great approach. Stepping back to look at the user +journey is the best way to determine if a feature genuinely serves the team's +workflow or just adds unnecessary complexity. + +Based on your current workflow, the documentation for the new experimental +feature, and standard Git worktree lifecycles, here is a breakdown of the key +user journeys. + +### 1. Create a new worktree for a new feature (from `main`) + +**User Goal:** Spin up an isolated environment to start fresh work, optionally +with a specific name, without messing up the primary `main` branch. + +- **Experimental Native Feature (Non-Interactive):** **Supported.** You launch + Gemini with `gemini --worktree `. It automatically creates a new branch + and a linked directory in `.gemini/worktrees/`. _(Note: It does not + automatically run `npm install` like your current skill does)._ +- **Experimental Native Feature (Interactive):** **Partially Supported.** You + cannot start a standard `gemini` session and then type a native slash command + (like `/worktree new`) to instantly pivot the current session into a worktree. + You must use the `--worktree` flag _when launching_ the CLI. However, once + inside any interactive session, you can always just ask the agent in natural + language to run standard `git worktree add` commands for you. + +### 2. Create a worktree from a remote branch or PR + +**User Goal:** Review a teammate's PR or continue work on a remote branch +without stashing current local changes. + +- **Experimental Native Feature (Non-Interactive):** **Not Supported Natively.** + The `--worktree` flag only creates _new_ branches from your current HEAD. It + does not accept a PR URL or remote branch name. You would have to manually + fetch the remote branch and use standard `git worktree add` commands before + launching Gemini. +- **Experimental Native Feature (Interactive):** **Not Supported Natively.** + Again, the native feature lacks a "PR-to-worktree" pipeline. To do this with + natural language, you still rely on the AI agent running shell commands (which + is exactly what your `_ux_git-worktree` skill automates so reliably). + +### 3. Discoverability: View existing local worktrees + +**User Goal:** See a list of all active projects/features currently in progress. + +- **Experimental Native Feature (Non-Interactive):** **Supported (but hidden).** + The native feature stores worktrees inside `.gemini/worktrees/`. Because this + is a hidden directory, you won't see your projects when doing a standard `ls` + in your file explorer. You have to explicitly check that hidden path or run + standard `git worktree list`. +- **Experimental Native Feature (Interactive):** **Supported.** You can ask the + agent, "What worktrees do I have open?" and it will run `git worktree list` to + tell you. + +### 4. Resume work on an existing worktree _(Missing Use-Case)_ + +**User Goal:** Switch context back to a feature you started yesterday. + +- **Experimental Native Feature (Non-Interactive):** **Supported.** You have to + manually `cd` into the hidden `.gemini/worktrees/` directory and run + `gemini` again. +- **Experimental Native Feature (Interactive):** **Supported.** If you want to + resume the exact AI conversation you were having in that worktree, you + navigate to the hidden folder and launch with `gemini --resume `. + +### 5. Clean up / Delete a finished worktree _(Missing Use-Case)_ + +**User Goal:** After a PR is merged, delete the local branch and the isolated +folder to free up space. + +- **Experimental Native Feature (Non-Interactive):** **Not Supported.** The + documentation explicitly states Gemini does not automatically clean up + worktrees. You must manually run `git worktree remove --force` and + `git branch -D `. +- **Experimental Native Feature (Interactive):** **Not Supported Natively.** You + can ask the AI agent to run the cleanup commands for you, but there is no + native garbage collection. + +--- + +### The Verdict for Your Team + +You are not misunderstanding things; your concerns are spot on. + +The new native `--worktree` feature is designed primarily for **AI +isolation**—giving the agent a safe sandbox so it doesn't break the user's main +repository while generating code. Because it hides these folders in +`.gemini/worktrees/`, it treats them as ephemeral AI scratchpads rather than +primary developer workspaces. + +Your team's **"Base Folder Strategy"** (creating sibling folders like +`../feature-name/`) is designed for **Developer ergonomics**. It keeps projects +visible, integrates directly with PR workflows, and handles environment setup +(`npm install`). + +**Conclusion:** The native feature does _not_ replace your skill. If you adopt +the native feature, your team will lose the PR checkout automation, the +automatic dependency installation, and the visibility of having worktrees as +top-level sibling folders. You should keep your `_ux_git-worktree` skill to +maintain your team's specific, natural-language-driven engineering standards.