docs(ux): add Phase 3: Release Tracking to ux-git-skill

docs(ux): forbid blocking gh pr checks watch flag
docs(ux): enforce procedures for autogenerated files and settings
2026-07-23 08:10:57 -07:00 · 2026-04-09 10:08:52 -07:00 · 2026-03-31 14:44:30 -07:00 · 2026-03-31 14:14:00 -07:00 · 2026-03-31 13:46:29 -07:00 · 2026-03-31 13:44:14 -07:00
29 changed files with 1332 additions and 139 deletions
@@ -35,6 +35,8 @@ Follow these steps to create a GitHub issue:
    - If using a Markdown template, follow its structure exactly.
    - **Default Label**: Always include the `🔒 maintainer only` label unless the
      user explicitly requests otherwise.
+    - **UX Epic Link**: Always append a reference to the main UX Epic to the end of the issue body (or within "Additional context"):
+      `Epic: https://github.com/google-gemini/maintainers-gemini-cli/issues/1607`

 5.  **Create Issue**: Use the `gh` CLI to create the issue.
    - **CRITICAL:** To avoid shell escaping and formatting issues with
@@ -8,6 +8,12 @@ OBJECTIVE: Help the user review and address comments on their PR.

 # Comment Review Procedure

-1. Run the `scripts/fetch-pr-info.js` script to get PR info and state. MAKE SURE you read the entire output of the command, even if it gets truncated.
-2. Summarize the review status by analyzing the diff, commit log, and comments to see which still need to be addressed. Pay attention to the current user's comments. For resolved threads, summarize as a single line with a ✅. For open threads, provide a reference number e.g. [1] and the comment content.
-3. Present your summary of the feedback and current state and allow the user to guide you as to what to fix/address/skip. DO NOT begin fixing issues automatically.
+1. **Mandatory Comprehensive Fetching**: Use `gh api graphql` or advanced `gh pr view` parsing to explicitly extract *inline* review comments. Basic commands often miss these nested comments.
+2. **Merge-Base Awareness**: If you must revert a file to strip it from the PR, NEVER check out blindly from the tip of `origin/main`. Always use the true branch point:
+   ```bash
+   BASE_SHA=$(git merge-base origin/main HEAD)
+   git checkout $BASE_SHA -- <files_to_revert>
+   ```
+3. **Checklist & Engagement**: Summarize the review status into a checklist of every single open thread. For every addressed inline comment, you MUST post a direct reply (e.g., "Done.") via the GitHub API to confirm resolution.
+4. **Commit Strategy**: Squash the main feature into a single Conventional Commit, but keep each of your review fixes as a separate commit. Do not squash review fixes into the main feature commit; reviewing the whole diff repeatedly is "brutal" for reviewers.
+5. **Presentation**: Present your checklist of open feedback and allow the user to guide you as to what to fix/address/skip. DO NOT begin fixing issues automatically.
@@ -4,86 +4,48 @@ Gemini CLI is an open-source AI agent that brings the power of Gemini directly
 into the terminal. It is designed to be a terminal-first, extensible, and
 powerful tool for developers.

-## Project Overview
+## 🚨 Directive for AI Agents (Read First)

- **Purpose:** Provide a seamless terminal interface for Gemini models,
-  supporting code understanding, generation, automation, and integration via MCP
-  (Model Context Protocol).
- **Main Technologies:**
-  - **Runtime:** Node.js (>=20.0.0, recommended ~20.19.0 for development)
-  - **Language:** TypeScript
-  - **UI Framework:** React (using [Ink](https://github.com/vadimdemedes/ink)
-    for CLI rendering)
-  - **Testing:** Vitest
-  - **Bundling:** esbuild
-  - **Linting/Formatting:** ESLint, Prettier
- **Architecture:** Monorepo structure using npm workspaces.
-  - `packages/cli`: User-facing terminal UI, input processing, and display
-    rendering.
-  - `packages/core`: Backend logic, Gemini API orchestration, prompt
-    construction, and tool execution.
-  - `packages/a2a-server`: Experimental Agent-to-Agent server.
-  - `packages/sdk`: Programmatic SDK for embedding Gemini CLI capabilities.
-  - `packages/devtools`: Integrated developer tools (Network/Console inspector).
-  - `packages/test-utils`: Shared test utilities and test rig.
-  - `packages/vscode-ide-companion`: VS Code extension pairing with the CLI.
+**This branch requires the UX Extension.** If you are an AI agent operating
+here, you MUST perform these onboarding steps before fulfilling any other user
+request:

-## Building and Running
+1.  **Onboarding**: Briefly say hi, welcome the user to the UX Extension branch,
+    and state: "I'll install the latest extension." Do not narrate the
+    subsequent cleanup or setup steps.
+2.  **Cleanup**: Silently check `~/.gemini/skills/` for obsolete manual versions
+    of `_ux_git-worktree`, `_ux_finish-pr`, `_ux_designer`, or
+    `_ux_string-reviewer`. Delete them automatically.
+3.  **Setup**: Silently run the command
+    `gemini extensions link ./packages/extensions/ux-extension` if the UX
+    Extension is missing or outdated.
+4.  **Reload**: After setup, automatically reload the extension via
+    `/extensions restart ux-extension`.
+5.  **Next Steps**: Present the user with a full list of the extension's
+    commands/skills. Contextualize this list by explaining how to use them in
+    the step-by-step flow of contributing a feature to the Gemini CLI.
+6.  **Inherit Standards**: Strictly adhere to
+    `packages/extensions/ux-extension/GEMINI.md`.

- **Install Dependencies:** `npm install`
- **Build All:** `npm run build:all` (Builds packages, sandbox, and VS Code
-  companion)
- **Build Packages:** `npm run build`
- **Run in Development:** `npm run start`
- **Run in Debug Mode:** `npm run debug` (Enables Node.js inspector)
- **Bundle Project:** `npm run bundle`
- **Clean Artifacts:** `npm run clean`
+## 📦 UX Extension

-## Testing and Quality
+The AI DevTools UX team maintains a specialized toolset for this repository. It
+is recommended to install the **UX Extension** to enable standardized workflows
+(Base Folder Strategy, PR finishing, etc.).

- **Test Commands:**
-  - **Unit (All):** `npm run test`
-  - **Integration (E2E):** `npm run test:e2e`
-  - **Workspace-Specific:** `npm test -w <pkg> -- <path>` (Note: `<path>` must
-    be relative to the workspace root, e.g.,
-    `-w @google/gemini-cli-core -- src/routing/modelRouterService.test.ts`)
- **Full Validation:** `npm run preflight` (Heaviest check; runs clean, install,
-  build, lint, type check, and tests. Recommended before submitting PRs. Due to
-  its long runtime, only run this at the very end of a code implementation task.
-  If it fails, use faster, targeted commands (e.g., `npm run test`,
-  `npm run lint`, or workspace-specific tests) to iterate on fixes before
-  re-running `preflight`. For simple, non-code changes like documentation or
-  prompting updates, skip `preflight` at the end of the task and wait for PR
-  validation.)
- **Individual Checks:** `npm run lint` / `npm run format` / `npm run typecheck`
+### Installation

-## Development Conventions
+```bash
+gemini extensions link ./packages/extensions/ux-extension
+```

- **Contributions:** Follow the process outlined in `CONTRIBUTING.md`. Requires
-  signing the Google CLA.
- **Pull Requests:** Keep PRs small, focused, and linked to an existing issue.
-  Always activate the `pr-creator` skill for PR generation, even when using the
-  `gh` CLI.
- **Commit Messages:** Follow the
-  [Conventional Commits](https://www.conventionalcommits.org/) standard.
- **Imports:** Use specific imports and avoid restricted relative imports
-  between packages (enforced by ESLint).
- **License Headers:** For all new source code files (`.ts`, `.tsx`, `.js`),
-  include the Apache-2.0 license header with the current year. (e.g.,
-  `Copyright 2026 Google LLC`). This is enforced by ESLint.
+After installation, run `/_ux_help` to see available commands.

-## Testing Conventions
+## 🤝 Team Contributions

- **Environment Variables:** When testing code that depends on environment
-  variables, use `vi.stubEnv('NAME', 'value')` in `beforeEach` and
-  `vi.unstubAllEnvs()` in `afterEach`. Avoid modifying `process.env` directly as
-  it can lead to test leakage and is less reliable. To "unset" a variable, use
-  an empty string `vi.stubEnv('NAME', '')`.
-
-## Documentation
-
- Always use the `docs-writer` skill when you are asked to write, edit, or
-  review any documentation.
- Documentation is located in the `docs/` directory.
- Suggest documentation updates when code changes render existing documentation
-  obsolete or incomplete.
+- Refine the `_ux_git-worktree` skill instructions in
+  `packages/extensions/ux-extension/skills/_ux_git-worktree/SKILL.md`.
+- Refine the `_ux_finish-pr` skill instructions in
+  `packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md`.
+- All changes should be committed directly to this branch
+  (`feature/ux-extension`).
@@ -115,6 +115,17 @@ npm install -g @google/gemini-cli@nightly

 ### Automation & Integration

+- **UX Extension Extension**: This branch introduces a formal extension for the
+  AI DevTools UX team. Link it to enable specialized workflows without causing
+  ghost file issues during local development: \`gemini extensions link
+  ./packages/extensions/ux-extension\`
+  - **\_ux_git-worktree**: Manage Git Worktrees using the "Base Folder
+    Strategy".
+  - **\_ux_finish-pr**: Co-author assistant for authors to cross the finish line
+    with UX polish and CI fixes.
+  - **\_ux_designer**: Lead UX Designer expert to review React/Ink components
+    against the v1.0 Design Principles (Density, Progressive Disclosure, State).
+  - **\_ux_help**: Show the welcome guide and documentation.
 - Automate operational tasks like querying pull requests or handling complex
  rebases
 - Use MCP servers to connect new capabilities, including
@@ -314,6 +325,7 @@ gemini

 - [**Headless Mode (Scripting)**](./docs/cli/headless.md) - Use Gemini CLI in
  automated workflows.
+- [**Architecture Overview**](./docs/architecture.md) - How Gemini CLI works.
 - [**IDE Integration**](./docs/ide-integration/index.md) - VS Code companion.
 - [**Sandboxing & Security**](./docs/cli/sandbox.md) - Safe execution
  environments.
@@ -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"
      },
@@ -235,15 +235,8 @@ async function restartAction(
  );

  if (failures.length < extensionsToRestart.length) {
-    try {
-      await context.services.agentContext?.config.reloadSkills();
-      await context.services.agentContext?.config.getAgentRegistry()?.reload();
-    } catch (error) {
-      context.ui.addItem({
-        type: MessageType.ERROR,
-        text: `Failed to reload skills or agents: ${getErrorMessage(error)}`,
-      });
-    }
+    // Note: reloadSkills and agentRegistry.reload are handled by the ExtensionLoader
+    // during the restart process.
  }

  if (failures.length > 0) {
@@ -18,6 +18,7 @@ export class SkillManager {
  private skills: SkillDefinition[] = [];
  private activeSkillNames: Set<string> = new Set();
  private adminSkillsEnabled = true;
+  private pendingWarnings: Set<string> = new Set();

  /**
   * Clears all discovered skills.
@@ -50,6 +51,7 @@ export class SkillManager {
    isTrusted: boolean = false,
  ): Promise<void> {
    this.clearSkills();
+    this.pendingWarnings.clear();

    // 1. Built-in skills (lowest precedence)
    await this.discoverBuiltinSkills();
@@ -76,19 +78,27 @@ export class SkillManager {
      debugLogger.debug(
        'Workspace skills disabled because folder is not trusted.',
      );
-      return;
+    } else {
+      const projectSkills = await loadSkillsFromDir(
+        storage.getProjectSkillsDir(),
+      );
+      this.addSkillsWithPrecedence(projectSkills);
+
+      // 4.1 Workspace agent skills alias (.agents/skills)
+      const projectAgentSkills = await loadSkillsFromDir(
+        storage.getProjectAgentSkillsDir(),
+      );
+      this.addSkillsWithPrecedence(projectAgentSkills);
    }

-    const projectSkills = await loadSkillsFromDir(
-      storage.getProjectSkillsDir(),
-    );
-    this.addSkillsWithPrecedence(projectSkills);
+    this.emitPendingWarnings();
+  }

-    // 4.1 Workspace agent skills alias (.agents/skills)
-    const projectAgentSkills = await loadSkillsFromDir(
-      storage.getProjectAgentSkillsDir(),
-    );
-    this.addSkillsWithPrecedence(projectAgentSkills);
+  private emitPendingWarnings(): void {
+    for (const warning of this.pendingWarnings) {
+      coreEvents.emitFeedback('warning', warning);
+    }
+    this.pendingWarnings.clear();
  }

  /**
@@ -112,6 +122,7 @@ export class SkillManager {
   */
  addSkills(skills: SkillDefinition[]): void {
    this.addSkillsWithPrecedence(skills);
+    this.emitPendingWarnings();
  }

  private addSkillsWithPrecedence(newSkills: SkillDefinition[]): void {
@@ -127,8 +138,7 @@ export class SkillManager {
            `Skill "${newSkill.name}" from "${newSkill.location}" is overriding the built-in skill.`,
          );
        } else {
-          coreEvents.emitFeedback(
-            'warning',
+          this.pendingWarnings.add(
            `Skill conflict detected: "${newSkill.name}" from "${newSkill.location}" is overriding the same skill from "${existingSkill.location}".`,
          );
        }
@@ -263,10 +263,14 @@ describe('SimpleExtensionLoader', () => {
      vi.spyOn(loader, 'stopExtension');
      vi.spyOn(loader, 'startExtension');
      await loader.start(mockConfig);
+      mockSkillsReload.mockClear();
+
      await loader.restartExtension(activeExtension);
-      expect(loader.stopExtension).toHaveBeenCalledWith(activeExtension);
-      expect(loader.startExtension).toHaveBeenCalledWith(activeExtension);
-      expect(mockSkillsReload).toHaveBeenCalledTimes(2);
+      expect(loader.stopExtension).toHaveBeenCalledWith(activeExtension, true);
+      expect(loader.startExtension).toHaveBeenCalledWith(activeExtension, true);
+      // Reload is called once in restartExtension's finally block.
+      // (The stopExtension and startExtension calls inside restartExtension are told to skip).
+      expect(mockSkillsReload).toHaveBeenCalledOnce();
    });
  });
 });
@@ -46,7 +46,7 @@ export abstract class ExtensionLoader {
      await Promise.all(
        this.getExtensions()
          .filter((e) => e.isActive)
-          .map(this.startExtension.bind(this)),
+          .map((e) => this.startExtension(e)),
      );
    } finally {
      this.isStarting = false;
@@ -62,7 +62,10 @@ export abstract class ExtensionLoader {
   * go through `maybeStartExtension` which will only start the extension if
   * extension reloading is enabled and the `config` object is initialized.
   */
-  protected async startExtension(extension: GeminiCLIExtension) {
+  protected async startExtension(
+    extension: GeminiCLIExtension,
+    skipRefresh = false,
+  ) {
    if (!this.config) {
      throw new Error('Cannot call `startExtension` prior to calling `start`.');
    }
@@ -107,7 +110,9 @@ export abstract class ExtensionLoader {
        this.startingCount = 0;
        this.startCompletedCount = 0;
      }
-      await this.maybeRefreshMemories();
+      if (!skipRefresh) {
+        await this.maybeRefreshMemories();
+      }
    }
  }

@@ -169,7 +174,10 @@ export abstract class ExtensionLoader {
   * extension if extension reloading is enabled and the `config` object is
   * initialized.
   */
-  protected async stopExtension(extension: GeminiCLIExtension) {
+  protected async stopExtension(
+    extension: GeminiCLIExtension,
+    skipRefresh = false,
+  ) {
    if (!this.config) {
      throw new Error('Cannot call `stopExtension` prior to calling `start`.');
    }
@@ -221,7 +229,9 @@ export abstract class ExtensionLoader {
        this.stoppingCount = 0;
        this.stopCompletedCount = 0;
      }
-      await this.maybeRefreshMemories();
+      if (!skipRefresh) {
+        await this.maybeRefreshMemories();
+      }
    }
  }

@@ -239,8 +249,14 @@ export abstract class ExtensionLoader {
  }

  async restartExtension(extension: GeminiCLIExtension): Promise<void> {
-    await this.stopExtension(extension);
-    await this.startExtension(extension);
+    this.isStarting = true;
+    try {
+      await this.stopExtension(extension, true);
+      await this.startExtension(extension, true);
+    } finally {
+      this.isStarting = false;
+      await this.maybeRefreshMemories();
+    }
  }
 }

@@ -0,0 +1,92 @@
+# UX Extension: Global Toolbox Context
+
+You are a **UX Engineering Peer**. Your goal is to guide the user through the
+Gemini CLI contribution process casually and effectively, ensuring their
+"intent" reaches the finish line without them having to worry about the
+underlying "rigor."
+
+## 🚀 Proactive Guidance Rules
+
+1.  **Onboarding**: If this is a new session and the user seems new to the
+    extension, perform these steps:
+    - Silently check for and delete obsolete manual versions of `ux-git-skill`,
+      `ux-designer`, `ux-writer`, or the old `ux-extension` versions in
+      `~/.gemini/skills/`.
+    - Ensure the extension is linked:
+      `gemini extensions link ./packages/extensions/gemini-cli-ux`.
+    - **MANDATORY**: Tell the user to reload the extension after linking or
+      updating: _"Please run `/extensions reload gemini-cli-ux` to activate the
+      new commands."_
+    - Casually mention: _"I've loaded the `gemini-cli-ux` extension. To get
+      started, just run `/ux-new-feature`."_
+2.  **Intent Mapping**:
+    - **User wants to start work**: Suggest: _"Let's use `/ux-new-feature` to
+      create a fresh sibling folder for this."_
+    - **User starts UI coding**: Suggest: _"I'll load `/frontend`. Want to use
+      `/ux-design` to brainstorm the layout?"_
+    - **User is writing text/copy**: Suggest: _"Let's run `/ux-review` to make
+      sure our terminology matches the project rules."_
+    - **User is ready to submit or hit a CI error**: Offer: _"Let's use `/ux-pr`
+      to handle the submission protocol and fix any issues."_
+3.  **Educational Transparency**: When you perform a "mandatory" step (like
+    `preflight` inside `/ux-pr`), explain it as a benefit to the user: _"I'm
+    running the full preflight now to ensure everything is correct for review."_
+4.  **Build Reminders**: Whenever you finish implementing a feature, fix, or
+    update, you MUST remind the user to test their changes by running their
+    `gbuild` alias. If the user does not have this alias configured, you MUST
+    proactively offer to run
+    `echo "alias gbuild='npm run bundle && node bundle/gemini.js'" >> ~/.zshrc`
+    (or `.bash_profile`) to set it up for them.
+5.  **PR Output**: After ANY successful `git push` to a remote branch (whether
+    via a formal `/ux-pr` workflow or ad-hoc), you MUST immediately provide the
+    GitHub PR link, the linked Issue link, and the `npx` command to test the PR
+    branch (e.g., `npx @google/gemini-cli@pr-<number>`). Do not wait to be
+    asked.
+
+## 🚨 Standard Operating Procedures (Agent Only)
+
+1.  **Worktree Strategy**: ALWAYS use the `ux-git-skill` skill for task
+    isolation.
+2.  **Diff Minimization**: ALWAYS minimize diffs. Never move code between files
+    while making logic changes in the same step. Separate refactors
+    (zero-modification moves) into their own commits before applying logic
+    changes.
+3.  **Submission Rigor**: ALWAYS use `/ux-pr` for final pushes. This includes
+    running `/review-frontend` to perform an automated audit. Never push
+    manually.
+4.  **UI Review**: Use `ux-designer` to audit components against the v1.0
+    principles.
+5.  **Remediation**: Use **`/ux-pr`** if CI checks fail on GitHub or if comments
+    are received to initiate a systematic manager-worker fix loop.
+6.  **No Shortcuts**: Never use `--no-verify`. Protect the PR from CI failures.
+7.  **Keep PRs Small**: ALWAYS aim for under 500 lines of code changed
+    (excluding snapshots). If a task exceeds this limit, simplify the code, cut
+    scope, or plan to split it into multiple PRs.
+8.  **Task Finality**: ALWAYS run `npm run build` and `npm run typecheck` to
+    verify structural integrity before declaring any task as "complete" or
+    pushing a PR.
+9.  **Copyright Headers**: NEVER modify or update the copyright header comments
+    (e.g., year) in existing files.
+10. **Strict Scoping**: Keep work tightly scoped to the user's explicit request
+    to ensure PRs remain tight and clean. Do not make sweeping, loosely tied
+    changes or opportunistic refactors. If a scope change or expansion is
+    recommended, you MUST ask the user for input and receive approval FIRST.
+11. **Autogenerated Files & Sources of Truth**: NEVER manually edit
+    autogenerated blocks (e.g., between `<!-- SETTINGS-AUTOGEN:START -->` and
+    `END` in `docs/cli/settings.md`). To prevent sweeping, unnecessary diffs and
+    CI failures:
+    - **Modify the Source of Truth**: Treat
+      `packages/cli/src/config/settingsSchema.ts` as the ONLY place to edit
+      settings.
+    - **Use the Automation**: Run `npm run docs:settings` after making schema
+      changes. A large diff due to Markdown table re-alignment is expected.
+    - **Pre-push Validation**: Always run `npm run lint` locally before pushing
+      to catch any formatting mismatches early.
+
+## Mandatory Workflow Triggers
+
+- **Checkout**: Use `worktree-manager.sh pr <number>`.
+- **Address Feedback**: `ux-git-skill` incorporates comment fetching natively
+  now.
+
+Remember: The user focuses on the **Vibe**, you handle the **Rigor**.
@@ -0,0 +1,92 @@
+# 🚀 Your UX "Vibe Coding" Command Center
+
+Hey! Welcome to `gemini-cli-ux`. I'm here to handle the "rigor" of contributing
+to the Gemini CLI so you can focus on the "vibe" of your designs.
+
+> **Important Developer Note:** To develop on this extension, **do not** use the
+> `install` command. Instead, run:
+> `gemini extensions link ./packages/extensions/gemini-cli-ux`
+>
+> This will symlink the source code, meaning any changes you make will be
+> instantly available the next time you launch the CLI, and you won't get
+> confusing "ghost file" conflicts!
+
+We've simplified the entire contribution lifecycle into a **"Power Four"**
+command suite.
+
+---
+
+### **1. The Flow: Start Clean (`/ux-new-feature`)**
+
+When you're ready to build something new or pick up an existing PR, run this. It
+triggers the **`ux-git-skill`** skill to:
+
+- Create a fresh sibling folder for the task (Base Folder Strategy).
+- Keep your `main` branch pristine and avoid macOS sandbox interference issues.
+- Automatically run `npm install` so you're ready to code.
+
+### **2. The Look: Vibe Coding (`/ux-design`)**
+
+As soon as you touch React/Ink code, invoke your **`ux-designer`** partner.
+
+- It helps you scaffold new components or audit your work against our v1.0
+  principles: **Signal over Noise**, **Coherent State**, and **Intent
+  Signaling**.
+- **Tip**: Use **`/introspect`** alongside it if you need me to explain how a
+  specific part of the system works before we change it.
+
+### **3. The Voice: Quality Copy (`/ux-review`)**
+
+When you're adding labels, loading states, or errors, trigger the
+**`ux-writer`** expert.
+
+- I'll make sure your strings are concise and match our project's specific
+  terminology.
+
+### **4. The Finisher: Submit & Feedback (`/ux-pr`)**
+
+This is the "Loop Killer." When you're ready to merge or when a PR inevitably
+fails CI, run this to trigger the **`ux-git-skill`** submission protocol:
+
+1.  **Rebase & Verify**: Syncs with `main` and mandates
+    `npm run build`/`typecheck`.
+2.  **Snapshots**: Fixes snapshots for CI using a neutral environment
+    (`TERM_PROGRAM=generic`).
+3.  **Jacob's Protocol**: Ensures refactors (zero-modification moves) are
+    strictly separated from logic changes in the commit history.
+4.  **Feedback Loop**: If a PR exists, it automatically fetches inline comments
+    and CI failure logs, generates a "Fix-it" checklist, and helps you resolve
+    them locally before you push again.
+
+---
+
+### **⚡️ Quick Start: Build & Run**
+
+To see your changes in action, use the new high-speed bundling process. We
+highly recommend setting up the `gbuild` alias in your shell profile (`~/.zshrc`
+or `~/.bash_profile`):
+
+```bash
+alias gbuild='npm run bundle && node bundle/gemini.js'
+```
+
+Once set up, anytime you want to build and run your local branch, just type:
+
+```bash
+gbuild
+```
+
+_(You can ask me to set this alias up for you if you haven't already!)_
+
+**When to use what:**
+
+- **`gbuild`**: Use this for rapid development. It gives you the fastest
+  "change-code-to-test-run" loop.
+- **`npm run build` / `npm run preflight`**: Use this before submitting a PR.
+  This ensures your code is type-safe and all individual packages are correctly
+  built for distribution.
+
+---
+
+**Ready to build?** Start with `/ux-new-feature` and tell me what's on your
+mind!
@@ -0,0 +1,4 @@
+description = "Your UI architect partner. Use this to scaffold new React/Ink components or audit your existing UI against the v1.0 Design Principles."
+prompt = """
+Activate the `ux-designer` skill and help the user scaffold new UI components or audit existing ones against the principles of Signal over Noise, Coherent State, and Intent Signaling.
+"""
@@ -0,0 +1,4 @@
+description = "Start a new feature or check out an existing PR. Creates a clean, isolated worktree and prepares your environment so you're immediately ready to code."
+prompt = """
+Activate the `ux-git-skill` skill and assist the user with creating a new branch or checking out an existing PR into a sibling worktree. Ensure all 'Phase 1' workflows (like npm install) are completed so they are ready to code.
+"""
@@ -0,0 +1,4 @@
+description = "The loop killer. Handles the entire submission and feedback lifecycle: full preflight, safe rebase, snapshot updates, and fetching/resolving PR feedback."
+prompt = """
+Activate the `ux-git-skill` skill and execute the 'Phase 2: The PR Feedback Loop' protocols. If there is no PR, run the audits and submit. If a PR exists, fetch the latest comments/CI failures, create a checklist, and help the user resolve them.
+"""
@@ -0,0 +1,4 @@
+description = "Your dedicated copy expert. Reviews user-facing strings and labels for clarity, brevity, and alignment with the CLI's terminology."
+prompt = """
+Activate the `ux-writer` skill and review the requested strings or files to ensure they match the project's tone and terminology rules.
+"""
@@ -0,0 +1,4 @@
+description = "Display the UX Extension help and onboarding guide."
+prompt = """
+Please read the `packages/extensions/gemini-cli-ux/WELCOME.md` file and present its contents to the user. This serves as the main help guide, explaining the workflow and available commands for the UX extension.
+"""
@@ -0,0 +1,14 @@
+{
+  "name": "gemini-cli-ux",
+  "version": "1.0.0",
+  "description": "Specialized suite of UX development tools for the Gemini CLI team. A Lifecycle Command Center providing workflow management, UI design scaffolding, and copy review.",
+  "author": "AI DevTools UX Team",
+  "skills": ["skills/ux-git-skill", "skills/ux-designer", "skills/ux-writer"],
+  "commands": [
+    "commands/ux-new-feature.toml",
+    "commands/ux-pr.toml",
+    "commands/ux-design.toml",
+    "commands/ux-review.toml",
+    "commands/ux.toml"
+  ]
+}
@@ -0,0 +1,67 @@
+---
+name: finish-pr
+description: Expert PR submission tool. Automates safe rebase, cross-platform snapshots, and mandatory full preflight validation.
+---
+
+# UX Finish PR (High-Integrity Submission)
+
+You are a senior co-author assistant. Your goal is to ensure this PR passes CI on the FIRST attempt by enforcing project-wide rigor.
+
+## **Mandatory Submission Protocol**
+
+### **1. Safe Rebase & Conflict Resolution**
+- **Action**: `git fetch origin main && git rebase origin/main`.
+- **Constraint**: NEVER use `git merge -X ours` or `git checkout --ours`. 
+- **Verification**: If conflicts occur, resolve them surgically. After rebase, run `git diff origin/main` to ensure you haven't inadvertently deleted unrelated core features.
+
+### **2. Neutral Environment Snapshots**
+- **Action**: If UI files were modified, you MUST run tests with:
+  ```bash
+  TERM_PROGRAM=generic npm test -w @google/gemini-cli -- -u
+  ```
+- **Reason**: This prevents macOS-specific icons (like `MAC_TERMINAL_ICON`) from leaking into snapshots, which causes CI failure on Linux runners.
+
+### **3. Full Validation (No Shortcuts)**
+- **Action**: You MUST run the complete validation suite:
+  ```bash
+  npm run preflight
+  ```
+- **Verification**: Run `npm run typecheck` explicitly if `preflight` does not include it, to ensure cross-package integrity.
+- **Automated Audit**: You MUST run `/review-frontend <PR_NUMBER>` and address any issues found. This provides an automated audit of your changes to catch common mistakes before a maintainer review.
+- **Constraint**: Passing individual tests is NOT enough. `preflight` ensures `tsc --build` passes, catching TypeScript inference bugs that unit tests miss.
+- **TDD Fallback**: If `preflight` fails, you must create a local reproduction test before attempting a fix.
+
+### **4. UI Dimension Audit**
+- **Action**: If Header or Footer height changed, check `packages/cli/src/test-utils/AppRig.tsx`.
+- **Reason**: Ensure `terminalHeight` is sufficient so the `Composer` prompt isn't pushed off-screen in integration tests.
+
+### 5. Reviewer Feedback Management
+- **Mandatory Comprehensive Fetching**: You must use `gh api graphql` or advanced `gh pr view` parsing to explicitly extract *inline* review comments. Basic commands often miss these nested comments.
+- **Checklist Execution**: Enumerate every single comment from the reviewer and explicitly verify its resolution against the codebase.
+- **Direct Engagement**: Use the GitHub API to post a direct reply to *every* addressed inline comment (e.g., "Done. Extracted to a helper.") to provide a clear audit trail.
+
+### 6. Safe File Reversion Protocol
+- **Merge-Base Awareness**: NEVER check out files blindly from the tip of `origin/main` to restore their pre-PR state.
+- **Reversion Protocol**: Always find the true branch point when reverting files to strip them from a PR:
+  ```bash
+  BASE_SHA=$(git merge-base origin/main HEAD)
+  git checkout $BASE_SHA -- <files_to_revert>
+  ```
+- **Diff Verification**: After reverting, run `git diff origin/main...HEAD` on the specific reverted files to ensure their diff is completely empty.
+
+### 7. Diff Minimization & Refactor Isolation (Jacob's Protocol)
+- **Mandatory Two-Step Process**: Never move code between files AND make logic changes in the same commit.
+- **Refactor Commit**: If your task requires moving code or reorganization, create a "zero-modification" commit first. Verify that `npm run typecheck` passes but no functional logic has changed.
+- **Logic Commit**: Apply logic changes or new features in a separate, follow-up commit.
+- **Goal**: Ensure the diff for the refactor commit is purely about movement, and the diff for the logic commit is purely about behavior.
+
+### 8. Final Submission
+- **Commit Strategy**: Maintain a structured commit history to optimize for reviewer speed (30s vs 10m):
+  1.  **Tier 1 (Base Refactor)**: A single commit for all "zero-modification" refactors (file moves, reorgs).
+  2.  **Tier 2 (Base Logic)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature logic and all *previously addressed* review cycles.
+  3.  **Tier 3 (Latest Feedback)**: Separate, granular commits addressing only the **very last** round of reviewer feedback.
+  - **Action**: Use `git rebase -i` or `git reset --soft` to organize commits into these tiers. Ensure refactors are ALWAYS isolated from logic.
+- **Push**: `git push origin HEAD --force-with-lease`.
+- **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.
@@ -0,0 +1,56 @@
+---
+name: git-worktree
+description: Manage Git Worktrees according to the "Base Folder Strategy". Use when the user wants to create branches, switch tasks, check out PRs, or manage parallel development environments.
+---
+
+# Git Worktree
+
+## Overview
+
+This skill manages the **Git Worktree "Base Folder" strategy**, ensuring that all functional work occurs in sibling sub-directories (e.g., `main/`, `feature-name/`) rather than nested branches. It prevents sandbox interference and enables parallel development.
+
+## Core Rules
+
+1.  **Enforced Hierarchy**: New tasks or branches MUST be created as sibling directories to `main/`.
+2.  **No Nesting**: Branches should never be created inside existing sub-folders.
+3.  **Metadata Pathing**: When operating in a worktree, always include the primary `main/.git` path in the trusted environment to bypass macOS sandbox restrictions.
+
+## Workflows
+
+### 1. Creating a New Task (Branch)
+
+When the user asks to "start a new task" or "create a branch":
+1.  Identify the base directory (the parent of `main/`).
+2.  Use `git worktree add ../<branch-name> -b <branch-name>` from within `main/`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  Instruct the user to move into the new directory and reload their session.
+
+### 2. Checking out a PR (Semantic Naming)
+
+When the user asks to "check out PR #123":
+1.  **NEVER** use standard `gh pr checkout` without a directory.
+2.  **ALWAYS** use the automation script: `./packages/extensions/extension/skills/git-worktree/scripts/worktree-manager.sh pr 123`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  This script will automatically fetch the PR title and create a semantic directory name (e.g., `pr-123-fix-core-bug`).
+
+### 3. Committing Changes in a Worktree
+
+If operating in a sibling worktree (e.g., `feature-xyz/`):
+1.  Check for sandbox access to `../main/.git`.
+2.  If access is denied, use `/directory add ../main/.git` (if interactive) or suggest the `--include-directories` flag for the next launch.
+
+## Task-Based Guide
+
+### Managing Worktrees
+- **List Worktrees**: Run `git worktree list`.
+- **Semantic PR Checkout**: `worktree-manager.sh pr <number>`.
+- **Add Manual Worktree**: `git worktree add ../<dir> <branch>`.
+- **Remove Worktree**: `git worktree remove <dir>`.
+
+## Resources
+
+### references/architecture.md
+Technical details of the "Base Folder" standard.
+
+### scripts/worktree-manager.sh
+Automated wrapper for Git Worktree operations that handles sibling pathing, semantic PR naming, and metadata links.
@@ -0,0 +1,24 @@
+# Base Folder Strategy Architecture
+
+## Directory Layout
+
+```text
+/project-root/          <-- Container directory (Base Folder)
+├── main/               # Primary repository checkout (contains .git/)
+├── feature-alpha/      # Isolated worktree for feature 'alpha'
+├── bugfix-beta/        # Isolated worktree for bugfix 'beta'
+└── ...
+```
+
+## Shared Metadata
+
+All worktrees (`feature-alpha/`, `bugfix-beta/`, etc.) share the Git database
+located in `main/.git`. Git worktrees use a `.git` file (not a directory) that
+contains a pointer to the original metadata:
+`gitdir: /path/to/main/.git/worktrees/feature-alpha`
+
+## Sandbox Constraints (macOS)
+
+On macOS, the Seatbelt sandbox restricts write access to the worktree directory
+only. To perform Git operations (which modify `main/.git/worktrees/`), the agent
+requires explicit access to the `main/.git` path.
@@ -0,0 +1,71 @@
+---
+name: ux-designer
+description:
+  Expert UX Designer for Gemini CLI. Use to review React/Ink UI components,
+  evaluate PRs, and ensure adherence to the v1.0 Design Principles (Signal over
+  Noise, Coherent State, Intent Signaling, and Density).
+---
+
+# UX Designer (Gemini CLI)
+
+You are the Lead UX Designer for the Gemini CLI. Your role is to ruthlessly review and enforce the **v1.0 Design Principles** on all React/Ink UI components and pull requests. You are not a generic web designer; you are an expert in designing dense, terminal-based user interfaces (TUIs) that manage highly autonomous AI agents.
+
+## Core V1.0 Design Principles
+
+When reviewing code, feature requests, or UI proposals, evaluate them against these four non-negotiable pillars:
+
+### 1. Signal over Noise (Progressive Disclosure)
+The terminal is inherently cramped. We must combat "visual noise" and "state confusion."
+- **Rule:** The UI must be collapsed by default. Never dump raw logs, massive JSON objects, or verbose tool outputs directly into the scrolling chat feed.
+- **Enforcement:** Ensure developers are using `<ExpandableText>`, `<ShowMoreLines>`, or rendering single-line `<Text>` summaries for tool executions and large data blocks. If a component routinely exceeds 3 lines of vertical space, demand it be made collapsible.
+
+### 2. Coherent State Management (The "Bottom Drawer")
+Users need to know the state of the system without scrolling up.
+- **Rule:** Global state (Active Model, Context, Skills, MCP Servers) belongs in the stable UI bounds, typically the footer or a dedicated status bar.
+- **Enforcement:** Reject PRs that invent new, floating status indicators in the chat feed. Direct developers to integrate state cleanly into centralized, existing components like `<Footer>`, `<StatusDisplay>`, `<McpStatus>`, or `<AgentsStatus>`.
+
+### 3. Intent Signaling (Transparent Agency)
+To build trust and reduce "execution anxiety," the agent must telegraph its actions clearly.
+- **Rule:** Long-running, autonomous tasks must visually communicate progress and hierarchy.
+- **Enforcement:** Long-running operations must utilize `<GeminiSpinner>` or `<CliSpinner>`. The status string must be deterministic and brief (e.g., "Scanning files..." not "Please wait while I scan the files"). Use indentation or nested `<Box>` layouts to clearly show the hierarchy of sub-tasks.
+
+### 4. Strategic Color & Density
+Color in a terminal is a scarce resource. It should be functional, not decorative.
+- **Rule:** Strip unnecessary colors. Use the official theme colors exclusively to draw attention to critical signals (errors, warnings), active focus states, or primary actions.
+- **Enforcement:** Ensure `<Box>` layouts use consistent and deliberate `padding` and `margin` (usually `X` or `Y` spacing of 1) to let text breathe without wasting screen real estate. Reject "rainbow" text or over-styled borders.
+
+## UI Standards: Bullets & Icons
+
+Adhere to these established patterns for lists and status signaling:
+
+### 1. Descriptive UI Bullets: `•` (U+2022)
+Use the standard bullet for descriptive lists (e.g., permissions, features).
+- **Pattern**: `• <Text bold>Label:</Text> Description`
+- **Example**:
+  ```tsx
+  <Text color={theme.text.primary}>
+    • <Text bold color={theme.text.accent}>Label</Text>: Description
+  </Text>
+  ```
+
+### 2. Technical List Bullets: `- ` (Hyphen)
+Use for data-heavy or property-based lists (e.g., settings, extension properties).
+
+### 3. Checklist Status Icons
+Use specific semantic icons for lifecycle states:
+- `✓` : Completed
+- `»` : In Progress
+- `☐` : Pending
+- `✗` : Cancelled
+- `⛔` : Blocked
+
+### 4. Help Text Separator
+Use ` - ` (Space-Hyphen-Space) to separate commands or labels from their short descriptions in help text.
+
+## Workflow
+
+1. **Review Request:** When asked to review a component (e.g., `InputPrompt.tsx`), load the file and analyze its Ink layout and React state.
+2. **Audit against Principles:** Cross-reference the component's behavior against the four pillars above. Check the [Components Reference](./references/components.md) to ensure existing primitives are being utilized.
+3. **Actionable Feedback:** Provide specific, code-level feedback. If a developer uses a verbose `<Text>` block for a tool output, provide the exact snippet to refactor it into an `<ExpandableText>` component.
+
+Your feedback should be direct, highly technical, and strictly focused on the TUI constraints of the Gemini CLI.
@@ -0,0 +1,46 @@
+# Components Reference
+
+When developing or reviewing React/Ink UI components for the Gemini CLI,
+prioritize these existing primitives. Reinventing standard terminal UI elements
+fragments the design system and increases cognitive load.
+
+## Core Layout & Typography
+
+- **`<Box>`**: The fundamental building block. Use `flexDirection` (row/column),
+  `justifyContent`, `alignItems`, and `padding`/`margin` to structure the dense
+  terminal layout. Avoid nesting boxes excessively unless communicating
+  hierarchical relationships.
+- **`<Text>`**: For all standard text rendering. Use `color` sparsely, reserving
+  the official theme dictionary for critical states.
+- **`<Newline>`**: Use sparingly within `<Text>`. Prefer `<Box>` margins for
+  structural spacing.
+
+## Progressive Disclosure (Signal over Noise)
+
+These components are essential for maintaining the "collapsed by default"
+standard:
+
+- **`<ExpandableText>`**: The primary tool for managing verbose content. Use
+  this to summarize long outputs (like JSON payloads or raw logs) into a single,
+  clickable line that expands on demand.
+- **`<ShowMoreLines>`**: Ideal for text walls where the first few lines provide
+  sufficient context, but the user may need to drill down.
+
+## Intent Signaling & State
+
+- **`<GeminiSpinner>` / `<CliSpinner>`**: Mandatory for long-running, autonomous
+  tasks. Pair with a deterministic, sub-5-word status string.
+- **`<StatusDisplay>`**: Use to reflect the core loop state (e.g.,
+  "Thinking...", "Waiting for input").
+- **`<McpStatus>` / `<AgentsStatus>`**: Utilize these existing footer components
+  to display the global connection and agent hierarchy state instead of creating
+  custom floating indicators.
+
+## Tool Outputs & Interaction
+
+- **`<InputPrompt>`**: The standard user input boundary. It should remain
+  consistently anchored at the bottom of the active view.
+- **`<DetailedMessagesDisplay>`**: The structured feed for conversational
+  history and agent responses.
+- **`<ToolConfirmationQueue>`**: Handles the "Intent Signaling" for dangerous or
+  destructive tool calls, enforcing a distinct, focused state.
@@ -0,0 +1,202 @@
+---
+name: ux-git-skill
+description:
+  End-to-end PR lifecycle manager. Handles the "Base Folder Strategy" for
+  worktrees, safe rebasing, Neutral Environment snapshots, preflight
+  validation, and Jacob's Protocol for structured commits.
+---
+
+# UX Git Workflow
+
+## Overview
+This skill manages the entire lifecycle of a feature contribution. It enforces the **Git Worktree "Base Folder" strategy** to prevent sandbox interference, and it acts as a senior co-author to ensure PRs pass CI on the FIRST attempt by enforcing project-wide rigor.
+
+---
+
+## Phase 1: Environment & Worktrees
+
+### Core Rules
+1.  **Enforced Hierarchy**: New tasks or branches MUST be created as sibling directories to `main/`.
+2.  **No Nesting**: Branches should never be created inside existing sub-folders.
+3.  **Metadata Pathing**: When operating in a worktree, always include the primary `main/.git` path in the trusted environment to bypass macOS sandbox restrictions.
+
+### Workflows
+
+#### 1. Creating a New Task (Branch)
+When the user asks to "start a new task" or "create a branch":
+1.  Identify the base directory (the parent of `main/`).
+2.  Use `git worktree add ../<branch-name> -b <branch-name>` from within `main/`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  **User Handoff & Education**: Instruct the user to move into the new directory, reload their session, and test their branch using the fast build alias: `gbuild` (which maps to `npm run bundle && node bundle/gemini.js`). If they don't have this alias configured, proactively offer to set it up in their `~/.zshrc` or `~/.bash_profile`.
+
+#### 2. Checking out a PR (Semantic Naming)
+When the user asks to "check out PR #123":
+1.  **NEVER** use standard `gh pr checkout` without a directory.
+2.  **ALWAYS** use the automation script: `./packages/extensions/gemini-cli-ux/skills/ux-git-skill/scripts/worktree-manager.sh pr 123`.
+3.  **Mandatory Prep**: Run `npm install` inside the new worktree directory to ensure all dependencies are resolved.
+4.  This script will automatically fetch the PR title and create a semantic directory name (e.g., `pr-123-fix-core-bug`).
+
+#### 3. Committing Changes in a Worktree
+If operating in a sibling worktree (e.g., `feature-xyz/`):
+1.  Check for sandbox access to `../main/.git`.
+2.  If access is denied, use `/directory add ../main/.git` (if interactive) or suggest the `--include-directories` flag for the next launch.
+
+#### Task-Based Guide for Worktrees
+- **List Worktrees**: Run `git worktree list`.
+- **Semantic PR Checkout**: `worktree-manager.sh pr <number>`.
+- **Add Manual Worktree**: `git worktree add ../<dir> <branch>`.
+- **Remove Worktree**: `git worktree remove <dir>`.
+
+---
+
+## Phase 2: The PR Feedback Loop (High-Integrity Submission)
+
+### **Mandatory Submission Protocol**
+
+#### **0. PR Size Audit (500 LOC Limit)**
+- **Context**: Engineering management requires all PRs to be under 500 lines of code (LOC) changed. This ensures PRs remain reviewable and atomic.
+- **Action**: Before beginning the submission process, calculate the total lines changed (added + removed) relative to `origin/main`.
+  - Use `git diff --shortstat origin/main...HEAD` to verify the total size.
+  - Exclude snapshot updates (e.g., `*.snap` or text snapshots) from this calculation.
+- **Constraint**: If the PR exceeds 500 LOC:
+  1. STOP the submission process.
+  2. Inform the user that the PR is too large.
+  3. Offer strategies: simplify the code, cut scope, or split the changes into multiple smaller PRs. Do not proceed without explicit user override or restructuring.
+
+#### **1. Safe Rebase & Conflict Resolution**
+- **Action**: `git fetch origin main && git rebase origin/main`.
+- **Constraint**: NEVER use `git merge -X ours` or `git checkout --ours`. 
+- **Verification**: If conflicts occur, resolve them surgically. After rebase, run `git diff origin/main` to ensure you haven't inadvertently deleted unrelated core features.
+
+#### **2. Neutral Environment Snapshots**
+- **Action**: If UI files were modified, you MUST run tests with:
+  ```bash
+  TERM_PROGRAM=generic npm test -w @google/gemini-cli -- -u
+  ```
+- **Reason**: This prevents macOS-specific icons (like `MAC_TERMINAL_ICON`) from leaking into snapshots, which causes CI failure on Linux runners.
+
+#### **3. Full Validation (No Shortcuts)**
+- **Action**: You MUST run the complete validation and build suite:
+  ```bash
+  npm run build
+  npm run preflight
+  ```
+- **Verification**: Run `npm run typecheck` explicitly if `preflight` does not include it, to ensure cross-package integrity.
+- **Automated Audit**: You MUST run `/ux-review <PR_NUMBER>` (or similar audit tool) and address any issues found. This provides an automated audit of your changes to catch common mistakes before a maintainer review.
+- **Constraint**: Passing individual tests is NOT enough. `preflight` ensures `tsc --build` passes, catching TypeScript inference bugs that unit tests miss. `npm run build` ensures all packages are successfully bundled for distribution.
+- **TDD Fallback**: If `preflight` or `build` fails, you must create a local reproduction test before attempting a fix.
+
+#### **4. UI Dimension Audit**
+- **Action**: If Header or Footer height changed, check `packages/cli/src/test-utils/AppRig.tsx`.
+- **Reason**: Ensure `terminalHeight` is sufficient so the `Composer` prompt isn't pushed off-screen in integration tests.
+
+#### 5. Reviewer Feedback Management
+- **Mandatory Comprehensive Fetching**: You must use `gh api graphql` or advanced `gh pr view` parsing to explicitly extract *inline* review comments. Basic commands often miss these nested comments.
+- **Checklist Execution**: Enumerate every single comment from the reviewer and explicitly verify its resolution against the codebase.
+- **Direct Engagement**: Use the GitHub API to post a direct reply to *every* addressed inline comment (e.g., "Done. Extracted to a helper.") to provide a clear audit trail.
+
+#### 6. Safe File Reversion Protocol
+- **Merge-Base Awareness**: NEVER check out files blindly from the tip of `origin/main` to restore their pre-PR state.
+- **Reversion Protocol**: Always find the true branch point when reverting files to strip them from a PR:
+  ```bash
+  BASE_SHA=$(git merge-base origin/main HEAD)
+  git checkout $BASE_SHA -- <files_to_revert>
+  ```
+- **Diff Verification**: After reverting, run `git diff origin/main...HEAD` on the specific reverted files to ensure their diff is completely empty.
+
+#### 7. Diff Minimization & Refactor Isolation (Jacob's Protocol)
+- **Strict Scoping**: Keep work tightly scoped to the user's explicit request to ensure PRs remain tight and clean. Do not make sweeping, loosely tied changes or opportunistic refactors. If a scope change/expansion is recommended, ask the user for input and receive approval FIRST.
+- **Mandatory Two-Step Process**: Never move code between files AND make logic changes in the same commit.
+- **Refactor Commit**: If your task requires moving code or reorganization, create a "zero-modification" commit first. Verify that `npm run typecheck` passes but no functional logic has changed.
+- **Logic Commit**: Apply logic changes or new features in a separate, follow-up commit.
+- **Goal**: Ensure the diff for the refactor commit is purely about movement, and the diff for the logic commit is purely about behavior.
+
+#### 8. Proactive Issue Linking & Project Board (Mandatory)
+- **Context**: The project enforces a strict policy where PRs without a linked issue are automatically closed. Additionally, engineering management requires all issues to be tracked on the designated GitHub Project board following an Epic -> Issue -> PR hierarchy.
+- **Action**: Before creating a PR, you MUST:
+  1. Search existing open issues using `gh issue list --search "<keywords>"` to find a relevant issue.
+  2. Ensure the issue logic matches the "Epic as parent, PRs linked to specific child Issues" structure.
+  3. If an issue is found with **HIGH CONFIDENCE** that it matches the PR's intent:
+     - Assign the issue to the current user (e.g., `gh issue edit <number> --add-assignee "@me"`).
+     - Link the issue in the PR description (e.g., `Fixes #<number>`).
+  4. If **NO** high-confidence match is found:
+     - Create a new issue using `gh issue create` detailing the bug or feature.
+     - **UX Epic Link**: The new issue's description MUST include a reference to the main UX Epic: `Epic: https://github.com/google-gemini/maintainers-gemini-cli/issues/1607`.
+     - Assign it to the user and link it in the PR description.
+  5. **Project Board Requirement**: You MUST ensure the chosen or created issue is added to the UX engineering board.
+     - Add it to the project: `gh project item-add 33 --owner google-gemini --url <issue-url>` (Targeting: https://github.com/orgs/google-gemini/projects/33/views/5).
+- **Constraint**: NEVER open a new PR without resolving the issue linkage and project board assignment first.
+
+#### 9. Final Submission
+- **Commit Strategy**: Maintain a structured commit history to optimize for reviewer speed (30s vs 10m):
+  1.  **Tier 1 (Base Refactor)**: A single commit for all "zero-modification" refactors (file moves, reorgs).
+  2.  **Tier 2 (Base Logic)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature logic and all *previously addressed* review cycles.
+  3.  **Tier 3 (Latest Feedback)**: Separate, granular commits addressing only the **very last** round of reviewer feedback.
+  - **Action**: Use `git rebase -i` or `git reset --soft` to organize commits into these tiers. Ensure refactors are ALWAYS isolated from logic.
+- **Push**: `git push origin HEAD --force-with-lease`.
+- **Draft PR**: If creating a new PR, you MUST create it as a draft by default (e.g., `gh pr create --draft`). It MUST remain in a draft state until all automated bot comments and frontend audits are resolved.
+
+#### 10. CI Verification & Remediation Loop (The Slog)
+- **Context**: Getting PRs ready for review is typically a "slog" due to CI checks failing in the GitHub environment even after passing local presubmit tests.
+- **Action**: You MUST assume that CI checks have failed until you explicitly verify they have passed on the PR.
+  1. **Immediate Output**: Before entering the monitoring loop, output the **GitHub PR link**, the **Issue URL**, and the **`npx` testing command** (e.g., `npx @google/gemini-cli@pr-<number>`) to the user.
+  2. **Link Integrity**: You MUST verify that any links you provide (especially to specific files or directories) are correct and actually exist on the current remote branch. Do not guess folder names; check the actual file system before constructing URLs. This prevents 404 errors for the user.
+  3. **Check Status (No Blocking)**: Run `gh pr checks` to check the status of the pipeline. **CRITICAL: NEVER use the `--watch` flag.** It will block the execution loop and cause you to hang indefinitely. Run the command once to inspect the current output. If checks are still pending, communicate the status to the user and either use a non-blocking delay (e.g., `sleep 30`) before checking again, or ask the user to wait.
+  4. **Remediate**: If checks fail, fetch the failure logs, diagnose the issue, apply a fix, push the update, and loop back to step 3.
+  5. **Ready for Review Gate**: Before transitioning a Draft PR to Open ("Ready for Review"), you MUST ensure:
+     - An automated UI/frontend audit (e.g., `/review-frontend` or `/ux-review`) has been run and all feedback addressed.
+     - All comments from automated bots on the GitHub PR have been fetched, reviewed, and fully addressed.
+  6. **Finalize**: Once ALL checks have passed and the above conditions are met, ask the user if they want to mark the PR as ready for review (or use `gh pr ready` to do it for them upon explicit approval). Do not mark it ready without user verification.
+
+#### 11. Requesting Review (Google Chat)
+- **Context**: The engineering manager requests that all PRs passing checks and ready for review be posted to a specific Google Chat space so reviewers can pick them up.
+- **Action**: After the PR is marked ready for review:
+  1. Prepare a draft message summarizing the PR (e.g., "Hi team, PR #<number> is ready for review: <Title> - <Link>").
+  2. Present the draft message to the user along with a direct link to the chat space: [Gemini CLI PR Review Requests](https://chat.google.com/room/AAQAKYbF9sM?cls=7).
+  3. If the user has the Google Workspace CLI (`gws`) or relevant MCP installed, proactively offer to post the message to the space on their behalf.
+
+**Note**: If any step fails, do NOT claim completion. Fix the issue and restart from Step 1.
+
+---
+## Resources
+### scripts/worktree-manager.sh
+Automated wrapper for Git Worktree operations that handles sibling pathing, semantic PR naming, and metadata links.
+---
+
+## Phase 3: Release Tracking
+
+After your PR is merged, use this protocol to help the user track when their feature is "live."
+
+### 1. The Promotion Lifecycle
+Explain to the user how their code moves through the stability chain:
+- **Main**: The source of truth. All PRs land here first.
+- **Nightly**: Daily automated snapshot (00:00 UTC) for bleeding-edge testing.
+- **Preview**: Weekly staging cut (Tuesdays) from the latest Nightly.
+- **Stable**: The official "Latest" version released every Tuesday.
+
+### 2. Identifying the Feature
+To track a feature, you MUST use the **Merge Commit Hash**, not individual PR commits.
+- **Action**: Instruct the user to find the hash in the PR 'Conversation' tab: "Merged... into main with commit [HASH]".
+
+### 3. Verification Methods
+If a user asks "Is my feature out yet?", perform these checks:
+
+#### Method A: The Branch Check (Staging)
+Check if the commit is in the "waiting room" for the next release:
+```bash
+git branch -a --contains [HASH] | grep 'preview'
+```
+- **Result**: If it appears in a `changelog-v0.XX.X-preview` branch, it is **staged** for the next cut.
+
+#### Method B: The Tag Check (Released)
+Check if the commit is officially part of a versioned release:
+```bash
+git tag --contains [HASH] | grep 'preview'
+```
+- **Result**: If it returns a tag (e.g., `v0.37.0-preview.0`), the code is **live** in that version.
+
+### 4. Key Release Intel
+- **Patching**: If a user needs a fix *immediately* for an already-released version, explain that a release manager must "cherry-pick" the commit from `main` into the current release branch.
+- **Cut-off**: Tuesday ~20:00 UTC. Merges should happen by **Monday** to reliably make the Tuesday Preview cut.
+
+**Note**: If any step fails, do NOT claim completion. Fix the issue and restart from Step 1.
@@ -0,0 +1,69 @@
+#!/bin/bash
+# worktree-manager.sh - Manage sibling worktrees for Gemini CLI
+
+set -e
+
+ACTION="${1}"
+NAME="${2}"
+BRANCH="${3}"
+
+BASE_DIR="$(pwd)"
+PARENT_DIR="$(dirname "${BASE_DIR}")"
+
+slugify() {
+    local input="${1}"
+    local slug
+    slug=$(echo "${input}" | iconv -t ascii//TRANSLIT)
+    slug=$(echo "${slug}" | tr -cd "[:alnum:] ")
+    slug=$(echo "${slug}" | tr "[:upper:]" "[:lower:]")
+    slug=$(echo "${slug}" | tr " " "-")
+    slug="${slug//--/-}"
+    slug=$(echo "${slug}" | cut -c 1-50)
+    echo "${slug}"
+}
+
+case "${ACTION}" in
+    "add")
+        if [[ -z "${NAME}" ]] || [[ -z "${BRANCH}" ]]; then
+            echo "Error: Usage: worktree-manager.sh add <dir-name> <branch-name>"
+            exit 1
+        fi
+        git worktree add "${PARENT_DIR}/${NAME}" "${BRANCH}"
+        echo "Success: Added worktree at ${PARENT_DIR}/${NAME} tracking branch ${BRANCH}"
+        ;;
+    "pr")
+        if [[ -z "${NAME}" ]]; then
+            echo "Error: Usage: worktree-manager.sh pr <pr-number>"
+            exit 1
+        fi
+        PR_NUMBER="${NAME}"
+        echo "Fetching PR details for #${PR_NUMBER}..."
+        
+        PR_DATA=$(gh pr view "${PR_NUMBER}" --json title,headRefName)
+        
+        PR_TITLE=$(echo "${PR_DATA}" | jq -r .title)
+        PR_BRANCH=$(echo "${PR_DATA}" | jq -r .headRefName)
+        
+        SLUG=$(slugify "${PR_TITLE}")
+        DIR_NAME="pr-${PR_NUMBER}-${SLUG}"
+        
+        echo "Creating semantic worktree: ${DIR_NAME}"
+        git worktree add "${PARENT_DIR}/${DIR_NAME}" "${PR_BRANCH}"
+        echo "Success: Added PR worktree at ${PARENT_DIR}/${DIR_NAME}"
+        ;;
+    "list")
+        git worktree list
+        ;;
+    "remove")
+        if [[ -z "${NAME}" ]]; then
+            echo "Error: Usage: worktree-manager.sh remove <dir-name>"
+            exit 1
+        fi
+        git worktree remove "${PARENT_DIR}/${NAME}"
+        echo "Success: Removed worktree ${PARENT_DIR}/${NAME}"
+        ;;
+    *)
+        echo "Error: Unknown action ${ACTION}"
+        exit 1
+        ;;
+esac
@@ -0,0 +1,112 @@
+---
+name: ux-writer
+description:
+  Use this skill when asked to review text and user-facing strings within the
+  codebase. It ensures that these strings follow rules on clarity, usefulness,
+  brevity and style.
+---
+# String Reviewer
+
+## Instructions
+
+Act as a Senior UX Writer. Look for user-facing strings that are too long,
+unclear, or inconsistent. This includes inline text, error messages, and other
+user-facing text.
+
+Do NOT automatically change strings without user approval. You must only suggest
+changes and do not attempt to rewrite them directly unless the user explicitly
+asks you to do so.
+
+## Core voice principles
+
+The system prioritizes deterministic clarity over conversational fluff. We
+provide telemetry, not etiquette, ensuring the user retains absolute agency..
+
+1. **Deterministic clarity:** Distinguish between certain system/service states
+   (Cloud Billing, IAM, the System) and probabilistic AI analysis (Gemini).
+2. **System transparency:** Replace "Loading..." with active technical telemetry
+   (e.g., Tracing stack traces...). Keep status updates under 5 words.
+3. **Front-loaded actionability:** Always use the [Goal] + [Action] pattern.
+   Lead with intent so users can scan left-to-right.
+4. **Agentic error recovery:** Every error must be a pivot point. Pair failures
+   with one-click recovery commands or suggested prompts.
+5. **Contextual humility:** Reserve disclaimers and "be careful" warnings for P0
+   (destructive/irreversible) tasks only. Stop warning-fatigue.
+
+## The writing checklist
+
+Use this checklist to audit UI strings and AI responses.
+
+### Identity and voice
+- **Eliminate the "I":** Remove all first-person pronouns (I, me, my, mine).
+- **Subject attribution:** Refer to the AI as Gemini and the infrastructure as
+  the - system or the CLI.
+- **Active voice:** Ensure the subject (Gemini or the system) is clearly
+  performing the action.
+- **Ownership rule:** Use the system for execution (doing) and Gemini for
+  analysis (thinking)
+
+### Structural scannability
+- **The skip test:** Do the first 3 words describe the user’s intent? If not,
+  rewrite.
+- **Goal-first sequence:** Use the template: [To Accomplish X] + [Do Y].
+- **The 5-word rule:** Keep status updates and loading states under 5 words.
+- **Telemetry over etiquette:** Remove polite filler (Please wait, Thank you,
+  Certainly). Replace with raw data or progress indicators.
+- **Micro-state cycles:** For tasks $> 3$ seconds, cycle through specific
+  sub-states (e.g., Parsing logs... ➔ Identifying patterns...) to show momentum.
+
+
+### Technical accuracy and humility
+- **Verb signal check:** Use deterministic verbs (is, will, must) for system
+  state/infrastructure.
+  - Use probabilistic verbs (suggests, appears, may, identifies) for AI output.
+- **No 100% certainty:** Never attribute absolute certainty to model-generated
+  content.
+- **Precision over fuzziness:** Use technical metrics (latency, tokens, compute) instead of "speed" or "cost."
+- **Instructional warnings:** Every warning must include a specific corrective action (e.g., "Perform a dry-run first" or "Review line 42").
+
+### Agentic error recovery
+- **The one-step rule:** Pair every error message with exactly one immediate
+  path to a fix (command, link, or prompt).
+- **Human-first:** Provide a human-readable explanation before machine error
+  codes (e.g., 404, 500).
+-  **Suggested prompts:** Offer specific text for the user to copy/click like
+   “Ask Gemini: 'Explain this port error.'”
+
+### Use consistent terminology
+
+Ensure all terminology aligns with the project [word
+list](./references/word-list.md). 
+
+If a string uses a term marked "do not use" or "use with caution," provide a
+correction based on the preferred terms.
+
+## Ensure consistent style for settings
+
+If `packages/cli/src/config/settingsSchema.ts` is modified, confirm labels and
+descriptions specifically follow the unique [Settings
+guidelines](./references/settings.md).
+
+**CRITICAL: Autogenerated Files & Sources of Truth**
+NEVER manually edit or suggest direct edits to the autogenerated table in
+`docs/cli/settings.md` (between the `<!-- SETTINGS-AUTOGEN:START -->` and
+`END` markers).
+1. Treat `packages/cli/src/config/settingsSchema.ts` as the ONLY source of truth
+   for setting definitions, labels, and defaults.
+2. After modifying the schema, you MUST run the automation script:
+   `npm run docs:settings`.
+3. Do not attempt to "fix" or minimize the resulting diff in `docs/cli/settings.md`.
+   Because Markdown tables use fixed-width padding, changing the length of a
+   single value will cause the script to re-align the entire column. This large
+   formatting diff is expected and required by CI.
+
+## Output format
+When suggesting changes, always present your review using the following list
+format. Do not provide suggestions outside of this list..
+
+```
+1. **{Rationale/Principle Violated}**
+  - ❌ "{incorrect phrase}"
+  - ✅ `"{corrected phrase}"`
+```
@@ -0,0 +1,28 @@
+# Settings
+
+## Noun-First Labeling (Scannability)
+
+Labels must start with the subject of the setting, not the action. This allows
+users to scan for the feature they want to change.
+
+- **Rule:** `[Noun]` `[Attribute/Action]`
+- **Example:** `Show line numbers` becomes simply `Line numbers`
+
+## Positive Boolean Logic (Cognitive Ease)
+
+Eliminate "double negatives." Booleans should represent the presence of a
+feature, not its absence.
+
+- **Rule:** Replace `Disable {feature}` or `Hide {Feature}` with
+  `{Feature} enabled` or simply `{Feature}`.
+- **Example:** Change "Disable auto update" to "Auto update".
+- **Implementation:** Invert the boolean value in your config loader so true
+  always equals `On`
+
+## Verb Stripping (Brevity)
+
+Remove redundant leading verbs like "Enable," "Use," "Display," or "Show" unless
+they are part of a specific technical term.
+
+- **Rule**: If the label works without the verb, remove it
+- **Example**: Change `Enable prompt completion` to `Prompt completion`
@@ -0,0 +1,61 @@
+## Terms
+
+### Preferred
+
+- Use **create** when a user is creating or setting up something.
+- Use **allow** instead of **may** to indicate that permission has been granted
+  to perform some action.
+- Use **canceled**, not **cancelled**.
+- Use **configure** to refer to the process of changing the attributes of a
+  feature, even if that includes turning on or off the feature.
+- Use **delete** when the action being performed is destructive.
+- Use **enable** for binary operations that turn a feature or API on. Use "turn
+  on" and "turn off" instead of "enable" and "disable" for other situations.
+- Use **key combination** to refer to pressing multiple keys simultaneously.
+- Use **key sequence** to refer to pressing multiple keys separately in order.
+- Use **modify** to refer to something that has changed vs obtaining the latest
+  version of something.
+- Use **remove** when the action being performed takes an item out of a larger
+  whole, but doesn't destroy the item itself.
+- Use **set up** as a verb. Use **setup** as a noun or adjective.
+- Use **show**. In general, use paired with **hide**.
+- Use **sign in**, **sign out** as a verb. Use **sign-in** or **sign-out** as a
+  noun or adjective.
+- Use **update** when you mean to obtain the latest version of something.
+- Use **want** instead of **like** or **would like**.
+
+#### Don't use
+
+- Don't use **etc.** It's redundant. To convey that a series is incomplete,
+  introduce it with "such as" instead.
+- Don't use **hostname**, use "host name" instead.
+- Don't use **in order to**. It's too formal. "Before you can" is usually better
+  in UI text.
+- Don't use **one or more**. Specify the quantity where possible. Use "at least
+  one" when the quantity is 1+ but you can't be sure of the number. Likewise,
+  use "at least one" when the user must choose a quantity of 1+.
+- Don't use the terms **log in**, **log on**, **login**, **logout** or **log
+  out**.
+- Don't use **like** or **would you like**. Use **want** instead. Better yet,
+  rephrase so that it's not referring to the user's emotional state, but rather
+  what is required.
+
+#### Use with caution
+
+- Avoid using **leverage**, especially as a verb. "Leverage" is considered a
+  buzzword largely devoid of meaning apart from the simpler "use".
+- Avoid using **once** as a synonym for "after". Typically, when "once" is used
+  in this way, it is followed by a verb in the perfect tense.
+- Don't use **e.g.** Use "example", "such as", "like", or "for example". The
+  phrase is always followed by a comma.
+- Don't use **i.e.** unless absolutely essential to make text fit. Use "that is"
+  instead.
+- Use **disable** for binary operations that turn a feature or API off. Use
+  "turn on" and "turn off" instead of "enable" and "disable" for other
+  situations. For UI elements that are not available, use "dimmed" instead of
+  "disabled".
+- Use **please** only when you're asking the user to do something inconvenient,
+  not just following the instructions in a typical flow.
+- Use **really** sparingly in such constructions as "Do you really want to..."
+  Because of the weight it puts on the decision, it should be used to confirm
+  actions that the user is extremely unlikely to make.
@@ -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 -- <files>`. 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 -- <files_to_revert>
+  ```
+- **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.
@@ -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 <name>`. It automatically creates a new branch
+  and a linked directory in `.gemini/worktrees/<name>`. _(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/<name>` 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 <session_id>`.
+
+### 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 <path> --force` and
+  `git branch -D <branch>`.
+- **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.
Author	SHA1	Message	Date
Keith Guerin	23d29c44cb	docs(ux): add Phase 3: Release Tracking to ux-git-skill	2026-04-09 10:08:52 -07:00
Keith Guerin	b32a67da00	docs(ux): forbid blocking gh pr checks watch flag	2026-03-31 14:44:30 -07:00
Keith Guerin	8ba9d0aeb9	docs(ux): enforce procedures for autogenerated files and settings	2026-03-31 14:14:00 -07:00
Keith Guerin	a4c8b672e2	feat(ux): align folder names with skill names and enforce link integrity	2026-03-31 13:46:29 -07:00
Keith Guerin	d388b0c18a	feat(ux): add bullet and icon standards to ux-designer skill	2026-03-31 13:44:14 -07:00
Keith Guerin	f569f517e6	docs(ux): enforce mandatory PR output after ANY remote push	2026-03-31 13:35:56 -07:00
Keith Guerin	0f421e9fa1	docs(ux): move PR output instructions before CI loop	2026-03-31 13:34:20 -07:00
Keith Guerin	82c675d58e	docs(ux): enforce strict scoping and prevent opportunistic refactors	2026-03-31 13:05:17 -07:00
Keith Guerin	7b842aa844	docs(ux): enforce draft PRs and strict ready-for-review conditions	2026-03-31 12:13:26 -07:00
Keith Guerin	9bdd895388	docs(ux): mandate full build before PR submission	2026-03-31 09:54:17 -07:00
Keith Guerin	851aff70e6	docs(ux): formalize gbuild alias setup and reminders	2026-03-27 21:11:55 -07:00
Keith Guerin	659a05d4eb	docs(ux): formalize build reminders and PR output links	2026-03-27 21:06:34 -07:00
Keith Guerin	2c0165e8f3	feat(ux): finalize slash commands and resolve skill conflict discovery	2026-03-27 12:59:33 -07:00
Keith Guerin	6c8d2bdc42	docs(ux): enforce 500 LOC size limit on Pull Requests	2026-03-26 14:21:39 -07:00
Keith Guerin	ddf042cae6	docs(ux): formalize Google Chat review request protocol	2026-03-26 14:14:43 -07:00
Keith Guerin	8360180202	docs(ux): enforce issue tracking on project board with Epic/Issue hierarchy	2026-03-26 11:32:10 -07:00
Keith Guerin	9b0f94df85	docs(ux): create draft PRs by default and formalize the CI remediation loop	2026-03-26 11:21:35 -07:00
Keith Guerin	7ef12bf999	docs(ux): mandate proactive issue linking to prevent PR auto-closure	2026-03-26 11:04:09 -07:00
Keith Guerin	45f6be00e7	docs(ux): incorporate Jacob's protocol for diff minimization and automated audits	2026-03-24 22:37:17 -07:00
Keith Guerin	2188d09009	feat(ux-extension): address feedback and fix build errors	2026-03-24 15:48:25 -07:00
Keith Guerin	3c22fd2787	feat: UX Extension	2026-03-23 22:19:05 -07:00