nav-pilot

用途

nav-pilot 负责把 Navigator 中已编写完成的任务文档交给 Pilot 执行：在 GitHub 上创建一条带 pilot 标签的 Issue（Pilot 会轮询该标签），然后把 Issue 地址记录回任务文档。

该技能不校验文档内容，规格检查由 Pilot 的 spec_validator 完成；它也不负责编写或归档文档，只消费 nav-task 产出的文档。

触发时机

当用户说以下内容时调用：

“Dispatch TASK-XX to Pilot”
“Hand this off to Pilot” / “send to Pilot”
“Queue TASK-XX for Pilot” / “create the Pilot issue”

以下情况不要调用：用户正在编写或归档任务文档（应使用 nav-task）；用户想查看 Pilot worker 状态（不在范围内，该技能是单向的）；尚不存在任务文档（应先提示用户用 nav-task 创建）。

执行步骤

步骤 1：定位目标任务文档

给出明确 ID（如 “TASK-07”）时，使用 .agent/tasks/TASK-07-*.md。
未给出 ID 时，选取 active/in-progress 状态的任务；若有歧义，列出候选（ls .agent/tasks/*.md）并询问。
文件不存在则停止，并提示用户先编写文档。
读取文档并提取：标题为第一个 H1（# TASK-XX: <name>），去掉 TASK-XX: 前缀（或保留完整 H1，以 Pilot 期望为准）；正文文件路径即文档本身（通过 --body-file 传入，不内联）。

步骤 2：加载 Pilot 配置

从 .agent/.nav-config.json 读取 pilot 配置：

"pilot": {
  "enabled": true,
  "label": "pilot",
  "repo": null
}

label（默认 "pilot"）：Pilot 轮询使用的标签。
repo（默认 null）：目标 owner/name。为 null 时 gh 使用当前 git 仓库的 origin，不传 --repo。
若 pilot.enabled 为 false，停止并提示用户启用。

步骤 3：构建命令

gh issue create \
  --title "<H1 title>" \
  --label "<pilot.label>" \
  --body-file ".agent/tasks/TASK-XX-<slug>.md" \
  [--repo "<pilot.repo>"]   # 仅当 pilot.repo 已设置时

步骤 4：执行前确认

创建 GitHub Issue 属于对外操作，必须先确认，展示仓库、标题、标签、正文文件及行数、完整命令，并提供“回车派发 / dry-run / 修改”选项。若用户要求 dry-run 或在此输入 dry-run，只打印完整 gh 命令并停止，不执行。

步骤 5：派发

运行 gh issue create，从 stdout 捕获返回的 Issue URL。失败处理：

未认证 → 提示运行 gh auth login。
仓库缺少标签 → 建议 gh label create pilot。
无 git remote / 仓库不存在 → 请用户在配置中设置 pilot.repo。

步骤 6：回写文档

编辑任务文档：在 ## Refs 下添加 - Pilot issue: <url>；将状态行更新为 Status: 🚀 Dispatched to Pilot；将 Last Updated 更新为当天。

步骤 7：确认

输出 Issue 地址、标签、任务编号与标题，说明已回写文档且 Pilot 将在下次轮询 pilot 标签 Issue 时接手。若启用了知识图谱，编辑会通过常规 PostToolUse hook 同步，无需额外操作。

适用场景

已经由 nav-task 编写好任务文档、希望交由 Pilot 执行的自动化工作流；尤其适合希望以 GitHub Issue 作为任务队列、由 Pilot 轮询接手的团队。

限制

单向设计：不监控 Pilot worker，也不拉取结果回来。
不做文档校验，校验由 Pilot 的 spec_validator 负责。
不支持编写或归档任务文档（由 nav-task 负责）。
依赖 gh CLI 认证、仓库存在对应标签，以及 git remote 或配置中的 pilot.repo。

技能介绍

用途

触发时机

执行步骤

适用场景

限制