@miniidealab/openlogos 0.3.0 → 0.3.2

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

@@ -0,0 +1,212 @@
+# Skill: DB Designer
+
+> Derive database table structures from API specifications and generate SQL DDL in the appropriate dialect. The database type is determined during Phase 3 Step 0 technology selection, ensuring that field types, constraints, indexes, and security policies are fully aligned with API endpoints.
+
+## Trigger Conditions
+
+- User requests database design or SQL writing
+- User mentions "Phase 3 Step 2", "DB design", "table structure"
+- API YAML specifications already exist and database design needs to be derived
+- User provides a data model that needs to be converted to DDL
+
+## Core Capabilities
+
+1. Derive table structures from API request/response structures
+2. Read `tech_stack.database` from `logos-project.yaml` to determine the database type
+3. Generate SQL DDL in the corresponding database dialect
+4. Design indexes with rationale for each
+5. Design security policies (RLS / application-level permissions)
+6. Add comments to every table and every field
+
+## Prerequisites
+
+- `logos/resources/api/` contains API YAML specifications (output from api-designer)
+- `tech_stack.database` in `logos-project.yaml` is filled in
+
+If the API directory is empty, prompt the user to complete the API design (api-designer) in Phase 3 Step 2 first. If `tech_stack.database` is not filled in, prompt the user to complete Phase 3 Step 0 (architecture-designer) first.
+
+## Execution Steps
+
+### Step 1: Determine Database Type
+
+Read the `tech_stack` field from `logos/logos-project.yaml` to determine the database type and dialect:
+
+- PostgreSQL → Use features like UUID, TIMESTAMPTZ, RLS, JSONB, etc.
+- MySQL → Use features like InnoDB, utf8mb4, TIMESTAMP, etc.
+- SQLite → Use simplified types like INTEGER PRIMARY KEY, TEXT, etc.
+- Other → Confirm with the user and select the closest dialect
+
+### Step 2: Extract Data Entities
+
+Extract all data entities that need to be persisted from the API YAML:
+
+1. Scan `requestBody` and `responses` across all endpoints to identify core data objects
+2. Distinguish between "needs persistence" and "transfer-only" data:
+   - Objects with CRUD operations → need a table (e.g., `users`, `projects`)
+   - Objects that only appear in requests/responses but are not stored directly → no table needed (e.g., `loginRequest`)
+3. Annotate each object with its source API endpoint
+
+Output an entity checklist for user confirmation:
+
+```markdown
+Identified N data entities requiring persistence from API specifications:
+
+| # | Entity | Source Endpoint | Core Fields |
+|---|--------|----------------|-------------|
+| 1 | users | auth.yaml → register, login | email, password, status |
+| 2 | projects | projects.yaml → create, list, get | name, description, owner_id |
+| 3 | subscriptions | billing.yaml → subscribe | plan, status, expires_at |
+```
+
+### Step 3: Design Table Structures
+
+Design complete table structures for each entity, following the current database dialect:
+
+**Every table must include**:
+- Primary key (UUID or auto-increment ID, depending on dialect)
+- Business fields (mapped from API schema, with types converted to database types)
+- Audit fields: `created_at`, `updated_at`
+- Soft delete field: `deleted_at` (as needed)
+- Field constraints: `NOT NULL`, `UNIQUE`, `CHECK`, `DEFAULT`
+
+**Type mapping principles**:
+- API `string + format: email` → `TEXT NOT NULL` (with CHECK constraint or application-level validation)
+- API `string + format: uuid` → `UUID` (PostgreSQL) / `CHAR(36)` (MySQL)
+- API `integer` → `INTEGER` / `BIGINT`
+- API `boolean` → `BOOLEAN` (PostgreSQL) / `TINYINT(1)` (MySQL)
+- API `string + enum` → `TEXT + CHECK` constraint (listing enum values)
+- Monetary fields → `INTEGER` (store in cents), **DECIMAL/FLOAT is prohibited**
+
+**Example (PostgreSQL)**:
+
+```sql
+-- Users table (source: auth.yaml → register, login)
+CREATE TABLE users (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  email       TEXT NOT NULL UNIQUE,
+  password    TEXT NOT NULL,
+  status      TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending', 'active', 'disabled')),
+  created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+### Step 4: Design Table Relationships
+
+Design foreign keys based on entity relationships in the API:
+
+1. Derive relationships from nested paths and reference fields in API endpoints (e.g., `/api/projects/:projectId/members` → `project_members` table linking `projects` and `users`)
+2. Determine relationship types (one-to-many, many-to-many)
+3. Design foreign key constraints and cascade strategies:
+   - `ON DELETE CASCADE`: child records are deleted when the parent record is deleted (e.g., user deleted → projects deleted)
+   - `ON DELETE SET NULL`: child records are retained but the foreign key is set to null when the parent is deleted
+   - `ON DELETE RESTRICT`: prevent deletion of the parent record if child records exist
+
+### Step 5: Design Security Policies
+
+Design corresponding security mechanisms based on the database type:
+
+**PostgreSQL — Row-Level Security (RLS)**:
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY projects_owner_policy ON projects
+  USING (owner_id = auth.uid());
+```
+
+- Enable RLS on all tables containing user data
+- Design at least one Policy per table (owner / admin / public)
+- Document the correspondence between RLS policies and the API authentication scheme
+
+**MySQL — Application-Level Permissions**:
+
+- Annotate data access permissions in table comments (owner-only / admin / public)
+- Do not implement permission control in DDL; delegate to the application layer
+
+### Step 6: Design Indexes
+
+Design indexes for common query patterns, with a rationale for each index:
+
+```sql
+-- User lookup by email (login scenario, source: S02)
+CREATE UNIQUE INDEX idx_users_email ON users(email);
+
+-- Project lookup by owner (project list, source: S04 Step 1)
+CREATE INDEX idx_projects_owner ON projects(owner_id);
+```
+
+Index design principles:
+- Foreign key columns: indexes are mandatory (to avoid full table scans on JOINs)
+- Unique constraint columns: unique indexes are created automatically
+- High-frequency query columns: determine based on API query parameters
+- Composite indexes: consider for multi-condition queries (leftmost prefix rule)
+- Avoid over-indexing: limit index count on write-heavy tables
+
+### Step 7: Output Complete DDL
+
+Organize the DDL file in the following order:
+
+1. File header comment (source, database type, generation timestamp)
+2. Base tables (tables without foreign key dependencies first)
+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`)
+
+Add a comment above each DDL block noting the source API endpoint.
+
+## 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)
+- 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 '...'` |
+
+## Best Practices
+
+### General (All Databases)
+
+- **Store monetary values as INTEGER in cents**: DECIMAL/FLOAT is prohibited to avoid floating-point precision issues
+- **Soft delete**: prefer a `deleted_at` timestamp field over physical deletion
+- **Audit fields**: every table should include `created_at` and `updated_at`
+- **Timestamp fields with timezone**: avoid timezone pitfalls
+- **Field names aligned with API**: DB column names should match API YAML field names as closely as possible (e.g., API uses `userId` → DB uses `user_id`; as long as the mapping rule is clear), reducing unnecessary transformations in the code layer
+- **Core tables first, auxiliary tables later**: don't try to design all tables at once — output core business tables for user review first, then add auxiliary tables
+
+### PostgreSQL-Specific
+
+- **Primary key**: `id UUID DEFAULT gen_random_uuid() PRIMARY KEY`
+- **Timestamp type**: use `TIMESTAMPTZ`
+- **RLS**: enable on all tables with `ALTER TABLE ... ENABLE ROW LEVEL SECURITY;`
+- **JSONB**: prefer JSONB for unstructured storage and create GIN indexes
+
+### MySQL-Specific
+
+- **Primary key**: `id CHAR(36) DEFAULT (UUID()) PRIMARY KEY` or auto-increment BIGINT
+- **Timestamp type**: use `TIMESTAMP` (automatic timezone conversion) or `DATETIME` (stored as-is)
+- **Character set**: specify `CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci` when creating tables
+- **Engine**: always use `ENGINE=InnoDB`
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me design the database`
+- `Derive database DDL from the API specifications`
+- `Help me design the database tables involved in S01`
+- `Help me add indexes and RLS policies to the existing table structures`

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/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`