ai-developer-skill-os 7.0.2 → 7.5.0

package/.agents/skills/qk-context-loader/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: qk-context-loader
+category: utilities
+version: 7.5.0
+description: "Tải context và vẽ dependency graph chính xác trước khi code — ngăn hallucination kiến trúc."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: low
+latency: fast
+risk: low
+side_effects: read_only
+produces: [context-graph]
+consumes: [source-code]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 100
+  max_shell_commands: 1
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-context-loader — Dependency Graph Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] Entry point file or module name is specified
+- [ ] Repository is accessible
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng chỉ định entry point (file hoặc module cần map)."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Trace imports/exports from entry point
+- ✅ Build topological dependency graph (max depth 3)
+- ✅ Identify risk level per module
+
+## Non-Goals
+- ❌ Modify any code
+- ❌ Load `node_modules` or vendor directories
+- ❌ Guess file names — only follow explicit imports
+- ❌ Load entire repo (max 5 files)
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Trace direct imports of entry point | Never |
+| P2 | Trace 2nd-level dependencies | Budget < 40% |
+| P3 | Identify shared/risky modules | Budget < 60% |
+| P4 | Annotate with risk levels | Budget < 70% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Entry Point Analysis
+
+**Steps:**
+1. `grep_search` — search for import/export statements in entry file
+2. `view_file[StartLine:EndLine]` — read import block only (first ~30 lines)
+3. List direct dependencies
+
+**Decision:**
+```
+IF entry file found and imports readable
+  → go to Phase 2
+
+ELSE IF entry file not found
+  → EXIT: BLOCKED — ask for correct path
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Graph Traversal (Max Depth 3)
+
+**Steps:**
+1. For each direct dependency → `grep_search` for its imports
+2. Build adjacency list: `{ file → [imports] }`
+3. Stop at depth 3 OR max_files_read reached
+
+**Decision:**
+```
+IF depth 3 reached OR max_files_read (5) hit
+  → EXIT: PARTIAL — note graph is truncated at depth N
+
+IF circular dependency detected
+  → Flag as [HIGH RISK] in output
+  → Continue building rest of graph
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Risk Assessment & Output
+
+**Steps:**
+1. Identify: shared modules (imported by 3+ files) = HIGH risk to change
+2. Identify: entry points with many dependents = CRITICAL to change carefully
+3. Generate graph in standard JSON + Markdown format
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format (Mandatory Schema)
+
+```json
+{
+  "entry": "src/modules/auth/auth.service.ts",
+  "depth_reached": 3,
+  "truncated": false,
+  "nodes": [
+    {
+      "file": "src/modules/auth/auth.service.ts",
+      "imports": ["src/common/jwt.util.ts", "src/users/users.repository.ts"],
+      "exports": ["AuthService"],
+      "risk_level": "high",
+      "imported_by_count": 4
+    }
+  ],
+  "risks": [
+    {
+      "file": "src/common/jwt.util.ts",
+      "reason": "Imported by 6 modules — changes here have wide blast radius",
+      "risk_level": "critical"
+    }
+  ]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[RISK] path/to/file.ts
+Reason:     [why this file is risky to change]
+Imported by: [N files]
+Exports:    [key exports]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["entry_point"],
+  "optional_fields": ["max_depth", "exclude_patterns"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-feature-delivery | qk-bug-resolution | qk-data-lifecycle | qk-api-lifecycle",
+  "output_fields": ["dependency_graph_json", "risk_summary", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Full graph built within depth limit | All imports traced |
+| PARTIAL | Graph truncated at token/depth limit | Note where it was cut |
+| BLOCKED | Entry point not found or inaccessible | Ask for correct path |
+| FAILED | Cannot determine architecture (circular imports, obfuscated code) | Report and escalate |
+
+---
+

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"]
+}
+```
+
+---
+