@miniidealab/openlogos 0.9.4 → 0.9.6

package/claude-plugin-template/skills/code-implementor/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: code-implementor
+description: "Generate business code and test code based on the full specification chain (sequence diagrams, API YAML, DB DDL, test case specs). Use when test cases exist in logos/resources/test/ but logos/resources/implementation/ is empty."
+---
+
+# Skill: Code Implementor
+
+> Generate business code and test code based on the full specification chain (sequence diagrams, API YAML, DB DDL, test case specs). Ensure strict spec fidelity, embed OpenLogos reporter, and deliver closed-loop batches per scenario.
+
+## Trigger Conditions
+
+- User requests code implementation or code generation
+- User mentions "Phase 3 Step 4", "code generation", "implement S01"
+- Test case design is complete (`logos/resources/test/` is non-empty) and coding should begin
+- User specifies a scenario number (e.g., S01) to implement
+
+## Prerequisites
+
+- `logos/resources/prd/3-technical-plan/2-scenario-implementation/` contains sequence diagrams (**required**)
+- `logos/resources/api/` contains API specifications (read if present)
+- `logos/resources/database/` contains DB DDL (read if present)
+- `logos/resources/test/` contains test case specifications (**required**)
+- `logos/logos-project.yaml` contains `tech_stack` (**required**)
+
+If sequence diagrams or test case directories are empty, prompt the user to complete Phase 3 Step 1 (scenario-architect) and Step 3a (test-writer) first.
+
+## Core Capabilities
+
+1. Load full specification context to establish an implementation baseline
+2. Plan batch execution strategy, splitting large tasks by scenario or module
+3. Generate business code strictly consistent with API YAML (routes, status codes, error codes, fields)
+4. Generate data access code strictly aligned with DB DDL (table names, column names, types, constraints)
+5. Generate test code with IDs exactly matching test-cases.md
+6. Embed OpenLogos reporter in test code (outputting to `test-results.jsonl`)
+7. Self-check after each batch to ensure spec fidelity
+
+## Relationship with test-writer and code-reviewer
+
+This Skill sits in the middle of a three-Skill chain:
+
+- **test-writer** (Step 3a): Designs test case **specification documents** (Markdown), defines UT/ST IDs — the "exam designer"
+- **code-implementor** (Step 4, this Skill): Transforms all specs into **runnable business code and test code** — the "exam taker"
+- **code-reviewer** (after Step 4): Audits generated business code against specs, outputs a review report — the "exam grader"
+
+test-writer writes no code; code-implementor designs no test cases; code-reviewer modifies no code. Together they form a **Design → Execute → Review** closed loop.
+
+## Execution Steps
+
+### Step 1: Load Specification Context
+
+**Before writing any line of code**, read the following documents to establish full context:
+
+| Document | Path | Purpose |
+|----------|------|---------|
+| Architecture | `prd/3-technical-plan/1-architecture/` | Overall structure, framework, design patterns |
+| Sequence diagrams | `prd/3-technical-plan/2-scenario-implementation/` | Implementation blueprint — Step sequence = code call chain |
+| API specs | `logos/resources/api/*.yaml` | Endpoint contracts — routes, methods, status codes, fields |
+| DB DDL | `logos/resources/database/*.sql` | Data layer contracts — table structures, constraints, indexes |
+| Test case specs | `logos/resources/test/*-test-cases.md` | Verification targets — UT/ST IDs, expected inputs/outputs |
+| Orchestration tests | `logos/resources/scenario/*.json` | End-to-end verification targets (API projects) |
+| Project config | `logos/logos-project.yaml` | `tech_stack`, `external_dependencies` |
+| Source roots | `logos/logos.config.json` → `sourceRoots` | Output root directories for business code and test code |
+
+After loading, confirm:
+- Which scenarios are in scope (S01, S02...)
+- Which API endpoints and DB tables are involved
+- Total UT/ST case count
+- Technology stack confirmation (language, framework, test framework)
+- Source output directories confirmed (read `sourceRoots.src` and `sourceRoots.test`; default to `src/` and `test/` if absent)
+
+### Step 2: Plan Batch Strategy
+
+**Large tasks must be batched, but each batch must be closed-loop.**
+
+1. **Split dimension**: By scenario (S01, S02) or by module (auth, projects)
+2. **Pre-batch declaration**: Before each batch, list the UT/ST case IDs covered, ensuring traceability to `logos/resources/test/*.md`
+3. **Closed-loop requirement**: Each batch must deliver all three elements — business code + test code + reporter
+4. **No deferred testing**: "Write all business code first, add tests later" is not allowed
+
+### Step 3: Generate Business Code
+
+Implement business logic following the sequence diagram Step sequence, strictly adhering to API YAML and DB DDL fidelity rules.
+
+### Step 4: Generate Test Code
+
+Every test file must embed the OpenLogos reporter per `logos/spec/test-results.md`:
+
+- Output path: `logos/resources/verify/test-results.jsonl`
+- Format: JSONL (one JSON object per line)
+- Each case outputs: `{ "id": "UT-S01-01", "status": "pass"|"fail"|"skip", ... }`
+
+### Step 5: Self-Check
+
+After each batch, verify:
+- [ ] API route paths and HTTP methods match YAML
+- [ ] HTTP status codes match YAML
+- [ ] DB operations use correct table/column names from DDL
+- [ ] All pre-declared UT/ST IDs exist in test code
+- [ ] Reporter is embedded with correct output path
+
+### Step 6: Guide Next Steps
+
+After all batches complete, guide the user to run `openlogos verify` for Gate 3.5 acceptance.
+
+## Output Specification
+
+- **Business code**: `sourceRoots.src` (default `src/`)
+- **Test code**: `sourceRoots.test` (default `test/`)
+- **JSONL results**: `logos/resources/verify/test-results.jsonl`
+- **Implementation manifest**: `logos/resources/implementation/implementation-manifest.md`
+
+## Recommended Prompts
+
+- `Help me implement S01`
+- `Execute Phase 3 Step 4, batch by scenario`
+- `Please execute Phase 3 Step 4 for S01. Deliver business code + test code + OpenLogos reporter in each batch.`

package/claude-plugin-template/skills/code-reviewer/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: code-reviewer
+description: "Review code for OpenLogos methodology compliance, including YAML validity checks. Use when reviewing code changes, checking pull requests, or performing code quality analysis."
+---
+
+# 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
+
+**Pre-check — YAML Validity (before anything else):**
+
+Before loading API specs, validate that all `logos/resources/api/*.yaml` files are syntactically valid YAML and conform to the OpenAPI 3.x schema. If any file fails parsing (e.g., unquoted special characters in `description` fields), report it as a **Critical** blocker immediately — do not proceed with the rest of the review until YAML errors are fixed.
+
+**Then** 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 |
+| YAML Validity | All `logos/resources/api/*.yaml` files parse as valid YAML and valid OpenAPI 3.x — unquoted special characters (`:`, `→`, `#`) in `description`/`summary` values are a common failure mode | Critical |
+
+**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`

package/claude-plugin-template/skills/db-designer/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: db-designer
+description: "Design database schema based on API and scenario requirements. Use when scenarios exist but logos/resources/database/ is empty."
+---
+
+# 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()
+);
+```
+
+**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:
+
+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: 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 = '...'`; 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 | 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
+
+### 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`
+
+### 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:
+
+- `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`