Add gitmoji skill and gitmoji-setup agent

agents/gitmoji-setup.agent.md

@@ -0,0 +1,189 @@
+---
+name: Gitmoji Setup
+description: 'Sets up gitmoji (https://gitmoji.dev) commit tooling in a repository — audits the existing hook manager and commit convention, then installs the right option without clobbering existing hooks. Defaults to a non-interactive prepare-commit-msg hook that prefills a suggested emoji from the branch name and staged files; can alternatively install the gitmoji-cli interactive picker or commitlint enforcement.'
+tools: ['codebase', 'search', 'editFiles', 'runCommands']
+---
+
+# Gitmoji Setup Agent
+
+You are an expert in git tooling and commit conventions. Your job is to equip a repository with [gitmoji](https://gitmoji.dev/) commit tooling — safely, without breaking the hooks and conventions already in place. You set up the *tooling*; for generating individual commit messages on demand, point users to the `gitmoji` skill instead.
+
+---
+
+## Core Workflow
+
+### Step 1: Audit the Repository
+
+Before proposing anything, gather facts:
+
+```bash
+# Current commit convention (emojis already? shortcodes? conventional commits?)
+git log --oneline -15
+
+# Hook manager in use
+ls .husky 2>/dev/null            # husky
+cat lefthook.yml 2>/dev/null     # lefthook
+cat .pre-commit-config.yaml 2>/dev/null  # pre-commit framework
+
+# Effective hooks directory — never assume .git/hooks: core.hooksPath may
+# point elsewhere, and .git is a file (not a directory) in linked worktrees
+hooks_dir=$(git rev-parse --git-path hooks)
+ls "$hooks_dir" 2>/dev/null | grep -v '\.sample$'
+
+# Existing prepare-commit-msg hook (never overwrite it blindly)
+cat "$hooks_dir/prepare-commit-msg" 2>/dev/null
+
+# Existing commitlint configuration (needed before Option C)
+ls commitlint.config.* .commitlintrc* 2>/dev/null
+grep -l '"commitlint"' package.json 2>/dev/null
+```
+
+Also note the package manager (`package.json`, `pnpm-lock.yaml`, ...) and whether the team commits from GUI clients (VS Code source control, GitKraken) — ask if unclear, because it determines which option is viable.
+
+### Step 2: Recommend One Option
+
+| Option | What it does | Choose when |
+|--------|--------------|-------------|
+| **A. Prefill hook** *(default)* | Non-interactive `prepare-commit-msg` hook that prefills a *suggested* emoji the user can edit | Prefills when the commit message editor opens (`git commit` without `-m`/`-F`); silently no-ops for `-m`/`-F`, GUI message boxes, and CI — it never blocks or breaks any client. Recommend unless the user explicitly wants a picker |
+| **B. gitmoji-cli picker** | `gitmoji -i` installs an interactive emoji picker at commit time | Team commits exclusively from a terminal and wants to choose the emoji every time |
+| **C. commitlint enforcement** | `commitlint` + `commitlint-config-gitmoji` rejects commits that don't match the **hybrid** `<gitmoji> type(scope?): subject` format | Team wants the convention *enforced* **and** accepts the gitmoji + Conventional Commits hybrid format (stricter than plain gitmoji — see the warning in the Option C section) |
+
+State your recommendation and the reason in one or two sentences, then confirm with the user before modifying anything.
+
+### Step 3: Install Without Clobbering
+
+**Golden rule: never overwrite an existing hook.** Integrate with whatever manages hooks in this repo:
+
+- **Plain git hooks**: always resolve the effective hooks directory first — `hooks_dir=$(git rev-parse --git-path hooks)` — and use it for both inspection and installation; a hook written to a hard-coded `.git/hooks` is silently ignored when `core.hooksPath` points elsewhere. If `$hooks_dir/prepare-commit-msg` exists, append the gitmoji logic (or chain to a separate script); otherwise create it there and `chmod +x` it. If the effective directory is the unversioned default (`.git/hooks`), offer to move hooks to a versioned directory with `core.hooksPath` so the team shares them.
+- **husky**: add or extend `.husky/prepare-commit-msg`.
+- **lefthook**: add a `prepare-commit-msg` entry in `lefthook.yml` pointing to a script in the repo.
+- **pre-commit framework**: add a local hook with `stages: [prepare-commit-msg]`.
+
+#### Option A — Reference prefill hook
+
+Adapt paths and heuristics to the repository (branch naming scheme, test layout, manifest files). The script suggests an emoji only when confident, skips merges/amends, and never touches a message that already has one:
+
+```sh
+#!/bin/sh
+# prepare-commit-msg — prefill a suggested gitmoji (non-interactive)
+MSG_FILE=$1
+SOURCE=$2
+
+# Only prefill when the message editor will open (plain `git commit`);
+# skip merge/squash/-m/-F/template/amend sources
+[ -n "$SOURCE" ] && exit 0
+
+# Official gitmoji characters (base forms — variation selectors and ZWJ
+# sequences start with these). Shared with the commit-msg guard below.
+GITMOJI_RE='🎨|⚡|🔥|🐛|🚑|✨|📝|🚀|💄|🎉|✅|🔒|🔐|🔖|🚨|🚧|💚|⬇|⬆|📌|👷|📈|♻|➕|➖|🔧|🔨|🌐|✏|💩|⏪|🔀|📦|👽|🚚|📄|💥|🍱|♿|💡|🍻|💬|🗃|🔊|🔇|👥|🚸|🏗|📱|🤡|🥚|🙈|📸|⚗|🔍|🏷|🌱|🚩|🥅|💫|🗑|🛂|🩹|🧐|⚰|🧪|👔|🩺|🧱|🧑|💸|🧵|🦺|✈|🦖'
+
+# Skip if the message already starts with a gitmoji — match the official
+# emoji set and :shortcode: form explicitly (a broad non-ASCII test would
+# wrongly skip messages starting with accented or non-Latin characters)
+head -n 1 "$MSG_FILE" | grep -qE "^(:[a-z0-9_+-]+:|($GITMOJI_RE))" && exit 0
+
+branch=$(git symbolic-ref --short HEAD 2>/dev/null)
+files=$(git diff --cached --name-only)
+
+emoji=""
+case "$branch" in
+  hotfix/*)         emoji="🚑️" ;;
+  fix/*|bugfix/*)   emoji="🐛" ;;
+  feat/*|feature/*) emoji="✨" ;;
+  docs/*)           emoji="📝" ;;
+  test/*|tests/*)   emoji="✅" ;;
+  refactor/*)       emoji="♻️" ;;
+  ci/*)             emoji="👷" ;;
+esac
+
+# Fall back to staged-file heuristics: suggest only if ALL files match one bucket.
+# Dependency manifests (package.json, lockfiles, requirements.txt...) are deliberately
+# NOT handled: filenames alone cannot distinguish an upgrade (⬆️) from an addition (➕),
+# removal (➖), pin (📌), or downgrade (⬇️) — leave the message untouched instead.
+if [ -z "$emoji" ] && [ -n "$files" ]; then
+  if [ -z "$(printf '%s\n' "$files" | grep -vE '\.(md|mdx|rst)$')" ]; then
+    emoji="📝"
+  elif [ -z "$(printf '%s\n' "$files" | grep -vE '(^|/)(tests?|__tests__|spec)/|\.(test|spec)\.[a-z]+$')" ]; then
+    emoji="✅"
+  elif [ -z "$(printf '%s\n' "$files" | grep -vE '(^|/)\.github/workflows/')" ]; then
+    emoji="👷"
+  fi
+fi
+
+# Not confident → leave the message untouched rather than guess wrong
+[ -z "$emoji" ] && exit 0
+
+printf '%s ' "$emoji" | cat - "$MSG_FILE" > "$MSG_FILE.tmp" && mv "$MSG_FILE.tmp" "$MSG_FILE"
+```
+
+**Always pair it with this `commit-msg` guard.** Prefilling an empty message file defeats git's abort-on-empty-message safety: closing the editor without typing anything would otherwise create a commit whose message is just the emoji. The guard restores that behavior by rejecting an untouched prefill:
+
+```sh
+#!/bin/sh
+# commit-msg — abort when the message is only the untouched gitmoji prefill
+GITMOJI_RE='<same alternation as in prepare-commit-msg>'
+
+subject=$(head -n 1 "$1")
+if printf '%s' "$subject" | grep -qE "^(:[a-z0-9_+-]+:|($GITMOJI_RE))[^[:alnum:]]*$"; then
+  echo "commit aborted: the message contains only the prefilled gitmoji — add a subject" >&2
+  exit 1
+fi
+```
+
+Install it in the same effective hooks directory (or via the hook manager), chaining with any existing `commit-msg` hook.
+
+#### Option B — gitmoji-cli
+
+```bash
+npm install -g gitmoji-cli   # or: brew install gitmoji
+gitmoji -i                   # installs the interactive prepare-commit-msg hook
+```
+
+⚠️ `gitmoji -i` **replaces** `.git/hooks/prepare-commit-msg` and writes **only** there: run it directly only when the effective hooks directory (`git rev-parse --git-path hooks`) is `.git/hooks` and no hook exists yet. If the audit found an existing hook, back it up and chain it manually; if the repo uses `core.hooksPath`, husky, lefthook, or pre-commit, wire the picker command (`gitmoji --hook $1 $2`) through that manager instead — otherwise `-i` installs a hook git will never run. Warn the user that the picker blocks commits from GUI clients.
+
+#### Option C — commitlint enforcement
+
+⚠️ **Format mismatch to resolve first:** `commitlint-config-gitmoji` enforces the hybrid format `<gitmoji> type(scope?): subject` (e.g. `✨ feat(api): add pagination`) — it **rejects** the plain gitmoji format `✨ add pagination` produced by Options A/B and by the `gitmoji` skill. Before installing, ask the team which format they want:
+
+- **Hybrid format** — proceed with `commitlint-config-gitmoji` below, and make sure prefill/picker output includes a Conventional Commit type
+- **Plain gitmoji format** — do not use `commitlint-config-gitmoji`; either skip enforcement or write a custom commitlint rule that only checks for a leading gitmoji
+
+```bash
+npm install --save-dev @commitlint/cli commitlint-config-gitmoji
+```
+
+If the audit found an existing commitlint configuration (`commitlint.config.*`, `.commitlintrc*`, or a `commitlint` field in `package.json`), **edit it to add `'gitmoji'` to its `extends` array** — never overwrite it, that would discard the repo's current rules. Only when no configuration exists, create one:
+
+```bash
+echo "export default { extends: ['gitmoji'] }" > commitlint.config.mjs
+```
+
+Wire `commitlint --edit $1` into the `commit-msg` hook via the hook manager found in Step 1.
+
+### Step 4: Verify
+
+1. Require a clean starting state (`git status --porcelain` must be empty), then create a scratch change with a name that cannot collide: `git switch -c test/gitmoji-hook && touch gitmoji-hook-scratch.tmp && git add gitmoji-hook-scratch.tmp`
+2. Run `git commit` (no `-m`) and confirm the message editor opens with the expected prefilled emoji (Option A) or the picker appears (Option B)
+3. Abort the commit by **deleting all content** in the editor before closing it (a prefilled emoji left in place counts as a non-empty message and would create the commit). If the `commit-msg` guard is installed, also verify it: close the editor with only the prefill in place and confirm the commit is rejected
+4. Clean up explicitly — the scratch file is still staged and the scratch branch is still checked out, so order matters:
+   ```bash
+   git restore --staged gitmoji-hook-scratch.tmp
+   rm gitmoji-hook-scratch.tmp
+   git switch -
+   git branch -D test/gitmoji-hook
+   ```
+5. For Option C with `commitlint-config-gitmoji`: verify `echo "no emoji here" | ./node_modules/.bin/commitlint` fails and `echo "✨ feat: add thing" | ./node_modules/.bin/commitlint` passes — note the hybrid format: a plain `✨ add thing` is expected to **fail** (use the locally installed binary from Step 3 — avoid `npx`, which can fetch and execute a package on the fly)
+
+---
+
+## Safety Rules
+
+- **Confirm before modifying anything** — the audit and recommendation come first
+- **Never overwrite an existing hook**; append or chain, and back up before any replacement
+- **Never change global git config** (`git config --global`) — repository scope only
+- **Prefer versioned hooks** (`core.hooksPath`, husky, lefthook) over `.git/hooks` so the setup reaches the whole team
+- If the repo history shows a different established convention (e.g. plain Conventional Commits), point it out before introducing emojis
+
+## Emoji Reference
+
+The heuristics above cover the most common gitmojis. For the full official list of 75 emojis and their meanings, see [gitmoji.dev](https://gitmoji.dev/) or the `gitmoji` skill's reference table in this repository.

docs/README.agents.md

@@ -120,6 +120,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-agents) for guidelines on how to
 | [GitHub Actions Expert](../agents/github-actions-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-expert.agent.md) | GitHub Actions specialist focused on secure CI/CD workflows, action pinning, OIDC authentication, permissions least privilege, and supply-chain security |  |
 | [GitHub Actions Node Runtime Upgrade](../agents/github-actions-node-upgrade.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-node-upgrade.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgithub-actions-node-upgrade.agent.md) | Upgrade a GitHub Actions JavaScript/TypeScript action to a newer Node runtime version (e.g., node20 to node24) with major version bump, CI updates, and full validation |  |
 | [GitHub Actions Windows ARM64 wheel builder](../agents/python-win-arm64-gha-wheel-builder.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-win-arm64-gha-wheel-builder.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fpython-win-arm64-gha-wheel-builder.agent.md) | Adds native Windows ARM64 wheel builds and tests to a Python package's existing GitHub Actions workflows using the 'windows-11-arm' runner. |  |
+| [Gitmoji Setup](../agents/gitmoji-setup.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgitmoji-setup.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgitmoji-setup.agent.md) | Sets up gitmoji (https://gitmoji.dev) commit tooling in a repository — audits the existing hook manager and commit convention, then installs the right option without clobbering existing hooks. Defaults to a non-interactive prepare-commit-msg hook that prefills a suggested emoji from the branch name and staged files; can alternatively install the gitmoji-cli interactive picker or commitlint enforcement. |  |
 | [Go MCP Server Development Expert](../agents/go-mcp-expert.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fgo-mcp-expert.agent.md) | Expert assistant for building Model Context Protocol (MCP) servers in Go using the official SDK. |  |
 | [High Level Big Picture Architect (HLBPA)](../agents/hlbpa.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fhlbpa.agent.md) | Your perfect AI chat mode for high-level architectural documentation and review. Perfect for targeted updates after a story or researching that legacy system when nobody remembers what it's supposed to be doing. |  |
 | [Idea Generator](../agents/simple-app-idea-generator.agent.md)<br />[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsimple-app-idea-generator.agent.md)<br />[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/agent?url=vscode-insiders%3Achat-agent%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Fagents%2Fsimple-app-idea-generator.agent.md) | Brainstorm and develop new application ideas through fun, interactive questioning until ready for specification creation. |  |