planning

name	planning
version	1.3.0
status	implemented
description	规划阶段 - 任务拆分和计划制定 正式规划链: .specs/<feature>/spec.md → plan.md → tasks.md → .contract.json task_plan.md 已降级为兼容投影层，供旧 runtime/frontier 读取 v1.3: 新增 planning_mode 字段标识规划模式
tags	["phase","planning"]
requires	{"tools":["Bash","Read","Write","Grep","Glob"]}

PLANNING

Preamble

{{include: ../_shared/preamble.md}}

Overview

PLANNING 阶段负责把任务拆成可以执行和验证的步骤。

默认策略: defer。复杂任务会进入正式规划链，但 skill 注入本身保持轻量， 避免把规划阶段做成默认重型上下文。

正式规划链 (spec-kit):

1. .specs/<feature>/spec.md - 用户故事和需求
2. .specs/<feature>/plan.md - 技术方案和约束
3. .specs/<feature>/tasks.md - 可执行任务清单
4. .contract.json - 履约契约（goals/verification/owned_files）

规划模式 (planning_mode):

模式	说明	触发条件
canonical	使用完整spec-kit	tasks.md 存在
legacy	使用 task_plan.md	task_plan.md 存在但无tasks.md
lightweight	轻量TodoWrite	XS/S 复杂度

在开始拆分前，优先检查当前 phase 上下文里的 memory_hints、memory_query 和 memory_intent。 如果长期记忆里已经有相似失败、重复约束或已验证的修复模式，规划时应先复用这些经验，再决定是否新增任务。

兼容投影层 (legacy):

• task_plan.md - 仍可读取，供旧 runtime/frontier 使用
• 不再作为主要输出

Entry Criteria

满足以下任一条件时进入 PLANNING：

• 用户要求计划、规划、拆分
• 任务明显涉及多个文件或步骤
• 执行前需要先定义范围、验收和顺序

Exit Criteria (按复杂度分级)

根据复杂度，以下条件必须全部满足才能退出 PLANNING 进入 EXECUTING：

XS/S: TodoWrite 已列出所有任务项（每项有验收标准） M: .specs/<feature>/tasks.md 已创建 + .contract.json 已生成 L/XL: 完整 spec-kit 已创建 + .contract.json 非 draft + 每个 P0 任务有 owned_files

禁止在没有任何计划产出的情况下进入 EXECUTING。

Iron Law: NO EXECUTING WITHOUT A PLAN FIRST

XS/S 复杂度（简单任务）

• 使用 TodoWrite 列出任务项即可，跳过 .specs/ 流程
• 不需要 .contract.json

M 复杂度（中等任务）

• .specs/<feature>/spec.md 已创建（用户故事 + 验收标准）
• .specs/<feature>/plan.md 已创建（技术方案 + 约束）
• .specs/<feature>/tasks.md 已创建（可执行任务清单）
• .contract.json 已创建或准备生成（用于履约门禁）
• task_plan.md 仅作为 legacy 投影，可选生成

L/XL 复杂度（复杂任务）

• .specs/<feature>/spec.md 已创建（用户故事 + 验收标准）
• .specs/<feature>/plan.md 已创建（技术方案 + 约束）
• .specs/<feature>/tasks.md 已创建（可执行任务清单）
• .contract.json 已创建（非 draft 状态）
• 每个关键任务都有验收方式和 owned_files

Auto-Verify

# 优先验证正式 spec 链；legacy task_plan 仅在兼容模式下接受
test -d .specs && find .specs -mindepth 1 -type f | grep -q . || test -f task_plan.md

Current File Conventions

正式规划链 (spec-kit):

阶段	文件	说明
需求	.specs/<feature>/spec.md	用户故事、验收标准
方案	.specs/<feature>/plan.md	技术方案、约束
任务	.specs/<feature>/tasks.md	可执行任务清单
履约	.contract.json	履约契约

兼容投影层 (legacy, 只读):

• task_plan.md - 旧 runtime/frontier 仍可读取

Core Process

1. Clarify Scope

• 提炼一句话目标
• 识别硬约束
• 明确不做什么

2. Break Work Down

优先拆成 P0 / P1 / P2：

• P0: 不完成就无法交付
• P1: 重要但不阻塞主路径
• P2: 优化项

每个任务至少包含：

• status
• description
• acceptance
• owned_files
• verification

3. Create Spec Artifacts

使用 workflow_engine 创建规范文件：

python3 scripts/workflow_engine.py --op init --prompt "任务描述"

或手动创建规范链：

mkdir -p .specs/<feature>/
# 创建 spec.md, plan.md, tasks.md

4. Create Contract

基于 plan.md 和 tasks.md 创建履约契约：

python3 -c "from contract_manager import create_phase_contract; create_phase_contract('任务名', '描述', '.')"

5. Output Contract Visualization（PLANNING 结束时必须输出）

PLANNING 阶段结束时，必须向用户输出可读的履约摘要：

## 📋 任务契约

**目标**: {一句话目标}
**复杂度**: {XS/S/M/L/XL}
**预计阶段**: {阶段序列}

### P0 任务（必须完成）
- [ ] {任务1} — 验收: {验收条件}
- [ ] {任务2} — 验收: {验收条件}

### P1 任务（重要）
- [ ] {任务3}

### 明确不做
- {不在范围内的事项}

**进入 EXECUTING 后，AI 将按上述顺序逐项执行。**

此摘要让用户在 EXECUTING 开始前确认范围，避免执行偏差。

Minimal Plan Schema

spec.md 应包含：

• 用户故事 (### Story N:)
• 验收标准 (Acceptance Criteria:)
• 成功标准 (## Success Criteria)
• 约束条件 (## Constraints)

plan.md 应包含：

• Goals

• Technical Context

• Structure Decisions

• Constraints

tasks.md 应包含：

• User Story 1

• User Story 2

• 每个任务含 Files, Verification, Blocked-By

Validation

最小验证命令：

# 使用 spec-kit 验证工具
bash scripts/check_template.sh .

# 创建规范链（spec -> plan -> tasks -> contract）
python3 -m task_decomposer --from-spec --feature-id myfeature
python3 -c "from contract_manager import create_phase_contract; create_phase_contract('任务名', '描述', '.')"

Windows:

scripts\win\check_template.bat .

Implemented Vs Planned

以下内容当前不应视为已落地的 planning runtime：

• 复杂状态机自动推进
• Dev Agent Record 自动持久化
• trajectory 自动写回 .specs/<feature>/tasks.md 的 legacy 投影（task_plan.md）
• HARD-GATE 自动评分系统

这些能力如果需要，应在脚本层实现后再回填文档。