ai-developer-skill-os 7.0.2 → 7.5.1

package/.agents/skills/qk-data-lifecycle/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: qk-data-lifecycle
+category: backend
+version: 7.5.0
+description: "Quản lý Schema, Migrations an toàn — schema freeze → backward-compat migration → cleanup."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: high
+side_effects: edit_files
+produces: [code, schema]
+consumes: [context-graph, user-description]
+token_budget:
+  max_files_read: 4
+  max_lines_per_read: 100
+  max_shell_commands: 1
+  stop_early: false
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-data-lifecycle — Database Schema & Repository Manager
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Existing schema is identified (ORM model files)
+- [ ] Change intent is clear (add field / modify field / drop field)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần xác định: schema hiện tại + loại thay đổi (add/modify/drop)."
+```
+
+---
+
+## Scope
+- ✅ Define strict schema BEFORE writing repository code
+- ✅ Always backward-compatible migrations (never destructive in first pass)
+- ✅ Separate schema (models) from business logic (services)
+
+## Non-Goals
+- ❌ DROP columns without deprecation phase first
+- ❌ Write complex business logic inside repositories
+- ❌ Dynamic queries without schema definitions
+
+---
+
+## Priority Order
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Read existing schema | Never |
+| P2 | Design migration (backward-compat) | Never |
+| P3 | Write migration file | Never |
+| P4 | Update repository layer | Budget < 30% |
+| P5 | Update affected service layer | Budget < 50% |
+
+---
+
+## Migration Safety Rules
+```yaml
+add_column:
+  strategy: nullable OR has default value (never NOT NULL without default)
+  
+modify_column:
+  strategy: add new column → migrate data → drop old column (3-phase)
+  
+drop_column:
+  strategy: Phase 1 — mark deprecated (keep in schema)
+            Phase 2 — next release — remove from queries
+            Phase 3 — next migration — DROP COLUMN
+
+rename_table:
+  strategy: create new table → migrate → drop old (never ALTER TABLE RENAME in prod)
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Schema Read
+1. `grep_search` for existing model/entity file
+2. Read current schema (targeted, ≤ 100 lines)
+3. Identify impact of proposed change
+
+### Phase 2 — Migration Design
+1. Choose safety strategy (see Migration Safety Rules)
+2. Write migration file (up + down)
+3. Verify down() is always defined (rollback support)
+
+### Phase 3 — Repository Update
+1. Update repository methods to use new schema
+2. Verify no raw queries reference old column names
+
+**Decision:**
+```
+IF migration is backward-compat AND down() defined → EXIT: SUCCESS
+ELSE IF destructive migration attempted → EXIT: BLOCKED — apply 3-phase strategy
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] migration: [filename]
+Issue:      [NOT NULL without default | missing down() | direct DROP]
+Confidence: HIGH
+Fix:        [specific safer strategy]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Schema, migration, and repository complete | Validated execution |
+| PARTIAL | Migration generated but untested | Missing DB connection |
+| BLOCKED | Fields or relationships ambiguous | Missing entity data |
+| FAILED | Migration involves destructive DROP without backup | Architecture violation |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Entity schema completely defined by user | Implement immediately |
+| MEDIUM | Schema inferred from JSON or forms | Ask for review before generating migration |
+| LOW | "Add database" request with no schema | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Data loss risk in migration | Direct `DROP TABLE` without data copy |
+| HIGH | Missing index on foreign key | Performance degrade on JOIN |
+| MEDIUM | N+1 query vulnerability in repository | Fetching related entities in a loop |
+| LOW | Naming convention violation | `userId` instead of `user_id` in DB |
+
+---
+
+## Retry Policy
+```
+Migration generation fails
+  └─ Syntax error in SQL/ORM
+       ├─ Fix syntax based on engine (Postgres/MySQL)
+       └─ Do NOT retry more than 1 time — risk of bad migration state
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Entity schema undefined
+Missing:
+  - List of fields (types, constraints)
+  - Relationships (1:1, 1:N, M:N)
+Questions:
+  1. Bảng này cần lưu những trường dữ liệu nào?
+  2. Bảng này có liên kết với bảng nào khác không? (ví dụ User)
+Recommended Assumptions:
+  - Add standard created_at, updated_at timestamps
+  - UUID primary keys
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["entity_name", "fields"],
+  "optional_fields": ["relationships", "db_engine"]
+}
+```
+### Produces
+```json
+{
+  "to": "user or db-optimizer",
+  "output_fields": ["schema_file", "migration_file", "repository_file", "exit_code"]
+}
+```
+
+---
+

package/.agents/skills/qk-db-optimizer/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: qk-db-optimizer
+category: backend
+version: 7.5.0
+description: "Tối ưu Database dựa trên bằng chứng: EXPLAIN → phân tích → index/join — không đoán mò."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: medium
+latency: medium
+risk: medium
+side_effects: edit_files
+produces: [code, report]
+consumes: [query-log, source-code]
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 100
+  max_shell_commands: 2
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-db-optimizer — Database Performance Tuner
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Slow query log OR specific slow query is provided
+- [ ] Database schema/ORM models accessible
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần: slow query log hoặc query cụ thể cần tối ưu."
+```
+
+---
+
+## Scope
+- ✅ Analyze EXPLAIN/query plans before adding indexes
+- ✅ Solve N+1 with Data Loaders or explicit Joins
+- ✅ Validate performance improvement
+
+## Non-Goals
+- ❌ Add indexes without slow query evidence
+- ❌ Add overlapping or redundant indexes
+- ❌ Optimize queries not shown in slow query log
+
+---
+
+## Priority Order
+| P | Issue Type | Action | Skip Threshold |
+|---|-----------|--------|----------------|
+| P1 | Sequential scan on large table (> 10k rows) | Add composite index | Never |
+| P2 | N+1 query pattern | Eager load / DataLoader | Budget < 30% |
+| P3 | Missing JOIN (multiple queries for related data) | Rewrite with JOIN | Budget < 50% |
+| P4 | SELECT * (over-fetching) | Select specific columns | Budget < 60% |
+
+---
+
+## EXPLAIN Decision Tree
+
+```
+Run EXPLAIN ANALYZE on slow query
+
+IF "Seq Scan" on table > 10k rows
+  → Check cardinality of filter column
+  → IF cardinality > 100 → add B-tree index
+  → IF low cardinality → add partial index or reconsider query
+
+IF "Nested Loop" with many iterations
+  → Check: is this N+1?
+  → IF yes → rewrite as single JOIN or use DataLoader
+
+IF "Sort" without index
+  → Add index on ORDER BY column
+
+IF index exists but not used ("Index Scan" missing)
+  → Check: is WHERE clause using non-leading column of composite index?
+  → Reorder composite index columns
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Evidence Collection
+1. Read slow query log or provided query
+2. Run EXPLAIN ANALYZE (1 command) — or analyze ORM-generated SQL
+3. Identify bottleneck pattern (seq scan / N+1 / sort / over-fetch)
+
+### Phase 2 — Solution Design
+1. Apply Decision Tree above
+2. Design minimal index or query rewrite
+
+### Phase 3 — Apply & Verify
+1. Apply change (add index migration OR rewrite query via `replace_file_content`)
+2. (Optional) Re-run EXPLAIN to verify improvement (2nd command)
+
+**Decision:**
+```
+IF improvement verified → EXIT: SUCCESS
+IF improvement not measurable → EXIT: PARTIAL, note "verify in production"
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] query in src/repositories/[name].ts:LINE
+Pattern:    [SEQ_SCAN | N+1 | MISSING_JOIN | OVER_FETCH | UNUSED_INDEX]
+Table:      [table_name] (~N rows estimated)
+Confidence: HIGH
+Fix:        [specific index or rewrite]
+Estimated improvement: [X% reduction in scan rows]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Index added or query rewritten, improvement verified | Post-optimization |
+| PARTIAL | Optimization applied but could not verify via EXPLAIN | DB access blocked |
+| BLOCKED | Log not provided or DB engine unknown | Missing inputs |
+| FAILED | Optimization breaks existing test or query syntax | Logic error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | EXPLAIN plan shows SEQ SCAN, user confirms index is missing | Add index / rewrite |
+| MEDIUM | Query looks inefficient but no EXPLAIN available | Ask to run EXPLAIN |
+| LOW | "Make DB faster" with no slow query log | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Query locking table in production | Long running UPDATE |
+| HIGH | Missing index on frequently joined table | Full scan on million rows |
+| MEDIUM | N+1 queries due to missing JOIN | ORM fetching relations in loop |
+| LOW | Over-fetching columns | `SELECT *` instead of specific |
+
+---
+
+## Retry Policy
+```
+EXPLAIN query fails
+  └─ Check SQL syntax error vs connection error
+       ├─ Syntax error → correct SQL → retry EXPLAIN
+       └─ Do NOT retry more than 1 time — risk of locking
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Slow query log not provided
+Missing:
+  - The actual slow query SQL
+  - Current schema of the involved tables
+Questions:
+  1. Câu query nào đang bị chậm? (Xin SQL / ORM log)
+  2. Bảng này hiện đang có những index nào?
+Recommended Assumptions:
+  - Do NOT assume table size or indexes blindly
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["slow_query"],
+  "optional_fields": ["schema", "explain_plan", "db_engine"]
+}
+```
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["optimized_query", "migration_file", "explain_diff", "exit_code"]
+}
+```
+
+---
+

package/.agents/skills/qk-docs/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: qk-docs
+category: documentation
+version: 7.5.0
+description: "Viết và duy trì tài liệu chính xác tuyệt đối — phải match code thực tế, cấm bịa đặt."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: low
+latency: fast
+risk: low
+side_effects: edit_files
+produces: [report]
+consumes: [source-code]
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 100
+  max_shell_commands: 0
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-docs — Technical Writer & Documentation Maintainer
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Target code file or module is specified
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Chỉ định file cần viết docs."
+```
+
+---
+
+## Scope
+- ✅ Document ONLY what exists in code — never invent params/behavior
+- ✅ Update docs whenever corresponding code changes
+- ✅ Use living documentation (JSDoc/TSDoc/Swagger) over isolated Markdown
+
+## Non-Goals
+- ❌ Guess API params not in the code
+- ❌ Write generic/useless comments (`// gets the user`)
+- ❌ Write docs for code that hasn't been read yet
+
+---
+
+## Priority Order
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Read source code first (never write before reading) | Never |
+| P2 | Document public API (exported functions/classes) | Never |
+| P3 | Document complex logic with WHY (not WHAT) | Budget < 40% |
+| P4 | Update README if public interface changed | Budget < 60% |
+
+---
+
+## Workflow
+
+### Phase 1 — Read Code
+1. `view_file[targeted]` — read function/class signatures
+2. Identify: params, return type, side effects, error cases
+
+**Decision:** `IF code is not readable → EXIT: BLOCKED — read code first`
+
+### Phase 2 — Write Documentation
+1. JSDoc/TSDoc format for functions: `@param`, `@returns`, `@throws`
+2. Comment: WHY (not WHAT) — code already shows what
+3. Example usage for complex APIs
+
+### Phase 3 — Verify Accuracy
+1. Re-read written docs vs code → spot check each param name
+
+**Decision:**
+```
+IF docs match code exactly → EXIT: SUCCESS
+IF any param name or type mismatch → fix immediately
+```
+
+---
+
+## Documentation Templates
+
+### Function (JSDoc)
+```typescript
+/**
+ * [One sentence — what it does and WHY it exists]
+ *
+ * @param {Type} paramName - [description]
+ * @returns {Type} [description of return value]
+ * @throws {ErrorType} [when this error is thrown]
+ * @example
+ * const result = functionName(arg);
+ */
+```
+
+### README Section
+```markdown
+## [Feature Name]
+[What it does — user-facing description]
+
+### Usage
+[Code example]
+
+### Configuration
+| Option | Type | Default | Description |
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] path/to/file.ts:LINE
+Issue:      [MISSING_PARAM | WRONG_TYPE | STALE_DOC | GENERIC_COMMENT]
+Confidence: HIGH
+Fix:        [specific correction]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Docs written and verified against source code | Execution complete |
+| PARTIAL | Docs written but some parts inferred (not verified) | MEDIUM confidence |
+| BLOCKED | Target source file missing or inaccessible | Cannot read source |
+| FAILED | Documentation fundamentally misrepresents the code | Gross error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Target code read, behavior understood | Write docs definitively |
+| MEDIUM | Target code too large, inferred from types/tests | Write with disclaimer |
+| LOW | "Write docs for this feature" without pointing to code | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Docs instruct user to do something dangerous | Documenting destructive API without warnings |
+| HIGH | API params documented incorrectly | Says string instead of object |
+| MEDIUM | Missing docs for edge cases | Doesn't explain error throws |
+| LOW | Typo or poor formatting | Misaligned markdown table |
+
+---
+
+## Retry Policy
+```
+Doc verification fails
+  └─ Target code changed during doc writing
+       ├─ Re-read target code
+       └─ Do NOT retry more than 1 time
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Target source file missing
+Missing:
+  - Exact path to the code that needs documenting
+Questions:
+  1. File code nào bạn muốn viết doc? (Xin đường dẫn)
+  2. Mục tiêu của doc này là cho user hay cho developer nội bộ?
+Recommended Assumptions:
+  - Developer-facing JSDoc if inside source files
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["target_file", "doc_type"],
+  "optional_fields": ["context"]
+}
+```
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["updated_files", "exit_code"]
+}
+```
+
+---
+