scrum-skills 0.3.2 → 0.3.3

package/package.json

@@ -1,41 +1,42 @@
-{
-  "name": "scrum-skills",
-  "version": "0.3.2",
-  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，Nuxt 看板可视化",
-  "type": "module",
-  "keywords": [
-    "agile",
-    "scrum",
-    "sprint",
-    "tdd",
-    "kanban",
-    "gantt",
-    "burndown",
-    "skills",
-    "cli"
-  ],
-  "bin": {
-    "scrum-skills": "./bin/scrum-skills.mjs",
-    "scsk": "./bin/scrum-skills.mjs"
-  },
-  "scripts": {
-    "validate": "node tools/validate.mjs",
-    "serve": "node tools/serve.mjs",
-    "test": "node --test",
-    "dev": "pnpm --dir apps/board run dev",
-    "build": "node scripts/build-board.mjs",
-    "prepublishOnly": "node scripts/build-board.mjs"
-  },
-  "files": [
-    "bin/",
-    "tools/",
-    "templates/",
-    ".agents/",
-    "assets/",
-    "docs/"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "MIT"
-}
+{
+  "name": "scrum-skills",
+  "version": "0.3.3",
+  "description": "结构化敏捷开发管理 skills + CLI：AI 对话产出结构化敏捷数据，TDD 驱动实施，Nuxt 看板可视化",
+  "type": "module",
+  "keywords": [
+    "agile",
+    "scrum",
+    "sprint",
+    "tdd",
+    "kanban",
+    "gantt",
+    "burndown",
+    "skills",
+    "cli"
+  ],
+  "bin": {
+    "scrum-skills": "./bin/scrum-skills.mjs",
+    "scsk": "./bin/scrum-skills.mjs"
+  },
+  "scripts": {
+    "validate": "node tools/validate.mjs",
+    "serve": "node tools/serve.mjs",
+    "test": "node --test",
+    "dev": "pnpm --dir apps/board run dev",
+    "build": "node scripts/build-board.mjs",
+    "sync:diagram": "node scripts/sync-diagram-skill.mjs",
+    "prepublishOnly": "node scripts/build-board.mjs"
+  },
+  "files": [
+    "bin/",
+    "tools/",
+    "templates/",
+    ".agents/",
+    "assets/",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/templates/AGENTS.md

@@ -1,74 +1,84 @@
-# AGENTS.md
-
-本项目采用结构化敏捷开发管理。**任何 agent（CodeBuddy / Claude Code / Cursor 等）在本项目内工作前，必须先读本文件并遵守以下纪律。**
-
-## 强制规则
-
-1. **数据是唯一事实来源**。所有需求、任务、进度状态以 `agile/` 目录下的 JSON 文件为准，对话记忆一律不作数。每次接手工作先读 `agile/` 掌握现状，再决定下一步。
-2. **必须使用敏捷 skills**（位于 `.agents/skills/`），按场景加载，不要全量加载（省上下文）：
-   - 需求澄清（brainstorming 式逐问收敛）、写故事、拆任务 → **scrum-planning**
-   - 排期、组建迭代、状态流转、收尾回顾 → **scrum-sprint**
-   - 领取任务写代码（TDD 循环 + 实施日志落库；含系统化排障纪律与交工前真实验证）→ **scrum-tdd**
-   - 看板/燃尽图/追溯链可视化 → **scrum-report**
-3. **对话产出必须落库**。凡是确认要做的事，必须写进 `agile/backlog.json`（结构见 `.agents/skills/scrum-planning/references/schema.md`），禁止只停留在对话里。每条故事必须带 `type` / `priority` / `value`，验收标准必须带 `verifyBy`；依赖写 `dependsOn`，被卡住写 `blocked`，中途插入或拆分出来的写 `scopeChange`——这些不写进 JSON，看板和甘特图就读不到。
-4. **TDD 铁律**：任务实施走 red → green → refactor 循环，没写过失败测试不许写实现；每步过程必须当场追加到 `agile/journal.json` 里对应 task 的 `entries`（不许事后补记）。
-5. **测试资产随任务收口登记**。task 推到 `done`、story 送进 `review` 之前，必须把本次新增 / 修改的用例与执行结果写进 **`agile/tests.json`**（结构见 schema 第 5 节）：
-   - 用例挂在 suite 下，`covers` 指向验收（`S-001-A1`），`expect` 写清预期结果；手工验证也要登记成 `automated: false` 的用例，`steps` 逐步写；
-   - 每次跑完测试追加一条 `runs`（命令 / 环境 / 总数 / 通过 / 失败 / 跳过 / 失败用例），并刷新对应用例的 `status` 与 `lastRun`；
-   - **没真跑过不许写 `pass`**；story 到 `review` 时每条验收至少被一条用例覆盖（校验器会查，缺口在 `/tests` 页的「缺口与风险」里）。
-6. **每次修改敏捷数据后必须运行校验**，校验不过不许继续：
-
-   ```bash
-   node tools/validate.mjs
-   ```
-
-   动了 `tools/validate.mjs` 本身则要跑回归测试，确认没把既有规则弄回退：
-
-   ```bash
-   pnpm test
-   ```
-
-7. **可视化**：
-
-   ```bash
-   node tools/serve.mjs        # http://localhost:4173 看板 / 燃尽图 / 测试用例 / story 追溯链
-   ```
-
-8. **每次功能开发完毕必须交工汇报**。task 推到 `done` 之后、向用户回话之前，把本次交付写进 **`agile/last-change.json`**（结构见 `.agents/skills/scrum-planning/references/schema.md` 第 4 节）。**写之前先查 git**：文件已提交就整份覆盖；还有没提交的改动就把本次结果并进旧记录，别冲掉还没入库的那一次。用 `node tools/last-change.mjs write <记录.json>` 写，它自己判状态、合并、写后校验、失败回滚。然后按同一顺序告诉用户：
-   1. 本次涉及的故事与任务：新增还是状态变更、变更内容、对应涉及文件（用表格）；
-   2. 额外做了什么事情（计划外的修复、文档、重构）；
-   3. 验证了哪些结果（命令 / 手工核对的结论，含没验到的边界）；
-   4. 调试访问地址与账号密码；
-   5. 测试前的准备动作（装依赖、起服务、灌数据，带命令）；
-   6. 单独列出每个测试场景：测试步骤 + 验收标准；
-   7. 最后的说明（口径、已知限制、遗留项）。
-
-   这七项按项目实际情况给——没有账号体系就不提账号，没有前端入口就不提地址，没有的就省略，**但不许编，也不许只回一句「做完了」**。看板「最后更新」（`/last-change`）页渲染的就是这个文件。
-
-## 状态机（摘要）
-
-- story: `draft → ready → in-progress → review → done`；不做就走 `cancelled`（已取消，终态，不要求验收与任务全 done）
-- task: `todo → red → green → refactored → done`（只能前进；task 状态编码了 TDD 阶段）
-- 详细规则与硬约束见 `.agents/skills/scrum-planning/references/schema.md`。
-
-## 目录索引
-
-| 路径 | 内容 |
-|---|---|
-| `.agents/skills/` | 四个敏捷 skill（planning / sprint / tdd / report） |
-| `agile/backlog.json` | 史诗 epics + 用户故事 stories（story 内联 tasks） |
-| `agile/sprints.json` | 迭代 sprints + 里程碑 milestones（MVP 节点 = `kind: "mvp"`） |
-| `agile/journal.json` | 每个 task 一条 TDD 实施日志（内联 entries） |
-| `agile/tests.json` | 测试资产：suites（层 × 级别 → cases，含 covers 映射与最近状态）+ runs（执行记录与代码覆盖率）；可选文件 |
-| `agile/last-change.json` | 最近一次交付的汇报（已提交才覆盖，未提交则合并）：变更清单 / 额外工作 / 验证 / 入口与账号 / 测试前准备 / 测试场景 / 说明 |
-| `tools/validate.mjs` | 数据校验（引用完整性 / 状态机 / TDD 纪律 / 测试资产 / 里程碑达成 / 交付说明） |
-| `tools/last-change.mjs` | 交付说明的写入工具：`check` 判 git 状态、`write` 自动覆盖或合并 + 写后校验回滚 |
-| `tools/serve.mjs` | 看板 server（`/api/agile` + 托管 Nuxt 静态产物） |
-| `apps/board/` | Nuxt 看板源码（看板 / 最后更新 / 甘特图 / 里程碑 / 燃尽图 / 测试用例 / 故事追溯） |
-| `assets/board/` | 看板静态产物，由 `serve` 托管；**不进 git**，用 `pnpm board:build` 重建（`npm publish` 的 prepack 会自动跑一次） |
-| `scripts/build-board.mjs` | 构建看板：`apps/board` → `assets/board` |
-| `tests/` | 校验器回归测试（`pnpm test`，18 个用例） |
-| `docs/` | README 配图 |
-| `README.md` | 包说明（npm 页面） |
-
-`agile/` 数据文件里目前是一整套演示数据（3 史诗 / 16 故事 / 4 迭代 / 5 里程碑 / 39 任务），正式使用前清空这些文件的数组即可。
+# AGENTS.md
+
+本项目采用结构化敏捷开发管理。**任何 agent（CodeBuddy / Claude Code / Cursor 等）在本项目内工作前，必须先读本文件并遵守以下纪律。**
+
+## 强制规则
+
+1. **数据是唯一事实来源**。所有需求、任务、进度状态以 `agile/` 目录下的 JSON 文件为准，对话记忆一律不作数。每次接手工作先读 `agile/` 掌握现状，再决定下一步。
+2. **必须使用敏捷 skills**（位于 `.agents/skills/`），按场景加载，不要全量加载（省上下文）：
+   - 需求澄清（brainstorming 式逐问收敛）、写故事、拆任务 → **scrum-planning**
+   - 排期、组建迭代、状态流转、收尾回顾 → **scrum-sprint**
+   - 领取任务写代码（TDD 循环 + 实施日志落库；含系统化排障纪律与交工前真实验证）→ **scrum-tdd**
+   - 看板/燃尽图/追溯链可视化 → **scrum-report**
+3. **对话产出必须落库**。凡是确认要做的事，必须写进 `agile/backlog.json`（结构见 `.agents/skills/scrum-planning/references/schema.md`），禁止只停留在对话里。每条故事必须带 `type` / `priority` / `value`，验收标准必须带 `verifyBy`；依赖写 `dependsOn`，被卡住写 `blocked`，中途插入或拆分出来的写 `scopeChange`——这些不写进 JSON，看板和甘特图就读不到。
+4. **TDD 铁律**：任务实施走 red → green → refactor 循环，没写过失败测试不许写实现；每步过程必须当场追加到 `agile/journal.json` 里对应 task 的 `entries`（不许事后补记）。
+5. **测试资产随任务收口登记**。task 推到 `done`、story 送进 `review` 之前，必须把本次新增 / 修改的用例与执行结果写进 **`agile/tests.json`**（结构见 schema 第 5 节）：
+   - 用例挂在 suite 下，`covers` 指向验收（`S-001-A1`），`expect` 写清预期结果；手工验证也要登记成 `automated: false` 的用例，`steps` 逐步写；
+   - 每次跑完测试追加一条 `runs`（命令 / 环境 / 总数 / 通过 / 失败 / 跳过 / 失败用例），并刷新对应用例的 `status` 与 `lastRun`；
+   - **没真跑过不许写 `pass`**；story 到 `review` 时每条验收至少被一条用例覆盖（校验器会查，缺口在 `/tests` 页的「缺口与风险」里）。
+6. **每次修改敏捷数据后必须运行校验**，校验不过不许继续：
+
+   ```bash
+   node tools/validate.mjs
+   ```
+
+   动了 `tools/validate.mjs` 本身则要跑回归测试，确认没把既有规则弄回退：
+
+   ```bash
+   pnpm test
+   ```
+
+7. **可视化**：
+
+   ```bash
+   node tools/serve.mjs        # http://localhost:4173 看板 / 燃尽图 / 测试用例 / story 追溯链
+   ```
+
+8. **每次功能开发完毕必须交工汇报**。task 推到 `done` 之后、向用户回话之前，把本次交付写进 **`agile/last-change.json`**（结构见 `.agents/skills/scrum-planning/references/schema.md` 第 4 节）。**写之前先查 git**：文件已提交就整份覆盖；还有没提交的改动就把本次结果并进旧记录，别冲掉还没入库的那一次。用 `node tools/last-change.mjs write <记录.json>` 写，它自己判状态、合并、写后校验、失败回滚。然后按同一顺序告诉用户：
+   1. 本次涉及的故事与任务：新增还是状态变更、变更内容、对应涉及文件（用表格）；
+   2. 额外做了什么事情（计划外的修复、文档、重构）；
+   3. 验证了哪些结果（命令 / 手工核对的结论，含没验到的边界）；
+   4. 调试访问地址与账号密码；
+   5. 测试前的准备动作（装依赖、起服务、灌数据，带命令）；
+   6. 单独列出每个测试场景：测试步骤 + 验收标准；
+   7. 最后的说明（口径、已知限制、遗留项）。
+
+   这七项按项目实际情况给——没有账号体系就不提账号，没有前端入口就不提地址，没有的就省略，**但不许编，也不许只回一句「做完了」**。看板「最后更新」（`/last-change`）页渲染的就是这个文件。
+
+9. **架构图例用内置的 diagram-design，不许让用户另外安装**。改动涉及模块边界 / 鉴权 / 支付 / 数据模型 / 外部集成时，交工前出图或重画：
+   - 读 `.agents/skills/diagram-design/SKILL.md`（随包分发，**不依赖 Python**），按其 §3 选型并先加载 `references/type-<type>.md`；
+   - 产物丢进 `agile/diagrams/`，用 `node tools/diagram.mjs add <file> --title "..." --kind sequence --story S-001` 登记，
+     它会先跑 `node tools/diagram-lint.mjs` 质检，不过不许入库；
+   - 索引 `agile/diagrams.json` 只由工具写，**不要手改**（结构见 schema 第 6 节）。
+
+## 状态机（摘要）
+
+- story: `draft → ready → in-progress → review → done`；不做就走 `cancelled`（已取消，终态，不要求验收与任务全 done）
+- task: `todo → red → green → refactored → done`（只能前进；task 状态编码了 TDD 阶段）
+- 详细规则与硬约束见 `.agents/skills/scrum-planning/references/schema.md`。
+
+## 目录索引
+
+| 路径 | 内容 |
+|---|---|
+| `.agents/skills/` | 四个敏捷 skill（planning / sprint / tdd / report） |
+| `agile/backlog.json` | 史诗 epics + 用户故事 stories（story 内联 tasks） |
+| `agile/sprints.json` | 迭代 sprints + 里程碑 milestones（MVP 节点 = `kind: "mvp"`） |
+| `agile/journal.json` | 每个 task 一条 TDD 实施日志（内联 entries） |
+| `agile/tests.json` | 测试资产：suites（层 × 级别 → cases，含 covers 映射与最近状态）+ runs（执行记录与代码覆盖率）；可选文件 |
+| `agile/diagrams.json` | 架构图例索引（自包含 HTML 产物在 `agile/diagrams/` 下）；可选文件 |
+| `.agents/skills/diagram-design/` | 内置的 diagram-design skill（架构 / 时序 / ER 图；不含 Python 脚本） |
+| `tools/diagram.mjs` | 图例入库：质检 → 分配 id → 落盘 → 建索引 → 校验回滚 |
+| `tools/diagram-lint.mjs` | 出图质检（安全 / 文档完整性 / 无障碍 / viewBox 越界 / 动画契约） |
+| `agile/last-change.json` | 最近一次交付的汇报（已提交才覆盖，未提交则合并）：变更清单 / 额外工作 / 验证 / 入口与账号 / 测试前准备 / 测试场景 / 说明 |
+| `tools/validate.mjs` | 数据校验（引用完整性 / 状态机 / TDD 纪律 / 测试资产 / 里程碑达成 / 交付说明） |
+| `tools/last-change.mjs` | 交付说明的写入工具：`check` 判 git 状态、`write` 自动覆盖或合并 + 写后校验回滚 |
+| `tools/serve.mjs` | 看板 server（`/api/agile` + 托管 Nuxt 静态产物） |
+| `apps/board/` | Nuxt 看板源码（看板 / 最后更新 / 甘特图 / 里程碑 / 燃尽图 / 测试用例 / 故事追溯） |
+| `assets/board/` | 看板静态产物，由 `serve` 托管；**不进 git**，用 `pnpm board:build` 重建（`npm publish` 的 prepack 会自动跑一次） |
+| `scripts/build-board.mjs` | 构建看板：`apps/board` → `assets/board` |
+| `tests/` | 校验器回归测试（`pnpm test`，18 个用例） |
+| `docs/` | README 配图 |
+| `README.md` | 包说明（npm 页面） |
+
+`agile/` 数据文件里目前是一整套演示数据（3 史诗 / 16 故事 / 4 迭代 / 5 里程碑 / 39 任务），正式使用前清空这些文件的数组即可。