diff --git a/GEMINI.md b/GEMINI.md index 4d9aee3b89..5eb1b1f55b 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,56 +1,38 @@ -# Workspace: Base Folder Strategy & Custom Skills +# Gemini CLI Project Context -This branch introduces the **\_ux_git-worktree**, **\_ux_finish-pr**, and -**\_ux_designer** skills and enforces the **Base Folder Strategy** for -repository management. It is maintained by the AI DevTools UX team. +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. -## 🚨 Directive for AI Agents (Read First) +## πŸ“¦ UX Toolkit Extension -**If you are an AI agent operating in this branch, your first task is to ensure -the custom skills are active.** +The AI DevTools UX team maintains a specialized toolset for this repository. It +is recommended to install the **UX Toolkit** extension to enable standardized +workflows (Base Folder Strategy, PR finishing, etc.). -1. Check if `~/.gemini/skills/_ux_git-worktree/`, - `~/.gemini/skills/_ux_finish-pr/`, and `~/.gemini/skills/_ux_designer/` - exist. -2. If any are missing, immediately execute `./scripts/sync-skills.sh`. -3. Prompt the user to run `/skills reload` if you are in an interactive session. +### Installation + +```bash +gemini extensions install ./packages/extensions/ux-toolkit +``` + +After installation, run `/_ux_help` to see available commands. + +## πŸ› οΈ Workspace Strategy: Base Folder + +This repository uses a **Git Worktree "Base Folder" strategy**. + +- Functional work (commits, code, tests) happens in sibling directories (e.g., + `main/`, `feature-name/`). +- The root directory is a container, not a repository itself. +- **ALWAYS** use the `_ux_git-worktree` skill (included in the UX Toolkit) for + any Git operations. ## 🀝 Team Contributions -This is a **Draft PR branch**. Your team is encouraged to: - - Refine the `_ux_git-worktree` skill instructions in - `packages/core/src/skills/builtin/_ux_git-worktree/SKILL.md`. + `packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md`. - Refine the `_ux_finish-pr` skill instructions in - `packages/core/src/skills/builtin/_ux_finish-pr/SKILL.md`. -- Improve the automation in `scripts/worktree-manager.sh`. + `packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md`. - All changes should be committed directly to this branch (`feature/gemini-cli-ux-team-skills`). - -## 1. Architectural Strategy - -Functional work happens in sibling directories (e.g., `main/`, `feature-name/`). -The root directory acts as a container. - -## 2. Setting Up Custom Skills - -To ensure this agent has the necessary procedural knowledge to manage worktrees -and PR reviews on your behalf, you must sync the custom skills to your local -user directory. - -### Sync Script - -Run the following from the root of this worktree: - -```bash -./scripts/sync-skills.sh -``` - -## 3. Mandatory Workflow - -- **ALWAYS** use the `_ux_git-worktree` skill for branch management. -- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance. -- Never use standard `git checkout -b`. -- Use `worktree-manager.sh pr ` for semantic PR checkouts. -- When operating in a worktree, ensure the primary `main/.git` path is included - in your trusted directories to bypass macOS sandbox restrictions. diff --git a/README.md b/README.md index 79d104e14b..9392bb8648 100644 --- a/README.md +++ b/README.md @@ -115,14 +115,16 @@ npm install -g @google/gemini-cli@nightly ### Automation & Integration -- **Custom Development Skills**: This branch introduces specialized skills for - the AI DevTools UX team: +- **UX Toolkit Extension**: This branch introduces a formal extension for the AI + DevTools UX team. Install it to enable specialized workflows: \`gemini + extensions install ./packages/extensions/ux-toolkit\` - **\_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 diff --git a/packages/extensions/ux-toolkit/GEMINI.md b/packages/extensions/ux-toolkit/GEMINI.md new file mode 100644 index 0000000000..83fdfaad1d --- /dev/null +++ b/packages/extensions/ux-toolkit/GEMINI.md @@ -0,0 +1,25 @@ +# UX Toolkit: Extension Context + +This extension provides the specialized toolset for the AI DevTools UX team. +When this extension is active, the agent must adhere to the following standards +and workflows. + +## 🚨 Agent Directives + +1. **Worktree Strategy**: Always prefer the **Base Folder Strategy**. Use + `_ux_git-worktree` to manage sibling directories for all tasks. +2. **PR Maintenance**: Use `_ux_finish-pr` to handle the final polish of pull + requests, ensuring all tests pass and snapshots are updated. +3. **UI Review**: Use `_ux_designer` to audit any new Ink/React components + against the v1.0 Design Principles (Density, Progressive Disclosure, State). +4. **UX Writing**: Use `_ux_string-reviewer` to ensure all user-facing strings + comply with project terminology and clarity rules. + +## Mandatory Workflow + +- **ALWAYS** use the `_ux_git-worktree` skill for branch management. +- **ALWAYS** use the `_ux_finish-pr` skill for pull request maintenance. +- Never use standard `git checkout -b`. +- Use `worktree-manager.sh pr ` for semantic PR checkouts. +- When operating in a worktree, ensure the primary `main/.git` path is included + in your trusted directories to bypass macOS sandbox restrictions. diff --git a/WELCOME.md b/packages/extensions/ux-toolkit/WELCOME.md similarity index 100% rename from WELCOME.md rename to packages/extensions/ux-toolkit/WELCOME.md diff --git a/packages/extensions/ux-toolkit/commands/ux-help.toml b/packages/extensions/ux-toolkit/commands/ux-help.toml new file mode 100644 index 0000000000..31f1b59905 --- /dev/null +++ b/packages/extensions/ux-toolkit/commands/ux-help.toml @@ -0,0 +1,4 @@ +description = "Show the UX Toolkit welcome guide and documentation." +prompt = """ +Read the welcome guide at \`packages/extensions/ux-toolkit/WELCOME.md\` and output its contents to the user. +""" diff --git a/packages/extensions/ux-toolkit/gemini-extension.json b/packages/extensions/ux-toolkit/gemini-extension.json new file mode 100644 index 0000000000..d0bbfa723f --- /dev/null +++ b/packages/extensions/ux-toolkit/gemini-extension.json @@ -0,0 +1,13 @@ +{ + "name": "ux-toolkit", + "version": "1.0.0", + "description": "Specialized suite of UX development tools for the Gemini CLI team, including worktree management, PR finishing, and design auditing.", + "author": "AI DevTools UX Team", + "skills": [ + "skills/_ux_git-worktree", + "skills/_ux_finish-pr", + "skills/_ux_designer", + "skills/_ux_string-reviewer" + ], + "commands": ["commands/ux-help.toml"] +} diff --git a/packages/core/src/skills/builtin/_ux_designer/SKILL.md b/packages/extensions/ux-toolkit/skills/_ux_designer/SKILL.md similarity index 100% rename from packages/core/src/skills/builtin/_ux_designer/SKILL.md rename to packages/extensions/ux-toolkit/skills/_ux_designer/SKILL.md diff --git a/packages/core/src/skills/builtin/_ux_designer/references/components.md b/packages/extensions/ux-toolkit/skills/_ux_designer/references/components.md similarity index 100% rename from packages/core/src/skills/builtin/_ux_designer/references/components.md rename to packages/extensions/ux-toolkit/skills/_ux_designer/references/components.md diff --git a/packages/core/src/skills/builtin/_ux_finish-pr/SKILL.md b/packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md similarity index 100% rename from packages/core/src/skills/builtin/_ux_finish-pr/SKILL.md rename to packages/extensions/ux-toolkit/skills/_ux_finish-pr/SKILL.md diff --git a/packages/core/src/skills/builtin/_ux_git-worktree/SKILL.md b/packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md similarity index 94% rename from packages/core/src/skills/builtin/_ux_git-worktree/SKILL.md rename to packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md index 4bc291cb74..b130da3e6b 100644 --- a/packages/core/src/skills/builtin/_ux_git-worktree/SKILL.md +++ b/packages/extensions/ux-toolkit/skills/_ux_git-worktree/SKILL.md @@ -29,7 +29,7 @@ When the user asks to "start a new task" or "create a branch": 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/core/src/skills/builtin/_ux_git-worktree/scripts/worktree-manager.sh pr 123`. +2. **ALWAYS** use the automation script: `./packages/extensions/ux-toolkit/skills/_ux_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`). diff --git a/packages/core/src/skills/builtin/_ux_git-worktree/references/architecture.md b/packages/extensions/ux-toolkit/skills/_ux_git-worktree/references/architecture.md similarity index 100% rename from packages/core/src/skills/builtin/_ux_git-worktree/references/architecture.md rename to packages/extensions/ux-toolkit/skills/_ux_git-worktree/references/architecture.md diff --git a/packages/core/src/skills/builtin/_ux_git-worktree/scripts/worktree-manager.sh b/packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh similarity index 100% rename from packages/core/src/skills/builtin/_ux_git-worktree/scripts/worktree-manager.sh rename to packages/extensions/ux-toolkit/skills/_ux_git-worktree/scripts/worktree-manager.sh diff --git a/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/SKILL.md b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/SKILL.md new file mode 100644 index 0000000000..90dced010f --- /dev/null +++ b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/SKILL.md @@ -0,0 +1,99 @@ +--- +name: _ux_string-reviewer +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). + +## 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}"` +``` \ No newline at end of file diff --git a/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/settings.md b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/settings.md new file mode 100644 index 0000000000..df054127a8 --- /dev/null +++ b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/settings.md @@ -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` diff --git a/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/word-list.md b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/word-list.md new file mode 100644 index 0000000000..1bb04b9817 --- /dev/null +++ b/packages/extensions/ux-toolkit/skills/_ux_string-reviewer/references/word-list.md @@ -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. diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh deleted file mode 100755 index ac1b7ea72a..0000000000 --- a/scripts/sync-skills.sh +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/bash -# sync-skills.sh - Syncs custom skills from the repo to the user's global ~/.gemini/skills folder. - -SKILLS_DIR="${HOME}/.gemini/skills" -COMMANDS_DIR="${HOME}/.gemini/commands" -REPO_SKILLS_PATH="packages/core/src/skills/builtin" - -mkdir -p "${SKILLS_DIR}" - -echo "Syncing skills..." - -# List of skills to sync -CUSTOM_SKILLS=("_ux_git-worktree" "_ux_finish-pr" "_ux_designer") - -for SKILL in "${CUSTOM_SKILLS[@]}"; do - if [[ -d "${REPO_SKILLS_PATH}/${SKILL}" ]]; then - # Sync Skill - cp -r "${REPO_SKILLS_PATH}/${SKILL}" "${SKILLS_DIR}/" - echo "βœ… Synced: ${SKILL}" - - # Clean up legacy explicit command files if they exist to prevent conflicts. - # Gemini CLI automatically registers a slash command for each skill based on its name. - COMMAND_FILE="${COMMANDS_DIR}/${SKILL}.toml" - if [[ -f "${COMMAND_FILE}" ]]; then - rm -f "${COMMAND_FILE}" - echo "🧹 Cleaned up redundant command file: ${COMMAND_FILE}" - fi - else - echo "❌ Error: Skill ${SKILL} not found in ${REPO_SKILLS_PATH}" - fi -done - -echo "Done. Run '/skills reload' in your Gemini session to apply changes." -echo "--------------------------------------------------" -echo "" -cat WELCOME.md