@miniidealab/openlogos 0.2.0 → 0.3.1

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

@@ -0,0 +1,209 @@
+# Skill: API Designer
+
+> Design OpenAPI 3.0+ YAML specifications based on sequence diagrams, letting APIs emerge naturally from scenarios rather than being defined in isolation. Every endpoint is traceable to a Step number in the sequence diagrams, ensuring "no scenario, no API design."
+
+## Trigger Conditions
+
+- User requests API design or API documentation
+- User mentions "Phase 3 Step 2" or "API design"
+- Scenario sequence diagrams already exist and API specifications need to be refined
+- User provides a specific API endpoint that needs detailed design
+
+## Prerequisites
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` contains scenario sequence diagrams
+- `logos/resources/prd/3-technical-plan/1-architecture/` contains the architecture overview (confirming frontend-backend separation approach, authentication scheme, etc.)
+- `tech_stack` in `logos-project.yaml` is filled in
+
+If the sequence diagram directory is empty, prompt the user to complete Phase 3 Step 1 (scenario-architect) first.
+
+## Core Capabilities
+
+1. Extract all cross-system-boundary API calls from sequence diagrams
+2. Deduplicate, merge, and group by domain to form an endpoint inventory
+3. Design OpenAPI 3.0+ YAML specifications (paths, parameters, request bodies, response structures)
+4. Define a unified error response format and error code system
+5. Design authentication schemes (Bearer Token / API Key / Cookie)
+6. Design standardized parameters for pagination, sorting, and filtering
+
+## Execution Steps
+
+### Step 1: Read Scenario Context
+
+Read the following files to establish complete context:
+
+- **Scenario sequence diagrams** (`logos/resources/prd/3-technical-plan/2-scenario-implementation/`): Extract all cross-system-boundary arrows
+- **Architecture overview** (`logos/resources/prd/3-technical-plan/1-architecture/`): Confirm authentication scheme, frontend-backend separation approach, API gateway, etc.
+- **`logos-project.yaml`**: Read `tech_stack` to confirm backend framework and deployment approach
+
+### Step 2: Extract Endpoint Inventory
+
+Traverse all scenario sequence diagrams and collect every cross-system-boundary call arrow:
+
+1. Identify "cross-system-boundary" arrows — client to server, server to external service, inter-service calls
+2. For each arrow, extract: HTTP method, path, source scenario number, and Step number
+3. Deduplicate and merge — the same endpoint may appear in multiple scenarios (e.g., `POST /api/auth/login` may appear in both S02 and S03)
+4. Output an endpoint inventory summary for user confirmation:
+
+```markdown
+Identified N API endpoints from sequence diagrams:
+
+| # | Method | Path | Source Scenario | Domain |
+|---|--------|------|-----------------|--------|
+| 1 | POST | /api/auth/register | S01 Step 2 | auth |
+| 2 | POST | /api/auth/login | S02 Step 1 | auth |
+| 3 | GET  | /api/projects | S04 Step 1 | projects |
+```
+
+### Step 3: Group by Domain
+
+Group endpoints by business domain, with each group corresponding to a YAML file:
+
+- `auth.yaml` — Authentication-related (registration, login, logout, password reset)
+- `projects.yaml` — CRUD for core business entities
+- `billing.yaml` — Payment and subscriptions
+
+Grouping principles:
+- Operations on the same data entity go together
+- Authentication/authorization is a separate group
+- Third-party service callbacks (e.g., payment callbacks) go under the corresponding business domain
+
+### Step 4: Design Unified Conventions
+
+Before generating specific endpoints, establish global conventions:
+
+**Authentication scheme** (read from architecture overview):
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+**Unified error response**:
+
+```yaml
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: Machine-readable error code (e.g., EMAIL_EXISTS)
+        message:
+          type: string
+          description: Human-readable error description
+        details:
+          type: object
+          description: Additional error information (e.g., field-level validation errors)
+```
+
+**Pagination parameters** (applicable to list endpoints):
+
+```yaml
+parameters:
+  - name: page
+    in: query
+    schema: { type: integer, minimum: 1, default: 1 }
+  - name: per_page
+    in: query
+    schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+```
+
+### Step 5: Design Detailed Specification per Endpoint
+
+Design a complete OpenAPI specification for each endpoint, **output by domain**, pausing after each domain for user review:
+
+Each endpoint must include:
+- `operationId`: Unique identifier for code generation
+- `summary`: One-sentence description
+- `description`: Annotate the source sequence diagram step (e.g., `Source: S01 Step 2 → Step 3`)
+- `requestBody`: Schema including all fields (with required, types, validation rules such as minLength/format)
+- `responses`: Cover the normal response + all known exceptions (extracted from EX use cases in sequence diagrams)
+
+**Example**:
+
+```yaml
+paths:
+  /api/auth/register:
+    post:
+      operationId: register
+      summary: User registration
+      description: "Source: S01 Step 2 → Step 3"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email: { type: string, format: email }
+                password: { type: string, minLength: 8 }
+      responses:
+        '201':
+          description: Registration successful, verification email sent
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId: { type: string, format: uuid }
+                  message: { type: string }
+        '409':
+          description: "Email already registered (EX-2.1)"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: Request parameter validation failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+```
+
+### Step 6: Verify Traceability Completeness
+
+After output is complete, perform a traceability check:
+
+1. **Forward check**: Every cross-system arrow in the sequence diagrams has a corresponding API endpoint
+2. **Reverse check**: Every API endpoint's `description` annotates the source Step
+3. **Exception coverage**: Every EX use case in the sequence diagrams has a corresponding HTTP error response
+
+If gaps are found, supplement them before outputting the final version.
+
+## Output Specification
+
+- File format: OpenAPI 3.1 YAML
+- Storage location: `logos/resources/api/`
+- Split by domain: `auth.yaml`, `projects.yaml`, `billing.yaml`
+- Each file contains complete `openapi`, `info`, `paths`, and `components` sections
+- Error responses uniformly reference `$ref: '#/components/schemas/ErrorResponse'`
+- Every endpoint's `description` must annotate the source sequence diagram step
+
+## 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
+- **Path naming**: RESTful style, use plural nouns, `/api/{resource}`
+- **Version prefix**: Do not add a version prefix initially (`/api/auth/register`); add `/api/v2/` when versioning becomes necessary
+- **Status code semantics**: Strictly follow HTTP status code semantics — 200 success, 201 created, 400 bad request, 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 500 server error
+- **Idempotent design**: PUT/DELETE operations must be idempotent
+- **Sensitive data**: Do not include plaintext sensitive information such as passwords or tokens in responses
+- **Output by domain**: Do not output all endpoints at once — output in batches by domain, letting the user review each batch before continuing
+- **Consistent field naming**: Field names in the API should be consistent with column names in the subsequent DB design (or have explicit mapping rules) to avoid unnecessary field transformations in the code layer
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with the AI:
+
+- `Help me design APIs`
+- `Generate OpenAPI YAML based on the sequence diagrams`
+- `Help me design the API specifications related to S01`
+- `Help me extract all cross-system calls from the sequence diagrams into APIs`

package/skills/api-designer/SKILL.md

@@ -0,0 +1,209 @@
+# Skill: API Designer
+
+> 基于时序图设计 OpenAPI 3.0+ YAML 规格，让 API 从场景中自然浮现而非凭空定义。每个端点可追溯到时序图的 Step 编号，确保"无场景不设计 API"。
+
+## 触发条件
+
+- 用户要求设计 API 或编写 API 文档
+- 用户提到 "Phase 3 Step 2"、"API 设计"
+- 已有场景时序图，需要细化 API 规格
+- 用户提供了一个 API 端点需要详细设计
+
+## 前置依赖
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` 中包含场景时序图
+- `logos/resources/prd/3-technical-plan/1-architecture/` 中包含架构概要（确认前后端分离方式、认证方案等）
+- `logos-project.yaml` 的 `tech_stack` 已填写
+
+如果时序图目录为空，提示用户先完成 Phase 3 Step 1（scenario-architect）。
+
+## 核心能力
+
+1. 从时序图中提取所有跨系统边界的 API 调用
+2. 去重、合并、按领域分组，形成端点清单
+3. 设计 OpenAPI 3.0+ YAML 规格（路径、参数、请求体、响应结构）
+4. 定义统一的错误响应格式和错误码体系
+5. 设计认证方案（Bearer Token / API Key / Cookie）
+6. 设计分页、排序、过滤的标准化参数
+
+## 执行步骤
+
+### Step 1: 读取场景上下文
+
+读取以下文件建立完整上下文：
+
+- **场景时序图**（`logos/resources/prd/3-technical-plan/2-scenario-implementation/`）：提取所有跨系统边界的箭头
+- **架构概要**（`logos/resources/prd/3-technical-plan/1-architecture/`）：确认认证方案、前后端分离方式、API 网关等
+- **`logos-project.yaml`**：读取 `tech_stack` 确认后端框架和部署方式
+
+### Step 2: 提取端点清单
+
+遍历所有场景时序图，收集每个跨系统边界的调用箭头：
+
+1. 识别"跨系统边界"的箭头——客户端到服务端、服务端到外部服务、服务间调用
+2. 为每个箭头提取：HTTP 方法、路径、所属场景编号和 Step 编号
+3. 去重合并——同一个端点可能在多个场景中出现（如 `POST /api/auth/login` 可能在 S02 和 S03 都有）
+4. 输出端点清单摘要供用户确认：
+
+```markdown
+从时序图中识别到 N 个 API 端点：
+
+| # | 方法 | 路径 | 来源场景 | 领域 |
+|---|------|------|---------|------|
+| 1 | POST | /api/auth/register | S01 Step 2 | auth |
+| 2 | POST | /api/auth/login | S02 Step 1 | auth |
+| 3 | GET  | /api/projects | S04 Step 1 | projects |
+```
+
+### Step 3: 按领域分组
+
+将端点按业务领域分组，每组对应一个 YAML 文件：
+
+- `auth.yaml` — 认证相关（注册、登录、登出、重置密码）
+- `projects.yaml` — 核心业务对象的 CRUD
+- `billing.yaml` — 支付和订阅
+
+分组原则：
+- 同一数据实体的操作放在一起
+- 认证/授权独立分组
+- 第三方服务回调（如支付回调）放在对应业务领域
+
+### Step 4: 设计统一约定
+
+在生成具体端点前，先确定全局约定：
+
+**认证方案**（从架构概要中读取）：
+
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+```
+
+**统一错误响应**：
+
+```yaml
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          description: 机器可读的错误码（如 EMAIL_EXISTS）
+        message:
+          type: string
+          description: 人类可读的错误描述
+        details:
+          type: object
+          description: 附加错误信息（如字段级校验错误）
+```
+
+**分页参数**（适用于列表端点）：
+
+```yaml
+parameters:
+  - name: page
+    in: query
+    schema: { type: integer, minimum: 1, default: 1 }
+  - name: per_page
+    in: query
+    schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+```
+
+### Step 5: 逐端点设计详细规格
+
+为每个端点设计完整的 OpenAPI 规格，**逐领域输出**，每完成一个领域暂停让用户 review：
+
+每个端点必须包含：
+- `operationId`：唯一标识符，用于代码生成
+- `summary`：一句话描述
+- `description`：标注来源时序图步骤（如 `来源：S01 Step 2 → Step 3`）
+- `requestBody`：包含所有字段的 schema（含 required、类型、校验规则如 minLength/format）
+- `responses`：覆盖正常响应 + 所有已知异常（从时序图的 EX 用例中提取）
+
+**示例**：
+
+```yaml
+paths:
+  /api/auth/register:
+    post:
+      operationId: register
+      summary: 用户注册
+      description: "来源：S01 Step 2 → Step 3"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [email, password]
+              properties:
+                email: { type: string, format: email }
+                password: { type: string, minLength: 8 }
+      responses:
+        '201':
+          description: 注册成功，发送验证邮件
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userId: { type: string, format: uuid }
+                  message: { type: string }
+        '409':
+          description: "邮箱已被注册（EX-2.1）"
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: 请求参数校验失败
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+```
+
+### Step 6: 验证追溯完整性
+
+输出完成后，做一次追溯检查：
+
+1. **正向检查**：每个时序图中的跨系统箭头都有对应的 API 端点
+2. **反向检查**：每个 API 端点的 `description` 都标注了来源 Step
+3. **异常覆盖**：时序图中的每个 EX 用例都有对应的 HTTP 错误响应
+
+如果发现遗漏，补充后再输出最终版本。
+
+## 输出规范
+
+- 文件格式：OpenAPI 3.1 YAML
+- 存放位置：`logos/resources/api/`
+- 按领域分文件：`auth.yaml`、`projects.yaml`、`billing.yaml`
+- 每个文件包含完整的 `openapi`、`info`、`paths`、`components` 段
+- 错误响应统一引用 `$ref: '#/components/schemas/ErrorResponse'`
+- 每个端点的 `description` 必须标注来源时序图步骤
+
+## 实践经验
+
+- **API 从时序图浮现**：如果一个 API 在时序图中找不到出处，它大概率不应该存在。先画时序图再设计 API，而非反过来
+- **路径命名**：RESTful 风格，使用复数名词，`/api/{resource}`
+- **版本前缀**：初期不加版本前缀（`/api/auth/register`），需要版本管理时再加 `/api/v2/`
+- **状态码语义**：严格遵循 HTTP 状态码语义——200 成功、201 创建、400 参数错误、401 未认证、403 无权限、404 不存在、409 冲突、422 校验失败、500 服务错误
+- **幂等设计**：PUT/DELETE 操作必须幂等
+- **敏感数据**：响应中不包含密码、token 等敏感信息的明文
+- **逐领域输出**：不要一次输出所有端点——按领域分批输出，每批让用户 review 后再继续
+- **字段命名一致**：API 中的字段名要与后续 DB 设计中的列名保持一致（或有明确的映射规则），避免代码层出现不必要的字段转换
+
+## 推荐提示词
+
+以下提示词可以直接复制给 AI 使用：
+
+- `帮我设计 API`
+- `基于时序图帮我生成 OpenAPI YAML`
+- `帮我设计 S01 相关的 API 规格`
+- `帮我把所有时序图中的跨系统调用提取为 API`

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

@@ -0,0 +1,181 @@
+# Skill: Architecture Designer
+
+> Before diving into per-scenario technical implementation, establish the project's technical global view — system architecture, technology selection, deployment topology, and non-functional constraints. Ensure that subsequent sequence diagrams, API designs, and code generation all proceed under consistent architectural constraints.
+
+## Trigger Conditions
+
+- User requests designing technical architecture, making technology selections, or planning system architecture
+- User mentions "Phase 3 Step 0", "architecture design", "technical plan"
+- Phase 2 product design documents are complete, and Phase 3 needs to begin
+- User wants to determine the tech stack or deployment strategy
+
+## Core Capabilities
+
+1. Read Phase 1 requirements documents and Phase 2 product design documents to understand the full product picture
+2. Based on product complexity and scenario characteristics, recommend suitable system architectures
+3. Provide selection rationale and alternative comparisons for each technology choice
+4. Draw system architecture diagrams (Mermaid) and deployment topology diagrams
+5. Update the `tech_stack` field in `logos-project.yaml`
+
+## Integration with Phase 1/2
+
+Architecture design is the bridge from Phase 2 (product design) to Phase 3 (technical implementation). Its inputs come from Phase 1/2, and its outputs influence all subsequent steps in Phase 3:
+
+| Input (from Phase 1/2) | Output (influences subsequent Phase 3 steps) |
+|------------------------|------------------------------|
+| Scenario list and complexity | System boundary definition → sequence diagram participants |
+| Non-functional requirements (performance, security) | Technology selection constraints → API design decisions |
+| Product interaction type (Web/Mobile/API) | Frontend tech stack → prototype implementation approach |
+| Data volume and access patterns | Database selection → DB design |
+| Third-party service dependencies (payment, email, etc.) | Integration approach → external participants in sequence diagrams |
+
+## Execution Steps
+
+### Step 1: Understand the Full Product Picture
+
+Read the following documents to build an overall understanding of the project:
+
+- **Requirements Document** (Phase 1): Product positioning, core scenarios, constraints and boundaries
+- **Product Design Document** (Phase 2): Information architecture, page structure, interaction complexity
+- **Existing `logos-project.yaml`**: Whether there are initial selections in the current `tech_stack`
+
+Key points to extract:
+- Number and complexity of core scenarios
+- Whether there are real-time requirements (WebSocket, SSE)
+- Whether there are background tasks (scheduled tasks, message queues)
+- List of third-party service dependencies
+- Expected user scale
+
+### Step 2: Determine System Architecture
+
+Choose an architecture pattern based on product complexity:
+
+**Simple Projects** (personal SaaS, utility products):
+- Monolithic architecture + single database
+- Architecture overview can be a paragraph of text + a simple diagram
+
+**Medium Projects** (team SaaS, multi-role systems):
+- Frontend-backend separation + monolithic backend + single database
+- May need auxiliary services like object storage, caching, etc.
+
+**Complex Projects** (multi-service, high-concurrency, multi-platform):
+- Microservices / modular monolith
+- Requires detailed Architecture Decision Records (ADR)
+
+Draw system architecture diagram using 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: Technology Selection
+
+Provide selection and rationale for each technology dimension:
+
+```markdown
+| Dimension | Selection | Rationale | Alternatives |
+|-----------|-----------|-----------|-------------|
+| Language | TypeScript | Unified frontend/backend, type safety | Go (when performance is priority) |
+| Frontend Framework | Next.js 15 | SSR + RSC, mature ecosystem | Astro (content sites), Nuxt (Vue ecosystem) |
+| Backend Framework | Hono | Lightweight, edge-first, native TS | Express (ecosystem), Fastify (performance) |
+| Database | PostgreSQL | Feature-rich, JSONB, RLS | MySQL (simple scenarios) |
+| Authentication | Supabase Auth | Out-of-the-box, RLS integration | NextAuth (self-hosted) |
+| Deployment | Vercel + Supabase | Zero-ops, auto-scaling | AWS (full control) |
+```
+
+**Selection Principles**:
+- Prefer technologies the team is already familiar with
+- When there is no significant difference, choose the option with the larger community
+- Selection rationale must be linked to specific product requirements or constraints
+
+### Step 4: Non-Functional Constraints
+
+Define key non-functional requirements:
+
+- **Performance Targets**: Core API response time, page load time
+- **Security Requirements**: Authentication method, data encryption, CORS policy
+- **Scalability**: Expected user scale, data growth estimates
+- **Observability**: Logging, monitoring, alerting strategy
+- **Developer Experience**: Local development environment, CI/CD pipeline
+
+### Step 5: External Dependencies and Test Strategies
+
+Catalog all external service dependencies for the project and determine the isolation strategy for each dependency during orchestration testing. The output of this step directly impacts whether Phase 3 Step 3 (orchestration testing) can be executed smoothly.
+
+1. Identify external dependencies from the architecture diagram and sequence diagram participants (email, SMS, verification codes, payment, OAuth, etc.)
+2. Confirm the test strategy for each dependency with the user
+
+Available test strategies:
+
+| Strategy | Description | Typical Scenario |
+|----------|-------------|-----------------|
+| `test-api` | Test environment provides a backdoor API | Email/SMS verification codes |
+| `fixed-value` | Specific test data uses fixed values | Fixed verification code for test phone numbers |
+| `env-disable` | Environment variable disables the feature | CAPTCHA, slider verification |
+| `mock-callback` | Orchestration actively calls a simulated callback | Payment callbacks, Webhooks |
+| `mock-service` | Local mock service as replacement | OAuth Provider |
+
+If the project has no external service dependencies (e.g., a pure CLI tool), this step can be skipped.
+
+### Step 6: Update logos-project.yaml
+
+Write the confirmed technology selections into the `tech_stack` field of `logos-project.yaml`, and write external dependencies and test strategies into the `external_dependencies` field, ensuring that all subsequent Skills and AI tools can read the unified tech stack and testing conventions.
+
+```yaml
+external_dependencies:
+  - name: "Email Service"
+    provider: "SendGrid"
+    used_in: ["S01-User Registration", "S03-Forgot Password"]
+    test_strategy: "test-api"
+    test_config: "GET /api/test/latest-email?to={email}"
+```
+
+## Output Specification
+
+- Architecture overview document: `logos/resources/prd/3-technical-plan/1-architecture/01-architecture-overview.md`
+- Architecture diagrams use Mermaid format
+- Technology selections use table format, each item must include rationale
+- Update the `tech_stack` and `external_dependencies` fields in `logos-project.yaml`
+- Simple projects are allowed to have streamlined output (not all sections are mandatory)
+
+## Best Practices
+
+- **Don't over-engineer**: For a solo developer building SaaS, monolith + PostgreSQL + Vercel is sufficient — don't jump straight to microservices
+- **Selection rationale matters more than the selection itself**: Documenting "why X was chosen" is more valuable than "X was chosen", because rationale needs to be re-evaluated as the project evolves
+- **Architecture diagrams are prerequisites for sequence diagrams**: System components in the architecture diagram become participants in subsequent sequence diagrams — the two must be consistent
+- **tech_stack is the AI's anchor**: Subsequent AI code generation reads `tech_stack` from `logos-project.yaml` — inaccurate selections will result in unusable generated code
+- **Start loose with non-functional constraints, tighten later**: Don't set overly strict performance targets initially; tighten them as real data becomes available
+- **Test strategies must be decided during the architecture phase**: If test approaches for verification codes, payments, and other external dependencies are left until orchestration testing, you'll often find that no backdoor APIs were provisioned, making fully automated orchestration tests impossible
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me design the technical architecture`
+- `Based on the product design, help me make technology selections`
+- `Help me draw the system architecture diagram`
+- `Help me determine the tech stack and update logos-project.yaml`