@miniidealab/openlogos 0.3.0 → 0.3.2

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`

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