@miniidealab/openlogos 0.3.3 → 0.3.4

package/dist/index.js

@@ -38,7 +38,7 @@ Examples:
 
 Learn more: https://openlogos.ai
 `;
-const VERSION = '0.3.3';
+const VERSION = '0.3.4';
 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.4",
   "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 |
 
 **输出格式**：