ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/skills/qk-design-to-code/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: qk-design-to-code
+category: frontend
+version: 7.5.0
+description: "Chuyển thiết kế Figma/Image thành UI component chuẩn pixel — zero AI-slop, 100% DESIGN.md."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: high
+latency: slow
+risk: low
+side_effects: edit_files
+produces: [code]
+consumes: [design-md, design-asset]
+
+token_budget:
+  max_files_read: 4
+  max_lines_per_read: 150
+  max_shell_commands: 0
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-design-to-code — Pixel-Perfect Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] `DESIGN.md` exists with color tokens, spacing scale, typography
+- [ ] Design reference (Figma link, image, or wireframe description) provided
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "DESIGN.md missing or design reference not provided."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Build UI from design reference using ONLY DESIGN.md tokens
+- ✅ Include all interactive states: hover, focus, active, disabled, loading
+- ✅ Responsive layouts (mobile + desktop)
+- ✅ Semantic HTML with ARIA roles
+
+## Non-Goals
+- ❌ Invent design tokens not in DESIGN.md
+- ❌ Use hardcoded hex colors, px sizes not from token system
+- ❌ Copy generic Tailwind/Bootstrap templates
+- ❌ Skip loading/error/empty states
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | HTML structure + semantic markup | Never |
+| P2 | DESIGN.md token application (colors, spacing, typography) | Never |
+| P3 | Interactive states (hover, focus, active) | Budget < 30% |
+| P4 | Responsive breakpoints (mobile) | Budget < 50% |
+| P5 | Loading / error / empty states | Budget < 60% |
+| P6 | Animation / micro-interactions | Budget < 70% |
+| P7 | ARIA roles + keyboard navigation | Budget < 80% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Extract Design System
+
+**Steps:**
+1. Read `DESIGN.md` → extract: colors (HSL), spacing scale, font families, border-radius, shadows, animation timing
+2. Map tokens to CSS variables or framework equivalents
+
+**Decision:**
+```
+IF DESIGN.md has all required tokens
+  → go to Phase 2
+
+ELSE IF some tokens missing
+  → Use reasonable fallback, note gap in output
+  → Confidence: MEDIUM
+
+ELSE IF DESIGN.md empty
+  → EXIT: BLOCKED
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Build Structure
+
+**Steps:**
+1. Create HTML structure (semantic: `article`, `section`, `nav`, `button`, NOT `div` soup)
+2. Apply layout: CSS Grid / Flexbox (NO absolute positioning unless unavoidable)
+3. Apply DESIGN.md tokens for colors, spacing, typography
+
+**Self-Check before next phase:**
+```
+✅ No hardcoded hex/rgb values (only CSS vars or DESIGN.md tokens)
+✅ No magic numbers for spacing (only from scale: 4, 8, 16, 24, 32...)
+✅ Semantic HTML elements used
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Interactive States
+
+**Steps:**
+1. Add hover, focus, active states for all interactive elements
+2. Add disabled state for form elements
+3. Use CSS transitions (duration from DESIGN.md, typically 150–300ms)
+
+**Self-Check:**
+```
+✅ Every button/link has hover + focus state
+✅ Focus visible (not outline: none without replacement)
+✅ Transition duration matches DESIGN.md
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 4 — Self-Audit (Anti-Slop Check)
+
+**Checklist (must pass ALL):**
+- [ ] No hardcoded colors — only DESIGN.md tokens
+- [ ] No font-size in px without token — use rem/token
+- [ ] No `margin: auto` soup — use proper grid/flex
+- [ ] All interactive elements have hover + focus state
+- [ ] Mobile viewport works (no horizontal overflow)
+- [ ] No `!important` overrides (except resets)
+- [ ] No inline styles except dynamic values
+- [ ] Loading state implemented (skeleton or spinner)
+- [ ] Error state implemented (clear message)
+- [ ] Empty state implemented (helpful illustration/text)
+
+**Decision:**
+```
+IF all 10 anti-slop checks pass
+  → EXIT: SUCCESS
+
+ELSE IF 1–2 minor fails
+  → Fix immediately, EXIT: SUCCESS
+
+ELSE IF > 2 fails OR hardcoded colors found
+  → Fix all, re-audit, EXIT: PARTIAL if still one gap
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | DESIGN.md complete, design reference clear | Build directly |
+| MEDIUM | Some tokens missing, inferring from context | Note gaps, proceed |
+| LOW | Design reference too vague or DESIGN.md empty | EXIT: BLOCKED |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format (Self-Audit Violations)
+
+```
+[SEVERITY] path/to/Component.tsx:LINE
+Category:   [TOKEN|SEMANTIC|INTERACTION|RESPONSIVE|STATE|ARIA]
+Reason:     [specific anti-slop violation]
+Confidence: HIGH
+Fix:        [applied immediately]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["design_reference", "design_md_path"],
+  "optional_fields": ["component_name", "framework"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-ui-audit (for verification)",
+  "output_fields": ["component_files", "tokens_used", "states_implemented", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🎨 Design → Code
+─────────────────────────────────────────────────
+Component:   [ComponentName]
+Tokens used: [list of DESIGN.md tokens applied]
+
+States implemented:
+  ✅ Default / ✅ Hover / ✅ Focus / ✅ Active
+  ✅ Loading / ✅ Error / ✅ Empty
+  ⚠️ [any state skipped — reason]
+
+Anti-Slop Audit:
+  ✅ [10/10 checks passed | N/10 — list failures]
+
+Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+
+---
+
+## Escalation Rules
+
+[Placeholder for Escalation Rules]
+
+
+---
+
+## Severity
+
+[Placeholder for Severity]
+
+
+---
+
+## Retry Policy
+
+[Placeholder for Retry Policy]
+
+
+---
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Component built, all 10 anti-slop checks passed | Production ready |
+| PARTIAL | Built but 1–2 minor gaps (e.g., animation skipped) | User review recommended |
+| BLOCKED | DESIGN.md or design reference missing | Cannot build |
+| FAILED | Anti-slop audit finds > 2 violations or hardcoded values | Rebuild required |
+
+---
+
+