@miniidealab/openlogos 0.2.0 → 0.3.1

package/skills/merge-executor/SKILL.en.md

@@ -0,0 +1,84 @@
+# Skill: Merge Executor
+
+> Read the MERGE_PROMPT.md instruction file generated by the CLI, and merge each delta file from the change proposal into the main documents one by one, ensuring changes are applied accurately.
+
+## Trigger Conditions
+
+- User requests AI to execute the merge after running `openlogos merge <slug>`
+- User mentions "execute merge", "merge", "merge the deltas into the main documents"
+- User mentions "read MERGE_PROMPT.md and execute"
+
+## Prerequisites
+
+1. `logos/changes/<slug>/MERGE_PROMPT.md` exists (generated by the `openlogos merge` command)
+2. The delta files and target main documents referenced in MERGE_PROMPT.md all exist
+
+If MERGE_PROMPT.md does not exist, prompt the user to run `openlogos merge <slug>` first.
+
+## Core Capabilities
+
+1. Parse merge instructions from MERGE_PROMPT.md
+2. Read each delta file and interpret ADDED / MODIFIED / REMOVED markers
+3. Precisely locate the corresponding sections in the main document and execute the merge
+4. Maintain formatting and style consistency of the main document
+5. Output a change summary
+
+## Execution Steps
+
+### Step 1: Read Merge Instructions
+
+Read `logos/changes/<slug>/MERGE_PROMPT.md` and parse:
+- Change proposal name and overview
+- Each delta file's path, corresponding target main document path, and operation type
+
+### Step 2: Merge Each Delta File
+
+Process delta files one by one in the order listed in MERGE_PROMPT.md:
+
+1. **Read the delta file**: Understand the ADDED / MODIFIED / REMOVED markers and content
+2. **Read the target main document**: Locate the sections that need modification
+3. **Execute the merge**:
+   - `ADDED`: Insert new content at the specified position in the main document
+   - `MODIFIED`: Replace the content of the same-named section in the main document
+   - `REMOVED`: Delete the corresponding section from the main document
+4. **Output summary**: List what modifications were made to the file
+
+### Step 3: Output Overall Change Report
+
+After all deltas have been processed, output:
+
+```
+Merge complete:
+- [file path 1]: added x sections, modified y sections, deleted z sections
+- [file path 2]: ...
+
+Please verify the changes are correct, then run `openlogos archive <slug>` to archive the proposal.
+```
+
+## Merge Principles
+
+1. **Maintain format consistency**: Merged content must match the existing format, indentation, and heading levels of the main document
+2. **Do not alter unrelated content**: Only modify the parts specified by the delta; do not reformat the entire document
+3. **Ask on conflict**: If a section referenced by the delta cannot be found in the main document (possibly already modified by another change), pause and ask the user how to proceed
+4. **Confirm after each file**: Show a modification summary after processing each delta file, and wait for user confirmation before processing the next one
+
+## Output Specification
+
+- Directly modify the main documents in `logos/resources/` (in-place editing)
+- Do not modify any files in `logos/changes/`
+- Do not create new files during the merge (unless a delta specifies adding a completely new document)
+
+## Best Practices
+
+- **Read everything before acting**: Read through all delta files and target documents first to understand the full picture, then merge one by one
+- **MODIFIED is the most error-prone**: Section titles may have minor differences (capitalization, spacing) — fuzzy matching is needed
+- **Preserve change traces**: If the main document has a "last updated" timestamp, remember to update it accordingly
+- **Delta order matters**: Requirement document changes should be processed before API document changes to ensure upstream-downstream consistency
+
+## Recommended Prompts
+
+The following prompts can be copied directly for AI use:
+
+- `Read logos/changes/<slug>/MERGE_PROMPT.md and execute the merge`
+- `Help me merge the add-remember-me changes into the main documents`
+- `Execute the change merge`

package/skills/merge-executor/SKILL.md

@@ -0,0 +1,84 @@
+# Skill: Merge Executor
+
+> 读取 CLI 生成的 MERGE_PROMPT.md 指令文件，将变更提案中的 delta 文件逐个合并到主文档，确保变更准确落地。
+
+## 触发条件
+
+- 用户运行完 `openlogos merge <slug>` 后要求 AI 执行合并
+- 用户提到"执行合并"、"merge"、"把 delta 合进主文档"
+- 用户提到"读取 MERGE_PROMPT.md 并执行"
+
+## 前置依赖
+
+1. `logos/changes/<slug>/MERGE_PROMPT.md` 存在（由 `openlogos merge` 命令生成）
+2. MERGE_PROMPT.md 中引用的 delta 文件和目标主文档均存在
+
+如果 MERGE_PROMPT.md 不存在，提示用户先运行 `openlogos merge <slug>`。
+
+## 核心能力
+
+1. 解析 MERGE_PROMPT.md 中的合并指令
+2. 逐个读取 delta 文件，理解 ADDED / MODIFIED / REMOVED 标记
+3. 精准定位主文档中的对应章节并执行合并
+4. 保持主文档的格式和风格一致性
+5. 输出变更摘要
+
+## 执行步骤
+
+### Step 1: 读取合并指令
+
+读取 `logos/changes/<slug>/MERGE_PROMPT.md`，解析出：
+- 变更提案名称和概述
+- 每个 delta 文件的路径、对应的目标主文档路径、操作类型
+
+### Step 2: 逐个 Delta 文件执行合并
+
+按 MERGE_PROMPT.md 中列出的顺序，逐个处理 delta 文件：
+
+1. **读取 delta 文件**：理解 ADDED / MODIFIED / REMOVED 标记及内容
+2. **读取目标主文档**：定位需要修改的章节
+3. **执行合并**：
+   - `ADDED`：在主文档的指定位置插入新内容
+   - `MODIFIED`：替换主文档中同名章节的内容
+   - `REMOVED`：从主文档中删除对应章节
+4. **输出摘要**：列出对该文件做了哪些修改
+
+### Step 3: 输出总体变更报告
+
+所有 delta 处理完毕后，输出：
+
+```
+合并完成：
+- [文件路径 1]：新增 x 节，修改 y 节，删除 z 节
+- [文件路径 2]：...
+
+请确认修改无误后，运行 `openlogos archive <slug>` 归档提案。
+```
+
+## 合并原则
+
+1. **保持格式一致**：合并后的内容必须与主文档的现有格式、缩进、标题层级保持一致
+2. **不改动无关内容**：只修改 delta 指定的部分，不重新格式化整个文档
+3. **冲突时询问**：如果主文档中找不到 delta 引用的章节（可能已被其他变更修改），暂停并询问用户如何处理
+4. **逐文件确认**：处理完每个 delta 文件后展示修改摘要，等待用户确认后再处理下一个
+
+## 输出规范
+
+- 直接修改 `logos/resources/` 中的主文档（就地编辑）
+- 不修改 `logos/changes/` 中的任何文件
+- 合并过程中不创建新文件（除非 delta 指定新增一个全新的文档）
+
+## 实践经验
+
+- **先全部读完再动手**：先通读所有 delta 文件和目标文档，理解全貌后再逐个合并
+- **MODIFIED 是最容易出错的**：章节标题可能有微小差异（大小写、空格），需要模糊匹配
+- **保留变更痕迹**：如果主文档有"最后更新"时间戳，记得同步更新
+- **delta 的顺序有意义**：需求文档的变更应在 API 文档之前处理，确保上下游一致
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `读取 logos/changes/<slug>/MERGE_PROMPT.md 并执行合并`
+- `帮我把 add-remember-me 的变更合并到主文档`
+- `执行变更合并`

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

@@ -0,0 +1,171 @@
+# Skill: PRD Writer
+
+> Assist in writing scenario-driven requirements documents — starting from user pain points, identifying core business scenarios, and defining GIVEN/WHEN/THEN acceptance criteria for each scenario. Scenario numbers will carry through all subsequent phases.
+
+## Trigger Conditions
+
+- User requests writing a requirements document, product requirements, or PRD
+- User discusses product positioning, target users, or feature requirements
+- User mentions "Phase 1", "requirements layer", or "WHY"
+- The project is currently in the requirements analysis phase
+
+## Core Capabilities
+
+1. Guide users through product positioning and target user profiling
+2. Extract user pain points and establish causal chains
+3. Identify and define business scenarios from pain points (assigning `S01`, `S02`... numbers)
+4. Write GIVEN/WHEN/THEN acceptance criteria for each scenario
+5. Prioritize scenarios
+6. Identify constraints and the "won't-do" list
+7. Generate scenario-driven requirements documents conforming to the OpenLogos specification
+
+## Execution Steps
+
+### Step 1: Understand Product Positioning
+
+Confirm the following key questions with the user (proactively ask if information is insufficient):
+
+- **One-line positioning**: What is this product? For whom? What problem does it solve?
+- **Target user persona**: Specific enough to describe a real person
+- **Core objectives**: What should the product achieve, and what metrics define success
+
+### Step 2: Extract User Pain Points
+
+Guide the user to identify pain points from the following dimensions:
+
+- How does the user currently do it? (Current state)
+- What difficulties are encountered in the process? (Pain points)
+- What consequences do the difficulties cause? (Impact)
+- How does the user expect it to be resolved? (Expectation)
+
+**Every pain point must have a causal chain**: Because [reason] → leads to [pain point] → results in [consequence]
+
+Assign a number to each pain point (`P01`, `P02`...) for scenario traceability.
+
+### Step 3: Identify and Define Scenarios
+
+**Scenarios are the anchor throughout the entire development lifecycle.** This step is critical.
+
+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**
+
+Assign a globally unique number to each scenario (`S01`, `S02`...). This number will carry through to Phase 2 and Phase 3.
+
+Output a scenario list table:
+
+```markdown
+| ID   | Scenario Name      | Trigger Condition          | Related Pain Point | Priority |
+|------|--------------------|----------------------------|--------------------|----------|
+| S01  | Email Registration  | New user's first visit     | P01                | P0       |
+| S02  | Password Login      | Registered user returns    | P01                | P0       |
+| S03  | Forgot Password     | User cannot log in         | P02                | P1       |
+```
+
+### Step 4: Write Scenario Acceptance Criteria
+
+Write acceptance criteria for every P0 and P1 scenario:
+
+```markdown
+### S01: Email Registration
+
+- **Trigger Condition**: New user's first visit, clicks "Sign Up"
+- **User Value**: Quickly create an account and start using the product (← P01)
+- **Priority**: P0
+- **Main Path**: User fills in email and password, submits the form, receives a verification email, clicks the link to complete registration
+
+#### Acceptance Criteria
+
+##### Normal: Complete registration flow
+- **GIVEN** the user has not registered before and is on the registration page
+- **WHEN** the user fills in a valid email and password (≥8 characters) and clicks "Sign Up"
+- **THEN** the system creates an account, sends a verification email, and the page displays "Please check your email for verification"
+
+##### Exception: Email already registered
+- **GIVEN** the email test@example.com is already registered
+- **WHEN** the user attempts to register using test@example.com
+- **THEN** the page displays "This email is already registered, please log in directly" and no email is sent
+
+##### Exception: Password does not meet requirements
+- **GIVEN** the user is on the registration page
+- **WHEN** the user fills in a valid email but a password with fewer than 8 characters and clicks "Sign Up"
+- **THEN** the page displays "Password must be at least 8 characters" and the request is not submitted
+```
+
+**Principles for writing acceptance criteria**:
+
+- Each scenario must have at least 1 normal + 1 exception acceptance criterion
+- GIVEN describes the initial state — specific enough to be reproducible
+- WHEN describes the user action — precise down to the button level
+- THEN describes the expected behavior — specific enough to be verifiable
+- Avoid vague wording: "fast", "friendly", "reasonable" → quantify with concrete metrics
+
+### Step 5: Identify Constraints and Boundaries
+
+- **Technical constraints**: Technology stack limitations, third-party service limitations
+- **Resource constraints**: Team size, time window
+- **"Won't-do" list**: Explicitly list features and scenarios that are out of scope for this phase to prevent scope creep
+
+### Step 6: Assemble the Requirements Document
+
+Output the complete document in the standard structure:
+
+```markdown
+# [Product Name] Requirements Document
+
+> Last updated: [date]
+
+## I. Product Background and Goals
+### 1.1 Product Positioning
+### 1.2 Core Objectives
+### 1.3 Target User Persona
+
+## II. User Pain Point Analysis
+### P01: [Pain Point Name]
+Because [reason] → leads to [pain point] → results in [consequence]
+### P02: ...
+
+## III. Scenario Overview
+[Scenario list table: ID / Name / Trigger Condition / Related Pain Point / Priority]
+
+## IV. Core Scenario Details
+### S01: [Scenario Name]
+[Trigger Condition + User Value + Priority + Main Path + Acceptance Criteria]
+### S02: ...
+
+## V. Constraints and Boundaries
+### 5.1 Technical Constraints
+### 5.2 Resource and Time Constraints
+### 5.3 "Won't-Do" List
+```
+
+## Output Specification
+
+- File format: Markdown
+- Storage location: `logos/resources/prd/1-product-requirements/`
+- File naming: `{sequence}-{english-name}.md`, e.g., `01-requirements.md`
+- Every scenario must be traceable to at least one user pain point
+- P0/P1 scenarios must have GIVEN/WHEN/THEN (≥1 normal + ≥1 exception)
+- Scenario numbers are globally unique and will carry through Phase 2 and Phase 3
+
+## 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
+- **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
+- **Once a scenario number is assigned, it is never reused**: Even if a scenario is deprecated, its number is not recycled, to avoid confusion
+- **Requirements documents are living documents**: They are continuously updated as the product evolves, with every change tracked through Delta change management
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with an AI:
+
+- `Help me write a requirements document`
+- `I want to build a xxx product, help me sort out the requirements`
+- `Help me organize these ideas into a structured requirements document`
+- `Help me add exception scenario acceptance criteria to an existing requirements document`

package/skills/prd-writer/SKILL.md

@@ -0,0 +1,171 @@
+# Skill: PRD Writer
+
+> 辅助撰写场景驱动的需求文档——从用户痛点出发，识别核心业务场景，为每个场景定义 GIVEN/WHEN/THEN 验收条件。场景编号将贯穿后续所有阶段。
+
+## 触发条件
+
+- 用户要求写需求文档、产品需求或 PRD
+- 用户讨论产品定位、目标用户、功能需求
+- 用户提到 "Phase 1"、"需求层"、"WHY"
+- 当前处于项目的需求分析阶段
+
+## 核心能力
+
+1. 引导用户梳理产品定位和目标用户
+2. 提炼用户痛点，建立因果链
+3. 从痛点中识别和定义业务场景（分配 `S01`, `S02`... 编号）
+4. 为每个场景编写 GIVEN/WHEN/THEN 验收条件
+5. 排列场景优先级
+6. 识别约束和"不做"清单
+7. 生成符合 OpenLogos 规范的场景驱动需求文档
+
+## 执行步骤
+
+### Step 1: 理解产品定位
+
+与用户确认以下核心问题（如果信息不足则主动追问）：
+
+- **一句话定位**：这个产品是什么？为谁？解决什么问题？
+- **目标用户画像**：具体到可以描述一个真实的人
+- **核心目标**：产品要达成什么，用什么指标衡量成功
+
+### Step 2: 提炼用户痛点
+
+引导用户从以下维度梳理痛点：
+
+- 用户当前是怎么做的？（现状）
+- 做的过程中遇到什么困难？（痛点）
+- 困难导致了什么后果？（影响）
+- 用户期望怎么被解决？（期望）
+
+**每条痛点必须有因果链**：因为 [原因] → 导致 [痛点] → 造成 [后果]
+
+为每条痛点分配编号（`P01`, `P02`...），便于场景追溯。
+
+### Step 3: 识别和定义场景
+
+**场景是贯穿整个研发周期的锚。** 这一步至关重要。
+
+从痛点和需求中提取业务场景。每个场景是一个**完整的用户操作路径**：
+
+- **谁**在**什么情况下**触发
+- 经过**什么步骤**
+- 达到**什么结果**
+
+为每个场景分配全局唯一编号（`S01`, `S02`...），这个编号将一路带到 Phase 2 和 Phase 3。
+
+输出场景清单表：
+
+```markdown
+| 编号 | 场景名称 | 触发条件 | 关联痛点 | 优先级 |
+|------|---------|---------|---------|--------|
+| S01  | 邮箱注册 | 新用户首次访问 | P01 | P0 |
+| S02  | 密码登录 | 已注册用户返回 | P01 | P0 |
+| S03  | 忘记密码 | 用户无法登录 | P02 | P1 |
+```
+
+### Step 4: 编写场景验收条件
+
+为每个 P0 和 P1 场景编写验收条件：
+
+```markdown
+### S01: 邮箱注册
+
+- **触发条件**：新用户首次访问，点击注册
+- **用户价值**：快速创建账号开始使用产品（← P01）
+- **优先级**：P0
+- **主路径**：用户填写邮箱和密码，提交后收到验证邮件，点击验证完成注册
+
+#### 验收条件
+
+##### 正常：完整注册流程
+- **GIVEN** 用户未注册过，且在注册页面
+- **WHEN** 用户填写有效邮箱和密码（≥8位），点击「注册」
+- **THEN** 系统创建账号，发送验证邮件，页面显示「请查收验证邮件」
+
+##### 异常：邮箱已注册
+- **GIVEN** 邮箱 test@example.com 已注册
+- **WHEN** 用户使用 test@example.com 尝试注册
+- **THEN** 显示「该邮箱已注册，请直接登录」，不发送任何邮件
+
+##### 异常：密码不符合要求
+- **GIVEN** 用户在注册页面
+- **WHEN** 用户填写有效邮箱但密码少于 8 位，点击「注册」
+- **THEN** 显示「密码至少 8 位」，不提交请求
+```
+
+**验收条件编写原则**：
+
+- 每个场景至少 1 个正常 + 1 个异常验收条件
+- GIVEN 描述初始状态，要具体到可复现
+- WHEN 描述用户操作，要精确到按钮级别
+- THEN 描述期望行为，要具体到可验证
+- 避免模糊词汇："快速"、"友好"、"合理" → 量化为具体指标
+
+### Step 5: 识别约束和边界
+
+- **技术约束**：技术栈限制、第三方服务限制
+- **资源约束**：团队规模、时间窗口
+- **"不做"清单**：明确列出本阶段不做的功能和场景，避免范围蠕变
+
+### Step 6: 组装需求文档
+
+按标准结构输出完整文档：
+
+```markdown
+# [产品名称] 需求文档
+
+> 最后更新：[日期]
+
+## 一、产品背景与目标
+### 1.1 产品定位
+### 1.2 核心目标
+### 1.3 目标用户画像
+
+## 二、用户痛点分析
+### P01: [痛点名称]
+因为 [原因] → 导致 [痛点] → 造成 [后果]
+### P02: ...
+
+## 三、场景总览
+[场景清单表：编号 / 名称 / 触发条件 / 关联痛点 / 优先级]
+
+## 四、核心场景详述
+### S01: [场景名称]
+[触发条件 + 用户价值 + 优先级 + 主路径 + 验收条件]
+### S02: ...
+
+## 五、约束与边界
+### 5.1 技术约束
+### 5.2 资源与时间约束
+### 5.3 "不做"清单
+```
+
+## 输出规范
+
+- 文件格式：Markdown
+- 存放位置：`logos/resources/prd/1-product-requirements/`
+- 文件命名：`{序号}-{英文名}.md`，如 `01-requirements.md`
+- 每个场景必须可追溯到至少一个用户痛点
+- P0/P1 场景必须有 GIVEN/WHEN/THEN（≥1 正常 + ≥1 异常）
+- 场景编号全局唯一，将贯穿 Phase 2 和 Phase 3
+
+## 实践经验
+
+- **先宽后窄**：第一轮尽可能多地识别场景，然后在优先级排序时砍掉非核心的
+- **场景 ≠ 功能**：一个功能（如"用户认证"）可能包含多个场景（注册、登录、找回密码）；一个场景（如"首次购买"）可能跨多个功能（浏览、加购、支付）。场景是"用户视角的完整路径"
+- **场景粒度**：Phase 1 阶段保持适中粒度。过细（"用户点击输入框"）没有意义，过粗（"用户使用产品"）无法验收。好的粒度是：一个场景能在 1-2 分钟内走完主路径
+- **验收条件是需求的精确表达**：如果写不出 GIVEN/WHEN/THEN，说明场景还没想清楚
+- **异常场景同等重要**：用户不可能总是走正常路径，异常处理往往决定产品体验
+- **"不做"清单是最难写的**：克制是产品经理最重要的能力
+- **场景编号一旦分配不复用**：即使场景被废弃，编号也不回收，避免混淆
+- **需求文档是活文档**：随着产品演进持续更新，通过 Delta 变更管理跟踪每次变化
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我写需求文档`
+- `我要做一个 xxx 产品，帮我梳理需求`
+- `帮我把这些想法整理成结构化的需求文档`
+- `帮我给现有需求文档补充异常场景的验收条件`