| name | plan-write |
| description | 读取 /plan-init 生成的 .plan/task.md，将任务列表写入 .plan/features.json 并创建开发日志。当用户说 "/plan-write"、"写入任务"、"完成初始化" 时触发。必须在 /plan-init 审批后运行。 |
Plan Write
读取 .plan/task.md，写入 .plan/features.json 和 .plan/dev log，完成初始化。
协议
步骤 1: 读取技术方案文档
使用 Read 工具读取 .plan/task.md，从中提取 ## 任务列表 章节下的完整 JSON 任务列表数组。
同时检查文档中是否包含 ## Test Cases 章节。如果有，提取其中的 JSON 内容（完整的 test-cases.json 格式），留待后续写入。
如果 .plan/task.md 不存在或无法提取任务列表，告知用户先运行 /plan-init。
步骤 2: 检查现有文件
检查是否已存在 .plan/features.json。
- 如果存在且非空，询问用户：覆盖（备份后）/ 追加 / 取消
- 如果不存在或为空，直接创建
步骤 3: 写入文件（按顺序执行全部操作）
操作 0：确保 .plan/ 目录存在
使用 Bash 工具执行 mkdir -p .plan，确保目录存在。
操作 0.5：多应用检测
扫描任务列表中所有任务的 appPath 字段：
- 单应用模式：所有任务都没有
appPath 字段，或所有任务的 appPath 相同 → 走原有逻辑（操作 1-4）
- 多应用模式：存在不同的
appPath → 走多应用写入流程（操作 M1-M4）
单应用模式（原有逻辑，不变）
操作 1：Write 工具 → 创建 .plan/dev-YYYY-MM-DD.log（YYYY-MM-DD 为当天日期）
=== Agent 初始化日志 ===
初始化时间: [ISO 时间戳]
格式: 增强结构化格式
日志类型参考:
- [Init] - 框架初始化
- [Explore] - 代码库探索
- [Pending] - 任务规划
- [TDD-Red] - 红灯确认
- [TDD-Green] - 绿灯验证
- [Completed] - 任务完成
- [Fix/Refactor/Optimization/Design/Test/Docs/Config] - 手动日志
所有条目按时间序写入本文件，通过 [Phase] Task N: 标签区分来源
---
[ISO 时间戳] [Init] Agent 框架设置
├─ Context: 用户初始化 Agent 进行结构化开发工作流
├─ Files: .plan/features.json（待创建）| .plan/dev-YYYY-MM-DD.log（本文件）
├─ Changes: 设置统一日志架构
├─ Tech: JSON 用于任务存储 | 统一日志文件简化管理
├─ Decision: 统一日志架构 → 简化管理，结构化标签保证可检索
└─ Result: 框架准备就绪，可定义项目目标和任务分解
---
操作 2：Write 工具 → 创建 .plan/features.json（原样写入完整任务列表）
将从 .plan/task.md 提取的任务列表 JSON 原样写入，保留 plan-init 生成的所有字段（domain、app、appPath、dependsOn、implementationGuide、apiContracts、boundary、references、dataSamples 等）。不得删减或简化字段。
格式示例：
[
{
"id": "1",
"domain": "backend",
"app": "order-service",
"appPath": "../order-service",
"dependsOn": [],
"complexity": "medium",
"category": "core",
"description": "实现用户列表查询接口",
"steps": ["创建 Controller", "实现 Service 层逻辑", "添加分页支持"],
"implementationGuide": {
"targetFiles": ["src/controller/UserController.java"],
"approach": "基于现有 BaseController 扩展",
"referenceCode": ["src/controller/OrderController.java:list()"],
"dataFlow": "请求参数 → Service 查询 → 分页封装 → 返回",
"keyInterfaces": ["UserService.listUsers(PageRequest)"]
},
"apiContracts": [
{
"method": "GET",
"path": "/api/users",
"description": "获取用户列表",
"request": { "query": { "page": "number", "size": "number" } },
"response": { "code": 200, "body": { "list": "User[]", "total": "number" } }
}
],
"acceptance": ["GET /api/users 返回分页用户列表", "支持 page 和 size 参数"],
"boundary": "只新增查询接口，不修改现有用户模块",
"test": "unit: UserController 单元测试 + integration: API 集成测试",
"references": ["OrderController.list() 的实现模式"],
"passes": false
},
{
"id": "2",
"domain": "frontend",
"dependsOn": ["1"],
"complexity": "medium",
"category": "ui",
"description": "实现用户列表页面，对接后端用户查询接口",
"steps": ["创建用户列表组件", "对接 GET /api/users 接口", "实现分页交互"],
"apiContracts": [
{
"method": "GET",
"path": "/api/users",
"description": "获取用户列表（来自任务 1）",
"request": { "query": { "page": "number", "size": "number" } },
"response": { "code": 200, "body": { "list": "User[]", "total": "number" } }
}
],
"acceptance": ["用户列表页正确展示数据", "分页功能正常"],
"test": "unit: 组件渲染测试 + e2e: 列表页交互测试",
"passes": false
}
]
操作 3：Edit 工具 → 追加任务分解日志到 .plan/dev-YYYY-MM-DD.log
[ISO 时间戳] [Init] 任务分解完成
├─ Context: 用户确认任务列表
├─ Tasks: [列出所有任务 ID 和简述]
├─ Files: .plan/features.json（已写入 N 个任务）
└─ Result: 任务已持久化，等待执行
---
操作 4：Edit 工具 → 追加初始化总结到 .plan/dev-YYYY-MM-DD.log
[ISO 时间戳] [Init] 初始化完成 - 准备执行
├─ Context: 框架设置完成，所有状态文件已创建
├─ Files: .plan/features.json（N 个任务）| .plan/dev-YYYY-MM-DD.log（3 条日志）
├─ Changes: 完成初始化 - 任务已定义，日志框架已设置
├─ Tech: 统一日志架构 | 基于 JSON 的任务管理
├─ Decision: 所有任务初始 passes:false → 需验证后才能标记完成
└─ Result: 系统准备好执行 /plan-next | 所有 N 个任务待处理
---
操作 5：Write 工具 → 创建 .plan/test-cases.json（仅当 .plan/task.md 含 Test Cases 章节时执行）
将从 .plan/task.md 的 ## Test Cases 章节中提取的 JSON 原样写入 .plan/test-cases.json。
如果 .plan/task.md 中不含 Test Cases 章节，跳过此操作。
多应用模式
当检测到多个不同 appPath 时，按应用分组写入。
操作 M1：为每个 app 创建目录和 features.json
对任务列表按 appPath 分组，对每个分组执行：
mkdir -p {appPath}/.plan- Write 工具 →
{appPath}/.plan/features.json（只包含该 app 的任务，JSON 数组格式，字段原样保留）
操作 M2：为每个 app 创建 dev log
对每个 appPath 执行：
Write 工具 → {appPath}/.plan/dev-YYYY-MM-DD.log，内容与单应用模式的操作 1 相同（=== Agent 初始化日志 === 模板），但 Files 行改为 {appPath}/.plan/features.json | {appPath}/.plan/dev-YYYY-MM-DD.log。
操作 M3：创建 app-registry.json 索引（含编译顺序）
Write 工具 → .plan/app-registry.json（当前编排目录）：
{
"apps": [
{ "app": "order-api", "appPath": "../order-api" },
{ "app": "order-service", "appPath": "../order-service" },
{ "app": "admin-web", "appPath": "../admin-web" }
],
"buildOrder": [
{
"app": "order-api",
"appPath": "../order-api",
"buildCmd": "mvn clean install -DskipTests -q",
"reason": "share 包，被 order-service 编译依赖（dependsOn）"
},
{
"app": "order-service",
"appPath": "../order-service",
"buildCmd": "mvn compile -q",
"reason": "业务服务，依赖 order-api"
},
{
"app": "admin-web",
"appPath": "../admin-web",
"buildCmd": null,
"reason": "前端应用，无编译依赖"
}
]
}
app 取自任务的 app 字段，appPath 取自任务的 appPath 字段。每个唯一的 app/appPath 组合一条记录。
buildOrder 推断规则：
从任务列表中的跨应用 dependsOn（app:id 格式）推断应用间的编译依赖链，生成拓扑排序后的构建顺序：
- 扫描所有任务的
dependsOn 字段，找出跨应用依赖（app:id 格式）
- 构建应用间的依赖图：如果 app B 的某个任务 dependsOn 了
app-A:X，则 app B 依赖 app A
- 拓扑排序：被依赖的应用排在前面
- 无跨应用依赖的应用可以并行执行（排序不分先后）
buildCmd 推断规则：
| 条件 | buildCmd |
|---|
| 被其他应用编译依赖的包（如 share/common/api 包） | mvn clean install -DskipTests -q（需安装到本地仓库） |
有 pom.xml 的普通后端应用 | mvn compile -q |
有 build.gradle 的应用 | gradle build -x test -q |
有 go.mod 的应用 | go build ./... |
前端应用（有 package.json） | null（前端不参与后端编译链） |
plan-next / backend-single / fullstack-single 在切换应用执行前，应先按 buildOrder 顺序执行依赖应用的 buildCmd（如果该应用有已完成的任务需要编译）。
操作 M4：追加日志到各 app 的 dev log
对每个 app 的 dev log 追加任务分解日志和初始化总结（同单应用模式的操作 3、操作 4，但任务列表只列该 app 的任务）。
操作 M5：Write 工具 → 创建测试用例文件（仅当 .plan/task.md 含 Test Cases 章节时执行）
将从 .plan/task.md 的 ## Test Cases 章节中提取的 JSON 写入测试用例文件。
写入位置根据 test-cases.json 中 serviceConfig.appPath 决定：
- 有 appPath → 写入
{appPath}/.plan/test-cases.json
- 无 appPath → 写入
.plan/test-cases.json
如果 .plan/task.md 中不含 Test Cases 章节，跳过此操作。
步骤 4: 输出确认
单应用模式：
✅ 初始化完成！
已创建:
• .plan/features.json - [N] 个任务已写入（全部 passes: false）
• .plan/dev-YYYY-MM-DD.log - 初始化日志已记录
• .plan/test-cases.json - [M] 个测试用例（[K] 个套件） ← 仅有测试用例时显示
日志架构:
→ 所有日志统一写入 .plan/dev-YYYY-MM-DD.log
→ 通过 [Phase] Task N: 标签区分来源，精准检索
下一步:
• 运行 /plan-next 开始第一个任务
多应用模式：
✅ 初始化完成！（多应用模式）
已创建:
[对每个 app 列出]
• {appPath}/.plan/features.json - [N] 个任务
• {appPath}/.plan/dev-YYYY-MM-DD.log - 初始化日志
[索引文件]
• .plan/app-registry.json - 应用索引（[M] 个应用）
[测试用例 - 仅有测试用例时显示]
• {appPath}/.plan/test-cases.json - [X] 个测试用例（[Y] 个套件）
下一步:
• 运行 /plan-next app=xxx 执行指定应用的任务
• 或运行 /plan-next 执行所有应用的任务（按依赖顺序）
⛔ 输出后立即停止，不得自动执行任务或调用 /plan-next。
