git-flow

开发分支生命周期管理

目标

当用户在一个配置了 .dev-flow.yml 的项目中开发新功能时，使用本 skill 管理 feature 分支的完整生命周期：创建分支、按实施步骤提交代码、推送远程、合并到测试分支，并在合并冲突时提供分类报告和解决建议。

V1 只管理单 feature 分支。即使 dev-spec 产出多个 implementation step，也在同一个 feat/{developer}/{feature} 分支内顺序提交。step branch 和 worktree 留作 V2，不在本 skill 中自动创建。

使用场景

当用户说出类似需求时触发：

• "拉一个新分支开发 xxx 功能"
• "创建 feature 分支"
• "提交代码"
• "推送到远程"
• "合并到测试分支"
• "把代码合到 test"

前置条件

项目根目录存在 .dev-flow.yml 配置文件，至少包含以下字段：

project:
  name: my-app
developers:
  zx: { name: your-name }
branching:
  production: master

完整配置参见 examples/dev-flow.example.yml。

阶段设计

本 skill 分为 5 个阶段，每个阶段可独立触发，也可通过编排器串联执行。

Phase 1: init — 创建 feature 分支

前置条件：

• 当前在项目仓库根目录
• .dev-flow.yml 存在且 branching 配置合法
• 工作区干净（无未提交变更）

执行流程：

1. 读取 .dev-flow.yml 的 branching.production 字段
2. git fetch origin
3. git checkout {production} && git pull origin {production}
4. 根据 branching.pattern 构造分支名
   • {developer} 从参数或活动状态文件获取
   • {feature} 从 spec slug 获取，或由用户指定
5. git checkout -b {branch-name}
6. 解析运行时状态路径：per-feature 模式（默认）下状态文件写到 .dev-flow/states/<feature>.json 并把活动指针 .dev-flow/active 指向该 feature；single 模式或显式 --state 覆盖时维持原行为
7. 更新状态文件：phase=branched，记录 branch、developer、feature 和 history 事件

输出：分支名

异常处理：

• 工作区有未提交变更 → 提示用户先 stash 或 commit
• 远程已存在同名分支 → 提示用户确认是续开发还是重新开始

命令：

bash scripts/init-branch.sh --developer zx --feature user-points

如只想执行 Git 操作、不写运行时状态，可追加 --no-state。

Phase 2: commit — 提交变更

前置条件：

• 当前在 feature 分支上
• 有已暂存或未暂存的变更
• 如果 .dev-flow-state.json 存在 implementation.current-step，提交内容应只覆盖当前 step 的合理范围

执行流程：

1. git status 查看变更范围
2. 检查是否包含敏感文件（.env、credentials、*secret*、*key*、*password*）→ 阻断并警告
3. 如果存在当前 step，核对改动是否与 step 的 suggested-scope 和 acceptance 一致
4. 如果有 lint/test 配置，运行与当前 step 相关的检查
5. git add {具体文件}（不用 git add -A）
6. git commit -m "{message}"
7. 将 commit hash、message、文件列表和 step id 追加到 .dev-flow-state.json
8. 输出 commit hash 和 summary

异常处理：

• 包含敏感文件 → 阻断并警告，列出被拦截的文件
• commit hook 失败 → 不用 --no-verify，修复后重新 commit
• 改动明显跨越后续 step → 暂停并让用户确认是否扩大当前 step 范围