plan-write

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 分组，对每个分组执行：

1. mkdir -p {appPath}/.plan
2. 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 格式）推断应用间的编译依赖链，生成拓扑排序后的构建顺序：

1. 扫描所有任务的 dependsOn 字段，找出跨应用依赖（app:id 格式）
2. 构建应用间的依赖图：如果 app B 的某个任务 dependsOn 了 app-A:X，则 app B 依赖 app A
3. 拓扑排序：被依赖的应用排在前面
4. 无跨应用依赖的应用可以并行执行（排序不分先后）

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。