ai-developer-skill-os 7.0.2 → 7.5.0

package/.agents/skills/qk-production-release/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: qk-production-release
+category: devops
+version: 7.5.0
+description: "Chuẩn bị release production với 8-gate checklist bắt buộc — không pass gate = không deploy."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: slow
+risk: high
+side_effects: run_commands
+produces: [report, plan]
+consumes: [validation-gate-result, source-code]
+
+token_budget:
+  max_files_read: 3
+  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-production-release — Release Gate
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] `qk-validation-gate` has been run and returned SUCCESS or PARTIAL
+- [ ] All HIGH priority bugs are resolved
+- [ ] Production environment variables are configured (not dev)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "qk-validation-gate must pass before release. Run it first."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Run 8-gate release checklist
+- ✅ Verify no dev artifacts in production build
+- ✅ Verify environment configuration
+
+## Non-Goals
+- ❌ Fix bugs — that's `qk-bug-resolution`
+- ❌ Deploy to infrastructure — that's DevOps/CI system
+- ❌ Skip any gate unless user explicitly overrides
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Gate | Block Release? |
+|----------|------|---------------|
+| P1 | Validation gate result (from qk-validation-gate) | YES — hard block |
+| P2 | No unresolved HIGH/CRITICAL bugs | YES — hard block |
+| P3 | No `console.log` / debug artifacts in src/ | YES — hard block |
+| P4 | .env.production exists (not .env.development) | YES — hard block |
+| P5 | Build succeeds in production mode | YES — hard block |
+| P6 | Bundle size within limit (< 500KB gzipped) | WARN only |
+| P7 | No dev dependencies in production build | YES — hard block |
+| P8 | CHANGELOG.md updated with release notes | WARN only |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Release Checklist (Mandatory)
+
+```
+[ ] P1: qk-validation-gate: SUCCESS
+[ ] P2: 0 unresolved HIGH/CRITICAL bugs
+[ ] P3: grep -r "console.log\|debugger" src/ → empty
+[ ] P4: .env.production configured, NODE_ENV=production
+[ ] P5: npm run build (production mode) → exit 0
+[ ] P6: Bundle size ≤ 500KB gzipped (warn if exceeded)
+[ ] P7: npm audit --production → 0 critical/high
+[ ] P8: CHANGELOG.md has entry for this release
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Pre-flight Checks (P1–P4)
+
+**Steps:**
+1. Verify validation-gate result (check previous output or re-read)
+2. `grep_search` for `console.log`, `debugger`, `TODO:`, `FIXME:`
+3. Check for `.env.production` vs `.env.development` configuration
+
+**Decision:**
+```
+IF any P1–P4 check fails
+  → EXIT: FAILED immediately
+  → Report which gate failed and exact fix required
+
+IF all P1–P4 pass
+  → go to Phase 2
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Build & Size Gate (P5–P7)
+
+**Steps:**
+1. (If allowed) `npm run build` — 1 command used
+2. Check bundle size if measurable
+3. `npm audit --production` — 2nd command
+
+**Decision:**
+```
+IF build fails
+  → EXIT: FAILED
+
+IF bundle size > 500KB
+  → Note as WARNING, do not block
+
+IF production audit has critical/high
+  → EXIT: FAILED
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Release Report
+
+Generate signed release report with all gate results.
+
+**Decision:**
+```
+IF all hard-block gates pass
+  → EXIT: SUCCESS — safe to deploy
+
+IF only WARN gates failed (P6, P8)
+  → EXIT: PARTIAL — deploy with noted caveats
+
+IF any hard-block gate failed
+  → EXIT: FAILED — do NOT deploy
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[SEVERITY] Gate: [P1-P8 name]
+Check:      [what was checked]
+Result:     [PASS | FAIL | WARN]
+Threshold:  [what the rule is]
+Actual:     [what was found]
+Fix:        [what must be done before release]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Escalation Rules
+
+```
+BLOCKED: qk-validation-gate not run
+Missing:
+  - Run qk-validation-gate first and share the result
+Questions:
+  1. Validation gate đã chạy chưa?
+  2. Có bug nào HIGH/CRITICAL chưa fix không?
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "qk-validation-gate",
+  "required_fields": ["gate_result", "coverage_percent"],
+  "optional_fields": ["bundle_size", "changelog_entry"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "CI/CD system or user",
+  "output_fields": ["release_checklist_result", "gates_passed", "gates_failed", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🚀 Production Release Gate
+─────────────────────────────────────────────────
+Version:    [vX.Y.Z]
+Date:       [YYYY-MM-DD]
+
+Gate Results:
+  P1 Validation:    [✅ PASS | ❌ FAIL]
+  P2 Open Bugs:     [✅ 0 HIGH/CRITICAL | ❌ N unresolved]
+  P3 Debug Cleanup: [✅ Clean | ❌ N artifacts found]
+  P4 Environment:   [✅ Production config | ❌ Dev config detected]
+  P5 Build:         [✅ SUCCESS | ❌ FAILED]
+  P6 Bundle Size:   [✅ NKB | ⚠️ NKB > 500KB]
+  P7 Security:      [✅ Clean | ❌ N critical/high]
+  P8 Changelog:     [✅ Updated | ⚠️ Missing]
+
+Verdict:    [✅ SAFE TO DEPLOY | ❌ DO NOT DEPLOY — fix: list]
+Exit Code:  [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+
+---
+
+## Confidence Model
+
+
+---
+
+## Severity
+
+
+---
+
+## Retry Policy
+
+
+---
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | All hard-block gates pass | Deploy approved |
+| PARTIAL | Hard gates pass, warnings exist | Deploy with noted caveats |
+| BLOCKED | Prerequisites missing | Run validation-gate first |
+| FAILED | Any hard gate failed | Do NOT deploy |
+
+---
+
+

package/.agents/skills/qk-project-bootstrap/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: qk-project-bootstrap
+category: fullstack
+version: 7.5.0
+description: "Khởi tạo dự án mới với cấu trúc chuẩn, linters, DESIGN.md — không bao giờ thiếu foundation."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: low
+side_effects: edit_files
+produces: [code, schema, plan]
+consumes: [user-description]
+token_budget:
+  max_files_read: 1
+  max_lines_per_read: 50
+  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-project-bootstrap — Project Foundation Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Framework/language preference is stated (or ask before proceeding)
+- [ ] Project purpose is clear (web app, API, CLI, library)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng cho biết: framework (React/Next.js/NestJS/Express...) và mục đích dự án."
+```
+
+---
+
+## Scope
+- ✅ Initialize project with standard tooling
+- ✅ Generate `DESIGN.md` (mandatory for any UI project)
+- ✅ Configure: ESLint, Prettier, TypeScript strict mode
+- ✅ Create standard directory structure
+
+## Non-Goals
+- ❌ Skip DESIGN.md for UI projects
+- ❌ Hardcode outdated dependency versions
+- ❌ Skip README
+
+---
+
+## Standard Directory Structures
+
+### Next.js / React
+```
+src/
+├── app/              # Pages (App Router) or pages/
+├── components/       # Shared UI components
+│   ├── ui/           # Design system primitives
+│   └── [feature]/    # Feature-specific components
+├── hooks/            # Custom React hooks
+├── lib/              # Utilities, helpers
+├── services/         # API service functions
+├── types/            # TypeScript type definitions
+└── styles/           # Global CSS + DESIGN.md tokens
+DESIGN.md             # Brand & Design Contract
+```
+
+### NestJS / Express API
+```
+src/
+├── modules/
+│   └── [feature]/
+│       ├── [feature].controller.ts
+│       ├── [feature].service.ts
+│       ├── [feature].repository.ts
+│       └── dto/
+├── common/           # Shared utilities, guards, interceptors
+├── config/           # Environment configuration
+└── main.ts
+```
+
+### Vite + React
+```
+src/
+├── assets/
+├── components/
+├── pages/
+├── router/
+├── services/
+├── stores/           # State management
+└── types/
+```
+
+---
+
+## Required Files Checklist
+```
+[ ] package.json — with lint + test + build scripts
+[ ] tsconfig.json — strict: true enabled
+[ ] .eslintrc / eslint.config.js — project standard
+[ ] .prettierrc — formatting config
+[ ] .gitignore — standard entries
+[ ] README.md — project description + setup instructions
+[ ] DESIGN.md — (UI projects) brand contract with color/font/spacing tokens
+[ ] .env.example — all env vars listed (no actual values)
+```
+
+---
+
+## DESIGN.md Minimum Template
+```markdown
+# Design System
+
+## Colors (HSL)
+--color-primary: hsl(220, 80%, 55%);
+--color-surface: hsl(220, 15%, 12%);
+--color-text: hsl(220, 10%, 90%);
+
+## Spacing Scale (4px base)
+--space-1: 4px; --space-2: 8px; --space-3: 16px;
+--space-4: 24px; --space-5: 32px; --space-6: 48px;
+
+## Typography
+--font-sans: 'Inter', system-ui, sans-serif;
+--font-size-base: 1rem;
+--font-size-lg: 1.25rem;
+
+## Border Radius
+--radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px;
+
+## Animation
+--transition-fast: 150ms ease;
+--transition-base: 250ms ease;
+```
+
+---
+
+
+---
+
+## Workflow
+
+
+---
+
+## Evidence Format
+
+
+---
+
+## Priority Order
+
+
+---
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | All required files created, structure matches framework standard | Full bootstrap complete |
+| PARTIAL | Structure created but DESIGN.md incomplete (UI project) | Follow-up needed |
+| BLOCKED | Framework/purpose not specified | Ask user |
+| FAILED | Cannot initialize (permission error, invalid framework) | Report error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Framework explicitly stated, directory structure clear | Build directly |
+| MEDIUM | Framework inferred from context (found React imports) | Note assumption, proceed |
+| LOW | Cannot determine framework or project type | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|----------|
+| CRITICAL | Security misconfiguration in bootstrap | .env with real secrets committed |
+| HIGH | Missing mandatory file blocks all future work | No DESIGN.md for UI project |
+| MEDIUM | Incomplete setup reduces developer experience | Missing ESLint config |
+| LOW | Cosmetic or optional file missing | Missing .editorconfig |
+
+---
+
+## Retry Policy
+```
+File creation fails
+  └─ Check: permission issue vs path error
+       ├─ Path error → correct path and retry
+       └─ Permission error → EXIT: FAILED, report exact path
+            └─ Do NOT retry more than 1 time per file
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Framework or project type not specified
+Missing:
+  - Framework name (React, Next.js, NestJS, Express, etc.)
+  - Project purpose (web app, API, CLI, library)
+Questions:
+  1. Framework nào bạn muốn dùng?
+  2. Dự án này là web app, API server, hay CLI tool?
+Recommended Assumptions (if proceeding):
+  - Default: Next.js 14 (App Router) + TypeScript + ESLint
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["framework", "project_purpose"],
+  "optional_fields": ["project_name", "existing_dir"]
+}
+```
+### Produces
+```json
+{
+  "to": "qk-feature-delivery or qk-design-to-code",
+  "output_fields": ["project_structure", "design_md_path", "tooling_config", "exit_code"]
+}
+```
+
+---
+
+

package/.agents/skills/qk-project-health/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: qk-project-health
+category: qa
+version: 7.5.0
+description: "Kiểm toán toàn diện Code Smells, Tech Debt, Architecture — health score 0–100 với actionable roadmap."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: low
+side_effects: read_only
+produces: [report]
+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-project-health — Complete Codebase Audit
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Project root is accessible
+
+---
+
+## Scope
+- ✅ Score 5 health dimensions (0–20 pts each = 100 total)
+- ✅ Identify deprecated packages and security vulnerabilities
+- ✅ Produce actionable refactoring roadmap
+
+## Non-Goals
+- ❌ Fix issues — report only
+- ❌ Hide systemic architectural flaws
+
+---
+
+## Health Scoring System
+
+| Dimension | Max Points | Key Checks |
+|-----------|-----------|------------|
+| Security | 20 | 0 critical CVEs, no hardcoded secrets, auth guards present |
+| Code Quality | 20 | Functions ≤ 30L, complexity ≤ 10, no God Files |
+| Architecture | 20 | Clean layers (UI/Logic/Data separated), no circular imports |
+| Dependencies | 20 | No deprecated packages, no unused deps, versions pinned |
+| Documentation | 20 | README complete, public APIs documented, DESIGN.md exists |
+
+**Total: 100 pts. Grades: A (90+) / B (75-89) / C (60-74) / D (<60)**
+
+---
+
+## Priority Order
+| P | Dimension | Never Skip? |
+|---|-----------|-------------|
+| P1 | Security | Yes |
+| P2 | Code Quality | Yes |
+| P3 | Architecture | Budget < 30% |
+| P4 | Dependencies | Budget < 50% |
+| P5 | Documentation | Budget < 60% |
+
+---
+
+## Workflow
+
+### Phase 1 — Quick Scan (P1+P2)
+1. `grep_search` for: hardcoded secrets, `eval(`, `any` types, `console.log`
+2. Sample 3 key files → check function lengths, file sizes
+3. Score Security (0–20) + Code Quality (0–20)
+
+### Phase 2 — Structure Scan (P3+P4)
+1. Read `package.json` — check outdated/deprecated packages
+2. Check import patterns for circular dependencies or layer violations
+3. Score Architecture (0–20) + Dependencies (0–20)
+
+### Phase 3 — Docs Scan (P5) + Report
+1. Check README, DESIGN.md, key function JSDoc
+2. Score Documentation (0–20)
+3. Generate full report + prioritized roadmap
+
+---
+
+## Evidence Format
+```
+[SEVERITY] Dimension: [SECURITY|QUALITY|ARCH|DEPS|DOCS]
+Finding:    [specific issue]
+Location:   [file:line OR package name]
+Confidence: HIGH
+Impact:     -N pts
+Fix:        [actionable suggestion]
+```
+
+---
+
+## Output Format
+```
+🏥 Project Health Report
+─────────────────────────────────────────────────
+Grade: [A|B|C|D] ([Score]/100)
+
+Scores:
+  Security:      [N/20]
+  Code Quality:  [N/20]
+  Architecture:  [N/20]
+  Dependencies:  [N/20]
+  Documentation: [N/20]
+
+Critical Issues (fix immediately):
+  [list CRITICAL findings]
+
+Refactoring Roadmap (priority order):
+  1. [Most impactful — estimated effort]
+  2. [Second — estimated effort]
+  3. [Third]
+
+Exit Code: [SUCCESS (A/B) | PARTIAL (C) | FAILED (D)]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Audit completed and report generated with scores | Normal completion |
+| PARTIAL | Audit completed but some directories skipped (token limit) | Large project |
+| BLOCKED | Project is empty or completely unreadable | Missing project |
+| FAILED | Cannot calculate score due to tool failure | Linter crashed |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Analyzed via AST, linters, or exhaustive search | Include in report as fact |
+| MEDIUM | Sampled a few files, assumed pattern holds | Note as "Project trend" |
+| LOW | Did not check | Do NOT include in report |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Security flaw or completely broken architecture | API keys committed, cyclical dependency |
+| HIGH | Major tech debt slowing down development | God objects, missing tests on core logic |
+| MEDIUM | Inconsistent patterns | Mixing fetch/axios, tabs/spaces |
+| LOW | Minor code smell | Magic numbers in UI |
+
+---
+
+## Retry Policy
+```
+Audit fails
+  └─ Token limit hit (project too large)
+       ├─ Ask user to narrow scope (e.g., audit only src/api/)
+       └─ Do NOT auto-retry full project scan
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Project unreadable or empty
+Missing:
+  - Source code
+Questions:
+  1. Thư mục mã nguồn chính nằm ở đâu? (ví dụ: src/, lib/)
+Recommended Assumptions:
+  - Scan typical directories (src, app, lib, test)
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": [],
+  "optional_fields": ["target_directory"]
+}
+```
+### Produces
+```json
+{
+  "to": "user or qk-system-evolution",
+  "output_fields": ["health_score", "critical_issues", "refactoring_roadmap", "exit_code"]
+}
+```
+
+---
+