Developer

Developer —— Plan 驱动的开发执行入口

> 框架不可变铁律（复用自 [AGENTS.md](../../AGENTS.md) 第 7 条） > 本 SKILL.md 及其 scripts/ / references/ / tests/ 等框架文件在"使用本 skill"过程中只读。 > 发现 bug 必须立刻停下，向用户报告，由用户决定是否开新会话修。

> Developer Git 安全铁律 > Developer 全流程禁止执行或生成自动执行的 git push 命令。 > Developer 全流程禁止自动 merge dev / master / main 分支：既不能把这些分支作为 merge 源，也不能切到这些分支作为 merge 目标后自动合入。 > 分支流转只允许在需求总分支与任务分支之间进行；涉及 dev / master / main 的合入、发布、推送必须停止并交给用户人工处理。

> AIWeave 整合附加（仅 Go 项目，叠加不替换） > > 任务入场前（在原有"读 plan / 检查分支 / 创建笔记目录"之后），按顺序执行： > 1. 读 plan_ir.aiweave_skill；有则读 runtime ~/.nexus-harness/aiweave/vendor/aiweave/templates/skills//SKILL.md 当执行指南（只读 runtime，不复制到业务源码外）。 > 2. 读 /docs/BUILD_STATUS.md 中本任务对应模块状态：🚫 拒绝阻塞 / 🟢 提示已实现要求确认 / ⬜ 继续。 > 3. 按 task_context.aiweave.docs_quick_index 直查 docs，禁止"先 Explore 项目结构再写测试"： > - docs_quick_index[] 已对每个 aiweave_docs_refs 解析出 path / anchor / abs_path / exists / byte_size / headings(level/title/line)。 > - 必须先据此判断每个 doc 是否值得 Read：exists=false → 立刻停下提示用户回 plan-from-trd 修；exists=true 时按 headings 命中本任务关键词的章节按行号 Read（只读相关章节，避免整篇吞）。 > - 若 byte_size - 命中后把 docs 中具体的 DDL 字段名 / 函数签名 / 错误码常量 / Redis Key 模板 / 接口路径**记到任务笔记**，RED/GREEN 直接复用这些常量，禁止重新发明命名。 > - **违反将被 preventexploreduringred.py 拦截**（任何派 Explore / general / search 子 agent，或单 turn Read/Grep/Glob 累计 > 8 次但仍未调 recorddocsread.py record），弹出三选一菜单： > - 场景 A（docs 够用，AI 自作主张）：[1] ✅ 按文档继续写测试 / [2] 接受风险翻代码（写笔记 reviewer 审） > - 场景 B（docs 章节缺失）：[1] ✅ 严格按 AIWeave 模板补 docs 再写测试（多花 1-3 分钟，docs 进 git，下个同模块任务直接读 docs 就快了） / [2] 凑合用现有内容写测试 / [3] 接受风险翻代码 > - 场景 C（docs 章节过薄）：[1] ✅ 严格按 AIWeave 模板填实薄章节再写测试 / [2] 接受风险翻代码 > 默认全部为 [1]（回车默认）。详见 scripts/preventexploreduringred.py。 > - 选择 [1] "补 docs" 时调用 skills/aiweave-bridge/scripts/rebuildtaskdocs.py，输出受 vendor 严格约束的 next_action 指令包；主 AI **必须**按指令包 step_order 执行（vendor SKILL 整段 Read → assert_write_target → lint_aiweave_invariants → vendor /doc-sync-check → record_docs_read 反向 grep）。**不得**新增 vendor 模板未列字段、不得改字段顺序、不得套其他 skill 模板；vendor 字段在代码里找不到对应实现 → 登记 vendortemplatemismatch 到任务 notes，docs 顶部插 。 > 4. 仅当 docsquickindex 全部缺失或不存在（如非 Go 项目、aiweave_status=non_go）时，才允许退化为传统 Explore 项目结构方式。 > > **RED**（先 docs 后写测试）： > 1. 已读完 docs_quick_index 命中章节后，按 tasksection.redtests 4 类用例（**正向 / 参数校验 / 业务错 / 副作用**）逐条设计： > - 业务错类 → 红灯断言必须使用 docs/architecture/statuscodes.md（或同等错误码文档）里的具体常量名 / errNo 数值。 > - 参数校验类 → 字段名、必填性、类型约束以 docs/api/.md 接口契约为准。 > - 副作用类 → 缓存 Key/TTL 取自 docs/cache/.md；DDL 字段、分库分表规则取自 docs/schema/.md。 > - 正向类 → 主流程契约取自 docs/api/.md + 路由注册模式取自 docs/architecture/routing.md（或同等架构文档）。 > 2. 4 类任一缺失视为 RED 不达标；测试用例命名引用 docs 章节中的字段/常量名，让 reviewer 四角对照能机械核对。 > > **GREEN**：实现严格对齐 docs（伪代码 / 签名 / DDL / Key 模板 / 错误码常量），命名复用 docs 中的常量；**禁止**为同一字段/错误另起新名。可选 useaiweaveskillskeleton=true（plan 元数据），开则按 vendor /new-service 等生成骨架再补业务实现。 > > **GREEN 反 Explore 闸门**：实现代码时**必须**复用 RED 阶段记到任务笔记的字段名 / 常量 / Redis Key / 错误码；需要参考现有同类实现 → 直接看 taskcontext.aiweave.relatedcodeexcerpts。**不允许**派 Explore / general / search 子 agent 翻业务源码（典型反例：「先查项目里 DB/Redis 使用模式」），违反将被 python3 skills/developer/scripts/preventexploreduringtdd.py --phase green 拦截。 > > 闸门弹出**双选项菜单**（RED / GREEN 完全一致）： > - [1] ✅ 继续——AI 看 TRD + related_code_excerpts，不够时自由 Explore；docs 留给 finish-project 统一回写（推荐，回车默认） > - [2] 暂停——回 TRD 重新 build（适合整个 docs 体系都没建好的紧急情况） > > **铁律：developer 全阶段（RED / GREEN / REFACTOR / repair）零 docs 写盘**。AIWeave docs 回写只在两个时机：① TRD 阶段首次 bootstrap；② finish-project 统一 sync-feature-to-docs。rebuildtaskdocs.py 仅供 finish-project 调用（CLI 强制 --called-from finish-project），developer 阶段误用直接报错。 > **Gate A TRD 回退**：当 aiweavedocsrefs[i] 命中 context.json.docsincrementplan（例如新接口 docs 章节留待 finish-project 同步），或兼容旧数据中 ref 备注含「待开发 / 占位」时，recorddocsread.py 自动回退到 TRD 做 key_tokens 反向 grep；evidence JSON 标 evidencesource=trdfallback；token 在 TRD 也找不到才真正拒绝（保留反虚填）。 > > **REFACTOR**：保持原 RED→GREEN 测试不变；如重构暴露 docs 与代码的偏差，记入 TASKDEVNOTES.md 由 finish 阶段统一同步 docs，不要在重构里顺手改 docs。 > > 任务**收尾**： > - buildstatusmodulepath 对应模块**不在 developer 阶段翻状态**；docs/BUILDSTATUS.md 的新增行与 ⬜→🟢 翻转全部收归 finish-project 的 sync-feature-to-docs（Gate F 规定 developer 全程不写 docs/；Gate B 已降级为只读 🚫 冲突检查）。 > - 可选 developer.pertaskaiweavesync=true（plan_ir 顶层）：开则每任务跑 vendor /sync-feature-to-docs（仅本任务 diff，写盘到 /docs/）。**默认关闭**：避免早期任务 docs 改写被后续覆盖；TRD 已预登记 docsincrementplan，最终 build 在 finish 一次性 sync 更适合 PR review。 > > 人工 Review 通过后展示「可选 AI sub-agent 评审」菜单（**默认推荐 [2] 但不自动选**）： > ` > ✅ 人工 Review 已通过。是否额外派发「AIWeave 四角对照」AI 审查？ > > [1] 跳过，直接进入下一任务 > [2] 派发 developer-reviewer（独立上下文 · 增量审查 · ~30s） > > 为什么推荐 [2]： > - 独立上下文：subagent 不会被你和主 Agent 的对话偏好"污染"，能查出主 Agent 自己看不见的盲区 > - 四角同步交叉验证（人工 review 通常只看 1~2 角）： > ① 代码 ↔ TRD 字段/签名一致 > ② TRD ↔ PRD 需求覆盖 > ③ 代码 ↔ docs/ 蓝图（伪代码 / DDL / Redis Key） > ④ 代码 ↔ AIWeave 纪律（BUILD_STATUS 无 🚫 冲突 / INDEX 完整 / 4 类测试齐 / 未写 docs/） > - 增量输入：只读本任务 git diff + 相关 docs/ 章节，token 成本低、速度快 > - 输出 dev_review_report.json，问题点直接定位到行号 / docs 章节 > ` > sub-agent 输入严格按增量原则：git diff + devnotes 路径 + aiweavedocsrefs 章节锚点 + lintaiweaveinvariants 报告，**不传**完整 PRD/TRD/Plan。 > > 非 Go 项目（go.mod` 不存在）跳过以上全部附加步骤，按原 developer 流程执行。

使命

developer 是开发阶段的控制台。它从 workspace/**/plans/**/STATUS.md 找到可开发任务，把代码写入 context.json.code_project_path 指向的业务仓库，并把进度、TDD 审计和 Review gate 状态记录回 nexus-harness 的 Plan 目录。

Developer 是状态机，不是一次性提示词。用户新开会话并选择「继续开发」时，不要求用户手写项目提示词；必须从 context.json、STATUS.md、当前任务文件和 TRD/PRD 自动恢复当前项目、当前任务、当前分支与下一步动作。

事实源优先级：

1. STATUS.md：当前任务、任务状态、TDD audit、用户 Review gate
2. 任务文件：当前任务的 RED/GREEN/REFACTOR 与文件落点
3. context.json：业务代码仓库、PRD、TRD、AI 知识库路径
4. TRD / PRD / KB：约束与来源

---

标准工作流

输出与停顿规则

任何需要用户继续输入的地方，必须把“下一步”放在最后，并给出明确选项；禁止把下一步埋在长段说明末尾，禁止只说“需要的话再说一声/回复继续”。

统一格式：

下一步：

请选择：
1. 
2. 
3. 

如果只有两种选择，也必须明确写出可回复内容，例如：回复「开始」或「取消」。

严禁以下弱引导：

• “需要我继续时回复继续”
• “需要我直接帮你写 GREEN 时回复继续 GREEN”
• “如需我处理再说一声”
• “要我在本会话继续 REFACTOR / 准备派发吗”
• “可选小整理后再派发”
• 只给一个自然语言口令、不给编号选项

Developer 因任何原因停下等待用户输入时，末尾必须给编号选项；优先使用 1/2/3，不要让用户猜该回复什么。

阶段汇报必须短。只要刚刚改了代码或测试代码，必须先用固定表格说明改动摘要，再接验证结论与“下一步”格式；不要输出依赖安装细节、完整失败日志或长段解释，除非用户明确要求。

改动摘要固定格式：

| 动作 | 说明 |
|---|---|
| 新增/修改/删除/依赖 |  —  |

表格规则：

• 只列本阶段关键改动，通常 3-6 行；不要展开完整 diff。
• 路径必须用相对业务仓库路径。
• “说明”只写当前阶段为什么改，禁止长句堆细节。
• 依赖项只有确实新增/调整依赖时才列；不要把测试命令输出当依赖项。

表格后只保留：

• 当前阶段是否完成
• 最关键验证结果（1-2 行）
• 下一步编号选项或自动进入下一阶段的动作
• 内部动作（dispatch_reviewer.py、Subagent prompt、revieweroutputpath、reviewer-report-path、回流命令、schema 路径）禁止作为“下一步”交给用户执行；这些必须由 Developer 主 Agent 自动执行。只有工具不可用或报告未落盘时，才向用户暴露阻塞选项。

验证结果规则：

• PASS（含 Skip） 不等于稳定 GREEN；如果关键断言被 Skip，必须写成“未完成 GREEN / 等待有效验证”，不得标记 GREEN 完成。
• 涉及 DB/ES/Redis/API 时，测试可使用 mock/fake/httptest/testcontainers/最小集成测试；真实连接配置由用户联调期处理，不作为 Developer Gate。
• 禁止输出“当前库无表所以 Skip，避免误报红”作为 GREEN 通过理由。

Step 1 · 发现开发项目

Step 1.0 · 智能恢复接管（强制）

用户表达出“继续刚才 / 继续开发 / 接着来 / 恢复项目 / 从上次中断处继续 / 继续 Txx / 刚才卡住了接着跑 / 重开后继续 / resume / continue”等语义时，即使命令中没有精确出现“继续”二字，也必须先走 Developer 恢复协议。

入口强制规则：

• 命中恢复语义时，禁止宿主 Agent 凭记忆、当前打开文件或当前代码 diff 直接继续写代码。
• 必须先运行 discover_tasks.py 找到 active 项目；若只有一个 active 项目，可直接进入恢复检查；多个 active 项目时先让用户选项目。
• 选定 plan_dir 后，必须运行：

python3 skills/developer/scripts/resume_session.py \
  --plan-dir 

• 恢复脚本成功后，Developer 必须按返回的 derived.next_required_action 继续；不得自行改判阶段。
• 恢复脚本返回 blockers 时，必须停止，让用户处理分支/证据不一致；禁止写代码。
• 没有 active session 时，回到 Step 1 / Step 2 的正常项目选择流程，不允许自由接管。

恢复意图识别示例（不限于这些词）：

• “继续”“接着”“恢复”“刚才卡住了”“从中断处来”“继续上次”“继续 T01/T04”
• “网络断了，接着跑”“任务停了，继续”“resume/continue”
• “我处理好了，往下走”“按刚才的进度继续”

恢复输出固定格式：

已恢复 Developer 会话：

任务：
阶段：
依据：
下一步：

请选择：
1. 继续
2. 查看恢复依据
3. 暂停

只有用户选择 1 后，才继续执行恢复出的下一步动作。选择 2 时展示 session / TDD_EVIDENCE / STATUS 的简要依据；选择 3 停止。

Developer session 文件固定为 /DEVELOPER_SESSION.json。developer_tdd_gate.py 每次 enter_* / verify_* 成功后会自动更新该文件；不得手写替代。 用户确认任务 completed 后，update_status.py --state completed 会把当前 session 标记为 inactive；进入下一任务时由新的 TDD gate 重新激活 session。

准备继续推进或准备输出最终回复前，优先运行统一执行入口：

python3 skills/developer/scripts/developer_autopilot.py \
  --plan-dir  \
  --task-id 

developer_autopilot.py 会先调用 developer_flow_guard.py，再通过 developer_step_runner.py 自动执行纯 gate 跳转（如 enter_green、enter_refactor、enter_review），最后只返回三类协议：result_type=agent_work_required、result_type=must_call_tool、result_type=can_stop。

主 Agent 必须按下面的循环执行，禁止改写成“回复继续 / 请贴 plan_dir / 请你执行 gate 命令”：

while autopilot.result_type != "can_stop":
  if autopilot.result_type == "agent_work_required":
    执行 autopilot.next_agent_action
  if autopilot.result_type == "must_call_tool":
    调用 autopilot.must_call_tool 指定工具
  完成后立刻执行 autopilot.after_completion.command

只有 autopilot 返回 result_type=can_stop、loop_required=false 且提供 message_template 时，才允许准备最终回复，并仍需通过 developer_response_gate.py。若返回 loop_required=true 或 after_completion.required=true，必须继续循环，不得输出用户菜单。

入口层已传入 plan_dir 时（即用户已在入口层通过 discover_workspace_stage.py 结果选定项目并通过 transition_confirmation），直接跳到 Step 2，不运行 discover_tasks.py，不展示项目列表。只有当 plan_dir 未知、或用户直接进入 developer 而未经入口层选择时，才执行以下发现流程。

运行：

python3 skills/developer/scripts/discover_tasks.py

返回 JSON 后，优先使用脚本返回的 presentation.projects_user_message，不要自行拼接项目进度或内部路由说明。presentation.projects_user_message 是 Markdown 正文，必须直接输出，禁止包进 ``text / ``markdown / 引用块，避免表格无法渲染。

• 如果 active_projects=1，直接展示 presentation.projects_user_message 中的当前任务确认文案，等待用户回复「是」或「否」；不要再让用户先回复项目编号。
• 如果 active_projects>1，只展示 presentation.projects_user_message 项目列表，等待用户回复编号；不要直接展开 Txx 任务。

如果用户说「继续开发」，也走本步骤：先扫描状态，再让用户选项目；禁止要求用户粘贴旧提示词。

如果 discover_tasks.py 返回 active_projects=0，不要直接判定“没有进行中项目”。必须继续运行：

python3 scripts/discover_workspace_stage.py

然后按返回的 projects[] 做上游阶段转交：

• stage=plan_required：说明项目已有 TRD 但还没生成 Plan。若项目含 transition_confirmation.required=true，先逐字展示 transition_confirmation.user_message 等用户选 1；用户确认后再读取 skills/plan-from-trd/SKILL.md，并把该项目 context_path 作为 project_context_path 进入 Plan 生成流程。
• stage=trd_required：说明项目已有 PRD 但还没生成 TRD。若项目含 transition_confirmation.required=true，先逐字展示 transition_confirmation.user_message 等用户选 1；用户确认后再读取 skills/prd-to-trd/SKILL.md，按该 skill 接管。
• stage=development_ready：说明 Plan 存在但 discover_tasks.py 没识别出 active 任务；展示该 plan_dir/status_dirs 的异常摘要，停止让用户确认是否修复 STATUS。
• 多个可继续项目时，只展示 scripts/discover_workspace_stage.py 返回的 presentation.user_message 原文让用户选一个；选中后若含 transition_confirmation，必须先展示阶段切换确认，不能直接进入下游。必须直接按 Markdown 输出，禁止包代码块。禁止追加“运行脚本 / 已识别到 / 进入对应流程 / 正在运行 / 选定后我会 / 加载某 skill / 把 context_path 设为...”等内部动作说明。用户只需要知道现在有哪些项目、回复哪个编号。
• 没有可继续项目时，才按“无可开发项目”停下，并提示先走 project-start 或提供已有 TRD/PRD 路径。

展示格式（仅当脚本缺少 presentation.projects_user_message 时才使用）：

请选择要进入开发的项目：

1.  /  / 
   进度：
2. ...

回复编号。

不要展示脚本校验过程、JSON 路径、字段完整性等测试信息；正式使用时只给项目列表。

禁止绕过 STATUS.md 直接凭记忆选择任务。

Step 2 · 展示选中项目进度与下一步

用户选择项目后，优先展示所选 projects[] 条目里的 presentation.task_confirmation_message 原文；不要再重复展示项目总进度、任务总数、已完成数、业务仓库路径、任务分支等细节。那些信息属于内部恢复/分支 gate 输入，不是这一屏要用户理解的内容。

如果脚本缺少 presentation.task_confirmation_message，再从同一份 JSON 的 tasks[] 中筛选该 plan_dir 下的任务，按极简格式展示：

展示格式：

 /  / 
当前任务： · 

是否开始？回复「是」或「否」。

这次确认是必要 gate：选择项目只代表进入哪个开发上下文，回复「是」才代表开始当前任务并允许进入业务仓库检查分支。

> 首进（首次开发）场景兜底：即使从 plan-from-trd 完成后直接选「开始开发」，也必须经过 Step 3 的分支门禁，绝不能直接读 STATUS.md 写业务代码。developer_step_runner 在执行 enter_red 之前会自动调用 branch_guard（required_action=branch_guard_initial），非 ready/resume_task 时脚本会停下展示创建分支菜单；Agent 在用户选 1 完成分支操作并再次调用 developer_autopilot.py 后，才能进入 RED。

Step 3 · 开发分支 Gate

用户回复「是」后，先做只读分支检查：

python3 skills/developer/scripts/branch_guard.py \
  --context-path  \
  --plan-dir  \
  --task-id  \
  --branch-slug 

规则：

• context.json 必须记录 code_integration_branch、code_branch 和 code_base_branch；没有则视为“从未开发过”。
• Go 项目默认基于 master；PHP 项目基于 docker；其他所有项目默认基于 master（用户可显式覆盖）。
• 如果本地 master / docker 落后 origin/，先提示用户手动更新，不创建分支。
• Developer 禁止生成或执行 git push；禁止自动 merge dev / master / main，也禁止把任务分支自动合入这些受保护分支。
• 如果业务仓库有未提交改动，先停下让用户处理。
• 分支采用两层：需求总分支 feature/，任务分支 feature/-t01。
• code_integration_branch 表示需求总分支，跨 Txx 稳定不变；code_branch 表示当前任务分支，进入 T02/T03 时必须更新为对应任务分支。
• 进入新任务前，目标分支必须按当前 task_id 重新计算；禁止因为 context.json.code_branch 仍是 T01，就在 T01 分支继续开发 T02。
• 分支名由系统生成，短、英文、易读；禁止汉字和长日期串。优先使用 context.json 中的 branch_slug / demand_slug / feature_slug；没有时从需求目录名里提取已有英文 token，仍提取不到则退回项目名。
• git 写操作必须有用户明确确认；若宿主或用户规则禁止 git 写操作，只展示 create_branch_commands，等用户手动执行。

Slug 生成规则：

• 在运行 branch_guard.py 前，若 context.json 没有 branch_slug，Developer 主 Agent 必须基于需求名、TRD 标题和项目语义生成一个短 slug。
• slug 必须是 1-4 个小写 ASCII token，用 - 连接；禁止中文、日期、项目名堆砌、任务号、长句。
• 生成方式由主 Agent 语义判断，不允许在脚本或 skill 中维护业务关键词字典。
• 如果语义不明确，退回项目名或让用户确认一个短 slug。
• 将生成的 slug 作为 --branch-slug 传给 branch_guard.py；创建分支后用 record_branch.py --branch-slug 写回 context.json。

正式开发流程：

• branch_guard.action=ready：已有开发分支，直接进入 Step 4。
• branch_guard.action=resume_task：当前分支就是当前任务分支，且工作区存在未提交改动；这是会话恢复场景，禁止要求用户先提交/stash/丢弃。直接进入 Step 4 加载任务上下文，并结合 next_tdd_phase、STATUS.md、当前 diff 和测试文件判断从 RED/GREEN/REFACTOR 哪一步继续。
• branch_guard.action=aiweave_docs_commit_required：AIWeave 产物（docs/ 骨架等）尚未 commit。禁止把 docs 提交到当前 base 分支（main / master / dev）——AIWeave 骨架必须落到 integration 分支。aiweave_commit_commands 已生成正确序列：先 git checkout -b （untracked 文件随之跟到新分支），在新分支上 git add + git commit，最后 git checkout -b ；当前分支全程不动。用极简格式展示，等用户执行后无需重新调用 branch_guard.py（这一组命令已涵盖 prepare_branch）：

⚠️ 创建开发分支前需先 commit AIWeave 骨架（ 个文件）

当前分支：（不会被修改）
总分支：（在此分支 commit docs）
任务分支：

请选择：
1. 由 Agent 自动执行（checkout -b 总分支 → commit docs → checkout -b 任务分支）
2. 我自己手动执行，完成后回复「已完成」
3. 取消

用户选 1 → Agent 严格按 aiweave_commit_commands 顺序执行全部命令（4 条：checkout -b 总分支、git add、git commit、checkout -b 任务分支）；任何对 base 分支（main / master / dev）执行 git add / git commit / git commit --amend 的操作一律视为反铁律，立即停止报告。完成后调 record_branch.py 写回 context，再进入 Step 4。用户选 2 → 等用户回复「已完成」后重新运行 branch_guard.py。任何步骤失败立即停止报告错误。

• 重名功能分支自动 rename（替代旧的 integration_branch_conflict / aiweave_docs_overlap_with_integration 两个菜单）：当本地已存在同名总分支（feature/）时——无论是别的项目残留、还是上次失败 bootstrap 留下的 stale context（信号 recorded_task_branch_missing / integration_branch_ahead_with_no_tdd_evidence 由 stale 探测就地清空 context.json 后触发）——branch_guard.py 都会直接调 _next_available_branch_stem 把 stem 升级成 -v2 / -v3 等下一个可用版本，然后照常返回 prepare_branch 或 aiweave_docs_commit_required。
• 旧分支保留不动；新建的总分支与任务分支沿用 feature/-v2 / feature/-v2- 命名，后续 T02 / T03 继续走同一前缀。
• branch_guard 输出会带上 auto_renamed_from_integration / auto_renamed_from_task / stale_context_signal 字段，_build_branch_transition_menu 在标题下加一行 banner 提示用户："分支重名：feature/X 已存在，自动改用 feature/X-v2 / feature/X-v2-t01（旧分支保留不动）"。
• 整条路径没有独立菜单——用户在 prepare_branch 默认菜单里照常选 1 即可一次性创建总分支 + 任务分支；不需要再走"自动 rename / 手动 rename / 暂停"三选一。
• 铁律：禁止用 git branch -D / git update-ref -d 删旧分支让路；禁止用 rm -rf docs/ / git clean -fd / git checkout -- . 等命令绕过 git checkout 冲突——auto-rename 已经把 git checkout -b 的目标换成新分支，工作区不会再被覆盖，任何此类命令都属于反作弊行为，developer_response_gate.py 的 _destructive_worktree_bypass 黑名单会判 blocking format_error。

• branch_guard.action=prepare_branch：只用极简格式向用户确认，禁止解释一大段背景、禁止展示完整命令：

需要创建开发分支：

总分支：
任务分支：

请选择：
1. 自动创建
2. 手动创建
3. 取消

用户选 1 后，才按 create_branch_commands 创建需求总分支和当前任务分支；成功后运行 record_branch.py，然后进入 Step 4。若当前宿主或用户规则禁止 git 写操作，则提示用户只能选 2 或 3。

• branch_guard.action=prepare_task_transition：从上一任务进入当前任务，必须明确展示“合并上一任务分支到总分支，再创建/切换当前任务分支”，禁止只说“创建开发分支”：

进入  前需要流转分支：

上一任务：
总分支：
当前任务：

将执行：合并上一任务到总分支 → 创建/切换当前任务分支

请选择：
1. 自动流转
2. 我手动处理
3. 取消

用户选 1 后，才按 create_branch_commands 执行；成功后运行 record_branch.py，把 code_branch 更新为当前任务分支。

• branch_guard.action=commit_before_task_transition：用户已确认上一任务没问题、准备进入当前任务，但业务仓库仍停在上一任务分支且有未提交改动。禁止直接要求用户清理，也禁止直接进入当前任务；展示 branch_auto_commands

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xurb-nexus
• Source: xurb-nexus/nexus-harness
• License: Apache-2.0
• Homepage: https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.