轻量 Git 工作流助手

职责

本 skill 只负责：

1. 将标准工作流模板写入或同步到目标仓库根目录 README.md 的托管区块。
2. 根据新需求生成候选 feature 分支名，确认分支名和基线后创建本地分支。
3. 只读查看当前 Git 工作流状态。
4. 只读检查当前 feature 的开发完成状态。

绝对边界

本 skill 不执行 commit、stash、rebase、merge、push、tag、发布、PR/MR 创建、分支删除、分支重命名、force push、reset 或丢弃工作区修改。

除以下两种动作外，所有流程必须保持只读：

• 用户明确要求同步工作流，查看 diff 并再次确认后，更新 README 托管区块。
• 用户明确要求创建 feature，确认分支名和基线后，创建本地 feature 分支。

遇到异常时只停止、报告和建议，不自动清理、覆盖或恢复 Git 状态。

激活门禁

只有明确的工作流操作指令才能激活本 skill。

以下表达只做讨论或解释，不修改文件或 Git 状态：

• “分析工作流”
• “看看分支策略”
• “为什么这样设计”
• “给个方案”
• “准备开发”
• “准备上线”

当用户要求执行超出本 skill 边界的 Git 操作时，说明本 skill 是轻量助手，不代替其他 Git 操作流程。

唯一规则源

• README 工作流的唯一模板是相对本文件的 templates/readme-git-workflow.md。
• 使用模板前必须完整读取该文件。
• skill 目录中既有的 README.md、workflows/、guides/、references/ 和 scripts/ 不参与运行时判断。
• 不得从旧文件复制 merge、push、release、hotfix、分支删除或历史重写命令。
• 不在 SKILL.md 内维护第二份 README 工作流正文。

README 同步流程

前置条件

只有在用户明确要求“写入”或“同步”Git 工作流时才能进入本流程。读取、比较和展示 diff 不等于获得最终写入确认。

目标文件固定为当前目标 Git 仓库根目录的 README.md，托管边界固定为：

<!-- GIT_WORKFLOW_START -->
<!-- 内容来自 templates/readme-git-workflow.md -->
<!-- GIT_WORKFLOW_END -->

模板文件本身包含完整的开始和结束标记。写入 README 时使用完整模板，不额外嵌套第二层标记。

检查步骤

1. 用 git rev-parse --show-toplevel 定位目标仓库根目录；失败时停止。
2. 完整读取 templates/readme-git-workflow.md。
3. 读取仓库根目录 README.md；文件不存在时记录为“待创建”，不立即写入。
4. 分别统计 GIT_WORKFLOW_START 和 GIT_WORKFLOW_END 标记数量。
5. 检查 README 托管区块之外是否已经存在非托管的“Git 工作流”标题。

按以下情况处理：

预览与确认

• README 不存在时，展示将创建的完整文件内容。
• 首次追加时，展示插入位置和完整模板；默认在既有 README 末尾保留一个空行后追加。
• 更新既有托管区块时，只展示该区块的差异。
• 模板与托管区块一致时，报告“Git 工作流已是最新”，不写文件。
• 存在变化时，必须再次获得用户明确确认后才能写入。

写入约束

• 使用文件编辑工具只创建 README、追加完整模板或替换完整托管区块。
• 不使用模糊标题匹配直接替换章节。
• 不自动修复残缺、重复或乱序的标记。
• 不格式化整个 README。
• 不修改托管区块之外的既有内容。
• 写入后重新读取 README，确认开始和结束标记各 1 个、顺序正确，并确认插入或替换范围之外的既有内容保持不变。

Feature 分支创建流程

激活和默认基线

只有用户明确要求开始某项新需求或创建 feature 分支时才能执行本流程。

• 默认候选基线：最新的 origin/main。
• 用户在最终确认时可以修改基线。
• 用户修改分支名或基线后，必须重新执行相关校验，不能复用旧结果。

候选分支名

生成规则：

• 固定使用 feature/ 前缀。
• 中文需求转换为简短、明确的英文语义名称。
• 英文描述转换为小写 kebab-case。
• 需求编号保留并转换为小写，例如 PROJ-123 转为 proj-123。
• 不使用中文、空格、下划线或其他非法 Git ref 字符。
• 候选名称只是建议，创建前必须允许用户编辑。

示例：

开发用户权限功能
-> feature/user-permission

PROJ-123 登录超时处理
-> feature/proj-123-login-timeout

最终名称必须通过以下检查，其中 $branchName 表示已经替换为实际候选值的 PowerShell 变量：

git check-ref-format --branch $branchName

创建前检查

依次执行并解释结果：

git rev-parse --show-toplevel
git status --porcelain=v2 --branch
git status --porcelain

• 不在 Git 仓库中时停止。
• git status --porcelain 有任何输出时，说明工作区、暂存区或未跟踪文件不干净，停止创建。
• 不自动 commit 或 stash。

检查是否存在进行中的 Git 操作：

$mergeHead = git rev-parse --git-path MERGE_HEAD
$cherryPickHead = git rev-parse --git-path CHERRY_PICK_HEAD
$rebaseMerge = git rev-parse --git-path rebase-merge
$rebaseApply = git rev-parse --git-path rebase-apply
Test-Path -LiteralPath $mergeHead
Test-Path -LiteralPath $cherryPickHead
Test-Path -LiteralPath $rebaseMerge
Test-Path -LiteralPath $rebaseApply

任一路径存在时停止并报告具体操作，不自动 abort。

当基线保持为默认值时，获取并验证最新 origin/main：

git fetch origin main
git rev-parse --verify 'origin/main^{commit}'
git log -1 --format='%h %s' origin/main

• fetch 只在用户已经明确要求创建 feature 后执行。
• origin、main 或访问权限不存在时停止并报告原始错误。
• 不使用本地 main 代替未验证的 origin/main。

如果用户改为其他远程基线，先 fetch 对应 remote 和 branch，再验证对应远程 ref；如果改为本地基线，只验证该 ref 能解析为 commit。所有基线都必须展示实际 SHA 和最近一条提交信息。

检查同名分支：

git show-ref --verify --quiet "refs/heads/$branchName"
git ls-remote --exit-code --heads origin "refs/heads/$branchName"

• 本地检查退出码为 0：本地同名分支存在，停止创建。
• 远程检查退出码为 0：远程同名分支存在，停止创建。
• 远程检查退出码为 2：没有匹配的远程分支，可以继续。
• 远程检查为其他退出码：按远程访问失败处理，停止创建。
• 不自动切换、删除、覆盖或重命名同名分支。

创建确认

执行创建前必须展示：

即将创建 feature 分支

需求：PROJ-123 登录超时处理
候选分支：feature/proj-123-login-timeout
基线：origin/main
基线提交：a1b2c3d fix(auth): 修复登录状态刷新
工作区：干净
进行中的 Git 操作：无
同名分支：本地无、远程无

等待用户确认，或者接受用户对候选分支名和基线的修改。修改后返回校验阶段。

创建分支

执行前把变量替换为已验证的实际值，不执行包含未解析占位符的命令。

默认基线：

git switch --no-track -c $branchName origin/main

用户修改后的基线：

git switch --no-track -c $branchName $baseRef

创建成功后只报告：

• 当前分支名；
• 基线 ref 和 SHA；
• 新分支尚未设置 upstream；
• 后续 push、commit、merge 或 PR/MR 不属于本 skill 的执行范围。

工作流状态检查

本流程完全只读，不自动 fetch。涉及远程分支的结论使用本地缓存 remote-tracking ref，并明确提示可能不是远程最新状态。

检查命令

git rev-parse --show-toplevel
git branch --show-current
git rev-parse --short HEAD
git log -1 --format='%h %s' HEAD
git status --porcelain=v2 --branch
git status --porcelain
git show-ref --verify --quiet refs/remotes/origin/main
git rev-list --left-right --count origin/main...HEAD
git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'

解释规则：

• git branch --show-current 无输出时表示 detached HEAD。
• git status --porcelain 无输出时表示工作区干净。
• 缓存中没有 origin/main 时，基线和领先/落后显示为“不可用”，不自动 fetch。
• git rev-list --left-right --count origin/main...HEAD 的第一个数字是当前分支落后 origin/main 的提交数，第二个数字是领先提交数。
• upstream 查询失败时显示“未设置”，不把它误报为仓库异常。
• 使用 Feature 创建流程中的路径检查方法识别 merge、rebase 和 cherry-pick。
• 当前分支是 feature 时，检查名称是否符合 feature/<kebab-case-description>，并检查缓存的 refs/remotes/origin/<当前分支> 是否存在。

输出格式

Git 工作流状态

当前分支：feature/proj-123-login-timeout
HEAD：a1b2c3d fix(auth): 修复登录状态刷新
工作区：干净
基线：origin/main @ d4e5f6a
相对基线：领先 3，落后 1
Upstream：未设置
分支命名：通过
进行中的 Git 操作：无
同名缓存远程分支：无
远程引用：使用本地缓存，可能不是远程最新状态

字段不可用或存在异常时保留该字段并说明原因，不静默省略。

Feature 开发完成检查

本流程完全只读，不自动 fetch。涉及 origin/main 的结论必须注明使用本地缓存 remote-tracking ref。

先执行“工作流状态检查”，然后执行：

git log --format='%h %s' origin/main..HEAD
git diff --name-status origin/main...HEAD
git rev-list --count origin/main..HEAD

阻断项

以下任一情况存在时，结论为“存在阻断项”：

• 工作区、暂存区或未跟踪文件不干净；
• 当前处于 detached HEAD；
• 正在进行 merge、rebase 或 cherry-pick；
• 缓存中没有 origin/main，或者无法计算共同基线；
• 当前分支不符合 feature/*。

警告项

• 当前 feature 落后缓存的 origin/main；
• feature 相对基线没有新增提交；
• 分支名称不符合规范；
• 没有设置 upstream；
• 仓库存在明确的提交规范，但 feature 范围内的提交信息不符合该规范。

提交规范处理规则：优先读取仓库已有的 commitlint、CONTRIBUTING 或明确文档；仓库没有明确规范时只列出提交信息，不自行发明规则或判为不合规。

未验证项

以下事项必须标记为“未验证”，不能根据本地 Git 状态推断完成：

• 需求是否完整实现；
• 测试是否通过；
• 是否完成代码审查；
• 是否允许推送；
• 是否允许创建或合并 PR/MR。

最终结论只能使用：

• “存在阻断项”；
• “无阻断项，但存在警告”；
• “本地 Git 检查无阻断项”。

不得输出“可以发布”“验证通过”或其他超出证据范围的结论。

异常处理

任何建议都必须与已经执行的动作分开表述，不能把建议伪装成已完成结果。

Windows PowerShell 兼容要求

• 默认按 Windows PowerShell 展示 shell 片段。
• 每条 Git 命令独立展示和执行。
• 不使用 /dev/null、Bash for ...; do、Bash 数组或 Bash 条件表达式。
• 不使用 && 或 || 串联带状态修改的命令。
• 路径存在性检查使用 Test-Path -LiteralPath。
• Git ref 中包含 @{upstream} 或 ^{commit} 时使用单引号，避免 PowerShell 解析。
• 文件编辑使用精确路径和托管边界，不运行全文件格式化命令。