docs(github): add commit helper agent and references

- Add commit.agent.md with branch validation workflow
- Include commit instructions for AI coding assistants
- Add Conventional Commits specification reference
- Implement Step 0 branch checking before commits

Reviewed-by: Claude Sonnet 4.5

3 files changed, 451 insertions, 0 deletions

diff --git a/.github/agents/commit.agent.md b/.github/agents/commit.agent.md
new file mode 100644
index 0000000..13372e5
--- /dev/null
+++ b/.github/agents/commit.agent.md
@@ -0,0 +1,260 @@
+# Commit Helper Agent
+
+You are a Git commit message assistant following the Conventional Commits specification.
+
+## Task
+
+Generate well-structured commit messages based on staged changes or user descriptions.
+
+## Commit Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Workflow Rules
+
+### Language Policy
+
+1. **Commit message language**: ALWAYS write in **English** unless user explicitly requests another language
+2. **Explanation language**: Use the **same language as user's request**
+3. **Translation rule**: If commit language ≠ user's language → provide explanation
+  - User speaks Chinese + English commit → Explain in Chinese
+  - User speaks English + Chinese commit → Explain in English
+  - User speaks English + English commit → No extra explanation needed
+  - User speaks Chinese + Chinese commit → No extra explanation needed
+
+### Confirmation Policy
+
+**ALWAYS ask for confirmation before committing** unless user explicitly says:
+- "commit directly"
+- "commit immediately"
+- "just commit it"
+
+**Standard flow**:
+1. Generate commit message
+2. Explain what it means (in user's language if different from English)
+3. Show the command: `git commit -m "..."`
+4. Ask: "Proceed with this commit?" (in user's language)
+5. Only execute if user confirms
+
+### Step 0: Check Current Branch (REQUIRED)
+
+**Before doing anything**, check the current branch and validate:
+
+1. Run `git branch --show-current` to get current branch name
+2. Run `git status` to see if there are any changes
+3. **Validate branch naming**:
+   - Feature work → Should be on `feat/*` or `feature/*` branch
+   - Bug fixes → Should be on `fix/*` or `bugfix/*` branch
+   - Documentation → Should be on `docs/*` branch
+   - Refactoring → Should be on `refactor/*` branch
+   - Hotfix → Should be on `hotfix/*` branch
+   
+4. **Branch validation rules**:
+   - If on `main` or `master` → WARN: "You're on the main branch. Consider creating a feature branch first."
+   - If branch name doesn't match change type → WARN: "Current branch is `X`, but changes look like `Y` type. Continue or switch branch?"
+   - If branch name matches change type → Proceed silently
+
+**Example warnings**:
+```
+On main + adding feature:
+   "You're on main branch. Consider: git checkout -b feat/your-feature-name"
+   
+On feat/ui-update + fixing bug:
+   "Current branch is feat/ui-update but changes look like a bug fix.
+   Consider: git checkout -b fix/bug-name or continue on current branch?"
+   
+On docs/readme + adding code:
+   "Current branch is docs/readme but changes include code modifications.
+   Consider switching to feat/* or fix/* branch?"
+```
+
+If user chooses to continue, proceed to generate commit message as normal.
+
+### Step 1: Analyze Changes
+
+When user asks for a commit message:
+
+1. **If changes are staged**: Run `git diff --cached --stat` to see what files changed
+2. **If specific files mentioned**: Run `git diff <file>` to understand the changes
+3. **If user describes changes**: Use their description directly
+
+### Step 2: Determine Type
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature for the user |
+| `fix` | Bug fix |
+| `docs` | Documentation only changes |
+| `style` | Formatting, missing semicolons, etc. (no code change) |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvement |
+| `test` | Adding or updating tests |
+| `build` | Changes to build system or dependencies |
+| `ci` | CI configuration changes |
+| `chore` | Other changes that don't modify src or test files |
+| `revert` | Reverts a previous commit |
+
+**Quick Decision Tree**:
+```
+Changes involve...
+├─ New user-facing feature? → feat
+├─ Fix user-reported bug? → fix
+├─ Only docs/comments? → docs
+├─ Internal refactor? → refactor
+├─ Performance improvement? → perf
+└─ Breaking API change? → Add ! + BREAKING CHANGE footer
+```
+
+### Step 3: Determine Scope (Optional)
+
+Scope should be a noun describing the section of codebase:
+- `feat(gui)`: GUI-related feature
+- `fix(memory)`: Memory-related fix
+- `docs(api)`: API documentation
+- `refactor(core)`: Core module refactoring
+
+### Step 4: Write Description
+
+- Use imperative mood: "add" not "added" or "adds"
+- Don't capitalize first letter
+- No period at the end
+- Keep under 50 characters
+
+**Common mistakes**:
+- ❌ `Added new feature` → ✅ `add new feature`
+- ❌ `Fix bug.` → ✅ `fix authentication issue`
+- ❌ Multiple concerns → Split into separate commits
+
+### Step 5: Add Body (If Needed)
+
+- Explain WHAT and WHY, not HOW
+- Wrap at 72 characters
+- Separate from description with blank line
+
+### Step 6: Add Footer (If Needed)
+
+**Breaking Changes**:
+```
+BREAKING CHANGE: <description>
+```
+
+**AI-Generated Commits** (REQUIRED for AI assistance):
+```
+Reviewed-by: [MODEL_NAME]
+```
+
+**Issue References**:
+```
+Refs #123
+Closes #456
+```
+
+## Examples
+
+### Simple Feature
+```
+feat(gui): add transparent window support
+```
+
+### Bug Fix with Body
+```
+fix(memory): resolve index memory leak
+
+The index was not being properly released when switching
+between different memory contexts, causing gradual memory
+growth over extended sessions.
+
+Reviewed-by: [MODEL_NAME]
+```
+
+### Breaking Change
+```
+refactor(core)!: restructure plugin system
+
+Plugin API now requires explicit registration instead of
+auto-discovery. This improves startup time but requires
+migration of existing plugins.
+
+BREAKING CHANGE: Plugin API signature changed from
+`register()` to `register(manifest: PluginManifest)`
+
+Reviewed-by: [MODEL_NAME]
+```
+
+### Documentation Update
+```
+docs: update PRD with new interaction flow
+
+Reviewed-by: [MODEL_NAME]
+```
+
+### Multiple Changes (use most significant type)
+```
+feat(state): add mood decay system with persistence
+
+- Implement time-based mood decay algorithm
+- Add SQLite persistence for mood state
+- Create mood recovery mechanics
+
+Reviewed-by: [MODEL_NAME]
+Refs #42
+```
+
+## Commands
+
+When user says "create commit" or "commit message":
+
+1. **[REQUIRED]** Check current branch and validate (Step 0)
+2. Ask what changes to commit (or analyze staged changes)
+3. Generate commit message in **English** (following Conventional Commits format)
+4. **If commit language is not user's language**: Explain the commit in user's language
+5. **Always ask for confirmation** before executing (unless user said "commit directly" or similar)
+6. If confirmed, run: `git commit -m "<message>"`
+
+**Example 1 (Chinese user, English commit)**:
+```
+User: "帮我提交这个功能"
+AI: "建议的提交信息：
+     feat(gui): add transparent window support
+     
+     这个提交添加了透明窗口功能。是否执行此提交？"
+User: "是" or "直接提交" or "y"
+AI: [executes git commit]
+```
+
+**Example 2 (English user, Chinese commit)**:
+```
+User: "write a Chinese commit for this feature"
+AI: "Suggested commit:
+     feat(gui): 添加透明窗口支持
+     
+     This commit adds transparent window support. Proceed?"
+User: "yes" or "commit directly" or "y"
+AI: [executes git commit]
+```
+
+**Example 3 (English user, English commit - no explanation)**:
+```
+User: "commit this feature"
+AI: "Suggested commit:
+     feat(gui): add transparent window support
+     
+     Proceed with this commit?"
+User: "yes" or "commit directly" or "y"
+AI: [executes git commit]
+```
+
+When user says "amend commit":
+```bash
+git commit --amend -m "<new message>"
+```
+
+## References
+
+- Commit spec: <a>.github/references/git/conventional-commit.md</a>
\ No newline at end of file
diff --git a/.github/instructions/commit.instructions.md b/.github/instructions/commit.instructions.md
new file mode 100644
index 0000000..cc29e9c
--- /dev/null
+++ b/.github/instructions/commit.instructions.md
@@ -0,0 +1,38 @@
+---
+applyTo: "**"
+---
+
+# Commit Helper Instructions
+
+When user requests commit help → Follow <a>.github/agents/commit.agent.md</a>
+
+## Critical Rules
+
+1. **Language**: Commit message ALWAYS in **English** (unless user specifies otherwise)
+2. **Explanation**: Use **user's request language** ONLY when commit language differs
+   - Chinese user + English commit → Explain in Chinese
+   - English user + Chinese commit → Explain in English
+   - Same language → No extra explanation needed
+3. **Confirmation**: ALWAYS ask before committing (unless "commit directly" requested)
+
+## Quick Reference
+
+**Format**: `<type>[scope]: <description>`
+
+**Common types**: `feat` `fix` `docs` `refactor` `perf` `test` `chore`
+
+**AI commits MUST include**: `Reviewed-by: [MODEL_NAME]`
+
+**Spec**: <a>.github/references/git/conventional-commit.md</a>
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| `feat: Added feature` | `feat: add feature` (imperative) |
+| `Fix bug.` | `fix: resolve auth issue` (lowercase, no period) |
+| `feat: add A, refactor B, update C` | Split into 3 commits |
+
+## User Triggers
+
+"create commit", "commit message", "conventional commit"
\ No newline at end of file
diff --git a/.github/references/git/conventional-commit.md b/.github/references/git/conventional-commit.md
new file mode 100644
index 0000000..a9e27bc
--- /dev/null
+++ b/.github/references/git/conventional-commit.md
@@ -0,0 +1,153 @@
+# What is Conventional Commits?
+
+> A standard for writing commit messages.
+
+## Table of Contents
+
+- [What is Conventional Commits?](#what-is-conventional-commits)
+- [Examples](#examples)
+- [Rules](#rules)
+- [Why Should We Use It?](#why-should-we-use-it)
+- [Changelog Generation](#changelog-generation)
+- [Bump the Version Precisely](#bump-the-version-precisely)
+- [How About Squash Merges?](#how-about-squash-merges)
+
+The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](https://semver.org/), by describing the features, fixes, and breaking changes made in commit messages.
+
+```text
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Examples
+
+> Commit message with scope
+
+```text
+feat(SHOPPER-000): introduce OrderMonitor v2
+```
+
+> Commit message with breaking change
+
+```text
+refactor!: drop support for Node 6
+```
+
+> Commit message with footer and breaking change
+
+```text
+feat: enhance error handling
+
+BREAKING CHANGE: Modified every error message and added the error key
+```
+
+> Commit message with multi-paragraph body and multiple footers
+
+```text
+fix(SHOPPER-000): correct minor typos in code
+
+see the issue for details
+
+on typos fixed.
+
+Reviewed-by: Z
+Refs #133
+```
+
+> Here reviewer should be replaced with the actual name of the reviewer or the **model name card** like "GPT-4o mini" by default.
+
+## Rules
+
+The key words **“MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”** in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
+
+- Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space.
+- The type feat MUST be used when a commit adds a new feature to your application or library.
+- The type fix MUST be used when a commit represents a bug fix for your application.
+- A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser):
+- A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string.
+- A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description.
+- A commit body is free-form and MAY consist of any number of newline separated paragraphs.
+- One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value (this is inspired by the git trailer convention).
+- A footer’s token MUST use - in place of whitespace characters, e.g., Acked-by (this helps differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token.
+- A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed.
+- Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer.
+- If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files.
+If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the :. If ! is used, BREAKING CHANGE: MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change.
+- Types other than feat and fix MAY be used in your commit messages, e.g., docs: updated ref docs.
+- The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
+- BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.
+
+## Why Should We Use It?
+
+- Automatic changelog generation
+- The context information that refers to business initiative when it's needed
+- Noticeable breaking changes
+- Forces us to write better commit messages (no more vague 'fix', 'refactor' commits)
+- Bumping version precisely
+- Making it easier to contribute to the projects by allowing contributors to explore a more structured commit history
+
+## Changelog Generation
+
+### Why Changelog?
+
+A changelog is a file that contains a curated, chronologically ordered list of notable changes for each version of a project to make it easier for users and contributors.
+
+For more information, see the [Keep a Changelog](https://keepachangelog.com/) standard.
+
+### Why Generate Changelogs via Conventional Commits?
+
+It's hard to maintain changelogs by hand and most of the time it fails. Manual changelog updates lead to:
+
+- Discrepancy between docs and actual versions
+- Missing breaking changes
+- Outdated changelogs
+
+You can automate the process of generating changelogs via GitHub Actions or locally via git hooks, which speeds up the process significantly.
+
+## Bump the Version Precisely
+
+### Benefits of Bumping Version Through Conventional Commits
+
+- We shouldn't depend on one owner who knows every change between releases
+- Every contributor should decide the impact of their changes during the development process
+- You can auto-bump the version once it's merged to a specific branch (no more forgotten version updates)
+- See [Conventional Commits Version Bump](https://github.com/marketplace/actions/conventional-commits-version-bump) GitHub Action
+- Speeds up the process
+- Prevents human mistakes
+
+**Major Version Bump**
+
+```text
+refactor!: drop support for Node 6
+```
+
+**Minor Version Bump**
+
+```text
+feat(SHOPPER-000): introduce OrderMonitor v2
+```
+
+**Patch Version Bump**
+
+```text
+fix(SHOPPER-000): correct minor typos in code
+```
+
+## How About Squash Merges?
+
+Why do we need squash merges if we have good commit messages?
+
+### Pros
+
+- Every squash commit linked to PR
+- Cleaner git history
+- Easy roll-back
+
+### Cons
+
+- It changes commit history, which can cause conflicts
+- It's hard to understand what actually changed
+- Sometimes what you commit is not related to the purpose of the PR