aep-autopilot

Autopilot

一条命令即可进入自主运行：初始化状态，执行首次 tick，然后持续运行，直到当前层完成。默认驱动器为目标驱动（/goal，Claude Code 和 Codex 原生支持）——每次 tick 都会推进当前层，只有在完成条件尚未满足时，运行时才会再次触发，因此当当前层中的每个故事都已合并并完成收尾，或遇到需要人工判断的关卡时，autopilot 会自行停止，然后交还控制权，以便通过层级关卡 / /aep-reflect，再为下一层重新调用。--loop 用于选择固定间隔的备用驱动器。设计原理： docs/decisions/goal-driven-autopilot.md。

适用流程： /aep-envision → /aep-map → /aep-validate → /aep-autopilot （目标：“完成第 N 层”）→ /aep-reflect。

会话： 仅限主会话——步骤 ① 会进行检查。 状态： .dev-workflow/autopilot-state.json（机器可读）+ .dev-workflow/autopilot-status.md（人类可读）。所有合法字段均在 references/autopilot-state.schema.json 中定义； references/state-schema.md 包含原子写入和 tick 锁定协议，以及用于检查状态文件的可运行命令（scripts/validate-state.mjs，基于共享的 scripts/json-schema.mjs）。

---

STOP — 编排器边界

你是编排器，不是执行者。所有代码操作都在工作区 Agent 内进行；主会话只能通过信号文件和 git 元数据评估进度，并通过 executor.nudge() 指引工作区。越过这条边界是 autopilot 最常见的失败，因此这里只设两项禁令。

两项严格禁令。 两者都约束编排器自身的工具使用，外部探测无法观察到这些操作——因此，与 AEP 中的其他规则不同，它们没有机器检查；每项禁令都只陈述一次，并附有对应的正向操作：

• 绝不读取工作区源文件（不得对工作树使用 Read/Grep/Bash）——只能通过信号文件（.dev-workflow/signals/）和 git 元数据（gh pr view、git diff --stat）评估。将实现内容引入编排器的上下文，会使其形成代码质量判断并据此采取行动。从主会话启动代码审查器也属于变相越界：仅基于信号的分析不是代码审查，而把工作树交给该 Agent 只会让越界行为更进一步。
• 绝不从编排器执行 gh pr merge——引导工作区 Agent 完成合并。 工作人员负责第 12 阶段（rebase、CI、解决评论），并在检查通过后合并；“PR 已就绪”不是工作人员的停止点。此规则仅约束主会话——绝不可将其传递给工作人员：告诉工作人员“不要合并”／“就绪后停止”，会让一个干净、可合并的 PR 永远搁置（即 codex-subagent 共享会话故障）。每次提示合并时都要说：“第 12 阶段通过后合并。”

编排器要做什么（正向）

需求	编排器操作
读取工作区进度	读取 .feature-workspaces/<name>/.dev-workflow/signals/status.json
检查 PR 状态	gh pr view <number> --json state（仅观察）
触发代码审查 / gen-eval	executor.nudge(<ws>, "<trigger>") — 工作区运行自己的评估器
发送反馈 / 指示	executor.nudge() 或写入 .feature-workspaces/<name>/.dev-workflow/signals/feedback.md
提醒卡住的 Agent	executor.nudge(<ws>, "<nudge>")
提示人工审核关卡	读取 signals/needs-human.md；通过相应模式的渠道转达人工答复
修复 / 测试 / 评估 / 合并代码	executor.nudge() — 工作区负责构建、测试、评估和 Phase-12 合并；监控 eval-response-*.md 获取结果

下方 CHECK 委托读取信号不违反边界 — 它将编排器自身的信号记录工作交由低成本上下文处理，且不读取代码。

两项 gen/eval 关注点 — 严格分开

关注点	负责人	评估内容	运行位置
代码质量	工作区 Agent	正确性、安全性、完整性	工作区 Worker 内
编排学习	Autopilot（主会话）	跨工作区模式：失败、成本、重试	主会话 → /aep-reflect（参见 references/orchestration-learning.md）

关于_何时_必须触发工作区 gen/eval 的检测逻辑： references/review-trigger.md。

执行器传输

每项工作区操作都通过三个执行器动词完成： executor.nudge(ws, msg)（传递指示）、executor.liveness(ws)（是否确实在工作 — 进程存在且工作树活跃，绝不能依据名册 / 状态成员关系判断）以及 executor.check(prompt, schema)（低成本、上下文隔离的读取）。各模式的传输方式、驱动器 × 后端矩阵、启动后的存活探测，以及启动 / 孤儿重新接管流程，均以 /aep-executor references/backends.md 中的说明为准 — 请查阅与你检测到的模式相对应的内容。Autopilot 需要可操控且兼容驱动器的模式；如果检测结果只有 workflow/headless（没有中途阶段操作界面 — 该批处理路径属于 /aep-dispatch … with workflow 编排器，不由 autopilot 驱动），请报告 autopilot 需要可操控模式，然后停止。

---

/aep-autopilot — 启动

初始化 autopilot，运行首次 tick，并启动驱动器 — 一个命令即可，无需第二步。

/aep-autopilot                  # goal driver (default) — drives the current layer to completion, then stops
/aep-autopilot --floor 3m       # goal driver, custom per-tick wait floor (default 5m)
/aep-autopilot --loop 10m       # fixed-interval loop driver (fallback), custom interval
/aep-autopilot status           # progress + escalations
/aep-autopilot stop             # gracefully stop the driver

**驱动器选择：**存在 --loop <interval> 时选择 loop 驱动器；否则选择 goal 驱动器（默认）。--floor <dur> 仅适用于 goal 驱动器（每 tick 等待时间，默认为 5m）；--max-turns <n> 为 goal 驱动器设定上限，作为失控时的保护措施（默认为 200）。

前置条件

# 1. Must be on main workspace (not inside a feature workspace)
pwd | grep -q '.feature-workspaces' && echo "ABORT: Run from main workspace only" && exit 1

# 2. Product context must exist
[ -f product-context.yaml ] || echo "ABORT: Run /aep-envision and /aep-map first"

# 3. Autonomous routing must be enabled
# Check topology.routing.autonomous: true in product-context.yaml

继续前请确认：

• 主工作区保护： pwd 中不得包含 .feature-workspaces
• 产品上下文存在： product-context.yaml 存在，且包含 stories 部分
• 已启用自主模式： 已设置 topology.routing.autonomous: true
• 有可用故事： 至少有一个故事处于 ready 或 in_progress 状态
• 已验证： 产品上下文已通过 /aep-validate（两轮检查）

启动协议

1. 如果 .dev-workflow/ 不存在，则创建它：

   mkdir -p .dev-workflow
   

2. 初始化 .dev-workflow/autopilot-state.json（字段类型必须与 references/autopilot-state.schema.json 中定义的每个字段一致）：

   {
     "version": 1,
     "status": "running",
     "started_at": "<ISO8601>",
     "last_tick_at": null,
     "tick_count": 0,
     "workspaces": {},
     "escalations": [],
     "stats": {
       "stories_completed": 0,
       "stories_failed": 0,
       "total_ticks": 0,
       "total_cost_usd": 0
     }
   }
   

3. 写入初始的 .dev-workflow/autopilot-status.md（状态：Running，tick 计数为 0，尚无活动工作区——填写 templates/autopilot-status.md.tmpl）。

4. 确定启动模式 + 驱动程序组合（执行器 detect() + 驱动程序 × 后端矩阵）。在 Claude Code 上，默认模式为 native-bg-subagent（无需创建团队——如果有任何活跃的 agent-teams 团队，先用 TeamDelete 删除它，因为活跃团队会干扰无团队的后台任务启动）。公布该组合，例如 “native-bg-subagent + /goal” 或 “codex-exec + launchd”。

5. 立即运行第一个 tick（见下方的 /aep-autopilot tick）。

6. 根据下方的选择器启动驱动程序。

驱动程序选择器

两种驱动程序都会让协调器持续运行（因此任何可引导模式都适用）；goal 驱动程序还会在该层完成时自行终止。无论使用哪种驱动程序，tick 的执行内容都相同——只有触发下一个 tick 的方式不同。完整配置说明（目标条件文本、各主机上的 /goal / /loop 命令、Codex launchd codex exec 代码片段）：references/drivers.md。

主机 / 运行方式	驱动程序	启动方式
Claude Code / Codex，有人值守	goal（默认）	/aep-autopilot 设置 /goal "<layer-N condition>"；每轮都会重新触发，直到该层完成或暂停
任何主机，固定间隔或不支持 /goal	loop（--loop）	/loop <interval> /aep-autopilot tick
由操作系统调度，无人值守	通过 cron/launchd 使用 loop	设置计划任务，运行 codex exec … "/aep-autopilot tick"（仅限绑定操作系统的模式）

驱动程序 × 后端兼容性：持续运行的驱动程序（goal 或会话内的 /loop）支持任何可引导模式；cron/launchd 每个 tick 使用新会话 的运行方式仅支持绑定操作系统的模式（claude-bg、codex-exec、legacy），由 /loop 或外部调度器驱动，因为 /goal 仅适用于会话内。完整矩阵： /aep-executor references/backends.md。 Goal 驱动程序的不变量：作用范围限于单个层；评估器只根据 第 ⑦ 步展示的仅包含信号的状态行进行判断；每个 tick 的最短等待时间为强制要求（没有它，/goal 会在一轮结束后立即进入紧密循环）；并且始终由 --max-turns（以及 Codex 的 token_budget）设置上限。

战略关卡 — full_auto 和 auto_design

两个 topology.routing 标志控制战略性（“要构建什么”／ 架构）人工关卡；两者默认都让人类掌握控制权：

• auto_design（默认 false）：处于非可派发就绪档位的故事，或 命中规范的重复尝试覆盖规则的故事，都会暂停， 等待人工处理。auto_design: true 则会将其路由至 /aep-design （非交互式），重新计算就绪状态，然后进入 /aep-launch——不会暂停。
• full_auto（默认 false）：位于更细粒度标志（auto_design、 auto_outcome_eval、watch.auto_create）之上的主开关—— full_auto: true 意味着启用所有这些标志，因此设计升级暂停和 定性结果合约评估都会根据 Agent 的判断自动继续。 默认设置会将所有战略性暂停交由人工处理。即使启用了这些标志，重复尝试 覆盖规则也始终会升级处理。

路由阈值和暂停协议位于应用这些规则的 tick 步骤中 （references/tick-protocol.md 第 ⑥ 步）；升级条目在 references/autopilot-state.schema.json 中定义类型，暂停时的 autopilot-status.md 章节位于 templates/autopilot-status.md.tmpl。

full_auto 不会影响旅程编写。 旅程文件始终是合并前的构建交付物 （/aep-build 第 6 阶段 A 步会根据该层的验收标准编写旅程文件，并与功能一同提交）。 因此，在 full_auto: false + journey_timing: post-deploy 的情况下， 旅程必须在部署后层级关卡移交前已经存在——移交会执行并切换状态，不会编写旅程。 如果某层到达关卡时没有旅程文件，就属于 /aep-wrap 覆盖率失败（构建阶段本应编写旅程）， 而不是关卡处需要人工编写的任务。

---

/aep-autopilot tick

由驱动程序（目标或循环）调用的逐 tick 处理程序；也可随时手动运行。 具幂等性——在外部状态没有变化时重新运行，不会产生重复操作。

执行模型——检查 → 执行。 每个 tick 都会在上下文隔离的轻量 Agent （executor.check()——Claude Code 中的 Haiku 子 Agent，Codex 中的一次性 codex exec）中读取状态，写入更新后的 autopilot-state.json + autopilot-status.md，并返回操作列表；然后由编排器执行这些操作（nudge、wrap、 launch、escalate / design），这样耗费大量 token 的读取就不会占用长期运行的会话。 在 Codex 中，整个 tick 本身就是隔离的 codex exec，因此其检查步骤可以内联运行。 各步骤分别由哪一半处理，详见 references/tick-protocol.md；操作列表的类型定义见 /aep-executor references/action-list.schema.json。

Tick 摘要（①–⑦，各步骤均为不变量）。 完整的步骤说明——检查提示词 内容、执行模板（包括 ④b/④c 的提示词文本）以及所有阈值——均以 references/tick-protocol.md 为规范版本：

① READ STATE       cat autopilot-state.json; exit if status≠running or a fresh tick lock is held; else take the tick lock.
② SYNC SIGNALS     fold each workspace signals/status.json into state; blocked_on==human → escalate human_gate (not stuck); orphan (session-bound mode, by real liveness) → emit a re-adopt launch into the existing worktree.
③ WRAP COMPLETED   story_status==completed → /aep-wrap (max one per tick, [one-wrap-per-tick]); remove from state; then skip to ⑦.
③.5 POST-MERGE GUARD  for each merged story, watch deploy health + host-aware dogfood across a window; UX finding → /aep-reflect story; confirmed hard regression → escalate (or revert if auto_revert). See references/post-merge-guard.md.
④ GUIDE COMPLETION per workspace: ④a check PR state; ④b quality gate — no eval PASS → trigger the workspace's own gen/eval via executor.nudge(); ④c eval PASS + PR open → nudge toward Phase-12 merge (once).
⑤ DETECT STUCK     (phase, completion_pct) unchanged vs last tick → run executor.liveness() before counting; then the stuck ladder (observe → nudge → escalate); human-gate exempt.
⑥ DISPATCH NEW WORK  capacity? run /aep-dispatch scoring (steps 1-3); wave + layer-gate + grouped-change ordering; dispatch-ready → /aep-launch, otherwise escalate or auto-design; max one launch per tick ([one-launch-per-tick]); runs after ③ ([wrap-before-dispatch]).
⑦ WRITE STATE + SURFACE + WAIT  atomic write state (.tmp → rename); append autopilot-history.jsonl; update autopilot-status.md; release the tick lock. Goal driver only: surface the signals-only AUTOPILOT status line, then wait the per-tick floor before ending the turn.

[方括号] 标签是机械式顺序不变量——确定性的 WHEN+SHAPE 规则，会因依赖行文回忆而发生偏移，并由类型化关卡保障。要扩展此循环的项目，应将其迁移到自身的类型化动词中： docs/decisions/deterministic-orchestration.md（目录见 references/deterministic-orchestration.md）。

---

/aep-autopilot status

读取并显示当前自动驾驶状态。

cat .dev-workflow/autopilot-status.md
ROOT=$(git rev-parse --show-toplevel); AP="$ROOT/.agents/skills/aep-autopilot"; [ -d "$AP" ] || AP="$ROOT/.claude/skills/aep-autopilot"
node "$AP/scripts/derive-workspace-state.mjs"   # logical state + flags per workspace

以 /aep-easy-explain 的表达风格为人类呈现说明：先用一行交代背景， 使用符合 ASD-STE100 的浅显英语，并采用项目自身的术语。

同时解析 .dev-workflow/autopilot-state.json 并呈现：状态 （运行中／已暂停／已停止）；运行时间（自 started_at 起的时间、tick 次数）； 活跃工作区（名称、story_id、阶段、completion_pct、last_action）； 待处理的升级事项（类型、story_id、原因）；统计数据（已完成、失败、总成本）。 **如果已暂停：**暂停原因、预期的人类反馈，以及恢复方式。

---

/aep-autopilot stop

优雅地停止 autopilot 并取消当前驱动程序。

1. 在 .dev-workflow/autopilot-state.json 中设置 status: "stopped"。
2. 在 .dev-workflow/autopilot-status.md 中更新停止状态。
3. 将停止事件记录到 .dev-workflow/autopilot-history.jsonl。
4. 取消驱动程序：
   • 目标驱动程序：/goal clear（Claude Code / Codex）。后续轮次不会再次触发。（目标驱动程序也会在层完成时自行清除，因此 stop 主要用于提前终止。）
   • **循环驱动程序：**取消 /loop（loop 技能的取消机制），或移除 OS 计划运行所使用的 cron/launchd 任务。
5. **native-bg-subagent：**后台子 Agent 与会话绑定，会在协调器会话结束时停止。若要在保留工作的同时提前停止，请让每个正在运行的 worker 到达阶段边界（或使用 TaskStop <agentId>）；所有状态都保存在工作树和 .dev-workflow/ 中，因此之后的 /aep-autopilot 会通过存活探测重新接管孤立任务。

**效果：**不再产生 tick；正在运行的工作区会继续自主运行（它们不依赖 autopilot——但要注意：主会话关闭时，与会话绑定的 worker 会成为孤立任务，并在下次启动时重新接管）。不会修改产品上下文，也不会触发收尾或合并。若要恢复：/aep-autopilot。

---

防护规则

没有适合归入常规步骤的规则（顺序不变量、原子写入和 tick 锁位于 references/tick-protocol.md / references/state-schema.md 中；WIP 上限 topology.routing.concurrency_limit 和 dependencies-completed 门控属于步骤 ⑥ 的派发检查）：

• 只有确实 PASS 后才能推动合并——对于集成/测试故事，这意味着至少有一项检查通过，或有明确的 eval-response PASS。只有 SKIP 的结果和“没有检查”都不构成证据，不能算通过。

---

后续步骤

autopilot 完成一个层或停止后：

操作	适用时机
/aep-reflect	一个层完成后——评估结果契约（步骤 2.75），对反馈进行分类
/aep-autopilot status	随时——检查进度和升级情况
/aep-autopilot	暂停问题解决后——恢复驱动程序（重新设置层目标）
/aep-dispatch	手动模式——以交互方式挑选特定故事