milestone-planning

里程碑规划（Ultraplan）

通过三个步骤将复杂任务拆解为多个里程碑：并行全面探索代码库，根据探索结果起草里程碑 DAG，然后将草案提交给一组对抗性评审者，让他们分轮攻击，直到草案经受住考验。

核心原则

里程碑是长期执行的基本单位。糟糕的里程碑拆分会导致数天的工作白白浪费。两项原则可以避免这种情况：

• 有依据。 草案基于并行探索收集到的实际代码库证据，而不是对代码可能是什么样的假设。
• 对抗性压力。 在执行以更高代价暴露问题之前，由独立评审者专门负责找出草案的问题。

评审者需要有具体产物可供攻击。这就是为什么要先起草再评审：“审查问题”只能得到建议；“攻破这份草案”才能得到具体发现。

硬性门槛

1. 先探索，再起草。 起草之前，先派遣多个探索 Agent 并行开展探索。每个里程碑的划分都必须引用探索证据——没有实际代码库依据的划分只是一个假设，而不是决策。
2. 每轮评审者都必须并行运行。 通过 Agent 工具在一条消息中并发派遣所有评审者。禁止顺序评审。
3. 每位评审者都必须收到完整的问题简报和完整草案。 不要针对不同评审者筛选或截取内容。
4. 评审者不得看到彼此的评审意见。 每轮评审保持独立，评审者之间达成一致才有意义。
5. 必须明确处理每条评审意见。 在评审意见处理日志中逐字记录每项发现，并标记为已接受（修改草案——说明如何修改）或已拒绝（给出有证据支持的理由）。默默丢弃评审意见属于规划失败。
6. 持续评审，直到没有新发现。 修改后，针对修订后的草案派遣新一轮评审者。只有当一整轮评审没有产生任何新的结构性或阻塞性发现时，草案才算定稿。最多进行 3 轮——第 3 轮结束后仍有争议的阻塞性发现，须向用户升级说明，并陈述双方观点。
7. 每个里程碑都必须有可通过二元判断的成功标准。 “正常工作”不是标准。每项标准都必须能通过运行命令或阅读代码来判断是否达成——采用与 plan-crafting 的验收标准规则相同的要求。
8. 里程碑依赖关系必须构成 DAG。 循环依赖意味着计划失败。每个里程碑都必须有明确的拓扑顺序。
9. 不要为简单任务生成里程碑。 如果问题可以在一个 plan-crafting 周期内解决（少于约 8 项任务），请告诉用户直接使用 plan-crafting。

适用场景

• 用户提出需要数天完成的复杂任务时
• 长期运行的执行框架需要拆分里程碑时
• 用户说“规划里程碑”“把这拆成几个里程碑”或“ultraplan”时
• 任务显然需要多个彼此独立的实施阶段时

不适用场景

• 单日任务（直接使用 plan-crafting）
• 少于约 8 个实施步骤的任务
• 里程碑已经定义，且用户希望开始执行时（使用 long-run）
• 工作范围仍不明确时（先进行澄清）

输入

此技能要求输入清晰的问题陈述。输入可以来自：

1. clarification 技能生成的上下文简报文件（首选）
2. 用户直接提供的详细请求（必须包含目标、范围和约束）

如果输入含糊不清，请先返回 clarification 技能，再继续处理。

流程

阶段 1：问题界定 + 广泛探索

1. 阅读输入内容（上下文简述或用户请求）
2. 确定：目标、范围边界、技术约束、成功标准
3. 并行派遣探索 Agent——同时运行多个只读 Explore 子 Agent，各自采用不同视角：
   • **架构与接口：**工作涉及的模块、边界和契约；需要遵循的现有模式
   • **依赖关系与数据流：**各项内容之间的依赖关系；共享状态（数据库架构、配置、全局变量）；外部系统及其设置要求
   • **验证现状：**端到端测试、集成测试、测试套件、CI 检查——这些信息将用于制定验证策略
   • **惯例与历史：**命名和结构惯例、近期相关变更、类似工作的既往尝试 根据问题需要增加特定任务视角（数据工作可增加架构/迁移视角；涉及安全的工作可增加身份验证/权限视角；API 变更可增加客户端兼容性视角）。
4. 编写问题简述——内容必须完整自洽；起草 Agent 和每位评审者都会收到：

## Problem Brief

**Goal:** [What must be achieved]

**Scope:**
- In: [What is included]
- Out: [What is explicitly excluded]

**Technical Context:**
[Relevant architecture, existing code, constraints]

**Exploration Digest:**
[Key findings per lens, with file references — this is the evidence base
 the draft cites and the critics check against]

**Constraints:**
[Time, compatibility, dependencies, performance requirements]

**Success Criteria:**
[Binary-decidable outcomes]

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact command to run the verification]
- **What it validates:** [what passing this verification proves]

**验证发现：**采用与计划制定相同的发现顺序（端到端测试 → 集成测试 → 验证技能/Agent → 测试套件 → 构建 + lint），并将结果记录在验证策略部分。如果不存在验证基础设施，集成验证里程碑的计划制定阶段（长程执行期间）将把创建它作为任务 0。

阶段 2：拆分草案（先拟定两个框架，再形成一份草案）

反复修改单份草案会使之后的每轮都受其初始结构限制——评审者会针对细节提出异议，而反复打磨直到没有问题的循环只能完善已有框架。应通过多样化的初始方案来避免这一点：先起草两份，再进行一次评审。

1. 并行派遣两名起草 Agent，让他们各自收到完整的问题简述 + 探索摘要，并采用不同的组织原则：
   • **框架 A——接口优先：**安排里程碑时，先定义契约和接口，再处理其使用方；边界遵循架构图
   • **框架 B——风险优先：**安排里程碑时，优先尽早验证风险最高的集成和最模糊的需求；边界遵循失效模式
2. **比较并组合，形成 DRAFT v1：**主 Agent 选出更强的框架，并融合另一框架中的优秀内容。在解决日志开头记录选择及理由（“框架：B，因为……；融合了 A 的 M2/M3 拆分”）。

草案采用完整的里程碑格式（见阶段 6），并明确标记为 DRAFT v1。

对于每个里程碑，草案必须注明：

• 名称、目标（一个句子）
• 成功标准（可通过二元判断确定——硬性关卡 7）
• 依赖项（必须先完成哪些里程碑）
• 受影响文件（依据依赖关系探索结果）
• 风险 / 工作量 / 用户价值 / 中止点
• **依据：**探索摘要中支持此边界的发现

依据字段为空的里程碑只是猜测——应继续探索，或将其合并到相邻里程碑中。

阶段 3：对抗式评审小组

针对草稿派发评审小组——所有评审者并发执行，在单条消息中派发，设置 run_in_background: true，不隔离工作树（评审者仅可读）。

小组构成——始终包含 4 位核心评审者：

1. 隐性复杂度评审者——质疑工作量估算：集成点、边缘情况、数据迁移、向后兼容性等因素可能让“Small”里程碑变成“大型”里程碑；以及需要先进行探索性研究才能估算的组件。
2. 依赖关系与顺序评审者——质疑 DAG：遗漏的依赖边、并行组内的文件冲突、无序里程碑修改的共享状态、在定义接口的里程碑之前就使用接口、未包含设置步骤的外部依赖。
3. 可验证性评审者——质疑成功标准：任何无法用二元结果判定的标准（需要解释才能判断）、无法在轮到时独立验证的里程碑、没有标准覆盖的跨里程碑接口。
4. 集成与风险评审者——质疑执行顺序：把风险最高的集成推迟到最后、最后才处理最模糊的需求（此时修正成本最高）、会让系统处于损坏状态的里程碑、规模过大且返工代价高的里程碑。

此外，最多加入 2 位任务专属评审者，根据问题性质选择：价值与顺序（尽早提供用户可见的价值、最小可行的首个里程碑、中止节点）、迁移与兼容性、安全与访问控制、性能。在解决记录中用一行说明选择理由。

评审者提示词模板（根据小组定义填写 {LENS}、{LENS_FOCUS}；完整复制问题简述和草稿）：

You are the {LENS} critic reviewing a draft milestone decomposition.
Your job is to find the ways this draft fails during execution.
You are not here to be agreeable — an easy approval from you is
a defect in the process.

## Problem Brief
{PROBLEM_BRIEF}

## Draft Milestone DAG (v{N})
{DRAFT}

## Your Task

Attack the draft strictly from your lens: {LENS_FOCUS}

Rules:
- Every finding must be concrete: name the milestone, quote the draft
  text you are attacking, and state the failure scenario during
  execution. Check claims against the Exploration Digest — a draft
  assertion that contradicts the digest is automatically a finding.
- Assign each finding a severity:
  - **Structural:** the decomposition's fundamental shape is wrong —
    wrong unit of decomposition, wrong ordering philosophy, or a
    missing phase that no milestone-level edit can add. Use only when
    revision cannot fix it; a Structural finding must include a 3-5
    line sketch of the alternative shape.
  - **Blocking:** execution will fail, produce the wrong thing, or
    require redoing a completed milestone
  - **Concern:** elevated risk that needs a stated mitigation
  - **Nit:** improvement, safe to ignore
- Do not propose a full alternative decomposition — attack this one.
  The only exceptions: the "smallest fix" per finding, and the 3-5
  line shape sketch required for a Structural finding.
- If you find nothing Blocking, earn it: list the attacks you attempted
  and why the draft survived each one.

## Output Format

For each finding:
- **[Severity] Finding:** [one sentence]
- **Where:** [milestone ID(s) + quoted draft text]
- **Failure scenario:** [what concretely goes wrong during execution]
- **Smallest fix:** [minimal change to the draft that removes the failure]

If nothing Blocking: list attempted attacks and why each failed.

评审者故障处理：

1. **超时或出错：**使用相同提示词重新派发失败的评审者一次。若再次失败，则在解决记录中记录缺失的评审视角，并在没有该评审者的情况下继续。
2. **输出为空或敷衍：**评审者未提出任何发现，且未列出尝试攻击的内容，说明其没有完成任务——重新派发一次。
3. **最低可行评审小组：**每轮至少 3 位评审者必须成功。少于 3 位 → 停止并向用户报告。

阶段 4：修订循环（评审直至无新发现）

1. 在评审解决记录中逐字记录每项发现——不要总结或弱化：

| # | Critic | Severity | Finding (verbatim) | Resolution | Rationale / Draft change |
|---|--------|----------|--------------------|-----------|--------------------------|
| 1 | Dependency | Blocking | "M3 consumes the API defined in M4..." | Accepted | Reordered: M4 now precedes M3 |
| 2 | Complexity | Concern | "M2's migration effort is Small but..." | Accepted | M2 split into M2a (spike) + M2b |
| 3 | Verifiability | Blocking | "M5 criterion 'UX feels responsive'..." | Accepted | Rewritten: "p95 interaction latency < 100ms in the perf test" |
| 4 | Integration | Nit | "..." | Rejected | Digest shows the interface is already exercised by e2e suite |

2. **结构性发现应触发重新起草，而非修订。**如果接受了结构性发现，则返回阶段 2 并重新组织草稿——该发现的形状草图和未使用的骨架都是输入。每次规划会话最多重新起草一次；若第二个结构性发现也被接受，则说明问题框定本身有误 → 升级给用户并重新审视阶段 1。
3. 修订草稿（v2、v3……），应用所有已接受的修正。
4. 如果本轮产生了任何结构性或阻塞性发现，针对修订后的草稿重新派发一轮全新的评审。使用没有先前轮次记忆的新实例——记得旧评审内容的评审者会执着于旧评审，而不是攻击新草稿。
5. **结束条件：**一整轮中没有新的结构性或阻塞性发现，即锁定草稿。待解决问题必须在受影响里程碑的备注中记录缓解措施；细微问题可选记录。
6. **轮次上限：**最多 3 轮（重新起草后计数重置一次）。第 3 轮结束后仍有争议的阻塞性发现 → 将其提交给用户，同时逐字呈现评审者的发现和草稿的反驳。

阶段 4.5：集成验证里程碑

草稿锁定后，主 Agent 自动追加一个集成验证里程碑，作为 DAG 中的最后一个里程碑。该里程碑是结构性保障——评审者无权决定是否存在此里程碑。

### M_final: Integration Verification

- **Goal:** Validate that all milestones work together as a complete system
- **Success Criteria:**
  - [ ] Highest-level project verification passes (command from Verification Strategy)
  - [ ] All milestone success criteria remain met after full integration
  - [ ] Full test suite passes — no regressions in pre-existing functionality
  - [ ] Cross-milestone interfaces are exercised end-to-end
- **Dependencies:** ALL other milestones
- **Files:** None (read-only verification — no new code)
- **Risk:** Medium (integration issues between independently-verified milestones)
- **Effort:** Small (verification only, no implementation)
- **User Value:** Confidence that the system works as a whole, not just per-milestone
- **Abort Point:** No (this is the final gate)

阶段 4.6：独立验证 DAG

追加集成验证里程碑后，主 Agent 会在向用户展示完整 DAG 结构前进行独立验证。不要依赖评审者发现所有问题。

1. **循环依赖检查：**追踪每个里程碑的依赖链；如果某个里程碑既是另一个里程碑的祖先，又是其后代，则 DAG 无效。修正草案，并针对修正结果重新运行依赖与排序评审者。
2. **并行里程碑的文件冲突检查：**没有依赖关系的里程碑，其“受影响文件”列表必须互不重叠。若有重叠 → 添加依赖边，或标记为需要用户决策。
3. **孤立项检查：**除第一个里程碑外，每个里程碑都必须至少有一项依赖，或明确标记为可独立并行执行并说明理由。
4. **验收标准检查：**每个里程碑至少有 2 项可通过二元判定的成功标准。需要解释才能判断的标准 → 在展示前重写。

阶段 5：用户审核与锁定

这是整个长期运行流程中唯一的审批关卡——用户在此锁定计划后，long-run 会执行所有里程碑，不再暂停等待审批。

**里程碑数量限制：**建议数量为 3-7 个。超过 7 个 → 警告：“此计划包含 N 个里程碑。请考虑是否应将问题拆分为多个项目。”超过 10 个 → 必须获得用户明确批准才能继续。

1. 展示已锁定的里程碑计划
2. 展示评审意见处理日志——用户必须看到评审者指出了哪些问题，以及每项发现是如何解决的
3. 展示执行顺序及并行化安排
4. 展示里程碑数量，并在适用时显示数量限制警告
5. 请用户批准、修改或拒绝
6. 如果获得批准：将所有产物保存到 harness 状态目录
7. 如果请求修改：应用修改，针对变更重新运行受影响的评审者，然后再次展示
8. 如果遭到拒绝：根据更新后的约束返回阶段 1

阶段 6：保存里程碑产物

docs/engineering-discipline/harness/<session-slug>/
├── state.md                      # Master state file
├── milestones/
│   ├── M1-<name>.md              # Individual milestone definition
│   ├── M2-<name>.md
│   └── ...
└── planning/
    ├── problem-brief.md          # includes Exploration Digest
    ├── draft-v1.md ... draft-vN.md
    ├── critiques/
    │   ├── round-1-complexity.md
    │   ├── round-1-dependency.md
    │   └── ...
    └── resolution-log.md         # Critique Resolution Log, all rounds

state.md 格式：

# Long Run State: [Session Name]

**Created:** YYYY-MM-DD HH:MM
**Last Updated:** YYYY-MM-DD HH:MM
**Status:** milestone-planning-complete | executing | paused | completing | completed | failed

**Verification Strategy:**
- **Level:** [e2e | integration | skill/agent | test-suite | build-only]
- **Command:** [exact verification command]
- **What it validates:** [what passing proves]

## Milestones

| ID | Name | Status | Attempts | Dependencies | Plan File | Review File |
|----|------|--------|----------|-------------|-----------|-------------|
| M1 | [name] | pending | 0 | — | — | — |
| M2 | [name] | pending | 0 | M1 | — | — |
| M3 | [name] | pending | 0 | M1, M2 | — | — |

Status values: pending | planning | executing | validating | completed | failed | skipped
Attempts: number of plan-execute-review cycles attempted (incremented at each Step 2-3 start)

## Execution Log

| Timestamp | Event | Details |
|-----------|-------|---------|
| YYYY-MM-DD HH:MM | milestones-locked | N milestones approved by user |

单个里程碑文件（M1-.md）格式：

# Milestone: [Name]

**ID:** M1
**Status:** pending
**Dependencies:** [None | M1, M2, ...]
**Risk:** [Low/Medium/High]
**Effort:** [Small/Medium/Large]

## Goal

[One sentence goal]

## Success Criteria

- [ ] [Binary-decidable criterion — answerable met/not-met by command or code inspection]
- [ ] [Binary-decidable criterion]
- [ ] [Binary-decidable criterion]

## Files Affected

- Create: [files to create]
- Modify: [files to modify]

## User Value

[What the user sees/can test after this milestone]

## Abort Point

[Yes/No — can user stop here and have something useful?]

## Notes

[Mitigations for open Concerns from the critique rounds; special considerations]

反模式

反模式	失败原因
评审问题陈述，而不是具体草案	只能提出建议，而不是发现问题；冲突直到执行时才会浮现
只起草一次，然后只做修订	多轮修订只能润色初始框架，无法跳出其限制；设置两个框架和结构性逃生方案，正是为了解决这个问题
不进行探索就起草	里程碑边界会沦为假设；评审者无法根据证据核查主张
按顺序运行评审者	浪费时间；评审者本来就是独立设计的
在解决评审意见前总结或弱化意见	会使发现经过起草者的偏见过滤；应原样记录
在没有修改草案或反驳的情况下将某项发现标为“已处理”	执行期间该问题会再次出现，届时要花数天而不是数分钟来解决
在多轮评审中重复使用同一个评审者实例	会受其先前评审意见影响，而不是评审修订后的草案
接受需要解释才能判定的标准	无法验证是否完成；“完成”会变得主观
创建过大的里程碑（每个 >12 项任务）	超出单次计划制定周期的承载范围；存在上下文丢失风险
创建过小的里程碑（每个 1-2 项任务）	计划制定、运行计划和审核工作的开销超过任务本身
未经用户批准创建超过 10 个里程碑	多个里程碑会累积风险；项目很可能需要拆分
允许用户跳过锁定审批	这是唯一的审批关卡——跳过就意味着在未经审核的计划下连续数天无人值守地执行

最小检查清单

• 起草前已派出并行探索 Agent
• 已编写问题简述，其中包含探索摘要和验证策略
• 已独立起草两份骨架（接口优先、风险优先）；已编写 DRAFT v1 并记录理由
• 草案 DAG 为每个里程碑引用了探索证据
• 每轮的所有审查者均已通过一条消息并行派出
• 每条评审意见均已逐字记录并解决（采纳并修改草案，或说明理由后驳回）
• 最后一轮未产生新的阻塞项（或已将争议提交给用户）
• 每个里程碑都有可通过二元判定的成功标准
• 里程碑 DAG 不存在循环依赖
• 已将集成验证里程碑追加为最后一个里程碑
• 用户已在锁定阶段批准里程碑计划
• 所有工件均已保存到框架状态目录

过渡

里程碑规划完成后：

• 开始执行 → long-run 技能
• 发现歧义 → 返回 clarification 技能
• 任务太小，无需拆分里程碑 → 直接使用 plan-crafting

此技能本身**不会调用下一项技能。**结束时会呈现里程碑计划，由用户选择下一步。