@miniidealab/openlogos 0.2.0 → 0.3.1

package/skills/architecture-designer/SKILL.md

@@ -0,0 +1,181 @@
+# Skill: Architecture Designer
+
+> 在逐场景的技术实现之前，建立项目的技术全局视图——系统架构、技术选型、部署拓扑和非功能性约束。确保后续的时序图、API 和代码生成在一致的架构约束下进行。
+
+## 触发条件
+
+- 用户要求设计技术架构、做技术选型或规划系统架构
+- 用户提到 "Phase 3 Step 0"、"架构设计"、"技术方案"
+- Phase 2 产品设计文档已完成，需要开始 Phase 3
+- 用户想要确定技术栈或部署方案
+
+## 核心能力
+
+1. 读取 Phase 1 需求文档和 Phase 2 产品设计文档，理解产品全貌
+2. 基于产品复杂度和场景特征，推荐适合的系统架构
+3. 为每项技术选型提供选型理由和替代方案对比
+4. 绘制系统架构图（Mermaid）和部署拓扑图
+5. 更新 `logos-project.yaml` 的 `tech_stack` 字段
+
+## 与 Phase 1/2 的衔接
+
+架构设计是 Phase 2（产品设计）到 Phase 3（技术实现）的桥梁。它的输入来自 Phase 1/2，输出影响 Phase 3 所有后续步骤：
+
+| 输入（来自 Phase 1/2） | 输出（影响 Phase 3 后续步骤） |
+|------------------------|------------------------------|
+| 场景清单和复杂度 | 系统边界划分 → 时序图的参与方 |
+| 非功能性需求（性能、安全） | 技术选型约束 → API 设计决策 |
+| 产品交互方式（Web/Mobile/API） | 前端技术栈 → 原型实现方式 |
+| 数据量和访问模式 | 数据库选型 → DB 设计 |
+| 第三方服务依赖（支付、邮件等） | 集成方式 → 时序图中的外部参与方 |
+
+## 执行步骤
+
+### Step 1: 理解产品全貌
+
+读取以下文档，建立对项目的整体认知：
+
+- **需求文档**（Phase 1）：产品定位、核心场景、约束与边界
+- **产品设计文档**（Phase 2）：信息架构、页面结构、交互复杂度
+- **已有的 `logos-project.yaml`**：当前 `tech_stack` 中是否已有初始选型
+
+重点提取：
+- 核心场景数量和复杂度
+- 是否有实时性需求（WebSocket、SSE）
+- 是否有后台任务（定时任务、消息队列）
+- 第三方服务依赖清单
+- 用户规模预期
+
+### Step 2: 确定系统架构
+
+根据产品复杂度选择架构模式：
+
+**简单项目**（个人 SaaS、工具类产品）：
+- 单体架构 + 单数据库
+- 架构概要可以用一段文字 + 一张简图
+
+**中等项目**（团队 SaaS、多角色系统）：
+- 前后端分离 + 单体后端 + 单数据库
+- 可能需要对象存储、缓存等辅助服务
+
+**复杂项目**（多服务、高并发、多端）：
+- 微服务 / 模块化单体
+- 需要详细的架构决策记录（ADR）
+
+用 Mermaid 绘制系统架构图：
+
+```mermaid
+graph TB
+    subgraph Frontend
+        Web[Web App - Next.js]
+    end
+    subgraph Backend
+        API[API Server - Node.js]
+        Worker[Background Worker]
+    end
+    subgraph Data
+        DB[(PostgreSQL)]
+        Cache[(Redis)]
+        S3[Object Storage]
+    end
+    subgraph External
+        Auth[Supabase Auth]
+        Email[SendGrid]
+    end
+
+    Web -->|REST API| API
+    API --> DB
+    API --> Cache
+    API --> S3
+    API --> Auth
+    Worker --> DB
+    Worker --> Email
+```
+
+### Step 3: 技术选型
+
+为每个技术维度给出选型和理由：
+
+```markdown
+| 维度 | 选型 | 理由 | 备选方案 |
+|------|------|------|---------|
+| 语言 | TypeScript | 前后端统一、类型安全 | Go（性能优先时） |
+| 前端框架 | Next.js 15 | SSR + RSC、生态成熟 | Astro（内容站）、Nuxt（Vue 生态） |
+| 后端框架 | Hono | 轻量、边缘优先、TS 原生 | Express（生态）、Fastify（性能） |
+| 数据库 | PostgreSQL | 功能丰富、JSONB、RLS | MySQL（简单场景） |
+| 认证 | Supabase Auth | 开箱即用、RLS 集成 | NextAuth（自托管） |
+| 部署 | Vercel + Supabase | 零运维、自动扩容 | AWS（自主控制） |
+```
+
+**选型原则**：
+- 优先选择团队已熟悉的技术
+- 在无明显差异时，选择社区更大的方案
+- 选型理由必须关联到具体的产品需求或约束
+
+### Step 4: 非功能性约束
+
+明确关键的非功能性要求：
+
+- **性能目标**：核心 API 响应时间、页面加载时间
+- **安全要求**：认证方式、数据加密、CORS 策略
+- **可扩展性**：预期用户规模、数据增长估算
+- **可观测性**：日志、监控、告警方案
+- **开发体验**：本地开发环境、CI/CD 流程
+
+### Step 5: 外部依赖与测试策略
+
+梳理项目的所有外部服务依赖，为每个依赖确定编排测试阶段的隔离策略。此步骤的产出直接影响 Phase 3 Step 3（编排测试）能否顺利执行。
+
+1. 从架构图和时序图参与方中识别外部依赖（邮件、短信、验证码、支付、OAuth 等）
+2. 与用户确认每个依赖的测试策略
+
+可选的测试策略：
+
+| 策略 | 说明 | 典型场景 |
+|------|------|---------|
+| `test-api` | 测试环境提供后门 API | 邮件/短信验证码 |
+| `fixed-value` | 特定测试数据使用固定值 | 测试手机号固定验证码 |
+| `env-disable` | 环境变量关闭该功能 | 图形验证码、滑块 |
+| `mock-callback` | 编排中主动调用模拟回调 | 支付回调、Webhook |
+| `mock-service` | 本地 mock 服务替代 | OAuth Provider |
+
+如果项目没有外部服务依赖（如纯 CLI 工具），可跳过此步骤。
+
+### Step 6: 更新 logos-project.yaml
+
+将确认的技术选型写入 `logos-project.yaml` 的 `tech_stack` 字段，将外部依赖和测试策略写入 `external_dependencies` 字段，确保后续所有 Skill 和 AI 工具都能读取到统一的技术栈和测试约定。
+
+```yaml
+external_dependencies:
+  - name: "邮件服务"
+    provider: "SendGrid"
+    used_in: ["S01-用户注册", "S03-忘记密码"]
+    test_strategy: "test-api"
+    test_config: "GET /api/test/latest-email?to={email}"
+```
+
+## 输出规范
+
+- 架构概要文档：`logos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md`
+- 架构图使用 Mermaid 格式
+- 技术选型使用表格格式，每项必须有理由
+- 更新 `logos-project.yaml` 的 `tech_stack` 和 `external_dependencies` 字段
+- 简单项目允许精简输出（不强制所有章节）
+
+## 实践经验
+
+- **不要过度设计**：独立开发者做 SaaS，单体 + PostgreSQL + Vercel 够用就行，不要上来就微服务
+- **选型理由比选型本身重要**：写清楚"为什么选 X"比"选了 X"更有价值，因为项目演进时需要重新评估
+- **架构图是时序图的前提**：架构图中的系统组件就是后续时序图的参与方，两者必须一致
+- **tech_stack 是 AI 的锚**：后续 AI 生成代码时会读取 `logos-project.yaml` 的 `tech_stack`，选型不准确会导致生成的代码无法使用
+- **非功能性约束宁可先宽后紧**：初期不要定太严格的性能目标，随着实际数据再收紧
+- **测试策略必须在架构阶段决定**：验证码、支付等外部依赖的测试方案如果等到编排测试时才想，往往发现没有预留后门 API，导致编排测试无法全自动执行
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计技术架构`
+- `基于产品设计帮我做技术选型`
+- `帮我画系统架构图`
+- `帮我确定技术栈并更新 logos-project.yaml`

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

@@ -0,0 +1,146 @@
+# Skill: Change Writer
+
+> Assist in writing change proposals — analyze the scope of change impact, generate a structured proposal.md and a phase-based tasks.md, ensuring changes are traceable and impact is controllable.
+
+## Trigger Conditions
+
+- User has just run `openlogos change <slug>` and wants AI help filling in the proposal
+- User describes a need to modify, add, or remove a scenario/feature
+- User mentions "change proposal", "iteration", "requirement change"
+
+## Prerequisites
+
+1. Project is initialized (`logos/logos.config.json` exists)
+2. Change proposal directory has been created by CLI (`logos/changes/<slug>/` exists)
+3. Main documents are readable (effective documents exist in `logos/resources/`)
+
+If prerequisites are not met, prompt the user to run `openlogos change <slug>` to create the proposal directory first.
+
+## Core Capabilities
+
+1. Understand the user's intended change
+2. Scan existing documents in `logos/resources/` to identify the affected scope
+3. Determine the change type based on change propagation rules (Requirement-level / Design-level / Interface-level / Code-level)
+4. Generate a compliant proposal.md
+5. Automatically break down tasks.md by change type
+
+## Execution Steps
+
+### Step 1: Understand the Change Intent
+
+Confirm the following information with the user (ask follow-up questions if insufficient, up to 2 rounds):
+
+- **What is the change**: What needs to be added, modified, or removed?
+- **Reason for the change**: Why is this change needed? Is it from requirement feedback, a bug, or an optimization?
+- **Related scenarios**: Which existing scenario IDs are involved (S01, S02...)?
+
+### Step 2: Analyze the Impact Scope
+
+Scan documents in `logos/resources/` to determine the impact scope:
+
+1. Read requirement documents (`prd/1-product-requirements/`) to check related scenario definitions
+2. Read product design (`prd/2-product-design/`) to check related functional specs and prototypes
+3. Read technical plans (`prd/3-technical-plan/`) to check related sequence diagrams
+4. Read API documents (`api/`) to check related endpoints
+5. Read DB documents (`database/`) to check related table structures
+6. Read orchestration tests (`scenario/`) to check related test cases
+
+### Step 3: Determine the Change Type
+
+Refer to change propagation rules to determine the change type and minimum update scope:
+
+| Change Type | Minimum Updates Required |
+|-------------|------------------------|
+| Requirement-level change | Full chain (Requirements → Design → Architecture → API/DB → Orchestration → Code) |
+| Design-level change | Prototypes + Scenarios + API/DB + Orchestration + Code |
+| Interface-level change | API/DB + Orchestration + Code |
+| Code-level fix | Code + Re-verification |
+
+### Step 4: Generate proposal.md
+
+Generate using the following template and write to `logos/changes/<slug>/proposal.md`:
+
+```markdown
+# Change Proposal: [Change Name]
+
+## Reason for Change
+[Why is this change needed? What requirement/feedback/bug does it originate from?]
+
+## Change Type
+[Requirement-level / Design-level / Interface-level / Code-level]
+
+## Change Scope
+- Affected requirement documents: [List, down to filename and section]
+- Affected functional specs: [List]
+- Affected business scenarios: [Scenario ID list]
+- Affected APIs: [Endpoint list]
+- Affected DB tables: [Table name list]
+- Affected orchestration tests: [List]
+
+## Change Summary
+[Describe in 1-3 paragraphs what specifically will change]
+```
+
+### Step 5: Generate tasks.md
+
+Automatically break down the task checklist based on the change type and impact scope. Only list the phases that need updating:
+
+```markdown
+# Implementation Tasks
+
+## Phase 1: Document Changes
+- [ ] Update acceptance criteria for S0x in requirement documents
+- [ ] Add/modify scenario in the scenario overview table
+
+## Phase 2: Design Changes
+- [ ] Update interaction design for S0x in functional specs
+- [ ] Update prototypes
+
+## Phase 3: Technical Changes
+- [ ] Update sequence diagram for S0x
+- [ ] Update API YAML
+- [ ] Update DB DDL
+- [ ] Update orchestration test cases
+- [ ] Implement code changes
+```
+
+### Step 6: Guide Follow-up Actions (Chain-driven)
+
+Provide a ready-to-use prompt that allows the user to kick off chain execution of all tasks with a single command:
+
+- **Requirement-level / Design-level changes** (multiple tasks): Suggest the user say "Follow tasks.md and help me progressively update all affected documents for S0x"
+- **Code-level fixes** (fewer tasks): Suggest the user say "Help me fix the [issue description] for S0x and re-verify"
+
+Chain execution behavior rules:
+1. AI reads `tasks.md` and executes items sequentially
+2. After completing each task, report a summary of changes and automatically prompt "Continue to the next item?"
+3. After the user says "Continue" or provides adjustments, proceed to the next item
+4. After all tasks are completed, remind the user to run `openlogos merge <slug>`
+
+**Key principle**: Do not make the user manually track the task checklist — AI should proactively drive the process.
+
+## Output Specification
+
+- File format: Markdown
+- Storage location: `logos/changes/<slug>/`
+- Filenames: `proposal.md` and `tasks.md` (overwrite the CLI-generated templates)
+
+## Best Practices
+
+- **Overestimate the impact scope**: Missing an update in one link is more dangerous than double-checking
+- **Change type determines workload**: Help users understand before they start that changing one requirement may require a full-chain update
+- **tasks.md is the execution checklist**: Check off each item with `[x]` upon completion for easy progress tracking
+- **Follow the process even for small changes**: A change that appears to be "just one API line" may affect orchestration tests and code
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+**Fill in proposal**:
+- `Help me fill in the change proposal <slug>`
+- `I want to add a "remember password" feature to the S02 login scenario, help me analyze the impact scope`
+- `This bug fix only involves the code layer, help me quickly write a proposal`
+
+**Execute tasks (after proposal is completed)**:
+- `Follow tasks.md and help me progressively update all affected documents for S02`
+- `Help me fix the 500 error on the S02 login endpoint and re-verify`

package/skills/change-writer/SKILL.md

@@ -0,0 +1,146 @@
+# Skill: Change Writer
+
+> 辅助填写变更提案——分析变更影响范围，生成结构化的 proposal.md 和按阶段拆解的 tasks.md，确保变更可追溯、影响可控。
+
+## 触发条件
+
+- 用户刚运行完 `openlogos change <slug>` 并希望 AI 帮忙填写提案
+- 用户描述需要修改、新增或删除某个场景/功能
+- 用户提到"变更提案"、"change proposal"、"迭代"、"改需求"
+
+## 前置依赖
+
+1. 项目已初始化（`logos/logos.config.json` 存在）
+2. 变更提案目录已由 CLI 创建（`logos/changes/<slug>/` 存在）
+3. 主文档可读（`logos/resources/` 中有已生效的文档）
+
+如果前置条件不满足，提示用户先运行 `openlogos change <slug>` 创建提案目录。
+
+## 核心能力
+
+1. 理解用户描述的变更意图
+2. 扫描 `logos/resources/` 中的现有文档，定位受影响范围
+3. 根据变更传播规则判断变更类型（需求级 / 设计级 / 接口级 / 代码级）
+4. 生成符合规范的 proposal.md
+5. 按变更类型自动拆解 tasks.md
+
+## 执行步骤
+
+### Step 1: 理解变更意图
+
+与用户确认以下信息（信息不足则追问，最多 2 轮）：
+
+- **变更是什么**：要新增、修改还是删除什么？
+- **变更原因**：为什么要做这个变更？来自需求反馈、Bug 还是优化？
+- **关联场景**：涉及哪些已有场景编号（S01, S02...）？
+
+### Step 2: 分析影响范围
+
+扫描 `logos/resources/` 中的文档，确定影响范围：
+
+1. 读取需求文档（`prd/1-product-requirements/`），检查相关场景定义
+2. 读取产品设计（`prd/2-product-design/`），检查相关功能规格和原型
+3. 读取技术方案（`prd/3-technical-plan/`），检查相关时序图
+4. 读取 API 文档（`api/`），检查相关端点
+5. 读取 DB 文档（`database/`），检查相关表结构
+6. 读取编排测试（`scenario/`），检查相关测试用例
+
+### Step 3: 判断变更类型
+
+参照变更传播规则确定变更类型及最小更新范围：
+
+| 变更类型 | 最少需要更新 |
+|---------|------------|
+| 需求级变更 | 全链路（需求 → 设计 → 架构 → API/DB → 编排 → 代码） |
+| 设计级变更 | 原型 + 场景 + API/DB + 编排 + 代码 |
+| 接口级变更 | API/DB + 编排 + 代码 |
+| 代码级修复 | 代码 + 重新验收 |
+
+### Step 4: 生成 proposal.md
+
+按以下模板生成，写入 `logos/changes/<slug>/proposal.md`：
+
+```markdown
+# 变更提案：[变更名称]
+
+## 变更原因
+[为什么要做这个变更？来源于哪个需求/反馈/Bug？]
+
+## 变更类型
+[需求级 / 设计级 / 接口级 / 代码级]
+
+## 变更范围
+- 影响的需求文档：[列表，精确到文件名和章节]
+- 影响的功能规格：[列表]
+- 影响的业务场景：[场景编号列表]
+- 影响的 API：[端点列表]
+- 影响的 DB 表：[表名列表]
+- 影响的编排测试：[列表]
+
+## 变更概述
+[用 1-3 段话概述具体改什么]
+```
+
+### Step 5: 生成 tasks.md
+
+根据变更类型和影响范围，自动拆解任务清单。只列出需要更新的阶段：
+
+```markdown
+# 实现任务
+
+## Phase 1: 文档变更
+- [ ] 更新需求文档中 S0x 的验收条件
+- [ ] 在场景总览表中新增/修改场景
+
+## Phase 2: 设计变更
+- [ ] 更新功能规格中 S0x 的交互设计
+- [ ] 更新原型
+
+## Phase 3: 技术变更
+- [ ] 更新 S0x 的时序图
+- [ ] 更新 API YAML
+- [ ] 更新 DB DDL
+- [ ] 更新编排测试用例
+- [ ] 实现代码变更
+```
+
+### Step 6: 引导后续操作（链式驱动）
+
+提供一条可直接执行的提示词，让用户一句话启动全部任务的链式执行：
+
+- **需求级 / 设计级变更**（多任务）：建议用户说「按 tasks.md 帮我逐步更新 S0x 的所有受影响文档」
+- **代码级修复**（少任务）：建议用户说「帮我修复 S0x 的 [问题描述] 并重新验收」
+
+链式执行的行为规范：
+1. AI 读取 `tasks.md`，按顺序逐项执行
+2. 每完成一项任务，汇报修改摘要，并自动提示「继续下一项？」
+3. 用户说「继续」或给出调整意见后，执行下一项
+4. 全部任务完成后，提醒用户运行 `openlogos merge <slug>`
+
+**关键原则**：不要让用户手动跟踪任务清单——AI 应主动驱动流程。
+
+## 输出规范
+
+- 文件格式：Markdown
+- 存放位置：`logos/changes/<slug>/`
+- 文件名：`proposal.md` 和 `tasks.md`（覆盖 CLI 生成的模板）
+
+## 实践经验
+
+- **宁可高估影响范围**：漏掉一个环节的更新比多检查一遍更危险
+- **变更类型决定工作量**：帮助用户在动手前理解改一个需求可能需要全链路更新
+- **tasks.md 是执行清单**：每完成一项打一个 `[x]`，方便追踪进度
+- **小变更也走流程**：看似"只改一行 API"的变更，可能影响编排测试和代码
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+**填写提案**：
+- `帮我填写变更提案 <slug>`
+- `我要给 S02 登录场景加一个记住密码功能，帮我分析影响范围`
+- `这个 Bug 修复只涉及代码层，帮我快速写个提案`
+
+**执行任务（提案填写完成后）**：
+- `按 tasks.md 帮我逐步更新 S02 的所有受影响文档`
+- `帮我修复 S02 登录接口的 500 错误并重新验收`

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

@@ -0,0 +1,204 @@
+# Skill: Code Reviewer
+
+> Review AI-generated code by performing systematic validation against the full OpenLogos specification chain (API YAML, sequence diagram EX cases, DB DDL), ensuring code is fully consistent with design documents, covers all exception paths, and meets security requirements.
+
+## Trigger Conditions
+
+- User requests a code review or Code Review
+- User mentions "Phase 3 Step 4", "code audit", "code review"
+- AI has just generated code that needs quality verification
+- Final check before deployment
+- Need to locate code issues after orchestration test failures
+
+## Prerequisites
+
+- `logos/resources/api/` contains API YAML specifications
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` contains scenario sequence diagrams (with EX cases)
+- `logos/resources/database/` contains DB DDL
+- The code to be reviewed is accessible
+
+For projects without APIs (pure CLI / libraries), API consistency checks can be skipped; focus on sequence diagram coverage and exception handling instead.
+
+## Core Capabilities
+
+1. Validate code implementation consistency with API YAML specifications
+2. Check whether exception handling covers all EX cases
+3. Check whether DB operations conform to DDL design
+4. Check security policies (authentication, RLS, input validation)
+5. Check code style and best practices
+6. Output a structured review report
+
+## Execution Steps
+
+### Step 1: Load Specification Context
+
+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
+- **DB DDL** (`logos/resources/database/`): Extract table structures, column types, constraints, and indexes
+- **`logos-project.yaml`**: Read `tech_stack` to confirm the technology stack, `external_dependencies` to confirm external dependencies
+
+Summarize into a review checklist:
+
+```markdown
+Review scope: S01-related code
+- API endpoints: 4 (auth.yaml)
+- EX exception cases: 7 (EX-2.1 ~ EX-5.2)
+- DB tables: 2 (users, profiles)
+- Security policies: 2 RLS rules
+```
+
+### Step 2: API Consistency Review
+
+Compare code implementation against API YAML specification endpoint by endpoint:
+
+**Checklist**:
+
+| Check Item | Description | Severity |
+|------------|-------------|----------|
+| Path Match | Whether route paths in code exactly match `paths` in YAML | Critical |
+| HTTP Method | Whether GET/POST/PUT/DELETE matches | Critical |
+| Request Body Fields | Whether code reads all required fields defined in YAML `requestBody.schema` | Critical |
+| Request Body Validation | Whether field type, format (email/uuid), minLength and other constraints are validated in code | Warning |
+| 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 |
+
+**Output format**:
+
+```markdown
+### API Consistency
+
+| Endpoint | Check Item | Status | Notes |
+|----------|------------|--------|-------|
+| POST /api/auth/register | Request body fields | ✅ | email, password both read |
+| POST /api/auth/register | Response status code | ❌ Critical | Registration success returns 200, YAML defines 201 |
+| POST /api/auth/register | Error code | ❌ Warning | Duplicate email returns generic 400, YAML defines 409 |
+```
+
+### Step 3: Exception Handling Coverage Review
+
+Map all EX exception cases from sequence diagrams to error handling in code one by one:
+
+1. List all EX case IDs and their expected behaviors for the scenario
+2. Search for corresponding try/catch, if/else, error handlers in code
+3. Flag uncovered EX cases
+
+**Key checks**:
+
+- Whether each EX case has a corresponding code branch
+- Whether the correct HTTP status code and error code are returned in exception scenarios
+- Whether there are "silently swallowed exceptions" (empty catch blocks or catch blocks that only log without returning errors)
+- Whether external service calls (DB, third-party APIs) all have timeout and error handling
+- Whether there are exception handlers in code that don't exist in sequence diagrams (which may indicate sequence diagram omissions)
+
+**Output format**:
+
+```markdown
+### Exception Handling Coverage
+
+| EX ID | Exception Description | Code Coverage | Notes |
+|-------|----------------------|---------------|-------|
+| EX-2.1 | Email already registered | ✅ | Returns 409, format correct |
+| EX-2.2 | Auth service unavailable | ❌ Critical | No try/catch wrapping the supabase.auth.signUp call |
+| EX-4.1 | profiles write failure | ❌ Critical | auth.users record not rolled back after INSERT failure |
+```
+
+### Step 4: DB Operations Review
+
+Check whether database operations in code conform to DDL design:
+
+**Checklist**:
+
+- **Table and column names**: Whether table/column names referenced in code match DDL (no typos, case differences)
+- **Field types**: Whether value types passed in code match DDL definitions (e.g., for an `INTEGER` amount field in DDL, whether code passes cents instead of dollars)
+- **Constraint compliance**: Whether NOT NULL fields always have values, whether UNIQUE fields have conflict handling, whether CHECK constraint enum values have corresponding constants in code
+- **Transaction usage**: Whether multi-table write operations are wrapped in transactions
+- **Migration consistency**: Whether the latest fields in DDL are used in code (avoid DDL being updated but code not following up)
+
+### Step 5: Security Review
+
+Check the security implementation of the code:
+
+| Check Item | Description | Severity |
+|------------|-------------|----------|
+| Authentication Check | Whether endpoints requiring authentication verify token/session before processing logic | Critical |
+| Authorization Check | Whether users can only access their own data (owner check) | Critical |
+| Input Validation | Whether user input has type validation and length limits (prevent injection, prevent XSS) | Critical |
+| Sensitive Data | Whether responses leak password hashes, internal IDs, or stack traces | Critical |
+| RLS Dependency | If relying on PostgreSQL RLS, whether code correctly sets the `auth.uid()` context | Warning |
+| SQL Injection | Whether parameterized queries are used (string-concatenated SQL is prohibited) | Critical |
+| Rate Limiting | Whether critical endpoints (login, registration) have rate limiting against brute force | Warning |
+
+### Step 6: Output Review Report
+
+Summarize all findings by severity and generate a structured report:
+
+```markdown
+# Code Review Report: S01 User Registration
+
+## Review Scope
+- Scenario: S01
+- Endpoints: 4
+- EX cases: 7
+- Code files: src/api/auth/register.ts, src/api/auth/login.ts
+
+## Review Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | 2 |
+| 🟡 Warning | 3 |
+| 🔵 Info | 1 |
+
+## Critical Findings
+
+### [C1] POST /api/auth/register status code mismatch
+- **Spec source**: auth.yaml → register → responses.201
+- **Issue**: Code returns 200, spec defines 201
+- **Fix suggestion**: Change `res.status(200)` to `res.status(201)`
+
+### [C2] EX-2.2 unhandled: Auth service unavailable
+- **Spec source**: S01 sequence diagram → EX-2.2
+- **Issue**: `supabase.auth.signUp()` call is not wrapped in try/catch
+- **Fix suggestion**: Add try/catch, return 503 on timeout or 5xx
+
+## Warning Findings
+...
+
+## Info Findings
+...
+```
+
+**Report principles**:
+- Critical issues must be fixed before proceeding to orchestration acceptance
+- Warning issues are recommended to fix but do not block delivery
+- Info items are improvement suggestions that can be addressed later
+- Every finding must reference a spec source (API YAML, EX ID, DDL)
+
+## Output Specification
+
+- Review report is output directly in the conversation (not written to a file)
+- Categorized by severity: Critical / Warning / Info
+- Each finding format: ID + spec source + issue description + fix suggestion
+- End with a summary and next-step recommendation (e.g., "Fix 2 Critical issues, then run orchestration acceptance")
+
+## Best Practices
+
+- **Consistency first**: Code must be fully consistent with API YAML — field names, types, and status codes must not deviate. Most production bugs come from subtle inconsistencies between code and specs
+- **Exception handling is the focus**: Most bugs occur in exception paths; carefully check that every EX case has a corresponding catch/error handler
+- **No shortcuts on security**: Authentication checks, RLS policies, input validation — any missing item is a Critical issue
+- **Don't over-review**: Code style issues should be marked as Info and not block delivery. The core goal of the review is "code matches specs", not "code is perfect"
+- **Run tests before reviewing**: If the code can run, execute orchestration tests first and use failing cases to pinpoint issues — this is more efficient than reading code line by line
+- **Watch for compensation logic**: If multi-step writes (e.g., first creating an auth user then writing a profile) fail midway, check whether there is a rollback or compensation mechanism — this is the most commonly missed Critical issue
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me do a code review`
+- `Help me check if this code conforms to the API YAML spec`
+- `Review the code implementation related to S01`
+- `Help me check if exception handling is complete`
+- `Help me check if security policies are in place`