diff --git a/packages/extensions/gemini-cli-ux/skills/ux-git-workflow/SKILL.md b/packages/extensions/gemini-cli-ux/skills/ux-git-workflow/SKILL.md new file mode 100644 index 0000000000..c49b3d26a3 --- /dev/null +++ b/packages/extensions/gemini-cli-ux/skills/ux-git-workflow/SKILL.md @@ -0,0 +1,125 @@ +--- +name: ux-git-workflow +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 ../ -b ` 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/gemini-cli-ux/skills/ux-git-workflow/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 `. +- **Add Manual Worktree**: `git worktree add ../ `. +- **Remove Worktree**: `git worktree remove `. + +--- + +## Phase 2: The PR Feedback Loop (High-Integrity Submission) + +### **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 ` 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 -- + ``` +- **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. Proactive Issue Linking (Mandatory) +- **Context**: The project enforces a strict policy where PRs without a linked issue are automatically closed. +- **Action**: Before creating a PR, you MUST: + 1. Search existing open issues using `gh issue list --search ""` to find a relevant issue. + 2. 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 --add-assignee "@me"`). + - Link the issue in the PR description (e.g., `Fixes #`). + 3. If **NO** high-confidence match is found: + - Create a new issue using `gh issue create` detailing the bug or feature. + - Assign it to the user and link it in the PR description. +- **Constraint**: NEVER open a new PR without resolving the issue linkage 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`. +- **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. + +--- +## Resources +### scripts/worktree-manager.sh +Automated wrapper for Git Worktree operations that handles sibling pathing, semantic PR naming, and metadata links. \ No newline at end of file