ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/skills/qk-system-evolution/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: qk-system-evolution
+category: maintenance
+version: 7.5.0
+description: "Nâng cấp thư viện/framework an toàn với rollback plan bắt buộc — incremental, không big-bang."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: high
+latency: slow
+risk: high
+side_effects: edit_files
+produces: [code, report, plan]
+consumes: [context-graph, source-code]
+
+token_budget:
+  max_files_read: 4
+  max_lines_per_read: 100
+  max_shell_commands: 2
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-system-evolution — Safe Upgrade Manager
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] Current version and target version are specified
+- [ ] Rollback strategy is defined (git tag OR package-lock.json snapshot)
+- [ ] Existing test suite is available to verify after upgrade
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Rollback plan required before any major upgrade. Specify: target version + rollback method."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Read official Changelog/Migration Guide for breaking changes
+- ✅ Apply incremental upgrades (not big-bang)
+- ✅ Verify each step with existing tests
+- ✅ Document rollback procedure
+
+## Non-Goals
+- ❌ Blindly run `npm update` — only targeted upgrades
+- ❌ Skip reading Changelog for major version bumps
+- ❌ Upgrade multiple major versions at once (one at a time)
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Check | Skip Threshold |
+|----------|-------|----------------|
+| P1 | Read Changelog for breaking changes | Never |
+| P2 | Snapshot rollback point (git tag) | Never |
+| P3 | Apply upgrade to package.json only | Never |
+| P4 | Run tests to detect breakage | Never |
+| P5 | Fix breaking changes if minor (< 3 files affected) | Budget < 40% |
+| P6 | Update documentation/README | Budget < 70% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Breaking Change Analysis
+
+**Steps:**
+1. `view_file` or `read_url` — read official Changelog for target version
+2. List all `BREAKING CHANGE` entries
+3. Map each breaking change to affected files in current codebase (`grep_search`)
+
+**Decision:**
+```
+IF 0 breaking changes
+  → Confidence: HIGH → go to Phase 2 (minor/patch upgrade)
+
+IF 1–3 breaking changes, all in < 5 files
+  → Confidence: MEDIUM → go to Phase 2
+
+IF > 3 breaking changes OR affects core files
+  → EXIT: BLOCKED — this is architectural migration, not an upgrade
+  → Recommend: plan as a dedicated migration project
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Rollback Snapshot
+
+**Steps:**
+1. Verify `git tag` or instruct user to create one: `git tag pre-upgrade-[package]-[version]`
+2. Copy `package-lock.json` snapshot reference
+3. Document exact rollback command:
+   ```
+   Rollback: git checkout pre-upgrade-[package]-[version]
+   OR: npm install [package]@[previous-version]
+   ```
+
+**Exit When:** Rollback procedure documented → go to Phase 3
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Incremental Upgrade
+
+**Steps:**
+1. Edit `package.json` — change version (one package at a time)
+2. Apply code changes for breaking changes (using `replace_file_content`)
+3. Run: `npm install` (1 command)
+
+**Decision:**
+```
+IF install succeeds
+  → go to Phase 4
+
+IF install fails (peer dep conflict)
+  → EXIT: PARTIAL — report conflict, suggest resolution
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 4 — Verification
+
+**Steps:**
+1. Run tests: `npm test` (2nd command)
+2. Parse test results for failures
+
+**Decision:**
+```
+IF all tests pass
+  → EXIT: SUCCESS
+
+IF 1–3 tests fail (related to upgrade)
+  → Fix if minor (< 10 lines change per fix)
+  → EXIT: PARTIAL
+
+IF > 3 tests fail OR core tests fail
+  → EXIT: FAILED — rollback recommended
+  → Provide exact rollback command
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Changelog read, breaking changes mapped, tests pass | Proceed |
+| MEDIUM | Changelog read, some uncertainties remain | Proceed with caution, note risks |
+| LOW | Cannot access Changelog or no tests available | EXIT: BLOCKED |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Severity
+
+| Level | Definition |
+|-------|-----------|
+| CRITICAL | Core authentication/security package upgrade |
+| HIGH | ORM, framework, or router upgrade |
+| MEDIUM | Utility library, build tool upgrade |
+| LOW | Dev dependency, formatter upgrade |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[SEVERITY] package: [name] v[old] → v[new]
+Breaking changes: [list from Changelog]
+Affected files:   [N files — list]
+Confidence:       [HIGH|MEDIUM|LOW]
+Rollback:         git checkout [tag] OR npm install [name]@[old-version]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Rollback Procedure (Required Output)
+
+Every upgrade must document:
+```
+🔄 Rollback Procedure
+─────────────────────────────────────────────────
+Method 1 (Git):  git checkout [tag-name]
+Method 2 (npm):  npm install [package]@[previous-version]
+Snapshot tag:    [pre-upgrade-[package]-[date]]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["package_name", "target_version", "rollback_method"],
+  "optional_fields": ["changelog_url", "affected_scope"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-validation-gate",
+  "output_fields": ["upgraded_packages", "breaking_changes_fixed", "rollback_procedure", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+
+---
+
+## Escalation Rules
+
+[Placeholder for Escalation Rules]
+
+
+---
+
+## Retry Policy
+
+[Placeholder for Retry Policy]
+
+
+---
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Upgrade complete, all tests pass | Clean upgrade |
+| PARTIAL | Upgrade done, some tests fail or peer conflict | Needs follow-up |
+| BLOCKED | No rollback plan or too many breaking changes | Plan migration instead |
+| FAILED | Tests fail after upgrade, rollback recommended | Provide rollback command |
+
+---
+
+

package/.qk-ai-skill-os/skills/qk-ui-audit/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: qk-ui-audit
+category: qa
+version: 7.5.0
+description: "Kiểm toán giao diện (UI) với 57-point Anti-Slop checklist — fail nếu score < 90/100."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: medium
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [design-md, source-code]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 150
+  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-audit — Anti-Slop UI Inspector
+
+> **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 in project root
+- [ ] Target UI file(s) or component(s) are specified
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "DESIGN.md not found. Run qk-project-bootstrap to create one, or provide design tokens manually."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Score UI components against DESIGN.md tokens
+- ✅ Detect generic AI-slop aesthetics
+- ✅ Verify ARIA roles and contrast ratios
+- ✅ Validate responsive, interactive, and animation states
+
+## Non-Goals
+- ❌ Fix the UI — only audit and report (fixes go to qk-design-to-code)
+- ❌ Pixel-level screenshot comparison
+- ❌ Read entire CSS files — use targeted reads
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Category | Points | Skip Threshold |
+|----------|----------|--------|----------------|
+| P1 | Accessibility (ARIA, contrast, keyboard) | 15pts | Never |
+| P2 | Layout & Spacing (tokens, grid, whitespace) | 15pts | Budget < 30% |
+| P3 | Typography & Colors (DESIGN.md compliance) | 15pts | Budget < 50% |
+| P4 | Interactions & Animations (hover, focus, transitions) | 15pts | Budget < 60% |
+| P5 | Anti-Slop Detection (generic templates, slop colors) | 15pts | Budget < 70% |
+| P6 | Performance & Best Practices | 10pts | Budget < 80% |
+| BONUS | Mobile & Cross-browser | 5pts extra | Always optional |
+
+**Total: 85 base + 5 bonus = 90 possible. Pass threshold: ≥ 90/100**
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Load Design Contract
+
+**Steps:**
+1. `grep_search` for DESIGN.md → read color tokens, spacing scale, typography
+2. Extract key tokens: primary colors (HSL), spacing unit, font families, border-radius, shadow levels
+
+**Exit When:**
+- Tokens extracted → go to Phase 2
+- DESIGN.md empty or incomplete → EXIT: BLOCKED
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Scan Target UI
+
+**Steps:**
+1. `view_file[targeted]` — read component file(s), focus on className, style, and JSX structure
+2. Check against each Priority category in order (P1 → P6)
+3. Log each finding with Evidence Format
+
+**Decision:**
+```
+IF score accumulates ≥ 90 after P1+P2+P3
+  → Can skip P4–P6 if token budget < 40%
+  → EXIT: PARTIAL (pass, but incomplete audit noted)
+
+IF CRITICAL violation found (e.g., hardcoded password in UI, broken ARIA)
+  → STOP audit, report immediately
+  → EXIT: FAILED
+```
+
+**Exit When:**
+- All categories checked → go to Phase 3
+- Token budget < 20% → go to Phase 3 with PARTIAL flag
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Score & Report
+
+**Steps:**
+1. Calculate total score per category
+2. Identify top 3 most impactful fixes
+3. Generate report with Evidence Format entries
+
+**Decision:**
+```
+IF total score ≥ 90
+  → EXIT: SUCCESS
+
+IF total score 70–89
+  → EXIT: PARTIAL — list required fixes
+
+IF total score < 70
+  → EXIT: FAILED — demand redesign, not patch
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Token clearly absent/present, ARIA attribute visible | Report directly |
+| MEDIUM | Inferred from surrounding code patterns | Note assumption |
+| LOW | Cannot verify without rendering (e.g., animation timing) | Mark as "unverifiable — manual check required" |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Severity
+
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Accessibility violation blocking disabled users | Missing alt text, contrast ratio < 3:1 |
+| HIGH | Design system contract broken | Hardcoded hex color not in DESIGN.md |
+| MEDIUM | UX degraded, workaround exists | Missing hover state, no loading indicator |
+| LOW | Minor inconsistency | Spacing off by 1 unit |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[SEVERITY] path/to/Component.tsx:LINE
+Category:   [Accessibility|Layout|Typography|Interaction|Anti-Slop|Performance]
+Reason:     [specific violation description]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [one-line actionable suggestion]
+Points:     -N pts
+```
+
+**Example:**
+```
+[HIGH] src/components/Button.tsx:23
+Category:   Typography
+Reason:     font-size hardcoded as "16px" — should use DESIGN.md token `--font-size-base`
+Confidence: HIGH
+Fix:        Replace with `var(--font-size-base)`
+Points:     -3 pts
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Retry Policy
+```
+Audit is read-only — no retry needed.
+If file is inaccessible → note as PARTIAL and continue with other files.
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Escalation Rules
+
+```
+BLOCKED: DESIGN.md missing or unreadable
+Missing:
+  - DESIGN.md with color tokens, spacing scale, typography definition
+Questions:
+  1. Có file design system nào khác không? (tokens.css, theme.ts, etc.)
+  2. Bạn có thể cung cấp màu sắc / font / spacing chính của dự án không?
+Recommended Assumptions (if proceeding):
+  - Use industry-standard: 8px spacing unit, Inter font, neutral gray palette
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["target_component_path", "design_md_path"],
+  "optional_fields": ["specific_checklist_categories"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-design-to-code (if fixes needed)",
+  "output_fields": ["audit_score", "violations_list", "top_3_fixes", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🎨 UI Audit Report
+─────────────────────────────────────────────────
+Component:   [path/to/component]
+DESIGN.md:   [found | not found]
+
+Scores:
+  P1 Accessibility:  [X/15]
+  P2 Layout:         [X/15]
+  P3 Typography:     [X/15]
+  P4 Interactions:   [X/15]
+  P5 Anti-Slop:      [X/15]
+  P6 Performance:    [X/10]
+  ─────────────────
+  Total:             [X/85] → [PASS ≥ 90% | FAIL < 90%]
+
+Violations (top priority first):
+  [SEVERITY] file:LINE — reason — Fix: suggestion (-Xpts)
+
+Top 3 Required Fixes:
+  1. [Most impactful fix]
+  2. [Second fix]
+  3. [Third fix]
+
+Verdict:     [PASS | FAIL — requires redesign]
+Exit Code:   [SUCCESS | PARTIAL | FAILED]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Score ≥ 90 — UI passes Anti-Slop | All checks done, no critical violations |
+| PARTIAL | Score 70–89 or incomplete audit | Some categories skipped due to token budget |
+| BLOCKED | DESIGN.md missing or target not specified | Cannot audit without design contract |
+| FAILED | Score < 70 or CRITICAL violation found | Generic slop detected, redesign required |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## References
+- Full 57-point checklist: `references/anti-slop-checklist.md`
+
+---
+