ship

name	ship
description	全流程实施：探索→计划→worktree→TDD→实施→PR→review→/fix Cx1/Cx2→人工确认。L1(跳过探索,1 reviewer)/L2(单agent探索,1 reviewer)/L3(默认,三agent探索,按diff行数1/2/3/6 reviewer自动)
argument-hint	[--level=L1|L2|L3] <#issue-number 或任务描述>
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","Agent","AskUserQuestion"]

prmonitor Ship — 全流程实施

多沟通原则（默认多问、有歧义即停）：L2/L3 在创建 worktree（阶段 3）之前必须完整呈现「方案方向 （阶段 1）+ 改动计划（阶段 2）」并经 AskUserQuestion 确认——不在未对齐时就开工。实施中（阶段 5）surface 阶段性进度与 blocker；阶段 7→8 呈现内置 review findings 表，Cx1/Cx2 IN_SCOPE 直接修；每条 IN_SCOPE Cx3（及 Cx4）经处置门 AskUserQuestion 判「当前 PR 修」or「defer」——判 defer 后自动建 issue 跟踪（不二次确认），判修则纳入本轮。 归属 / 取舍不清也停下问。任何方案歧义 / 范围不清 / 取舍没把握 → 停下问，不默默假设。

剥离 --level= flag 后，剩余参数匹配 ^#?[0-9]+$ 时视为 issue 号，先 bash hack/automation/forge.sh issue-view <N> 拉取作为任务上下文；后续阶段以 issue title/body 替代自由文本任务描述，阶段 6 PR body 追加 $(bash hack/automation/forge.sh pr-close-ref <N>)。state != "open"（closed / merged 等）或 issue-view 失败均用 AskUserQuestion 让用户裁定是否继续。

等级

等级	探索	计划确认	实施 agent	review
L1	不探索	不需要	1-2 并行	1 reviewer
L2	1 explorer	展示给用户	1-2 并行	1 reviewer
L3（默认）	3 并行 explorer	AskUserQuestion 确认	≤ 4 并行	1/2/3/6 reviewer（按 diff 行数自动，见阶段 7）

---

阶段 1：探索（L1 跳过）

L2：启动 1 个 explorer agent，研究本仓既有实现模式与必要的对标做法（Tauri command / serde 契约 / 切片 trait seam），提取接口签名、生命周期、错误处理关键设计，输出采纳建议和偏离理由。

L3（默认）：并行启动 3 个 explorer agent：

1. 本仓既有模式 + 对标参考实现（切片结构、trait seam、Tauri/serde 用法、Rust/Vue 社区惯例）
2. 测试策略（Rust 单测 / serde 往返 / 前端 vitest 覆盖模式）
3. 边界条件与安全处理（子进程调用、外部输入、进程生命周期）

全部完成后按「方案与计划原则（含自检）」汇总并逐条自查，再用 AskUserQuestion 与用户确认方案方向后继续。

---

方案与计划原则（含进入下一步前的自检）

阶段 1 汇总 / 阶段 2 计划必须满足下列原则；L3 在 AskUserQuestion 前逐条自查，任一不通过 → 在确认问题中显式列出取舍及理由，不默认放行：

• 彻底：根因 + 完整解法，范围内紧密相关的小工作一并纳入。自查「是否还藏 TODO/FIXME/follow-up、兼容代码、未列入范围的关联工作？」→ 合并进当前 PR 或写明 blocker 理由。
• 不向后兼容：删字段/改签名/换实现直接做。自查「是否留了 deprecation 别名、旧字段、兼容 shim、双路径？」→ 删掉或写明保留理由。
• 优雅简洁：最少代码改动达成目标，不引入新抽象层、不预设未来需求。自查「能否用更少的代码/抽象/新文件达成同样目标？」→ 简化或写明保留理由。
• 开源对标：阶段 1 必产至少一条 ref: {framework} {path}@{ref}（真实拉源码 + prmonitor 侧对应）。自查「是否真有 ref: 产出？」→ 无则二选一：① 回阶段 1 重跑 explorer 补对标；② 确属无对标场景（纯内部重构 / 治理文档 / 无同类框架）时在 PR body 写明一行 本 PR 无需对标：<理由>（理由合理性由阶段 7 reviewer 核查）。二者必居其一，禁止静默省略（由阶段 6 机器门校验）。

---

阶段 2：计划

按「方案与计划原则（含自检）」生成改动文件清单（按依赖顺序）、任务分组（串行/并行批次）、TDD 测试先写清单、对标参考（ref: framework file）。生成后逐条自查，L3 用 AskUserQuestion 与用户确认计划后继续。

并行批次分析（改动文件 ≥ 4 时必须在计划中明确）：

• 标注各任务的文件归属和批次编号
• 标注批次间依赖关系（有依赖 → 串行；无依赖 → 可并行）
• 解决同文件冲突：同一文件必须归入同一批次/agent

---

阶段 3：Worktree

基于激活 forge remote 的 develop 分支创建（依照 git-worktree skill 约定）：

REMOTE=$(bash hack/automation/forge.sh remote)
git fetch "$REMOTE"
git worktree add worktrees/<type>/<issue#-short-name> -b <type>/<issue#-short-name> "$REMOTE/develop"

命名依 git-worktree skill：编号 = 关联 issue#（无 issue 不编号），path 与分支首段含 type（feature/fix/refactor/docs/experiment，一律小写）。下文 worktrees/<wt> 简写指该 worktree 目录。

---

阶段 4：TDD — 先写测试

在 worktree 中，对有可测逻辑的改动先写测试（Rust #[cfg(test)] / 前端 vitest），覆盖正常/边界/错误路径。运行对应测试确认先 FAIL，再进入实施：

cargo test --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --locked <test-name>
pnpm -C worktrees/<wt> test <test-name>

纯配置/纯文档/纯 UI 展示改动无可测逻辑时可跳过本阶段并注明。

---

阶段 5：实施

5.0 分组与并行度决策（实施前必须执行）

主 agent 根据阶段 2 的改动文件清单和批次依赖关系，自主决定：

• 哪些任务无文件交叉且无逻辑依赖 → 可并行启动 developer agent
• 哪些任务有依赖或改同一文件 → 串行或归入同一 agent

硬约束：

• 同一文件只能分给同一 agent（防写冲突）
• 有前置依赖的批次必须等上一批全部完成后再启动
• 并行 developer agent 上限 4 个

5.1 Sub-agent prompt 自包含要求

每个 developer sub-agent prompt 必须包含：

• worktree 路径（worktrees/<wt>）
• 分配的任务列表（文件路径 + 改动描述）
• 命令格式：cargo build/test --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --locked、pnpm -C worktrees/<wt> build/test
• CLAUDE.md 关键约束（垂直切片自包含、跨切片只走 model.rs、trait seam PrSource/ReviewEngine、组装根 lib.rs、前后端类型对齐 types.ts↔model.rs）
• commit 格式：<type>(<scope>): <描述>

每个 sub-agent 在自己负责的任务上串行执行 Edit-Test Loop，完成后跑 lint（0 warnings 才 commit）：

pnpm -C worktrees/<wt> build
cargo fmt    --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --all -- --check
cargo clippy --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --all-targets --locked -- -D warnings

5.2 主 agent 汇总（所有并行 agent 完成后）

pnpm -C worktrees/<wt> build
pnpm -C worktrees/<wt> test
cargo build  --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --locked
cargo test   --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --locked
cargo fmt    --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --all -- --check
cargo clippy --manifest-path worktrees/<wt>/src-tauri/Cargo.toml --all-targets --locked -- -D warnings   # 0 warnings 才进阶段 6

---

阶段 6：PR

# 对标产出门（Soft→Medium，守卫单源 + selftest 见 hack/automation/pr-benchmark-gate.sh）：
# PR body 必含有效 `ref: {framework} {path}` 或非空 `本 PR 无需对标：<理由>`，缺则回阶段 1（不问人）
bash hack/automation/pr-benchmark-gate.sh <填好的 pull_request_template.md> || exit 1
git -C worktrees/<wt> push -u "$(bash hack/automation/forge.sh remote)" <branch>
bash hack/automation/forge.sh pr-create "..." <填好的 pull_request_template.md> develop <branch>
bash hack/automation/forge.sh pr-add-label <PR#> pr-status/in-progress   # 进入 ship→review→fix→check 流程（见 .github/project-template/PROJECT.md §5）

PR body 结构单源 = .github/project-template/pull_request_template.md；读模版填占位（Refs: Closes #<ID> + ref: framework file），不在技能内重述结构。本仓 PR 全程 CLI 创建，必须 --body-file 读填好的模版。

---

阶段 7：Review（内置 reviewer）

ship 的 review 是 ship→review→fix→check 流程里的内置首审（6 维 reviewer）；外部再审（codex / /pr-review）由你在外部跑， 续修走 /fix <PR#>（见 .github/project-template/PROJECT.md §5）。ship 单独使用只做内置审。

L1/L2：1 个 reviewer agent（prmonitor 六维度）。

L3：按 PR diff 净增删行数确定 reviewer agent 数量：

git -C worktrees/<wt> diff --shortstat "$(bash hack/automation/forge.sh remote)/develop"   # N files changed, X insertions(+), Y deletions(-)

diff 行数 = X + Y（缺项按 0 计）。阶段 7 被单独调用（无 worktree）时回退仓库根 git diff --shortstat "$(bash hack/automation/forge.sh remote)/develop"。

prmonitor 六维度 = 架构合规 / 安全 / 测试 / 运维可观测 / DX / 产品。reviewer 数 + 维度切分单源 = .claude/agents/reviewer.md §派发分档（按上面算出的 diff 行数定档，区间左闭右开，边界归更高档）。

多 agent 时并行启动，每个 agent prompt 自包含其负责维度 + 必读 .github/project-template/PROJECT.md §3（P/Cx 评级单源）；全部完成后由主 agent 汇总去重 findings 表（含 Cx 分级）。

---

阶段 8：Fix（内置审 findings）+ 收尾

pm: 评论统一*：填 pr-comment.md 模板（无损 file:line + 详表入 <details>）+ pr-meta.sh emit-block --kind=<k> --pr=<PR#> 追加机器块到 body 末尾 + issues B4 贴（回显 URL）。

1. 打印：窗口完整打印内置 findings 表（P/Cx + IN_SCOPE/OOS 归属 + file:line，输出纪律见 PROJECT.md §5）。pm:ship 留痕在步骤 5 唯一贴（不在此重复贴）。
2. Cx3 处置门（阻塞，先于直接修与切 label）：每条 IN_SCOPE Cx3/Cx4 用 AskUserQuestion 判「当前 PR 修」or「defer」——判修（pm:ship 记 ✅ 已修）；判 defer → 自动按 issues B1 建 issue 跟踪（pm:ship 记 ⏸ defer，不再二次确认）；Cx4 默认 defer。处置完再 Cx1/Cx2 IN_SCOPE 直接修（派 developer agent Edit-Test 修，不逐条问）。归属/取舍没把握仍 AskUserQuestion。
3. 推送 + 冲突预检（阻塞）：git -C worktrees/<wt> push，按 issues B5 ① 验冲突（冲突则 git merge "$(bash hack/automation/forge.sh remote)/develop" --no-edit 再 push），过则立即进 4（不等 CI）。
4. OOS → 建 issue + pm:oos（有 OOS 时；artifact 先于 pm:ship）：逐条按 issues B1 建 backlog issue（无损填 backlog.md + 四轴标签 cx/area/type/pri，issue-labels.sh validate 过门，派生注 Discovered via /ship）；pri-p0→停 AskUserQuestion、validate 失败→deferred=labels-underivable 回退草稿；贴 pm:oos（--kind=oos，每 item 必带 issue 或 deferred，否则 emit-block 拒绝）。
5. pm:ship（--kind=ship，OOS artifact 已存在、指针有效）：IN_SCOPE findings 无损写入（reviewer 数 / 已修 Cx1-Cx2 / Cx3 处置）；OOS 仅一行指针 🚦 OUT_OF_SCOPE（见 pm:oos）。
6. 切 label：bash hack/automation/forge.sh pr-set-labels <PR#> --add pr-status/needs-review-again --remove pr-status/in-progress。
7. CI 异步收敛（非阻塞）：bash hack/automation/forge.sh ci-watch <PR#>（azure 无 CI 返回 no-ci → 降级本地 pnpm build && pnpm test + cargo build/test/fmt/clippy，不贴 pm:ci）；有 CI 按 issues B5 ② 熔断、失败回 fix 再推，贴 pm:ci（--kind=ci，全绿 ci-green / 熔断仍红 ci-failed + 失败摘要）。
8. 延迟启监控（必做）：评论 + label 完成后延迟约 15min 启 /pr-monitor <PR#> --mode=auto（review-side）；外部 app 监听 needs-review-again 跑 review，pr-monitor 检测 needs-fix 即接力 /fix（判定由 fix 自理）。

收尾不变式（artifact-before-summary/trigger）：OOS issue + pm:oos（步骤 4）+ 处置门判 defer 的 IN_SCOPE Cx3/Cx4 issue（步骤 2）必须先于 pm:ship（步骤 5）落地——pm:ship 的 OOS 指针指向已存在的 pm:oos，不悬空；再切 needs-review-again（步骤 6）；CI（步骤 7）异步在后。 ship 到此结束。再审（codex / /pr-review）后续修走 /fix <PR#>。

---

阶段 9：人工确认

PR: #<编号> <URL>
评论: <pm:ship 评论 URL，含 #issuecomment-<id>（来自 issues B4 回显）>
已完成：TDD / 实施 / PR / review（实跑 reviewer 数：按 diff 1/2/3/6 自动） / Cx1-Cx2 fix / CI 绿

已处置问题——处置门已判修/defer，**defer 项已自动建 issue 跟踪**；本表仅摘要 + 指针；完整无损详表（证据/三维根因/三级方案种子）见 pm:ship
评论的 `<details>`；OOS + 判 defer 的 Cx3+/RELATED 的 issue #N / 原因见本 PR 的 pm:oos / pm:ship 评论：
| # | Finding (file:line) | Cx | 归属 | 建议方案 | 原因 |
|---|---------------------|----|------|---------|----|

---

约束

• lint 0 issues 才 push；不 --no-verify；不 amend 已 push commit
• worktree merge 后提示用户手动 git worktree remove，不自动删除