heraspec 0.1.14 → 0.1.15

package/dist/core/templates/skills/sql-queries/skill.md

@@ -0,0 +1,67 @@
+# Skill: SQL Queries (Cross-Cutting)
+
+## Purpose
+
+Write correct, readable, and highly performant SQL queries across all major database systems and data warehouse dialects (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## When to Use
+
+- When writing complex analytical queries involving CTEs, window functions, and cohort retention calculations.
+- When optimizing slow-running SQL queries or translating queries between database dialects.
+- When designing data models, schema migrations, and indexing strategies.
+
+## Step-by-Step Process
+
+### Step 1: Analyze Schema & Dialect
+- Identify the target database engine (PostgreSQL, BigQuery, Snowflake, etc.).
+- Review available table schemas, keys, indexes, and partitioning keys.
+
+### Step 2: Structure Using CTEs
+- Break down complex logic into small, readable Common Table Expressions (CTEs) representing logical steps.
+
+### Step 3: Write Dialect-Specific Logic
+- Implement date/time arithmetic, string manipulation, JSON/array functions, and window functions using syntax specific to the selected dialect.
+
+### Step 4: Performance Optimization
+- Apply database-specific optimization rules:
+  - PostgreSQL: Use `EXPLAIN ANALYZE`, index columns, prefer `EXISTS` over `IN` for subqueries.
+  - BigQuery: Minimize scanned bytes, partition on date columns, use `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Leverage clustering keys, transient tables, and avoid unnecessary warehouse resizing.
+
+### Step 5: Test & Debug
+- Verify correct handling of boundary cases (division by zero, null fields, type mismatch casting).
+
+## Required Input
+
+- **Database Engine**: PostgreSQL, BigQuery, Snowflake, etc.
+- **Goal/Query Purpose**: What analytical question the query should answer.
+- **Table Schema**: Definitions, keys, and partitioning details.
+
+## Expected Output
+
+- **Optimized SQL Code**: Full query code formatted using uppercase keywords and standard alignment.
+- **Performance Explanation**: Brief details on partition pruning, indexing, or dialect-specific functions used to speed up the query.
+- **Query Flow Explanation**: Explanation of each CTE step for developer readability.
+
+## Tone & Rules
+
+- Write clean, modern SQL using uppercase for keywords (SELECT, FROM, WHERE, etc.).
+- Always qualify column names with table aliases when using JOINs.
+- Avoid nested subqueries; always prefer Common Table Expressions (CTEs) for readability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to document database schemas or technical data flow maps.
+- **debug**: Use to diagnose and resolve errors returned by SQL execution engines.

package/dist/core/templates/skills/sql-queries/skill.vi.md

@@ -0,0 +1,67 @@
+# Kỹ năng: Truy vấn SQL (SQL Queries) (Cross-Cutting)
+
+## Mục đích
+
+Viết các câu truy vấn SQL chính xác, dễ đọc và đạt hiệu năng tối ưu trên các hệ thống cơ sở dữ liệu và kho dữ liệu phổ biến (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## Khi nào sử dụng
+
+- Khi viết các câu truy vấn phân tích phức tạp có sử dụng CTEs, hàm cửa sổ (window functions) và tính toán tỷ lệ giữ chân khách hàng (cohort retention).
+- Khi tối ưu hóa các câu lệnh SQL chạy chậm hoặc chuyển đổi cú pháp truy vấn giữa các hệ quản trị cơ sở dữ liệu khác nhau.
+- Khi thiết kế mô hình dữ liệu, viết mã dịch chuyển cấu trúc bảng (migrations) và lập chiến lược đánh chỉ mục (indexing).
+
+## Quy trình từng bước
+
+### Bước 1: Phân tích Lược đồ & Cú pháp Dialect
+- Xác định hệ quản trị cơ sở dữ liệu đích (PostgreSQL, BigQuery, Snowflake, v.v...).
+- Xem xét cấu trúc các bảng dữ liệu, khóa chính/phụ, chỉ mục (indexes) và khóa phân vùng (partition keys).
+
+### Bước 2: Cấu trúc hóa bằng CTEs
+- Chia nhỏ logic phức tạp thành các biểu thức bảng chung (Common Table Expressions - CTEs) dễ đọc, đại diện cho từng bước xử lý dữ liệu tuần tự.
+
+### Bước 3: Viết Logic Đặc thù theo Dialect
+- Triển khai các phép toán ngày/tháng, xử lý chuỗi văn bản, trích xuất JSON/mảng và các hàm cửa sổ sử dụng đúng cú pháp của cơ sở dữ liệu đích.
+
+### Bước 4: Tối ưu hóa Hiệu năng (Performance Optimization)
+- Áp dụng các quy tắc tối ưu đặc thù:
+  - PostgreSQL: Sử dụng `EXPLAIN ANALYZE` để xem chi tiết thực thi, đánh chỉ mục các cột lọc/join, ưu tiên `EXISTS` thay vì `IN` cho truy vấn con.
+  - BigQuery: Giảm thiểu dung lượng quét dữ liệu (scanned bytes), lọc theo cột phân vùng date, sử dụng `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Tận dụng khóa gom cụm (clustering keys), bảng tạm thời (transient tables) và tránh thay đổi kích thước warehouse không cần thiết.
+
+### Bước 5: Kiểm thử & Sửa lỗi
+- Xác minh cách xử lý các trường hợp đặc biệt (chia cho 0, giá trị null, ép kiểu dữ liệu mismatch).
+
+## Input yêu cầu
+
+- **Database Engine**: Loại cơ sở dữ liệu (PostgreSQL, BigQuery, Snowflake, v.v...).
+- **Mục đích truy vấn**: Câu hỏi nghiệp vụ cần trả lời bằng dữ liệu.
+- **Lược đồ bảng (Table Schema)**: Định nghĩa các bảng, kiểu dữ liệu, các trường khóa và chi tiết phân vùng.
+
+## Output mong đợi
+
+- **Mã lệnh SQL Tối ưu**: Câu lệnh SQL hoàn chỉnh được định dạng viết hoa các từ khóa chính và căn lề chuẩn mực.
+- **Giải thích Hiệu năng**: Mô tả ngắn gọn về phân vùng dữ liệu, chỉ mục hoặc hàm đặc thù được dùng để tăng tốc truy vấn.
+- **Giải thích Luồng truy vấn**: Giải thích rõ ràng mục đích của từng bước CTE để nhà phát triển dễ đọc hiểu.
+
+## Giọng điệu & Quy tắc
+
+- Viết mã SQL sạch, hiện đại bằng cách viết hoa các từ khóa chuẩn (SELECT, FROM, WHERE, v.v...).
+- Luôn đặt tên viết tắt (alias) cho các bảng và gọi tên cột kèm alias khi thực hiện JOINs.
+- Hạn chế viết các truy vấn con lồng nhau phức tạp; luôn ưu tiên sử dụng CTEs để giữ code sạch sẽ.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Sử dụng để viết tài liệu thiết kế cơ sở dữ liệu hoặc sơ đồ luồng dữ liệu kỹ thuật.
+- **debug**: Sử dụng để chẩn đoán và khắc phục các lỗi cú pháp/logic do công cụ cơ sở dữ liệu trả về.

package/dist/core/templates/skills/sql-queries-skill.md

@@ -0,0 +1,67 @@
+# Skill: SQL Queries (Cross-Cutting)
+
+## Purpose
+
+Write correct, readable, and highly performant SQL queries across all major database systems and data warehouse dialects (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## When to Use
+
+- When writing complex analytical queries involving CTEs, window functions, and cohort retention calculations.
+- When optimizing slow-running SQL queries or translating queries between database dialects.
+- When designing data models, schema migrations, and indexing strategies.
+
+## Step-by-Step Process
+
+### Step 1: Analyze Schema & Dialect
+- Identify the target database engine (PostgreSQL, BigQuery, Snowflake, etc.).
+- Review available table schemas, keys, indexes, and partitioning keys.
+
+### Step 2: Structure Using CTEs
+- Break down complex logic into small, readable Common Table Expressions (CTEs) representing logical steps.
+
+### Step 3: Write Dialect-Specific Logic
+- Implement date/time arithmetic, string manipulation, JSON/array functions, and window functions using syntax specific to the selected dialect.
+
+### Step 4: Performance Optimization
+- Apply database-specific optimization rules:
+  - PostgreSQL: Use `EXPLAIN ANALYZE`, index columns, prefer `EXISTS` over `IN` for subqueries.
+  - BigQuery: Minimize scanned bytes, partition on date columns, use `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Leverage clustering keys, transient tables, and avoid unnecessary warehouse resizing.
+
+### Step 5: Test & Debug
+- Verify correct handling of boundary cases (division by zero, null fields, type mismatch casting).
+
+## Required Input
+
+- **Database Engine**: PostgreSQL, BigQuery, Snowflake, etc.
+- **Goal/Query Purpose**: What analytical question the query should answer.
+- **Table Schema**: Definitions, keys, and partitioning details.
+
+## Expected Output
+
+- **Optimized SQL Code**: Full query code formatted using uppercase keywords and standard alignment.
+- **Performance Explanation**: Brief details on partition pruning, indexing, or dialect-specific functions used to speed up the query.
+- **Query Flow Explanation**: Explanation of each CTE step for developer readability.
+
+## Tone & Rules
+
+- Write clean, modern SQL using uppercase for keywords (SELECT, FROM, WHERE, etc.).
+- Always qualify column names with table aliases when using JOINs.
+- Avoid nested subqueries; always prefer Common Table Expressions (CTEs) for readability.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to document database schemas or technical data flow maps.
+- **debug**: Use to diagnose and resolve errors returned by SQL execution engines.

package/dist/core/templates/skills/sql-queries-skill.vi.md

@@ -0,0 +1,67 @@
+# Kỹ năng: Truy vấn SQL (SQL Queries) (Cross-Cutting)
+
+## Mục đích
+
+Viết các câu truy vấn SQL chính xác, dễ đọc và đạt hiệu năng tối ưu trên các hệ thống cơ sở dữ liệu và kho dữ liệu phổ biến (PostgreSQL, Snowflake, BigQuery, Redshift, Databricks SQL).
+
+## Khi nào sử dụng
+
+- Khi viết các câu truy vấn phân tích phức tạp có sử dụng CTEs, hàm cửa sổ (window functions) và tính toán tỷ lệ giữ chân khách hàng (cohort retention).
+- Khi tối ưu hóa các câu lệnh SQL chạy chậm hoặc chuyển đổi cú pháp truy vấn giữa các hệ quản trị cơ sở dữ liệu khác nhau.
+- Khi thiết kế mô hình dữ liệu, viết mã dịch chuyển cấu trúc bảng (migrations) và lập chiến lược đánh chỉ mục (indexing).
+
+## Quy trình từng bước
+
+### Bước 1: Phân tích Lược đồ & Cú pháp Dialect
+- Xác định hệ quản trị cơ sở dữ liệu đích (PostgreSQL, BigQuery, Snowflake, v.v...).
+- Xem xét cấu trúc các bảng dữ liệu, khóa chính/phụ, chỉ mục (indexes) và khóa phân vùng (partition keys).
+
+### Bước 2: Cấu trúc hóa bằng CTEs
+- Chia nhỏ logic phức tạp thành các biểu thức bảng chung (Common Table Expressions - CTEs) dễ đọc, đại diện cho từng bước xử lý dữ liệu tuần tự.
+
+### Bước 3: Viết Logic Đặc thù theo Dialect
+- Triển khai các phép toán ngày/tháng, xử lý chuỗi văn bản, trích xuất JSON/mảng và các hàm cửa sổ sử dụng đúng cú pháp của cơ sở dữ liệu đích.
+
+### Bước 4: Tối ưu hóa Hiệu năng (Performance Optimization)
+- Áp dụng các quy tắc tối ưu đặc thù:
+  - PostgreSQL: Sử dụng `EXPLAIN ANALYZE` để xem chi tiết thực thi, đánh chỉ mục các cột lọc/join, ưu tiên `EXISTS` thay vì `IN` cho truy vấn con.
+  - BigQuery: Giảm thiểu dung lượng quét dữ liệu (scanned bytes), lọc theo cột phân vùng date, sử dụng `APPROX_COUNT_DISTINCT`.
+  - Snowflake: Tận dụng khóa gom cụm (clustering keys), bảng tạm thời (transient tables) và tránh thay đổi kích thước warehouse không cần thiết.
+
+### Bước 5: Kiểm thử & Sửa lỗi
+- Xác minh cách xử lý các trường hợp đặc biệt (chia cho 0, giá trị null, ép kiểu dữ liệu mismatch).
+
+## Input yêu cầu
+
+- **Database Engine**: Loại cơ sở dữ liệu (PostgreSQL, BigQuery, Snowflake, v.v...).
+- **Mục đích truy vấn**: Câu hỏi nghiệp vụ cần trả lời bằng dữ liệu.
+- **Lược đồ bảng (Table Schema)**: Định nghĩa các bảng, kiểu dữ liệu, các trường khóa và chi tiết phân vùng.
+
+## Output mong đợi
+
+- **Mã lệnh SQL Tối ưu**: Câu lệnh SQL hoàn chỉnh được định dạng viết hoa các từ khóa chính và căn lề chuẩn mực.
+- **Giải thích Hiệu năng**: Mô tả ngắn gọn về phân vùng dữ liệu, chỉ mục hoặc hàm đặc thù được dùng để tăng tốc truy vấn.
+- **Giải thích Luồng truy vấn**: Giải thích rõ ràng mục đích của từng bước CTE để nhà phát triển dễ đọc hiểu.
+
+## Giọng điệu & Quy tắc
+
+- Viết mã SQL sạch, hiện đại bằng cách viết hoa các từ khóa chuẩn (SELECT, FROM, WHERE, v.v...).
+- Luôn đặt tên viết tắt (alias) cho các bảng và gọi tên cột kèm alias khi thực hiện JOINs.
+- Hạn chế viết các truy vấn con lồng nhau phức tạp; luôn ưu tiên sử dụng CTEs để giữ code sạch sẽ.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Sử dụng để viết tài liệu thiết kế cơ sở dữ liệu hoặc sơ đồ luồng dữ liệu kỹ thuật.
+- **debug**: Sử dụng để chẩn đoán và khắc phục các lỗi cú pháp/logic do công cụ cơ sở dữ liệu trả về.

package/dist/core/templates/skills/suggestion/skill.md

@@ -0,0 +1,118 @@
+# Skill: Feature Suggestion (Cross-Cutting)
+
+## Purpose
+
+This skill is used to analyze existing project structure and suggest new features that would integrate well with the current codebase. It helps identify opportunities for enhancements and new functionality based on existing patterns and architecture.
+
+## When to Use
+
+- When planning new features for a project
+- When identifying gaps in functionality
+- When analyzing project structure for enhancement opportunities
+- When proposing improvements based on existing patterns
+- When suggesting features that align with project architecture
+
+## Step-by-Step Process
+
+### Step 1: Analyze Project Structure
+- Read and understand `heraspec/project.md`
+- Review existing specs in `heraspec/specs/`
+- Analyze existing changes and their patterns
+- Identify project type and tech stack
+- Map current feature set
+
+### Step 2: Identify Integration Points
+- Find logical places for new features
+- Identify patterns in existing code
+- Determine appropriate project structure locations
+- Consider dependencies and relationships
+- Map feature hierarchy
+
+### Step 3: Generate Suggestions
+- Create feature suggestions based on analysis
+- Ensure suggestions align with project type
+- Consider existing patterns and conventions
+- Propose features that enhance current functionality
+- Suggest improvements and extensions
+
+### Step 4: Organize Suggestions
+- Group suggestions by category/domain
+- Prioritize based on feasibility and value
+- Create suggestion files in appropriate locations
+- Link suggestions to existing features
+- Document integration points
+
+### Step 5: Review and Refine
+- Review suggestions for consistency
+- Ensure suggestions follow project conventions
+- Verify integration points are correct
+- Refine based on project requirements
+- Prepare for implementation planning
+
+## Required Input
+
+- **Project structure**: Understanding of project organization
+- **Existing specs**: Current feature specifications
+- **Project type**: Type of project (plugin, module, app, etc.)
+- **Tech stack**: Technologies used in the project
+- **Domain context**: Business domain and requirements
+
+## Expected Output
+
+- Feature suggestion files
+- Suggestions organized by category
+- Integration points identified
+- Suggestions linked to existing features
+- Documentation of suggested enhancements
+
+## Tone & Rules
+
+### Suggestion Quality
+- Suggest features that add value
+- Align with project type and architecture
+- Consider existing patterns and conventions
+- Propose realistic and feasible features
+- Enhance rather than replace existing functionality
+
+### Integration
+- Identify appropriate locations for features
+- Consider dependencies and relationships
+- Follow existing project structure
+- Maintain consistency with current patterns
+- Document integration approach
+
+### Documentation
+- Clearly describe suggested features
+- Explain integration points
+- Link to related existing features
+- Provide context and rationale
+- Include implementation considerations
+
+### Limitations
+- ❌ DO NOT suggest features that conflict with existing architecture
+- ❌ DO NOT ignore project conventions
+- ❌ DO NOT suggest overly complex features
+- ❌ DO NOT duplicate existing functionality
+- ❌ DO NOT suggest features without considering integration
+
+## Available Templates
+
+- `templates/suggestion-template.md` - Template for feature suggestions
+- `templates/suggestion-category-template.md` - Template for organizing suggestions by category
+
+## Available Scripts
+
+- `scripts/analyze-project-structure.py` - Analyze project structure for suggestion opportunities
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-suggestions/` - Well-structured feature suggestions
+- `bad-suggestions/` - Examples to avoid
+
+## Links to Other Skills
+
+- **documents**: Use to document suggestion rationale
+- **unit-test**: Consider testability when suggesting features
+- **integration-test**: Consider integration testing when suggesting features
+

package/dist/core/templates/skills/system-design/skill.md

@@ -0,0 +1,70 @@
+# Skill: System Design (Cross-Cutting)
+
+## Purpose
+
+Evaluate architectural decisions, design API endpoints, model data schemas, and analyze trade-offs.
+
+## When to Use
+
+- When architecting a new microservice, system, or database model
+- When defining API boundaries and integration contracts between components
+- When scaling system capacities and outlining horizontal/vertical tradeoffs
+
+## Step-by-Step Process
+
+### Step 1: Gather Requirements & Constraints
+- List functional requirements (what the system must do)
+- List non-functional requirements (throughput, scale, latency, availability)
+- Identify technical constraints (team skill set, budget, timeline, existing stack)
+
+### Step 2: High-Level Design
+- Map out system components (services, clients, data stores)
+- Outline data flow and request/response lifecycles
+- Choose datastores (SQL, NoSQL, Cache, Document store)
+
+### Step 3: Deep Dive & Contract Design
+- Define database schema models and indexing strategies
+- Design concrete API contracts (REST endpoints, GraphQL query structures, gRPC specs)
+- Design error-handling patterns, caching strategies, and event queue definitions
+
+### Step 4: Trade-off Analysis
+- Document choices explicitly using architectural trade-offs (e.g. Read latency vs Write latency)
+- Formulate scaling strategies (sharding, replication, failover mechanisms)
+
+## Required Input
+
+- Architecture goals, specifications, or user stories
+- Expected load (requests per second, data size)
+- Pre-existing tech stack constraints
+
+## Expected Output
+
+- System design document containing:
+  - Architecture diagram (ASCII or Mermaid)
+  - Data model and DB schema
+  - API endpoint specifications
+  - Cache/Queue strategy
+  - Explicit trade-off analysis
+
+## Tone & Rules
+
+- Every design decision must have a corresponding trade-off analyzed.
+- Keep designs modular and explain service boundaries clearly.
+- Avoid over-engineering. Design for 10x scale, but build for 1.5x scale.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to generate product and technical specification documents.
+- **suggestion**: Use to analyze existing systems and suggest architectural improvements.

package/dist/core/templates/skills/system-design/skill.vi.md

@@ -0,0 +1,70 @@
+# Kỹ năng: Thiết kế Hệ thống (System Design) (Cross-Cutting)
+
+## Mục đích
+
+Đánh giá các quyết định kiến trúc, thiết kế các API endpoint, mô hình hóa lược đồ dữ liệu (database schemas) và phân tích các yếu tố đánh đổi (trade-offs).
+
+## Khi nào sử dụng
+
+- Khi thiết kế một microservice, hệ thống, hoặc mô hình cơ sở dữ liệu mới
+- Khi định nghĩa các ranh giới API và hợp đồng tích hợp (integration contracts) giữa các component
+- Khi mở rộng quy mô hệ thống và phác thảo các yếu tố đánh đổi giữa mở rộng theo chiều dọc và chiều ngang
+
+## Quy trình từng bước
+
+### Bước 1: Thu thập Yêu cầu & Ràng buộc
+- Liệt kê các yêu cầu chức năng (hệ thống phải làm gì)
+- Liệt kê các yêu cầu phi chức năng (throughput, quy mô, độ trễ, tính sẵn sàng)
+- Xác định các ràng buộc kỹ thuật (năng lực của team, ngân sách, thời gian, công nghệ hiện có)
+
+### Bước 2: Thiết kế Mức Cao (High-Level Design)
+- Phác thảo sơ đồ các component (services, clients, data stores)
+- Phác thảo luồng dữ liệu và vòng đời của request/response
+- Lựa chọn giải pháp lưu trữ (SQL, NoSQL, Cache, Document store)
+
+### Bước 3: Thiết kế Chi tiết & Hợp đồng API
+- Định nghĩa các mô hình schema database và chiến lược đánh index
+- Thiết kế hợp đồng API cụ thể (REST endpoints, cấu trúc GraphQL, đặc tả gRPC)
+- Thiết kế cơ chế xử lý lỗi, chiến lược lưu cache và định nghĩa hàng đợi sự kiện (event queue)
+
+### Bước 4: Phân tích Đánh đổi (Trade-off Analysis)
+- Tài liệu hóa rõ ràng các lựa chọn kiến trúc kèm phân tích đánh đổi (ví dụ: Tối ưu đọc vs. Tối ưu ghi)
+- Xây dựng chiến lược mở rộng (sharding, replication, cơ chế failover)
+
+## Input yêu cầu
+
+- Mục tiêu kiến trúc, đặc tả kỹ thuật hoặc user stories
+- Tải trọng dự kiến (requests mỗi giây, kích thước dữ liệu)
+- Ràng buộc về công nghệ hiện có của dự án
+
+## Output mong đợi
+
+- Tài liệu thiết kế hệ thống bao gồm:
+  - Sơ đồ kiến trúc (ASCII hoặc Mermaid)
+  - Mô hình dữ liệu và DB schema
+  - Đặc tả kỹ thuật các API endpoint
+  - Chiến lược Cache/Queue
+  - Phân tích đánh đổi rõ ràng
+
+## Giọng điệu & Quy tắc
+
+- Mọi quyết định thiết kế đều phải kèm theo phân tích đánh đổi tương ứng.
+- Đảm bảo tính mô-đun của thiết kế và giải thích rõ ranh giới giữa các service.
+- Tránh over-engineering (thiết kế quá phức tạp). Hãy thiết kế cho quy mô 10x nhưng xây dựng cho quy mô 1.5x trước.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để tạo tài liệu đặc tả kỹ thuật và sản phẩm.
+- **suggestion**: Dùng để phân tích hệ thống hiện tại và đề xuất cải tiến kiến trúc.

package/dist/core/templates/skills/system-design-skill.md

@@ -0,0 +1,70 @@
+# Skill: System Design (Cross-Cutting)
+
+## Purpose
+
+Evaluate architectural decisions, design API endpoints, model data schemas, and analyze trade-offs.
+
+## When to Use
+
+- When architecting a new microservice, system, or database model
+- When defining API boundaries and integration contracts between components
+- When scaling system capacities and outlining horizontal/vertical tradeoffs
+
+## Step-by-Step Process
+
+### Step 1: Gather Requirements & Constraints
+- List functional requirements (what the system must do)
+- List non-functional requirements (throughput, scale, latency, availability)
+- Identify technical constraints (team skill set, budget, timeline, existing stack)
+
+### Step 2: High-Level Design
+- Map out system components (services, clients, data stores)
+- Outline data flow and request/response lifecycles
+- Choose datastores (SQL, NoSQL, Cache, Document store)
+
+### Step 3: Deep Dive & Contract Design
+- Define database schema models and indexing strategies
+- Design concrete API contracts (REST endpoints, GraphQL query structures, gRPC specs)
+- Design error-handling patterns, caching strategies, and event queue definitions
+
+### Step 4: Trade-off Analysis
+- Document choices explicitly using architectural trade-offs (e.g. Read latency vs Write latency)
+- Formulate scaling strategies (sharding, replication, failover mechanisms)
+
+## Required Input
+
+- Architecture goals, specifications, or user stories
+- Expected load (requests per second, data size)
+- Pre-existing tech stack constraints
+
+## Expected Output
+
+- System design document containing:
+  - Architecture diagram (ASCII or Mermaid)
+  - Data model and DB schema
+  - API endpoint specifications
+  - Cache/Queue strategy
+  - Explicit trade-off analysis
+
+## Tone & Rules
+
+- Every design decision must have a corresponding trade-off analyzed.
+- Keep designs modular and explain service boundaries clearly.
+- Avoid over-engineering. Design for 10x scale, but build for 1.5x scale.
+
+## Available Templates
+
+- None
+
+## Available Scripts
+
+- None
+
+## Examples
+
+See `examples/` directory.
+
+## Links to Other Skills
+
+- **documents**: Use to generate product and technical specification documents.
+- **suggestion**: Use to analyze existing systems and suggest architectural improvements.

package/dist/core/templates/skills/system-design-skill.vi.md

@@ -0,0 +1,70 @@
+# Kỹ năng: Thiết kế Hệ thống (System Design) (Cross-Cutting)
+
+## Mục đích
+
+Đánh giá các quyết định kiến trúc, thiết kế các API endpoint, mô hình hóa lược đồ dữ liệu (database schemas) và phân tích các yếu tố đánh đổi (trade-offs).
+
+## Khi nào sử dụng
+
+- Khi thiết kế một microservice, hệ thống, hoặc mô hình cơ sở dữ liệu mới
+- Khi định nghĩa các ranh giới API và hợp đồng tích hợp (integration contracts) giữa các component
+- Khi mở rộng quy mô hệ thống và phác thảo các yếu tố đánh đổi giữa mở rộng theo chiều dọc và chiều ngang
+
+## Quy trình từng bước
+
+### Bước 1: Thu thập Yêu cầu & Ràng buộc
+- Liệt kê các yêu cầu chức năng (hệ thống phải làm gì)
+- Liệt kê các yêu cầu phi chức năng (throughput, quy mô, độ trễ, tính sẵn sàng)
+- Xác định các ràng buộc kỹ thuật (năng lực của team, ngân sách, thời gian, công nghệ hiện có)
+
+### Bước 2: Thiết kế Mức Cao (High-Level Design)
+- Phác thảo sơ đồ các component (services, clients, data stores)
+- Phác thảo luồng dữ liệu và vòng đời của request/response
+- Lựa chọn giải pháp lưu trữ (SQL, NoSQL, Cache, Document store)
+
+### Bước 3: Thiết kế Chi tiết & Hợp đồng API
+- Định nghĩa các mô hình schema database và chiến lược đánh index
+- Thiết kế hợp đồng API cụ thể (REST endpoints, cấu trúc GraphQL, đặc tả gRPC)
+- Thiết kế cơ chế xử lý lỗi, chiến lược lưu cache và định nghĩa hàng đợi sự kiện (event queue)
+
+### Bước 4: Phân tích Đánh đổi (Trade-off Analysis)
+- Tài liệu hóa rõ ràng các lựa chọn kiến trúc kèm phân tích đánh đổi (ví dụ: Tối ưu đọc vs. Tối ưu ghi)
+- Xây dựng chiến lược mở rộng (sharding, replication, cơ chế failover)
+
+## Input yêu cầu
+
+- Mục tiêu kiến trúc, đặc tả kỹ thuật hoặc user stories
+- Tải trọng dự kiến (requests mỗi giây, kích thước dữ liệu)
+- Ràng buộc về công nghệ hiện có của dự án
+
+## Output mong đợi
+
+- Tài liệu thiết kế hệ thống bao gồm:
+  - Sơ đồ kiến trúc (ASCII hoặc Mermaid)
+  - Mô hình dữ liệu và DB schema
+  - Đặc tả kỹ thuật các API endpoint
+  - Chiến lược Cache/Queue
+  - Phân tích đánh đổi rõ ràng
+
+## Giọng điệu & Quy tắc
+
+- Mọi quyết định thiết kế đều phải kèm theo phân tích đánh đổi tương ứng.
+- Đảm bảo tính mô-đun của thiết kế và giải thích rõ ranh giới giữa các service.
+- Tránh over-engineering (thiết kế quá phức tạp). Hãy thiết kế cho quy mô 10x nhưng xây dựng cho quy mô 1.5x trước.
+
+## Templates có sẵn
+
+- Không có
+
+## Scripts có sẵn
+
+- Không có
+
+## Ví dụ
+
+Xem thư mục `examples/`.
+
+## Liên kết với các kỹ năng khác
+
+- **documents**: Dùng để tạo tài liệu đặc tả kỹ thuật và sản phẩm.
+- **suggestion**: Dùng để phân tích hệ thống hiện tại và đề xuất cải tiến kiến trúc.