ai-developer-skill-os 7.5.0 → 8.1.4

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

@@ -1,285 +0,0 @@
----
-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

@@ -1,314 +0,0 @@
----
-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`
-
----
-