@miniidealab/openlogos 0.4.3 → 0.5.3

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

@@ -92,6 +92,27 @@ CREATE TABLE users (
 );
 ```
 
+**Example (SQLite — using `@comment` structured annotations)**:
+
+```sql
+-- Users table (source: auth.yaml → register, login)
+CREATE TABLE users (
+  -- @comment User unique identifier, UUID v4 string
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment User email, normalized to lowercase
+  email TEXT NOT NULL UNIQUE,
+  -- @comment Argon2id password hash, stores hash only
+  password_hash TEXT NOT NULL,
+  -- @comment Creation time, ISO 8601 format
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment Last update time
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+-- @table-comment users Users table storing core registered user information
+```
+
+> **SQLite Comment Convention**: SQLite does not support `COMMENT ON` syntax. You MUST use `-- @comment` preceding annotations (for columns) and `-- @table-comment <table> <description>` trailing annotations (for tables). See `logos/spec/sql-comment-convention.md` for details.
+
 ### Step 4: Design Table Relationships
 
 Design foreign keys based on entity relationships in the API:
@@ -153,29 +174,42 @@ Organize the DDL file in the following order:
 3. Association tables (tables with foreign key dependencies after)
 4. Indexes
 5. Security policies (RLS / Policy)
-6. Table and field comments (PostgreSQL uses `COMMENT ON`)
+6. Table and field comments:
+   - PostgreSQL: use `COMMENT ON TABLE` / `COMMENT ON COLUMN`
+   - MySQL: use inline `COMMENT`
+   - SQLite: use `-- @comment` (columns) + `-- @table-comment` (tables), see SQLite comment rules below
 
 Add a comment above each DDL block noting the source API endpoint.
 
+**SQLite Comment Rules (MUST Follow)**:
+
+When `tech_stack.database` is SQLite, you MUST use the following structured comment format:
+
+1. **Column comments**: write `-- @comment <description>` on the line **immediately above** the column definition
+   - **No blank lines** allowed between `-- @comment` and the column (blank lines break the association)
+   - Multi-line: consecutive `-- @comment` lines are concatenated automatically
+2. **Table comments**: write `-- @table-comment <table_name> <description>` on the line **immediately after** `CREATE TABLE ... ();`
+3. Constraint lines (`FOREIGN KEY`, standalone `CHECK`, `UNIQUE`) do **not** need `-- @comment`
+
 ## Output Specification
 
 - File format: SQL (dialect determined by `tech_stack.database`)
 - Storage location: `logos/resources/database/`
 - Single file output: `schema.sql` (simple projects); or split by domain: `auth.sql`, `billing.sql` (complex projects)
-- Every table must have a comment (PostgreSQL: `COMMENT ON TABLE`; MySQL: `COMMENT = '...'`)
-- Every field must have a comment (PostgreSQL: `COMMENT ON COLUMN`; MySQL: `COMMENT '...'` after field definition)
+- Every table must have a comment (PostgreSQL: `COMMENT ON TABLE`; MySQL: `COMMENT = '...'`; SQLite: `-- @table-comment`)
+- Every field must have a comment (PostgreSQL: `COMMENT ON COLUMN`; MySQL: `COMMENT '...'` after field definition; SQLite: `-- @comment`)
 - Add a SQL comment above each DDL block noting the source API endpoint
 
 ## Database Dialect Quick Reference
 
-| Feature | PostgreSQL | MySQL |
-|---------|-----------|-------|
-| UUID Primary Key | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` or use `BINARY(16)` |
-| Timestamp Type | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP` (mind timezone handling) |
-| JSON Support | `JSONB` (indexable) | `JSON` (limited functionality) |
-| Row-Level Security | RLS (`ENABLE ROW LEVEL SECURITY`) | Not supported; must be implemented at the application layer |
-| Table Comment | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` |
-| Column Comment | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` |
+| Feature | PostgreSQL | MySQL | SQLite |
+|---------|-----------|-------|--------|
+| UUID Primary Key | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` or `BINARY(16)` | `TEXT PRIMARY KEY NOT NULL` (app-generated UUID) |
+| Timestamp Type | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP` (mind timezone handling) | `TEXT` (ISO 8601 string) |
+| JSON Support | `JSONB` (indexable) | `JSON` (limited functionality) | `TEXT` (app-layer JSON serialization) |
+| Row-Level Security | RLS (`ENABLE ROW LEVEL SECURITY`) | Not supported; application layer | Not supported; application layer |
+| Table Comment | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` | `-- @table-comment t description` |
+| Column Comment | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` | `-- @comment description` (preceding line) |
 
 ## Best Practices
 
@@ -202,6 +236,14 @@ Add a comment above each DDL block noting the source API endpoint.
 - **Character set**: specify `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` when creating tables
 - **Engine**: always use `ENGINE=InnoDB`
 
+### SQLite-Specific
+
+- **Primary key**: `TEXT PRIMARY KEY NOT NULL` (app-generated UUID v4) or `INTEGER PRIMARY KEY AUTOINCREMENT`
+- **Timestamp type**: use `TEXT` with ISO 8601 strings, default `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`
+- **Foreign keys**: must execute `PRAGMA foreign_keys = ON;` at connection time
+- **Comments**: MUST use `-- @comment` / `-- @table-comment` structured annotations (see `logos/spec/sql-comment-convention.md`)
+- **No triggers**: `updated_at` must be refreshed at the application layer; do not rely on `ON UPDATE` triggers
+
 ## Recommended Prompts
 
 The following prompts can be copied directly for use with AI:

package/skills/db-designer/SKILL.md

@@ -92,6 +92,27 @@ CREATE TABLE users (
 );
 ```
 
+**示例（SQLite — 使用 `@comment` 结构化注释）**：
+
+```sql
+-- 用户表（来源：auth.yaml → register, login）
+CREATE TABLE users (
+  -- @comment 用户唯一标识，UUID v4 字符串
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 用户邮箱，已归一化为小写
+  email TEXT NOT NULL UNIQUE,
+  -- @comment Argon2id 密码哈希，仅存哈希
+  password_hash TEXT NOT NULL,
+  -- @comment 创建时间，ISO 8601 格式
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment 最后更新时间
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+-- @table-comment users 用户表，存储注册用户的核心信息
+```
+
+> **SQLite 注释约定**：SQLite 不支持 `COMMENT ON` 语法，必须使用 `-- @comment` 前置注释（字段）和 `-- @table-comment <表名> <描述>` 后置注释（表）。规则详见 `logos/spec/sql-comment-convention.md`。
+
 ### Step 4: 设计表间关联
 
 根据 API 中的实体关系设计外键：
@@ -153,29 +174,42 @@ CREATE INDEX idx_projects_owner ON projects(owner_id);
 3. 关联表（有外键依赖的表后建）
 4. 索引
 5. 安全策略（RLS / Policy）
-6. 表和字段注释（PostgreSQL 使用 `COMMENT ON`）
+6. 表和字段注释：
+   - PostgreSQL：使用 `COMMENT ON TABLE` / `COMMENT ON COLUMN`
+   - MySQL：使用内联 `COMMENT`
+   - SQLite：使用 `-- @comment`（字段）+ `-- @table-comment`（表），详见下方 SQLite 注释规则
 
 每段 DDL 上方用注释标注来源 API 端点。
 
+**SQLite 注释规则（MUST Follow）**：
+
+当 `tech_stack.database` 为 SQLite 时，必须使用以下结构化注释格式：
+
+1. **字段注释**：在字段定义行的**紧邻上方**写 `-- @comment <描述>`
+   - 与字段之间**不允许空行**（空行会断开关联）
+   - 多行注释：连续多个 `-- @comment` 行自动拼接
+2. **表注释**：在 `CREATE TABLE ... ();` 语句**紧邻下方**写 `-- @table-comment <表名> <描述>`
+3. 约束行（`FOREIGN KEY`、独立 `CHECK`、`UNIQUE`）**不需要** `-- @comment`
+
 ## 输出规范
 
 - 文件格式：SQL（方言由 `tech_stack.database` 决定）
 - 存放位置：`logos/resources/database/`
 - 单文件输出：`schema.sql`（简单项目）；或按领域分文件：`auth.sql`、`billing.sql`（复杂项目）
-- 每张表必须有注释（PostgreSQL: `COMMENT ON TABLE`；MySQL: `COMMENT = '...'`）
-- 每个字段必须有注释（PostgreSQL: `COMMENT ON COLUMN`；MySQL: 字段定义后 `COMMENT '...'`）
+- 每张表必须有注释（PostgreSQL: `COMMENT ON TABLE`；MySQL: `COMMENT = '...'`；SQLite: `-- @table-comment`）
+- 每个字段必须有注释（PostgreSQL: `COMMENT ON COLUMN`；MySQL: 字段定义后 `COMMENT '...'`；SQLite: `-- @comment`）
 - 每段 DDL 上方用 SQL 注释标注来源 API 端点
 
 ## 数据库方言差异速查
 
-| 特性 | PostgreSQL | MySQL |
-|------|-----------|-------|
-| UUID 主键 | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` 或使用 `BINARY(16)` |
-| 时间类型 | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP`（注意时区处理） |
-| JSON 支持 | `JSONB`（可索引） | `JSON`（功能受限） |
-| 行级安全 | RLS (`ENABLE ROW LEVEL SECURITY`) | 不支持，需在应用层实现 |
-| 表注释 | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` |
-| 字段注释 | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` |
+| 特性 | PostgreSQL | MySQL | SQLite |
+|------|-----------|-------|--------|
+| UUID 主键 | `UUID DEFAULT gen_random_uuid()` | `CHAR(36) DEFAULT (UUID())` 或 `BINARY(16)` | `TEXT PRIMARY KEY NOT NULL`（应用层生成 UUID） |
+| 时间类型 | `TIMESTAMPTZ` | `DATETIME` / `TIMESTAMP`（注意时区处理） | `TEXT`（ISO 8601 字符串） |
+| JSON 支持 | `JSONB`（可索引） | `JSON`（功能受限） | `TEXT`（应用层 JSON 序列化） |
+| 行级安全 | RLS (`ENABLE ROW LEVEL SECURITY`) | 不支持，需在应用层实现 | 不支持，需在应用层实现 |
+| 表注释 | `COMMENT ON TABLE t IS '...'` | `CREATE TABLE t (...) COMMENT = '...'` | `-- @table-comment t 描述` |
+| 字段注释 | `COMMENT ON COLUMN t.c IS '...'` | `col_name TYPE COMMENT '...'` | `-- @comment 描述`（紧邻字段上方） |
 
 ## 实践经验
 
@@ -202,6 +236,14 @@ CREATE INDEX idx_projects_owner ON projects(owner_id);
 - **字符集**：建表时指定 `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci`
 - **引擎**：一律使用 `ENGINE=InnoDB`
 
+### SQLite 特有
+
+- **主键**：`TEXT PRIMARY KEY NOT NULL`（应用层生成 UUID v4）或 `INTEGER PRIMARY KEY AUTOINCREMENT`
+- **时间类型**：使用 `TEXT` 存储 ISO 8601 字符串，默认值 `DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`
+- **外键**：须在连接时执行 `PRAGMA foreign_keys = ON;`
+- **注释**：必须使用 `-- @comment` / `-- @table-comment` 结构化注释（见 `logos/spec/sql-comment-convention.md`）
+- **无触发器**：`updated_at` 须在应用层刷新，不依赖 `ON UPDATE` 触发器
+
 ## 推荐提示词
 
 以下提示词可以直接复制给 AI 使用：

package/skills/project-init/SKILL.en.md

@@ -141,7 +141,7 @@ Report to the user which files and directories were created, and provide next-st
 
 ## Output Specification
 
-- `logos/logos.config.json`: Valid JSON, conforming to `spec/logos.config.schema.json`
+- `logos/logos.config.json`: Valid JSON, conforming to `logos/spec/logos.config.schema.json`
 - `logos/logos-project.yaml`: Valid YAML
 - `AGENTS.md` / `CLAUDE.md`: Markdown format, located in the project root directory
 - All directories under `logos/` are created; empty directories contain `.gitkeep`

package/skills/project-init/SKILL.md

@@ -141,7 +141,7 @@ Read `logos/logos-project.yaml` first to understand the project resource index.
 
 ## 输出规范
 
-- `logos/logos.config.json`：有效的 JSON，符合 `spec/logos.config.schema.json`
+- `logos/logos.config.json`：有效的 JSON，符合 `logos/spec/logos.config.schema.json`
 - `logos/logos-project.yaml`：有效的 YAML
 - `AGENTS.md` / `CLAUDE.md`：Markdown 格式，位于项目根目录
 - `logos/` 下所有目录已创建，空目录包含 `.gitkeep`

package/skills/test-orchestrator/SKILL.en.md

@@ -130,7 +130,7 @@ Orchestration behavior for different strategies:
 - **Concurrency testing**: Key scenarios should account for concurrent situations (e.g., two users registering with the same email simultaneously)
 - **Check the external dependency list first**: Before starting orchestration design, read `external_dependencies` from `logos-project.yaml`; proactively remind the user to add any undeclared external calls
 - **Do not decide mock strategies on your own**: Test strategies are determined during S12 technical architecture design (Phase 3 Step 0, architecture-designer); the orchestration test phase only consumes them — do not modify them unilaterally
-- **Relationship with `openlogos verify`**: API orchestration tests can also produce JSONL results in the same format as `spec/test-results.md`. After orchestration tests run, results are also written to `logos/resources/verify/test-results.jsonl`, and `openlogos verify` reads them uniformly to determine acceptance
+- **Relationship with `openlogos verify`**: API orchestration tests can also produce JSONL results in the same format as `logos/spec/test-results.md`. After orchestration tests run, results are also written to `logos/resources/verify/test-results.jsonl`, and `openlogos verify` reads them uniformly to determine acceptance
 
 ## Recommended Prompts
 

package/skills/test-orchestrator/SKILL.md

@@ -130,7 +130,7 @@
 - **并发测试**：关键场景需要考虑并发情况（如：两人同时注册同一邮箱）
 - **外部依赖先查清单**：开始设计编排前先读 `logos-project.yaml` 的 `external_dependencies`，没有声明的外部调用要主动提醒用户补充
 - **mock 策略不要自行决定**：测试策略由 S12 技术架构设计（Phase 3 Step 0, architecture-designer）确定，编排测试阶段只负责消费，不要擅自更改
-- **与 `openlogos verify` 的关系**：API 编排测试也可产出与 `spec/test-results.md` 相同格式的 JSONL 结果。编排测试运行后，结果同样写入 `logos/resources/verify/test-results.jsonl`，`openlogos verify` 统一读取并判定验收
+- **与 `openlogos verify` 的关系**：API 编排测试也可产出与 `logos/spec/test-results.md` 相同格式的 JSONL 结果。编排测试运行后，结果同样写入 `logos/resources/verify/test-results.jsonl`，`openlogos verify` 统一读取并判定验收
 
 ## 推荐提示词
 

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

@@ -224,7 +224,7 @@ Test case IDs (`UT-S01-01`, `ST-S01-01`) serve as a **binding contract** between
 - `openlogos verify` maps execution results back to test case specifications via IDs, automatically determining acceptance
 - When modifying case IDs, the corresponding IDs in the test code must be updated simultaneously
 
-See `spec/test-results.md` for the detailed JSONL format definition and reporter code templates for each language.
+See `logos/spec/test-results.md` for the detailed JSONL format definition and reporter code templates for each language.
 
 ## Best Practices
 

package/skills/test-writer/SKILL.md

@@ -224,7 +224,7 @@
 - `openlogos verify` 通过 ID 将运行结果映射回测试用例规格，自动判定验收
 - 修改用例 ID 时必须同步修改测试代码中的 ID
 
-详细的 JSONL 格式定义和各语言 reporter 代码模板见 `spec/test-results.md`。
+详细的 JSONL 格式定义和各语言 reporter 代码模板见 `logos/spec/test-results.md`。
 
 ## 实践经验
 

package/spec/agents-md.md

@@ -0,0 +1,117 @@
+# AGENTS.md 生成规范
+
+> 版本：0.3.0
+>
+> 本文档定义 AGENTS.md 的内容结构、生成规则和多平台适配机制。AGENTS.md 是面向 AI 助手的指令文件，让 AI 工具打开项目就知道该遵循什么规范。
+
+## 概述
+
+AGENTS.md 放在项目根目录。当 AI 工具（Cursor、Claude Code、OpenCode 等）打开项目时，自动读取此文件，了解项目遵循的规范和工作方式。
+
+## 内容结构
+
+```markdown
+# AI Assistant Instructions
+
+This project follows the **OpenLogos** methodology.
+Read `logos/logos-project.yaml` first to understand the project resource index.
+
+## Project Context
+- Config: `logos/logos.config.json`
+- Resource Index: `logos/logos-project.yaml`
+- Tech Stack: [从 logos-project.yaml 读取]
+
+## Methodology Rules
+1. Never write code without first completing the design documents
+2. Follow the Why → What → How progression
+3. All API designs must originate from scenario sequence diagrams
+4. All code changes must have corresponding API orchestration tests
+5. Use the Delta change workflow for iterations (see logos/changes/ directory)
+
+## Interaction Guidelines
+When the user's request is vague or they ask "what should I do next":
+1. Scan `logos/resources/` to determine the current project phase
+2. Suggest the specific next step based on what's missing
+3. Provide a ready-to-use prompt the user can directly say
+4. Never start generating documents without confirming key information
+
+Phase detection logic:
+- `logos/resources/prd/1-product-requirements/` is empty → suggest Phase 1 (prd-writer)
+- requirements exist but `2-product-design/` is empty → suggest Phase 2 (product-designer)
+- design exists but `3-technical-plan/1-architecture/` is empty → suggest Phase 3 Step 0 (architecture-designer)
+- architecture exists but `3-technical-plan/2-scenario-implementation/` is empty → suggest Phase 3 Step 1 (scenario-architect)
+- scenarios exist but `logos/resources/api/` is empty → suggest Phase 3 Step 2 (api-designer + db-designer)
+- API exists but `logos/resources/test/` is empty → suggest Phase 3 Step 3a (test-writer)
+- test cases exist but `logos/resources/scenario/` is empty → suggest Phase 3 Step 3b (test-orchestrator, API projects only)
+- All above exist → suggest Phase 3 Step 4 (code generation)
+- code generated but `logos/resources/verify/` is empty → suggest Phase 3 Step 5 (run tests then `openlogos verify`)
+
+## Active Skills
+[根据 `logos.config.json` 的 `aiTool` 字段动态生成]
+
+当 aiTool = "cursor" 时，列出 `.cursor/rules/` 下部署的 `.mdc` 文件：
+- `skills/prd-writer` — `.cursor/rules/prd-writer.mdc`
+- `skills/product-designer` — `.cursor/rules/product-designer.mdc`
+- ...（共 12 项）
+
+当 aiTool = "claude-code" 或 "other" 时，列出 `logos/skills/` 下部署的 `SKILL.md` 文件：
+- `skills/prd-writer` — `logos/skills/prd-writer/SKILL.md`
+- `skills/product-designer` — `logos/skills/product-designer/SKILL.md`
+- ...（共 12 项）
+
+## Conventions
+- [从 logos-project.yaml 的 conventions 段读取]
+- When writing Markdown files that contain triple-backtick code blocks inside other code blocks, use 4-backtick fences (````) for the outer block
+```
+
+## 生成规则
+
+### 数据来源
+
+AGENTS.md 的内容从以下文件中自动提取：
+
+| 字段 | 来源 |
+|------|------|
+| Tech Stack | `logos-project.yaml` → `tech_stack` |
+| Active Skills | `logos.config.json` → `aiTool` 字段决定路径前缀 + 扫描项目中已部署的 Skills |
+| Conventions | `logos-project.yaml` → `conventions` |
+| Methodology Rules | 固定内容（OpenLogos 核心规则） |
+
+### 核心规则（固定内容）
+
+以下规则在所有 OpenLogos 项目中一致，不可自定义：
+
+1. Never write code without first completing the design documents
+2. Follow the Why → What → How progression
+3. All API designs must originate from scenario sequence diagrams
+4. All code changes must have corresponding API orchestration tests
+5. Use the Delta change workflow for iterations
+6. All generated test code must include an OpenLogos reporter (see spec/test-results.md)
+
+### 生成时机
+
+- `openlogos init`：初始化项目时首次生成（含 Active Skills 段，Skills 同步部署）
+- `openlogos sync`：手动触发重新生成（当项目配置变化时，同时重新部署 Skills 并刷新 Active Skills 段）
+- `project-init` Skill：AI 初始化项目时生成
+
+## 多平台适配
+
+不同 AI 工具使用不同的指令文件名，但内容一致：
+
+| 工具 | 指令文件 | Skills 部署位置 | 处理方式 |
+|------|---------|---------------|---------|
+| **Cursor** | `AGENTS.md`（原生支持） | `.cursor/rules/*.mdc` | `init` / `sync` 自动部署 |
+| **Claude Code** | `CLAUDE.md` | `logos/skills/*/SKILL.md` | `init` / `sync` 自动部署 |
+| **OpenCode** | `AGENTS.md` | `logos/skills/*/SKILL.md` | `init` / `sync` 自动部署 |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | 规划中 | Phase 1.5 |
+
+`openlogos sync` 命令会同时生成所有需要的指令文件，确保不同 AI 工具看到的指令一致。
+
+## 与 logos-project.yaml 的关系
+
+| 文件 | 格式 | 受众 | 内容 |
+|------|------|------|------|
+| `logos-project.yaml` | 结构化 YAML | AI + 工具 | 资源索引、技术栈、约定 |
+| `AGENTS.md` | 自然语言 Markdown | AI 助手 | 行为指令、规则、Skill 列表 |
+
+两者互补：AGENTS.md 引导 AI 去读 logos-project.yaml，logos-project.yaml 提供结构化数据。

package/spec/change-management.md

@@ -0,0 +1,197 @@
+# Delta 变更管理规范
+
+> 版本：0.3.0
+>
+> 本文档定义 OpenLogos 的 Delta 变更管理机制。每次功能迭代或 Bug 修复，先创建变更提案，审核通过后再合并回主文档。确保变更过程可追溯、可审核、可回滚。
+
+## 核心原则
+
+1. **不直接修改主文档**：每次变更先在 `logos/changes/` 中创建提案
+2. **影响分析先行**：在 `proposal.md` 中明确变更范围
+3. **按需传播**：不是每次都全链路更新，只更新受影响的环节
+4. **归档留痕**：变更完成后归档，保留完整历史
+
+## 目录结构
+
+```
+project-root/
+└── logos/
+    ├── resources/                    # 主文档（当前已生效的"真相"）
+    │
+    └── changes/                      # 变更提案工作区
+        ├── add-remember-me/          # 一个变更提案
+        │   ├── proposal.md           # 变更说明
+        │   ├── tasks.md              # 实现任务清单
+        │   └── deltas/               # 增量修改（Delta）
+        │       ├── prd/
+        │       ├── api/
+        │       ├── database/
+        │       └── scenario/
+        │
+        └── archive/                  # 已完成变更的历史归档
+            └── add-remember-me/
+```
+
+## 文件规范
+
+### proposal.md
+
+变更说明文档，必须包含：
+
+```markdown
+# 变更提案：[变更名称]
+
+## 变更原因
+[为什么要做这个变更？来源于哪个需求/反馈/Bug？]
+
+## 变更范围
+- 影响的需求文档：[列表]
+- 影响的功能规格：[列表]
+- 影响的业务场景：[列表]
+- 影响的 API：[列表]
+- 影响的 DB 表：[列表]
+
+## 变更概述
+[用 1-3 段话概述具体改什么]
+```
+
+### tasks.md
+
+实现任务清单，按 Phase 组织：
+
+```markdown
+# 实现任务
+
+## Phase 1: 文档变更
+- [ ] 更新需求文档的用户故事和验收条件
+- [ ] 更新产品设计文档的功能规格
+
+## Phase 2: 设计变更
+- [ ] 更新 HTML 原型
+- [ ] 更新场景时序图
+- [ ] 更新 API YAML
+- [ ] 更新 DB DDL
+
+## Phase 3: 编排与代码
+- [ ] 更新 API 编排测试用例
+- [ ] 实现代码变更
+- [ ] 部署到测试环境
+- [ ] 运行编排验收
+```
+
+### deltas/ 目录
+
+增量修改文件，使用标记格式：
+
+```markdown
+## ADDED — [新增内容标题]
+[新增的完整内容]
+
+## MODIFIED — [修改内容标题]
+[修改后的完整内容，替换主文档中同名章节]
+
+## REMOVED — [删除内容标题]
+[说明删除原因]
+```
+
+Delta 文件的目录结构映射主文档目录：
+- `deltas/prd/` → 对应 `logos/resources/prd/` 的变更
+- `deltas/api/` → 对应 `logos/resources/api/` 的变更
+- `deltas/database/` → 对应 `logos/resources/database/` 的变更
+- `deltas/scenario/` → 对应 `logos/resources/scenario/` 的变更
+
+## 变更工作流
+
+```
+1. 创建变更提案（CLI）
+   └── openlogos change {slug}
+   └── 生成 logos/changes/{slug}/proposal.md + tasks.md + deltas/
+
+2. AI 辅助填写提案（change-writer Skill）
+   └── AI 分析影响范围，填写 proposal.md 和 tasks.md
+
+3. 按 tasks.md 逐项产出 Delta 文件（各阶段 Skill）
+   └── 每完成一项任务，将增量变更写入 deltas/ 对应子目录
+
+4. 审核变更提案
+   └── 团队/自审 proposal.md 和 delta 文件
+
+5. 生成合并指令（CLI）
+   └── openlogos merge {slug}
+   └── 扫描 deltas/，生成 MERGE_PROMPT.md
+
+6. AI 执行合并（merge-executor Skill）
+   └── AI 读取 MERGE_PROMPT.md，逐个 delta 合并到主文档
+
+7. 归档变更（CLI）
+   └── openlogos archive {slug}
+   └── 将 logos/changes/{slug}/ 移入 logos/changes/archive/
+```
+
+## 变更传播规则
+
+不是每次变更都需要全链路更新。根据变更类型决定影响范围：
+
+| 变更类型 | 最少需要更新 | 说明 |
+|---------|------------|------|
+| 需求级变更 | 全链路 | 需求变了，所有下游都可能受影响 |
+| 设计级变更 | 原型 + 场景 + API/DB + 编排 + 代码 | 需求不变，实现方案调整 |
+| 接口级变更 | API/DB + 编排 + 代码 | 设计不变，接口细节调整 |
+| 代码级修复 | 代码 + 重新验收 | Bug 修复，不涉及设计变更 |
+
+## Git 集成
+
+- 每个变更提案对应一个 Git 分支：`change/{change-name}`
+- 分支合并时，`logos/changes/{change-name}/` 同步移入 `logos/changes/archive/`
+- 重大变更在文档顶部的"最后更新"时间戳中标注
+- `logos/changes/archive/` 提供完整变更历史
+
+## MERGE_PROMPT.md 文件规范
+
+`openlogos merge` 命令自动生成的指令文件，结构如下：
+
+```markdown
+# Merge Instruction
+
+## 变更提案
+- 提案名称：{slug}
+- 提案目录：logos/changes/{slug}/
+
+## 提案内容
+[从 proposal.md 中读取的完整内容]
+
+## 需要合并的 Delta 文件
+
+### 1. {delta-relative-path}
+- Delta 文件：`logos/changes/{slug}/deltas/{category}/{file}`
+- 目标目录：`logos/resources/{category}/`
+- 操作：读取 delta 中的 ADDED / MODIFIED / REMOVED 标记，合并到目标目录中对应的主文档
+
+## 执行要求
+1. 逐个 Delta 文件处理，每处理完一个报告修改摘要
+2. 对于 ADDED 标记：在主文档的指定位置插入新内容
+3. 对于 MODIFIED 标记：替换主文档中同名章节的内容
+4. 对于 REMOVED 标记：从主文档中删除对应章节
+5. 保持主文档的原有格式和风格
+6. 如果主文档有"最后更新"时间戳，同步更新
+7. 所有变更完成后，列出修改清单
+8. 完成后提醒用户运行 `openlogos archive {slug}`
+```
+
+## CLI 命令
+
+```bash
+# 创建变更提案
+openlogos change add-remember-me
+
+# 生成合并指令（由 AI 执行实际合并）
+openlogos merge add-remember-me
+
+# 归档已完成的变更
+openlogos archive add-remember-me
+```
+
+## AI Skills 集成
+
+- **change-writer**：在 `openlogos change` 后使用，辅助填写 proposal.md 和 tasks.md
+- **merge-executor**：在 `openlogos merge` 后使用，读取 MERGE_PROMPT.md 执行实际合并