@miniidealab/openlogos 0.3.3 → 0.3.5

package/dist/index.js

@@ -38,7 +38,7 @@ Examples:
 
 Learn more: https://openlogos.ai
 `;
-const VERSION = '0.3.3';
+const VERSION = '0.3.5';
 async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miniidealab/openlogos",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "CLI tool for the OpenLogos software engineering methodology",
   "type": "module",
   "bin": {

package/skills/api-designer/SKILL.en.md

@@ -188,6 +188,22 @@ If gaps are found, supplement them before outputting the final version.
 - Error responses uniformly reference `$ref: '#/components/schemas/ErrorResponse'`
 - Every endpoint's `description` must annotate the source sequence diagram step
 
+## YAML Formatting Rules (MUST Follow)
+
+YAML is whitespace- and character-sensitive. AI-generated YAML frequently breaks due to unquoted special characters. **Strictly follow these rules:**
+
+1. **Always double-quote `description` and `summary` values** — any string containing `:`, `→`, `#`, `&`, `*`, `!`, `>`, `|`, `%`, `@`, `` ` ``, `{`, `}`, `[`, or `]` MUST be wrapped in `"..."`.
+   ```yaml
+   # ❌ WRONG — colon + arrow breaks YAML parsing
+   description: Source: S05 Step 1 → Step 4.
+
+   # ✅ CORRECT
+   description: "Source: S05 Step 1 → Step 4."
+   ```
+2. **Always quote response status code keys** — use `'201'` not `201` to prevent YAML interpreting them as integers.
+3. **Self-check after generation** — after generating each YAML file, mentally re-parse it to verify no unquoted special characters exist. Pay special attention to `description` fields that reference scenario steps (they always contain `:`).
+4. **When in doubt, quote it** — quoting a safe string is harmless; leaving a dangerous string unquoted breaks the entire file.
+
 ## Best Practices
 
 - **APIs emerge from sequence diagrams**: If an API cannot be traced back to a sequence diagram, it most likely should not exist. Design sequence diagrams first, then APIs — not the other way around

package/skills/api-designer/SKILL.md

@@ -188,6 +188,22 @@ paths:
 - 错误响应统一引用 `$ref: '#/components/schemas/ErrorResponse'`
 - 每个端点的 `description` 必须标注来源时序图步骤
 
+## YAML 格式规则（必须遵守）
+
+YAML 对空白和特殊字符敏感。AI 生成的 YAML 经常因为特殊字符未加引号而导致解析失败。**必须严格遵守以下规则：**
+
+1. **`description` 和 `summary` 的值必须用双引号包裹** — 任何包含 `:`、`→`、`#`、`&`、`*`、`!`、`>`、`|`、`%`、`@`、`` ` ``、`{`、`}`、`[`、`]` 的字符串都必须用 `"..."` 包裹。
+   ```yaml
+   # ❌ 错误 — 冒号和箭头导致 YAML 解析失败
+   description: 来源：S05 Step 1 → Step 4.
+
+   # ✅ 正确
+   description: "来源：S05 Step 1 → Step 4."
+   ```
+2. **响应状态码 key 必须加引号** — 使用 `'201'` 而非 `201`，防止 YAML 将其解析为整数。
+3. **生成后自检** — 每生成一个 YAML 文件后，重新审视是否存在未加引号的特殊字符。尤其注意引用场景步骤的 `description` 字段（它们总是包含 `:`）。
+4. **拿不准就加引号** — 给安全字符串加引号无害，但漏掉危险字符串的引号会导致整个文件解析失败。
+
 ## 实践经验
 
 - **API 从时序图浮现**：如果一个 API 在时序图中找不到出处，它大概率不应该存在。先画时序图再设计 API，而非反过来

package/skills/change-writer/SKILL.en.md

@@ -99,6 +99,7 @@ Automatically break down the task checklist based on the change type and impact
 ## Phase 3: Technical Changes
 - [ ] Update sequence diagram for S0x
 - [ ] Update API YAML
+- [ ] **Validate API YAML** — all files in `logos/resources/api/` must be valid YAML and valid OpenAPI 3.x (all `description`/`summary` values containing `:` or special chars must be double-quoted)
 - [ ] Update DB DDL
 - [ ] Update orchestration test cases
 - [ ] Implement code changes

package/skills/change-writer/SKILL.md

@@ -99,6 +99,7 @@
 ## Phase 3: 技术变更
 - [ ] 更新 S0x 的时序图
 - [ ] 更新 API YAML
+- [ ] **验证 API YAML** — `logos/resources/api/` 下所有文件必须为有效 YAML 且符合 OpenAPI 3.x 规范（所有包含 `:` 或特殊字符的 `description`/`summary` 值必须用双引号包裹）
 - [ ] 更新 DB DDL
 - [ ] 更新编排测试用例
 - [ ] 实现代码变更

package/skills/code-reviewer/SKILL.en.md

@@ -32,7 +32,11 @@ For projects without APIs (pure CLI / libraries), API consistency checks can be
 
 ### Step 1: Load Specification Context
 
-Read the following files to establish a "reference baseline" for the code review:
+**Pre-check — YAML Validity (before anything else):**
+
+Before loading API specs, validate that all `logos/resources/api/*.yaml` files are syntactically valid YAML and conform to the OpenAPI 3.x schema. If any file fails parsing (e.g., unquoted special characters in `description` fields), report it as a **Critical** blocker immediately — do not proceed with the rest of the review until YAML errors are fixed.
+
+**Then** read the following files to establish a "reference baseline" for the code review:
 
 - **API YAML** (`logos/resources/api/*.yaml`): Extract endpoint inventory, record each endpoint's path, method, request body schema, response schema, and status codes
 - **Scenario Sequence Diagrams** (`logos/resources/prd/3-technical-plan/2-scenario-implementation/`): Extract all EX exception case IDs and expected behaviors
@@ -64,6 +68,7 @@ Compare code implementation against API YAML specification endpoint by endpoint:
 | Response Fields | Whether JSON field names and types returned by code match YAML `responses.schema` | Critical |
 | Status Codes | Whether HTTP status codes returned in normal and error cases match YAML definitions | Critical |
 | Error Response Format | Whether error responses follow the unified `{ code, message, details? }` format | Warning |
+| YAML Validity | All `logos/resources/api/*.yaml` files parse as valid YAML and valid OpenAPI 3.x — unquoted special characters (`:`, `→`, `#`) in `description`/`summary` values are a common failure mode | Critical |
 
 **Output format**:
 

package/skills/code-reviewer/SKILL.md

@@ -32,7 +32,11 @@
 
 ### Step 1: 加载规格上下文
 
-读取以下文件，建立代码审查的"参照基准"：
+**前置检查 — YAML 有效性（优先于一切）：**
+
+在加载 API 规格之前，先验证所有 `logos/resources/api/*.yaml` 文件是否为有效 YAML 且符合 OpenAPI 3.x 规范。如果任何文件解析失败（例如 `description` 字段中特殊字符未加引号），立即报告为 **Critical** 阻塞项——在 YAML 错误修复前不进行后续审查。
+
+**然后**读取以下文件，建立代码审查的"参照基准"：
 
 - **API YAML**（`logos/resources/api/*.yaml`）：提取端点清单，记录每个端点的路径、方法、请求体 schema、响应 schema、状态码
 - **场景时序图**（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）：提取所有 EX 异常用例编号和预期行为
@@ -64,6 +68,7 @@
 | 响应字段 | 代码返回的 JSON 字段名和类型是否与 YAML 中 `responses.schema` 一致 | Critical |
 | 状态码 | 正常和异常情况下返回的 HTTP 状态码是否与 YAML 定义一致 | Critical |
 | 错误响应格式 | 错误响应是否遵循 `{ code, message, details? }` 统一格式 | Warning |
+| YAML 有效性 | `logos/resources/api/*.yaml` 所有文件是否为有效 YAML 且符合 OpenAPI 3.x 规范——`description`/`summary` 值中未加引号的特殊字符（`:`、`→`、`#`）是常见故障点 | Critical |
 
 **输出格式**：
 

package/skills/prd-writer/SKILL.en.md

@@ -49,8 +49,8 @@ Assign a number to each pain point (`P01`, `P02`...) for scenario traceability.
 Extract business scenarios from pain points and requirements. Each scenario is a **complete user action path**:
 
 - **Who** triggers it under **what circumstances**
-- Through **what steps**
-- To achieve **what outcome**
+- Through **what steps** (must involve multiple interactions, not a single API call)
+- To achieve **what business outcome** (a value the user can perceive)
 
 Assign a globally unique number to each scenario (`S01`, `S02`...). This number will carry through to Phase 2 and Phase 3.
 
@@ -64,6 +64,33 @@ Output a scenario list table:
 | S03  | Forgot Password     | User cannot log in         | P02                | P1       |
 ```
 
+#### Scenario Granularity Self-Check (MUST Pass)
+
+After generating the scenario list, run these 4 tests. **If any test fails, re-organize the scenarios before proceeding.**
+
+1. **Single-API Test**: If a scenario can be completed with just 1 API call, it is NOT a scenario — it is an operation. Merge it into a larger scenario.
+2. **CRUD Test**: If the scenario list contains "Create X", "Read X", "Update X", "Delete X" as 4 separate scenarios, the granularity is too fine. Re-organize by user goals (e.g., "Manager plans weekly tasks" instead of "Create task" + "Assign task" + "Update task" + "Delete task").
+3. **Business Value Test**: Describe in one sentence the value the user gains after completing the scenario. If the answer is merely "data was written/read/deleted", there is no real business goal — merge the scenario into a goal-driven one.
+4. **Step Count Test**: A scenario's main path must contain at least 3 user-perceivable steps. Fewer than 3 means the granularity is too fine.
+
+#### ❌ Anti-Pattern: One API = One Scenario
+
+```markdown
+| S01 | Create Task    | User clicks "New"       |
+| S02 | Get Task List  | User opens the page      |
+| S03 | Update Task    | User edits a task        |
+| S04 | Delete Task    | User deletes a task      |
+→ This is an API inventory, NOT a scenario list!
+```
+
+#### ✅ Correct: Organize by Business Goals
+
+```markdown
+| S01 | Team Lead Plans Weekly Tasks   | Lead logs in → creates tasks → sets priority & deadline → assigns to members → members receive notifications |
+| S02 | Developer Completes & Delivers | Dev views to-do → updates progress → marks complete → lead is notified and reviews |
+| S03 | Lead Reviews Project Progress  | Lead opens dashboard → filters by status/member → exports weekly report |
+```
+
 ### Step 4: Write Scenario Acceptance Criteria
 
 Write acceptance criteria for every P0 and P1 scenario:
@@ -153,8 +180,8 @@ Because [reason] → leads to [pain point] → results in [consequence]
 ## Best Practices
 
 - **Cast a wide net first, then narrow down**: In the first pass, identify as many scenarios as possible, then cut non-core ones during prioritization
-- **Scenarios ≠ Features**: A single feature (e.g., "user authentication") may contain multiple scenarios (registration, login, password recovery); a single scenario (e.g., "first purchase") may span multiple features (browsing, adding to cart, payment). A scenario is a "complete path from the user's perspective"
-- **Scenario granularity**: Keep granularity moderate in Phase 1. Too fine-grained ("user clicks the input box") is meaningless; too coarse ("user uses the product") is unverifiable. Good granularity: the main path of a scenario can be walked through in 1–2 minutes
+- **Scenarios ≠ Features, Scenarios ≠ APIs**: A scenario is a "complete path from the user's perspective to achieve a business goal". A single feature (e.g., "user authentication") may contain multiple scenarios (registration, login, password recovery); a single scenario (e.g., "first purchase") may span multiple features (browsing, adding to cart, payment). **Never define a single CRUD operation as a standalone scenario.**
+- **Scenario granularity**: Keep granularity moderate in Phase 1. Too fine-grained ("user creates a record") is just an API call; too coarse ("user uses the product") is unverifiable. Good granularity: the main path of a scenario can be walked through in 1–2 minutes and involves at least 3 distinct steps
 - **Acceptance criteria are the precise expression of requirements**: If you cannot write GIVEN/WHEN/THEN, the scenario is not yet well thought out
 - **Exception scenarios are equally important**: Users don't always follow the happy path — exception handling often defines the product experience
 - **The "won't-do" list is the hardest to write**: Restraint is the most important skill of a product manager

package/skills/prd-writer/SKILL.md

@@ -49,8 +49,8 @@
 从痛点和需求中提取业务场景。每个场景是一个**完整的用户操作路径**：
 
 - **谁**在**什么情况下**触发
-- 经过**什么步骤**
-- 达到**什么结果**
+- 经过**什么步骤**（必须包含多个交互环节，不能只是单个 API 调用）
+- 达到**什么业务成果**（用户可感知的价值）
 
 为每个场景分配全局唯一编号（`S01`, `S02`...），这个编号将一路带到 Phase 2 和 Phase 3。
 
@@ -64,6 +64,33 @@
 | S03  | 忘记密码 | 用户无法登录 | P02 | P1 |
 ```
 
+#### 场景粒度自检（必须通过）
+
+生成场景清单后，运行以下 4 项测试。**任何一项不通过，必须重新组织场景后再继续。**
+
+1. **单 API 测试**：如果一个场景只需要调用 1 个 API 就能完成，它不是场景——它是一个操作。应将其合并到更大的场景中。
+2. **CRUD 测试**：如果场景清单中出现"创建X"、"查询X"、"更新X"、"删除X"作为 4 个独立场景，说明粒度过细。应按用户目标重新组织（例如用"负责人规划周任务"代替"创建任务"+"分配任务"+"更新任务"+"删除任务"）。
+3. **业务价值测试**：用一句话描述场景完成后用户获得的价值。如果答案只是"数据被写入/读取/删除了"，说明缺少真正的业务目标——应合并到有明确目标的场景中。
+4. **步骤数测试**：一个场景的主路径至少包含 3 个用户可感知的步骤。少于 3 个说明粒度过细。
+
+#### ❌ 反模式：一个 API = 一个场景
+
+```markdown
+| S01 | 创建任务   | 用户点击"新建"   |
+| S02 | 获取任务列表 | 用户打开页面     |
+| S03 | 更新任务   | 用户编辑任务     |
+| S04 | 删除任务   | 用户删除任务     |
+→ 这是 API 清单，不是场景清单！
+```
+
+#### ✅ 正确：按业务目标组织场景
+
+```markdown
+| S01 | 团队负责人规划周任务 | 负责人登录 → 创建多个任务 → 设置优先级和截止日期 → 分配给成员 → 成员收到通知 |
+| S02 | 开发者完成并交付任务 | 开发者查看待办 → 更新进度 → 标记完成 → 负责人收到通知并审核 |
+| S03 | 负责人查看项目进度   | 负责人打开看板 → 按状态/成员筛选 → 导出周报 |
+```
+
 ### Step 4: 编写场景验收条件
 
 为每个 P0 和 P1 场景编写验收条件：
@@ -153,8 +180,8 @@
 ## 实践经验
 
 - **先宽后窄**：第一轮尽可能多地识别场景，然后在优先级排序时砍掉非核心的
-- **场景 ≠ 功能**：一个功能（如"用户认证"）可能包含多个场景（注册、登录、找回密码）；一个场景（如"首次购买"）可能跨多个功能（浏览、加购、支付）。场景是"用户视角的完整路径"
-- **场景粒度**：Phase 1 阶段保持适中粒度。过细（"用户点击输入框"）没有意义，过粗（"用户使用产品"）无法验收。好的粒度是：一个场景能在 1-2 分钟内走完主路径
+- **场景 ≠ 功能，场景 ≠ API**：场景是"用户视角为达成业务目标而走过的完整路径"。一个功能（如"用户认证"）可能包含多个场景（注册、登录、找回密码）；一个场景（如"首次购买"）可能跨多个功能（浏览、加购、支付）。**绝不要将单个 CRUD 操作定义为独立场景。**
+- **场景粒度**：Phase 1 阶段保持适中粒度。过细（"用户创建一条记录"）只是一次 API 调用，过粗（"用户使用产品"）无法验收。好的粒度是：一个场景能在 1-2 分钟内走完主路径，且至少包含 3 个不同步骤
 - **验收条件是需求的精确表达**：如果写不出 GIVEN/WHEN/THEN，说明场景还没想清楚
 - **异常场景同等重要**：用户不可能总是走正常路径，异常处理往往决定产品体验
 - **"不做"清单是最难写的**：克制是产品经理最重要的能力

package/skills/product-designer/SKILL.en.md

@@ -40,6 +40,8 @@ Read the Phase 1 requirements document and extract:
 - Constraints and boundaries → determine product type
 - `tech_stack` in `logos-project.yaml` → confirm technical form
 
+**Scenario Granularity Check**: While reading the scenario list, watch for signs that scenarios are actually single CRUD operations (e.g., "Create Task", "Get Task List", "Update Task", "Delete Task" as 4 separate scenarios). If detected, recommend returning to Phase 1 to re-organize scenarios by business goals before proceeding with product design. Designing interactions for CRUD-level "scenarios" will produce shallow specs that don't reflect real user workflows.
+
 Output the product type determination and rationale for the prototype strategy selection.
 
 ### Step 2: Design Information Architecture

package/skills/product-designer/SKILL.md

@@ -40,6 +40,8 @@
 - 约束与边界 → 判断产品类型
 - `logos-project.yaml` 的 `tech_stack` → 确认技术形态
 
+**场景粒度检查**：在阅读场景列表时，留意场景是否实际上是单个 CRUD 操作（如"创建任务"、"获取任务列表"、"更新任务"、"删除任务"作为 4 个独立场景）。如果发现此模式，建议回到 Phase 1 按业务目标重新组织场景，再进行产品设计。为 CRUD 级别的"场景"设计交互规格只会产出浅层规格，无法反映真实的用户工作流。
+
 输出产品类型判断和原型策略选择理由。
 
 ### Step 2: 设计信息架构

package/skills/scenario-architect/SKILL.en.md

@@ -36,6 +36,16 @@
 
 Read scenario definitions from the Phase 1 requirements document, Phase 2 product design document, and Phase 3 Step 0 technical architecture summary. **Do not reinvent scenarios**—directly reuse existing numbers and descriptions. Participant naming should be consistent with the system components in the architecture diagram.
 
+**Scenario Granularity Pre-Check (before drawing any sequence diagram):**
+
+Before proceeding, verify that the scenario definitions from Phase 1 have proper granularity. Check for these anti-patterns:
+
+- **One-API scenarios**: If a scenario's main path only has 1-2 steps (e.g., "Create Task" = just `POST /api/tasks`), it is too fine-grained
+- **CRUD fragmentation**: If the scenario list contains separate "Create X", "Read X", "Update X", "Delete X" scenarios for the same entity, they should be merged into goal-driven scenarios
+- **No business goal**: If a scenario's outcome is just "data was written/read", it lacks a real user goal
+
+**If any anti-pattern is detected**: Stop and recommend returning to Phase 1 to re-organize scenarios by business goals before drawing sequence diagrams. Drawing sequence diagrams for overly fine-grained scenarios will propagate the problem to API design, test cases, and code.
+
 Confirm the following for each scenario:
 - **Scenario number**: Reuse Phase 1's `S01`, `S02`... (or Phase 2 sub-scenarios `S01.1`)
 - **Participants**: Identify which system components are involved from Phase 2's interaction flows

package/skills/scenario-architect/SKILL.md

@@ -36,6 +36,16 @@
 
 读取 Phase 1 需求文档、Phase 2 产品设计文档和 Phase 3 Step 0 技术架构概要中的场景定义。**不要重新发明场景**——直接沿用已有编号和描述。参与方命名应与架构图中的系统组件保持一致。
 
+**场景粒度前置检查（绘制时序图之前必须执行）：**
+
+在继续之前，先验证 Phase 1 中的场景定义是否粒度合理。检查以下反模式：
+
+- **单 API 场景**：如果一个场景的主路径只有 1-2 个步骤（如"创建任务"= 仅 `POST /api/tasks`），粒度过细
+- **CRUD 碎片化**：如果场景列表中对同一实体出现了独立的"创建X"、"查询X"、"更新X"、"删除X"场景，应合并为目标导向的场景
+- **缺少业务目标**：如果场景的结果只是"数据被写入/读取了"，说明缺少真正的用户目标
+
+**如果检测到以上任何反模式**：停止绘制时序图，建议回到 Phase 1 按业务目标重新组织场景。为粒度过细的场景绘制时序图会将问题传导到 API 设计、测试用例和代码实现。
+
 确认每个场景的：
 - **场景编号**：沿用 Phase 1 的 `S01`, `S02`...（或 Phase 2 的子场景 `S01.1`）
 - **参与方**：从 Phase 2 的交互流程中识别涉及哪些系统组件