ai-developer-skill-os 7.5.0 → 8.1.4

package/.agents/skills/qk-ui-builder/references/themes/modern-minimal.md

@@ -0,0 +1,52 @@
+# Theme: Modern Minimal
+
+**Genre:** modern-minimal  
+**Use case:** SaaS, startups, portfolios
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | mid (30–85% lightness) |
+| Display style | geometric-sans |
+| Accent hue | neutral |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 15%, 98%);
+  --color-surface: hsl(220, 15%, 100%);
+  --color-text: hsl(220, 20%, 12%);
+  --color-text-muted: hsl(220, 10%, 50%);
+  --color-accent: hsl(220, 15%, 45%);
+  --color-accent-hover: hsl(220, 15%, 38%);
+  --font-display: 'Inter', 'Helvetica Neue', sans-serif;
+  --font-body: 'Inter', 'Helvetica Neue', sans-serif;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --shadow-sm: 0 1px 2px hsl(220, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(220, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Stat-Led
+- ✅ Index-First
+- ❌ Marquee Hero (too noisy)
+- ❌ Manifesto (too expressive)
+
+## Anti-Patterns (Modern Minimal-specific)
+
+- ❌ Decorative illustrations
+- ❌ Gradient buttons or backgrounds
+- ❌ More than 2 font families
+- ❌ Heavy drop shadows
+
+## Voice
+
+- Single-word actions: "Sign in", "Pricing", "Docs"
+- No decorative copy
+- Metrics and social proof prominent

package/.agents/skills/qk-ui-builder/references/themes/playful.md

@@ -0,0 +1,52 @@
+# Theme: Playful
+
+**Genre:** playful  
+**Use case:** games, kids, entertainment
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | light (85–100% lightness) |
+| Display style | rounded-sans |
+| Accent hue | warm (30–60°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(45, 60%, 97%);
+  --color-surface: hsl(45, 60%, 100%);
+  --color-text: hsl(45, 50%, 12%);
+  --color-text-muted: hsl(45, 20%, 45%);
+  --color-accent: hsl(35, 85%, 55%);
+  --color-accent-hover: hsl(35, 85%, 48%);
+  --font-display: 'Nunito', 'Varela Round', sans-serif;
+  --font-body: 'Nunito', 'Varela Round', sans-serif;
+  --radius-sm: 12px;
+  --radius-md: 16px;
+  --shadow-sm: 0 2px 4px hsl(45, 60%, 85%);
+  --shadow-md: 0 6px 16px hsl(45, 60%, 85%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Bento Grid
+- ✅ Marquee Hero
+- ✅ Feature Stack
+- ❌ Long Document (too text-heavy)
+- ❌ Quote-Led (too serious)
+
+## Anti-Patterns (Playful-specific)
+
+- ❌ Serious or corporate tones
+- ❌ Monochrome palettes
+- ❌ Minimal whitespace (dense layouts)
+- ❌ Sharp corners or rigid grids
+
+## Voice
+
+- Exclamation marks and emoji allowed
+- Action verbs: "Play", "Join", "Explore"
+- Friendly, inclusive language

package/.agents/skills/qk-ui-builder/references/themes/specimen.md

@@ -0,0 +1,52 @@
+# Theme: Specimen
+
+**Genre:** editorial  
+**Use case:** design systems, documentation
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | mid (30–85% lightness) |
+| Display style | high-contrast-serif |
+| Accent hue | neutral |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(40, 10%, 96%);
+  --color-surface: hsl(40, 10%, 100%);
+  --color-text: hsl(40, 15%, 8%);
+  --color-text-muted: hsl(40, 5%, 45%);
+  --color-accent: hsl(40, 5%, 45%);
+  --color-accent-hover: hsl(40, 5%, 38%);
+  --font-display: 'Playfair Display', Georgia, serif;
+  --font-body: 'Source Sans 3', 'Helvetica Neue', sans-serif;
+  --radius-sm: 4px;
+  --radius-md: 4px;
+  --shadow-sm: 0 1px 2px hsl(40, 15%, 90%);
+  --shadow-md: 0 4px 12px hsl(40, 15%, 90%);
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Type Specimen
+- ✅ Index-First
+- ✅ Component Playground
+- ❌ Marquee Hero (too playful)
+- ❌ Bento Grid (too casual)
+
+## Anti-Patterns (Specimen-specific)
+
+- ❌ Playful illustrations or mascots
+- ❌ Warm saturated accents (orange, coral)
+- ❌ Rounded corners > 4px
+- ❌ Gradient hero backgrounds
+
+## Voice
+
+- Typographic precision: "Style guide", "Type scale", "Spacing rhythm"
+- Noun-first labels: "Design tokens", "Component states"
+- Neutral, authoritative tone

package/.agents/skills/qk-ui-builder/references/themes/terminal.md

@@ -0,0 +1,52 @@
+# Theme: Terminal
+
+**Genre:** tech  
+**Use case:** CLI tools, developer tools, terminals
+
+## Axes
+
+| Axis | Value |
+|------|-------|
+| Paper band | dark (0–30% lightness) |
+| Display style | mono |
+| Accent hue | phosphor green (120–150°) |
+
+## Token Overrides
+
+```css
+:root {
+  --color-background: hsl(220, 15%, 4%);
+  --color-surface: hsl(220, 15%, 8%);
+  --color-text: hsl(120, 30%, 75%);
+  --color-text-muted: hsl(120, 10%, 45%);
+  --color-accent: hsl(120, 60%, 55%);
+  --color-accent-hover: hsl(120, 60%, 48%);
+  --font-display: 'JetBrains Mono', 'Fira Code', monospace;
+  --font-body: 'JetBrains Mono', 'Fira Code', monospace;
+  --radius-sm: 0px;
+  --radius-md: 0px;
+  --shadow-sm: none;
+  --shadow-md: none;
+}
+```
+
+## Macrostructure Affinity
+
+- ✅ Workbench
+- ✅ Component Playground
+- ✅ Stat-Led
+- ❌ Manifesto (too expressive)
+- ❌ Photographic (too visual)
+
+## Anti-Patterns (Terminal-specific)
+
+- ❌ Serif or display fonts
+- ❌ Warm accent hues
+- ❌ Decorative shadows or borders
+- ❌ Smooth transitions/animations
+
+## Voice
+
+- Command-line syntax: `$ npm install`, `> init()`
+- Terse, imperative: "Run", "Deploy", "Configure"
+- Status codes and badges

package/.agents/skills/qk-ui-builder/references/typography.md

@@ -0,0 +1,129 @@
+# Typography
+
+Foundational rules for font selection, type scale, and textual hierarchy. These rules exist to guarantee readable, professional, and consistent type across every generated UI.
+
+## The 2+1 Rule
+
+Use **at most 2 font families + 1 monospace** per project. Exceeding this causes visual noise and slows load time.
+
+- **Display / Heading family** (1): used for titles, hero text.
+- **Body / UI family** (1): used for paragraphs, labels, controls.
+- **Monospace** (1, optional): used for code, IDs, numeric tables, logs.
+
+```css
+:root {
+  --font-display: "Playfair Display", Georgia, serif;
+  --font-body: "Inter", system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, monospace;
+}
+```
+
+If you only need one family, the body family can double as the display family. Do not introduce a third decorative family.
+
+## Font Catalog
+
+Pick from this approved catalog. Prefer fonts that share the same optical quality and load reliably via Google Fonts or system fallbacks.
+
+| Family | Role | Notes |
+| --- | --- | --- |
+| Inter | Body / UI | Neutral, legible at small sizes. Default choice. |
+| Source Serif 4 | Display / Body | Serif companion to Inter; good for reading-heavy UI. |
+| Playfair Display | Display | High-contrast serif for hero/editorial headings. |
+| JetBrains Mono | Mono | Developer-friendly monospace. |
+| Poppins | Display / UI | Geometric, friendly; use sparingly. |
+| Roboto / Roboto Flex | Body / UI | Safe system-adjacent alternative. |
+| IBM Plex Sans / Mono | Body / Mono | Corporate, consistent pairing. |
+
+Pairing examples that work:
+- **Inter + Playfair Display + JetBrains Mono** (editorial + code)
+- **Inter + Source Serif 4 + JetBrains Mono** (clean + reading)
+- **Poppins + Inter + JetBrains Mono** (friendly branding)
+
+## Type Scale
+
+Use only these sizes. Do not invent intermediate sizes.
+
+```
+12px   caption / meta
+14px   small text / secondary
+16px   body (base)
+18px   lead / intro paragraph
+24px   h3 / section title
+32px   h2 / page title
+48px   h1 / hero
+64px   display / marketing hero
+```
+
+```css
+:root {
+  --text-xs: 0.75rem;   /* 12px */
+  --text-sm: 0.875rem;  /* 14px */
+  --text-base: 1rem;    /* 16px */
+  --text-lg: 1.125rem;  /* 18px */
+  --text-xl: 1.5rem;    /* 24px */
+  --text-2xl: 2rem;     /* 32px */
+  --text-3xl: 3rem;     /* 48px */
+  --text-4xl: 4rem;     /* 64px */
+}
+```
+
+## Line Height
+
+| Content | Line height |
+| --- | --- |
+| Body text | **1.5** |
+| Headings (h1–h3) | **1.2** |
+| Tight display (64px) | 1.1 |
+
+```css
+p, li, label { line-height: 1.5; }
+h1, h2, h3 { line-height: 1.2; }
+```
+
+## Hierarchy
+
+Establish hierarchy with **size + weight + color**, not decoration.
+
+```css
+h1 { font-family: var(--font-display); font-size: var(--text-3xl); font-weight: 700; }
+h2 { font-family: var(--font-display); font-size: var(--text-2xl); font-weight: 600; }
+h3 { font-family: var(--font-body);    font-size: var(--text-xl);  font-weight: 600; }
+body { font-family: var(--font-body);   font-size: var(--text-base); font-weight: 400; }
+.meta { font-size: var(--text-sm); color: var(--color-text-muted); }
+```
+
+Keep weight range tight: 400 (body), 500/600 (emphasis), 700 (headings). Avoid 900 unless for a single display word.
+
+## Prose Measure
+
+Constrain reading width for paragraphs to **45–75 characters** (`ch`).
+
+```css
+.prose {
+  max-width: 65ch;
+  font-size: var(--text-base);
+  line-height: 1.5;
+}
+```
+
+For multi-column or card text, keep each text block within this measure. Never let body copy stretch across a full 1200px container.
+
+## Ban List
+
+Do **not** use these as an identity or UI font:
+
+- Comic Sans
+- Papyrus
+- Bradley Hand
+- Any `cursive` generic family used as a primary brand font
+- Other "novelty" fonts that undermine legibility
+
+System fallbacks (`system-ui`, `sans-serif`, `serif`, `monospace`) are allowed only as graceful degradation, never as the chosen aesthetic.
+
+## Practical Checklist
+
+- [ ] At most 2 families + 1 mono.
+- [ ] Sizes only from the 8-step scale.
+- [ ] Body line-height 1.5, headings 1.2.
+- [ ] Prose capped at 65ch.
+- [ ] No banned novelty fonts.

package/.agents/skills/qk-ui-system-builder/SKILL.md

@@ -1,9 +1,66 @@
 ---
+# ── Identity ───────────────────────────────────────────────
 name: qk-ui-system-builder
-category: frontend
-version: 7.5.0
+version: 8.0.0
+status: stable
 description: "Xây dựng Design System và token library từ DESIGN.md — không tự đặt ra token ngoài contract."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - ui-system-design
+  - frontend-development
+
+complexity:
+  level: medium
+  criteria:
+    files_affected: "1-5"
+    has_behavior_change: true
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "tạo design system"
+  - "build token"
+  - "ui system"
+  - "setup css"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+
+tools:
+  - filesystem
+  - terminal
+
+related_skills:
+  - qk-ui-builder
+
+knowledge_scope:
+  owns:
+    - design-tokens
+    - ui-system
+  references:
+    - design-system
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: feature
+
+selection:
+  priority: medium
+  confidence_threshold: 0.80
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
 execution_mode: deterministic
 cost: medium
 latency: medium
@@ -11,15 +68,14 @@ risk: low
 side_effects: edit_files
 produces: [code, tokens]
 consumes: [design-md]
+
 token_budget:
   max_files_read: 2
   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-ui-system-builder — Design System Constructor

package/.agents/skills/qk-validation-gate/SKILL.md

@@ -1,11 +1,70 @@
 ---
+# ── Identity ───────────────────────────────────────────────
 name: qk-validation-gate
-category: qa
-version: 7.5.0
+version: 8.0.0
+status: stable
 description: "Cổng kiểm tra chất lượng bắt buộc với ngưỡng pass/fail cụ thể — chặn đứng mọi mã nguồn lỗi."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
 
+# ── V8: Classification ─────────────────────────────────────
+type: utility
+
+intent:
+  - quality-assurance
+  - verification
+  - code-review
+
+complexity:
+  level: low
+  criteria:
+    files_affected: "1-5"
+    has_behavior_change: false
+    has_external_dependency: false
+    has_breaking_change: false
+
+triggers:
+  - "verify"
+  - "kiểm tra"
+  - "lint"
+  - "test"
+  - "run checks"
+
+selection:
+  priority: high
+  confidence_threshold: 0.75
+
+# ── V8: References ─────────────────────────────────────────
+workflow: code-review
+
+rules:
+  - global
+
+tools:
+  - filesystem
+  - terminal
+
+related_skills:
+  - qk-engineering-standard
+
+knowledge_scope:
+  owns:
+    - verification
+    - quality-gates
+    - test-execution
+  references:
+    - coding
+    - architecture
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: review
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
 cost: medium
 latency: medium
 risk: low
@@ -20,19 +79,12 @@ token_budget:
   stop_early: false  # Must run all checks — cannot skip for token budget
 
 exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
 ---
 
 # qk-validation-gate — Quality Gate
 
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
 
 ## Preconditions
 - [ ] Project has `package.json` with lint/test scripts (or equivalent for other runtimes)

package/.agents/skills/qk-web-quality-gate/SKILL.md

@@ -0,0 +1,114 @@
+---
+# ── Identity ───────────────────────────────────────────────
+name: qk-web-quality-gate
+version: 8.1.0
+status: experimental
+description: "Kiểm toán tổng thể chất lượng Web: Accessibility (A11y), SEO, Web Performance, Security, UX Heuristics."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+
+# ── V8: Classification ─────────────────────────────────────
+type: capability
+
+intent:
+  - web-performance
+  - accessibility
+  - seo
+  - lighthouse
+  - ux-audit
+
+complexity:
+  level: high
+  criteria:
+    files_affected: "1-5"
+    has_behavior_change: false
+    has_external_dependency: true
+    has_breaking_change: false
+
+triggers:
+  - "kiểm tra web"
+  - "tối ưu web"
+  - "lighthouse"
+  - "audit ui"
+  - "core web vitals"
+
+# ── V8: References ─────────────────────────────────────────
+workflow: feature-delivery
+
+rules:
+  - global
+  - coding
+
+tools:
+  - filesystem
+  - terminal
+
+related_skills:
+  - qk-frontend-architecture
+
+knowledge_scope:
+  domain:
+    - web-performance
+    - web-accessibility
+  concepts:
+    - lighthouse
+    - seo
+    - ux-heuristics
+  references:
+    - architecture
+
+decision_boundary:
+  owns:
+    - lighthouse audit
+    - accessibility review
+    - performance audit
+    - seo audit
+  does_not_own:
+    - ui component implementation
+  conflicts_with: []
+
+# ── V8: Verification ───────────────────────────────────────
+verification:
+  required: true
+  strategy: 
+    - lighthouse
+    - accessibility
+    - performance
+
+selection:
+  priority: medium
+  confidence_threshold: 0.80
+
+examples: []
+learnings: []
+
+# ── V7 Runtime ─────────────────────────────────────────────
+execution_mode: deterministic
+cost: medium
+latency: slow
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [user-description]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 150
+  max_shell_commands: 2
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-web-quality-gate — Web Quality Auditor
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+## Preconditions
+- [ ] Ứng dụng web đã có thể chạy hoặc code đã được viết một phần.
+
+## Scope
+- Thực hiện kiểm toán A11y (Accessibility standards như WCAG).
+- Đánh giá Performance (Core Web Vitals, Bundle size, Lazy loading, Cache, Optimize images).
+- Kiểm tra SEO best practices (Meta tags, heading structure, semantic HTML).
+- Đánh giá UX Heuristics cơ bản.
+- Đưa ra khuyến nghị (Recommendation), không phải tự tay fix code nếu chưa được yêu cầu.