docs(spec): add English prompt construction specification (#5)

* docs(spec): add English prompt construction specification

- create prompt_construction_en.md with universal tool description pattern
- define three-part structure: function description, when to use, best practices
- provide detailed requirements, examples, and quality check standards
- include applicable formats in markdown, plain text, and JSON

* feat(prompts): standardize and enhance system prompts

- update generator prompt with usage, best practices, and format
- expand git_bot system prompt for comprehensive guidance
- rewrite git_edit and git_read prompts with clear usage and best practices
- list available operations explicitly in tool prompts

* docs: add extension development guide

- create EXTENSION_DEVELOPMENT_GUIDE.md with comprehensive instructions
- cover extension architecture, structure, feature integration, and examples
- include best practices, testing, and API reference for developers

* 修复和优化：更新多个 Git 相关扩展文件，提升功能稳定性和代码一致性

* 提交所有修改

* 修复和更新代码：提交所有当前更改

* fix(git): 修正 commit_message 字段描述文本截断问题

* refactor(gitcommit): 优化 slash_commands 相关实现

- 移除未使用的 Job 依赖
- 调整相关函数结构，提升可读性和维护性

* fix(git): 修复 cherry-pick 命令参数拼接方式

* refactor(git): 优化 push 参数处理逻辑

- 简化 force、remote、branch、tags、tag_name 参数插入流程
- 提高代码可读性和维护性

* docs(git): update push function docstring

- Remove 'asynchronously' from push function comment
- Clarify documentation for push operation

* fix(git_edit): 修正无提交信息时的提示文本

- 将提示内容从分析diff生成信息改为引导用户使用 @git_read diff --staged 工具查看变更并生成提交信息
- 优化了用户交互流程

* refactor(git_edit): 移除 rebase 相关代码和 schema 配置

- 删除 rebase 相关的 schema 字段和描述
- 移除 rebase 操作的实现逻辑
- 更新可用操作列表，去除 rebase

* docs(readme): add GEMINI.md with project overview and usage

- Introduce project features, installation, and usage instructions
- Document configuration options and safety features

Author: jinzhongjia

EXTENSION_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,73 @@
+# Project Overview: CodeCompanion Git Commit Extension
+
+This project is a CodeCompanion extension designed to generate AI-powered Git commit messages following the Conventional Commits specification. It integrates powerful Git tools for enhanced workflow.
+
+## Key Features:
+
+- **AI Commit Generation**: Generates Conventional Commits compliant messages using CodeCompanion's LLM adapters.
+- **Git Tool Integration**: Allows execution of Git operations via `@git_read` (read-only) and `@git_edit` (write) tools within chat.
+- **Multi-language Support**: Supports generating commit messages in multiple languages (e.g., English, Chinese).
+- **Smart Buffer Integration**: Auto-generates commit messages in gitcommit buffers.
+- **File Filtering**: Supports glob patterns to exclude generated files from analysis.
+- **Natural Language Interface**: Enables controlling Git workflows through conversational commands.
+
+## Installation:
+
+Add this extension to your CodeCompanion configuration in `init.lua` or similar:
+
+```lua
+require("codecompanion").setup({
+  extensions = {
+    gitcommit = {
+      callback = "codecompanion._extensions.gitcommit",
+      opts = {
+        adapter = "openai",
+        model = "gpt-4",
+        languages = { "English", "Chinese" },
+        exclude_files = { "*.pb.go", "*.min.js", "package-lock.json", "dist/*", "build/*", "node_modules/*" },
+        buffer = {
+          enabled = true,
+          keymap = "<leader>gc",
+          auto_generate = true,
+          auto_generate_delay = 100,
+        },
+        add_slash_command = true,
+        add_git_tool = true,
+        add_git_commands = true,
+      }
+    }
+  }
+})
+```
+
+## Usage:
+
+### Commands:
+
+- `:CodeCompanionGitCommit` or `:CCGitCommit`: Generate Git commit message.
+- `:CodeCompanionGit` or `:CCGit`: Open Git assistant chat.
+
+### Git Tool Operations in Chat:
+
+- **Read-only (`@git_read`)**: e.g., `@git_read status`, `@git_read log --count 5`
+- **Write (`@git_edit`)**: e.g., `@git_edit stage --files ["src/main.lua", "README.md"]`, `@git_edit create_branch --branch_name "feature/new-ui"`
+
+### Workflow Examples:
+
+- **Quick commit**: Check status, stage files, then generate commit message.
+- **Branch management**: List branches, create new branch, make changes, stage files, then generate commit message.
+
+## Configuration Options:
+
+Key configurable options include LLM adapter and model, supported languages, file exclusion patterns, buffer integration settings (enable, keymap, auto-generate), and toggles for slash commands, Git tools, and Git commands.
+
+## Safety Features:
+
+- Read-only operations (`@git_read`) require no confirmation.
+- Modifying operations (`@git_edit`) require user confirmation.
+- Repository validation ensures operations in valid Git repositories.
+- Comprehensive error handling.
+
+## License:
+
+MIT License

GEMINI.md

@@ -187,7 +187,7 @@ function Buffer._insert_commit_message(bufnr, message)
   -- Move cursor to the beginning of the commit message
   vim.api.nvim_win_set_cursor(0, { 1, 0 })
 
-  vim.notify("✅ Commit message generated and inserted!", vim.log.levels.INFO)
+  vim.notify("Commit message generated and inserted!", vim.log.levels.INFO)
 end
 
 ---Get current configuration

lua/codecompanion/_extensions/gitcommit/buffer.lua

@@ -7,7 +7,7 @@ local codecompanion_schema = require("codecompanion.schema")
 local Generator = {}
 
 --- @type string?
-local _adapater = nil
+local _adapter = nil
 --- @type string?
 local _model = nil
 
@@ -19,12 +19,12 @@ local CONSTANTS = {
 --- @param adapter string?  The adapter to use for generation
 --- @param model string? The model of the adapter to use for generation
 function Generator.setup(adapter, model)
-  _adapater = adapter or codecompanion_config.strategies.chat.adapter
+  _adapter = adapter or codecompanion_config.strategies.chat.adapter
   _model = model or codecompanion_config.strategies.chat.model
 
   -- Validate adapter
-  if not codecompanion_adapter.resolve(_adapater) then
-    error("Invalid adapter specified: " .. tostring(_adapater))
+  if not codecompanion_adapter.resolve(_adapter) then
+    error("Invalid adapter specified: " .. tostring(_adapter))
   end
 end
 
@@ -35,7 +35,7 @@ end
 ---@param callback fun(result: string|nil, error: string|nil) Callback function
 function Generator.generate_commit_message(diff, lang, callback)
   -- Setup adapter
-  local adapter = codecompanion_adapter.resolve(_adapater)
+  local adapter = codecompanion_adapter.resolve(_adapter)
   if not adapter then
     return callback(nil, "Failed to resolve adapter")
   end
@@ -73,32 +73,34 @@ end
 ---@return string prompt The formatted prompt
 function Generator._create_prompt(diff, lang)
   return string.format(
-    [[You are an expert at following the Conventional Commit specification.
+    [[Generate Conventional Commit compliant messages
 
-Please only return a commit message that strictly follows the Conventional Commit specification, without any additional text or explanations. The commit message should include:
+When to use:
+• When analyzing git diffs for commit messages
+• When standardizing commit format across projects  
+• When ensuring consistent commit message patterns
+• When generating structured commit documentation
 
-1. Type (required): lowercase, e.g., feat, fix, docs, style, refactor, perf, test, chore
-2. Scope (optional): in parentheses after type, e.g., feat(parser)
-3. Description (required): space after colon, start with verb, be concise
-4. Body (optional): use bullet points (-) to list specific changes
+Best practices:
+• Must include required type (feat, fix, docs, style, refactor, perf, test, chore)
+• Use lowercase for type, optional scope in parentheses
+• Start description with imperative verb, keep under 50 characters
+• Add body with bullet points for complex changes
+• Ensure language matches specification: %s
 
-Example format:
+Format: type(scope): description
 
-feat(scope): add new feature
+Example:
+feat(auth): add OAuth2 integration
 
-- implement X functionality
-- update Y module
-- add tests for Z
-
-Note: You need to answer in %s.
-
-Based on the git diff provided below, generate a standardized commit message.
+- implement Google OAuth provider
+- update user authentication flow
+- add integration tests
 
+Generate commit message for this diff:
 ```diff
 %s
-```
-
-]],
+```]],
     lang or "English",
     diff
   )
@@ -111,10 +113,15 @@ end
 ---@param callback fun(result: string|nil, error: string|nil) Callback function
 function Generator._handle_response(err, data, _adapter, callback)
   -- Handle request errors
-  if err and err.stderr ~= "{}" then
-    local error_msg = "Error generating commit message: " .. (err.stderr or "Unknown error")
+  if err then
+    local error_msg = "Error generating commit message: " .. (err.stderr or err.message or "Unknown error")
     return callback(nil, error_msg)
   end
+  
+  -- Check for empty or invalid data
+  if not data then
+    return callback(nil, "No response received from LLM")
+  end
 
   -- Process successful response
   if data then

lua/codecompanion/_extensions/gitcommit/generator.lua

@@ -1,7 +1,7 @@
 ---@class CodeCompanion.GitCommit.Git
 local Git = {}
 
--- 存储配置
+-- Store configuration
 local config = {}
 
 ---Setup Git module with configuration
@@ -201,7 +201,7 @@ function Git.get_contextual_diff()
     end
   end
 
-  -- 3. Fallback: If no staged changes and not amending, check for all local changes (working directory vs. HEAD)
+  -- Fallback: If no staged changes and not amending, check for all local changes (working directory vs. HEAD)
   local all_local_diff = vim.fn.system("git diff --no-ext-diff HEAD")
   if vim.v.shell_error == 0 and vim.trim(all_local_diff) ~= "" then
     local filtered_diff = Git._filter_diff(all_local_diff)
@@ -240,7 +240,7 @@ function Git.commit_changes(message)
     return false
   end
 
-  -- 直接通过 stdin 传递 commit message，无需临时文件
+  -- Pass commit message directly through stdin without temporary files
   local cmd
   if Git.is_amending() then
     cmd = "git commit --amend -F -"

lua/codecompanion/_extensions/gitcommit/git.lua

@@ -92,7 +92,19 @@ local function setup_tools(opts)
     chat_tools.groups = chat_tools.groups or {}
     chat_tools.groups["git_bot"] = {
       description = "A Git agent that can perform read and write operations.",
-      system_prompt = "You are a Git assistant. You have access to the `git_read` and `git_edit` tools to manage the git repository.",
+      system_prompt = [[Provide Git repository assistance and management
+
+When to use:
+• When users need comprehensive Git operations
+• When combining read and write Git operations
+• When providing guided Git workflow assistance
+• When troubleshooting Git repository issues
+
+Best practices:
+• Use git_read tool for repository analysis first
+• Ensure operations are safe before execution
+• Avoid destructive operations without user confirmation
+• Provide clear explanations for Git commands]],
       tools = {
         "git_read",
         "git_edit",
@@ -127,30 +139,44 @@ local function setup_slash_commands(opts)
   end
 
   local slash_commands = require("codecompanion.config").strategies.chat.slash_commands
-  local Job = require("plenary.job")
 
   local function get_commit_content(chat, choice)
-    Job:new({
-      command = "git",
+    local stdout = vim.uv.new_pipe(false)
+    local stderr = vim.uv.new_pipe(false)
+    local output = ""
+    local error_output = ""
+
+    local handle = vim.uv.spawn("git", {
       args = { "show", choice.hash },
-      on_exit = function(j, rv)
-        local content = table.concat(j:result(), "\n")
-        vim.schedule(function()
-          if rv ~= 0 or not content or content == "" then
-            chat:add_reference(
-              { role = "user", content = "Error: Failed to get commit content." },
-              "git",
-              "<git_error>"
-            )
-          else
-            chat:add_reference({
-              role = "user",
-              content = string.format("Selected commit (%s) full content:\n```\n%s\n```", choice.hash, content),
-            }, "git", "<git_commit>")
-          end
-        end)
-      end,
-    }):start()
+      stdio = { nil, stdout, stderr },
+    }, function(code, signal)
+      vim.schedule(function()
+        stdout:close()
+        stderr:close()
+        if code == 0 then
+          chat:add_reference({
+            role = "user",
+            content = string.format("Selected commit (%s) full content:\n```\n%s\n```", choice.hash, output),
+          }, "git", "<git_commit>")
+        else
+          chat:add_reference(
+            { role = "user", content = "Error: Failed to get commit content.\n" .. error_output },
+            "git",
+            "<git_error>"
+          )
+        end
+      end)
+    end)
+
+    vim.uv.read_start(stdout, function(err, data)
+      if err then return end
+      if data then output = output .. data end
+    end)
+
+    vim.uv.read_start(stderr, function(err, data)
+      if err then return end
+      if data then error_output = error_output .. data end
+    end)
   end
 
   local function select_commit(chat, items)
@@ -167,20 +193,22 @@ local function setup_slash_commands(opts)
   end
 
   local function get_commit_list(chat, opts)
-    Job:new({
-      command = "git",
+    local stdout = vim.uv.new_pipe(false)
+    local stderr = vim.uv.new_pipe(false)
+    local output = ""
+    local error_output = ""
+
+    local handle = vim.uv.spawn("git", {
       args = { "log", "--oneline", "-n", tostring(opts.gitcommit_select_count) },
-      on_exit = function(j, rv)
-        local output = j:result()
-        vim.schedule(function()
-          if rv ~= 0 then
-            return chat:add_reference({ role = "user", content = "Error: Failed to get git log" }, "git", "<git_error>")
-          end
-          if not output or #output == 0 then
-            return chat:add_reference({ role = "user", content = "No commits found." }, "git", "<git_error>")
-          end
+      stdio = { nil, stdout, stderr },
+    }, function(code, signal)
+      vim.schedule(function()
+        stdout:close()
+        stderr:close()
+        if code == 0 then
+          local lines = vim.split(output, "\n")
           local items = {}
-          for _, line in ipairs(output) do
+          for _, line in ipairs(lines) do
             local hash, msg = line:match("^(%w+)%s(.+)$")
             if hash and msg then
               table.insert(items, { label = hash .. " " .. msg, hash = hash })
@@ -190,9 +218,21 @@ local function setup_slash_commands(opts)
             return chat:add_reference({ role = "user", content = "No commits found." }, "git", "<git_error>")
           end
           select_commit(chat, items)
-        end)
-      end,
-    }):start()
+        else
+          chat:add_reference({ role = "user", content = "Error: Failed to get git log\n" .. error_output }, "git", "<git_error>")
+        end
+      end)
+    end)
+
+    vim.uv.read_start(stdout, function(err, data)
+      if err then return end
+      if data then output = output .. data end
+    end)
+
+    vim.uv.read_start(stderr, function(err, data)
+      if err then return end
+      if data then error_output = error_output .. data end
+    end)
   end
 
   slash_commands["gitcommit"] = {
@@ -396,6 +436,13 @@ return {
         local GitTool = require("codecompanion._extensions.gitcommit.tools.git").GitTool
         return GitTool.search_commits(pattern, count)
       end,
+
+      ---Merge a branch
+      ---@param branch string The branch to merge
+      merge = function(branch)
+        local GitTool = require("codecompanion._extensions.gitcommit.tools.git").GitTool
+        return GitTool.merge(branch)
+      end,
     },
   },
 }