ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/skills/qk-orchestrator/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: qk-orchestrator
+category: core
+version: 7.5.0
+description: "Điều hướng yêu cầu của người dùng đến đúng skill với kỷ luật thép — kiểm tra preconditions và routing table."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: low
+latency: fast
+risk: low
+side_effects: none
+produces: [plan]
+consumes: [user-request]
+
+token_budget:
+  max_files_read: 1
+  max_lines_per_read: 50
+  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-orchestrator — Request Routing
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] User request is provided (any language)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng mô tả yêu cầu của bạn."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Analyze user intent and route to the correct skill
+- ✅ Verify preconditions of target skill BEFORE delegating
+- ✅ Enforce sequential pipeline when skills depend on each other
+
+## Non-Goals
+- ❌ Write code directly — delegate to specialist skills
+- ❌ Hallucinate non-existent skills
+- ❌ Allow UI work without `DESIGN.md` verified
+- ❌ Allow logic work without context graph from `qk-context-loader`
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Check | Skip Threshold |
+|----------|-------|----------------|
+| P1 | Match intent to routing table | Never |
+| P2 | Verify target skill preconditions | Never |
+| P3 | Check pipeline dependencies (e.g., context-loader first) | Never for logic tasks |
+| P4 | Estimate cost/latency for user info | Budget < 70% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Intent Classification
+
+**Steps:**
+1. Parse user request → extract intent keywords
+2. Match against routing table (see `references/routing-table.md`)
+3. Resolve to primary skill + pipeline order
+
+**Decision:**
+```
+IF single clear match found
+  → Confidence: HIGH → go to Phase 2
+
+ELSE IF 2–3 possible matches
+  → Pick highest-priority match
+  → Confidence: MEDIUM → go to Phase 2, note ambiguity
+
+ELSE IF no match
+  → EXIT: BLOCKED — ask clarifying question
+```
+
+**Exit When:**
+- Skill identified → go to Phase 2
+- No matching skill → EXIT: BLOCKED
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Precondition Check
+
+**Steps:**
+1. Read target skill's `Preconditions` section
+2. Verify each precondition against current context
+
+**Decision:**
+```
+IF all preconditions met
+  → go to Phase 3
+
+ELSE IF missing precondition is resolvable
+  → Resolve it first (e.g., run qk-context-loader, find DESIGN.md)
+  → Then go to Phase 3
+
+ELSE
+  → EXIT: BLOCKED
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Pipeline Enforcement
+
+**Steps:**
+1. Check if target skill `consumes` output from another skill
+2. If yes → ensure that upstream skill has run first
+3. Delegate to target skill with full context
+
+**Pipeline Rules:**
+```
+UI tasks:
+  [DESIGN.md check] → [qk-ui-audit (optional)] → [qk-design-to-code | qk-feature-delivery]
+
+Logic tasks:
+  [qk-context-loader] → [qk-feature-delivery | qk-bug-resolution | qk-api-lifecycle]
+
+Data tasks:
+  [qk-context-loader] → [qk-data-lifecycle | qk-db-optimizer]
+
+Release tasks:
+  [qk-validation-gate] → [qk-production-release]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Routing Table (Quick Reference)
+Full table: see `references/routing-table.md`
+
+| Intent Keywords | Primary Skill | Pipeline |
+|----------------|---------------|----------|
+| bug, lỗi, error, broken, crash, fix, sửa | `qk-bug-resolution` | direct |
+| tính năng, feature, thêm, mới, add, implement | `qk-feature-delivery` | context-loader first |
+| UI, giao diện, design, component, layout, màn hình | `qk-design-to-code` | DESIGN.md check |
+| slow, query, index, N+1, performance DB | `qk-db-optimizer` | context-loader first |
+| deploy, release, production, CI/CD, build | `qk-production-release` | validation-gate first |
+| schema, migration, database, table, model | `qk-data-lifecycle` | context-loader first |
+| refactor, clean, SOLID, DRY, code quality | `qk-engineering-standard` | direct |
+| test, lint, validate, check quality | `qk-validation-gate` | direct |
+| upgrade, update thư viện, migrate library | `qk-system-evolution` | direct |
+| docs, documentation, README, comment | `qk-docs` | direct |
+| API, endpoint, route, contract | `qk-api-lifecycle` | context-loader first |
+| access, role, permission, RBAC, auth | `qk-access-policy` | direct |
+| AI, prompt, RAG, LLM, embedding | `qk-ai-builder` | direct |
+| design system, token, CSS variable | `qk-ui-system-builder` | DESIGN.md check |
+| project audit, health, tech debt | `qk-project-health` | direct |
+| new project, bootstrap, init | `qk-project-bootstrap` | direct |
+| memory, context, recall, lưu | `qk-project-memory` | direct |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Single clear keyword match | Route directly |
+| MEDIUM | Multiple possible skills | Route to most likely, note ambiguity |
+| LOW | Request is too vague | Ask clarifying question |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Escalation Rules
+
+```
+BLOCKED: Cannot determine correct skill
+Missing:
+  - More specific description of the task
+Questions:
+  1. Bạn muốn làm gì? (fix bug / thêm tính năng / tối ưu / deploy)
+  2. File hoặc module nào bị ảnh hưởng?
+Recommended Assumptions: none — routing requires clear intent
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["request_text"],
+  "optional_fields": ["affected_file", "context"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "[target-skill]",
+  "output_fields": ["routed_skill", "pipeline_order", "preconditions_verified", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🧭 Orchestrator Routing
+─────────────────────────────────────────────────
+Intent:      [Classified intent]
+Skill:       [qk-skill-name]
+Pipeline:    [skill-a → skill-b → skill-c]
+Confidence:  [HIGH | MEDIUM | LOW]
+
+Preconditions:
+  ✅ [Condition met]
+  ✅ [Condition met]
+
+Exit Code:   SUCCESS
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Skill routed, preconditions verified, delegation in progress | Normal flow |
+| PARTIAL | Routed with MEDIUM confidence — ambiguity noted | Multi-match situation |
+| BLOCKED | Cannot classify intent or precondition missing | Vague request or missing DESIGN.md |
+| FAILED | No skill matches and cannot escalate | Unknown domain request |
+
+---
+

package/.qk-ai-skill-os/skills/qk-orchestrator/references/routing-table.md

@@ -0,0 +1,77 @@
+# Routing Table — qk-orchestrator V7.5
+
+> Full intent → skill mapping. Updated whenever a new skill is added.
+
+---
+
+## Primary Routes
+
+| Intent Keywords (Vietnamese + English) | Primary Skill | Pipeline Required |
+|----------------------------------------|---------------|-------------------|
+| bug, lỗi, error, broken, crash, fix, sửa, không hoạt động | `qk-bug-resolution` | direct |
+| tính năng, feature, thêm, mới, add, implement, xây dựng | `qk-feature-delivery` | `qk-context-loader` first |
+| UI, giao diện, design, component, layout, màn hình, hiển thị | `qk-design-to-code` | DESIGN.md check |
+| slow, chậm, query, index, N+1, performance DB, tối ưu DB | `qk-db-optimizer` | `qk-context-loader` first |
+| deploy, release, production, CI/CD, build, xuất bản | `qk-production-release` | `qk-validation-gate` first |
+| schema, migration, database, table, model, ORM | `qk-data-lifecycle` | `qk-context-loader` first |
+| refactor, clean, SOLID, DRY, code quality, tái cấu trúc | `qk-engineering-standard` | direct |
+| test, lint, validate, check quality, kiểm tra | `qk-validation-gate` | direct |
+| upgrade, update thư viện, migrate library, nâng version | `qk-system-evolution` | direct |
+| docs, documentation, README, comment, tài liệu | `qk-docs` | direct |
+| API, endpoint, route, contract, swagger | `qk-api-lifecycle` | `qk-context-loader` first |
+| access, role, permission, RBAC, phân quyền | `qk-access-policy` | direct |
+| AI, prompt, RAG, LLM, embedding, pipeline AI | `qk-ai-builder` | direct |
+| design system, token, CSS variable, design tokens | `qk-ui-system-builder` | DESIGN.md check |
+| project audit, health, tech debt, kiểm toán dự án | `qk-project-health` | direct |
+| new project, bootstrap, init, khởi tạo dự án | `qk-project-bootstrap` | direct |
+| memory, context, recall, lưu ngữ cảnh | `qk-project-memory` | direct |
+| security, policy, authorization, bảo mật | `qk-policy-engine` | → redirect to `qk-access-policy` |
+| help, danh sách, list skills, hướng dẫn | `qk-help` | direct |
+| consume API, tích hợp API backend, gọi API từ FE | `qk-fe-api-integration` | `qk-context-loader` first |
+| UI audit, kiểm tra giao diện, anti-slop check | `qk-ui-audit` | DESIGN.md check |
+
+---
+
+## Pipeline Templates
+
+### UI Pipeline
+```
+1. Check DESIGN.md exists (qk-project-bootstrap if missing)
+2. [Optional] qk-ui-audit — audit existing UI
+3. qk-design-to-code OR qk-feature-delivery (UI part)
+4. qk-validation-gate — lint + type check
+```
+
+### Logic/Feature Pipeline
+```
+1. qk-context-loader — build dependency graph
+2. qk-feature-delivery — implement
+3. qk-validation-gate — test + lint
+4. [Optional] qk-production-release
+```
+
+### Database Pipeline
+```
+1. qk-context-loader — map schema dependencies
+2. qk-data-lifecycle (schema) OR qk-db-optimizer (performance)
+3. qk-validation-gate — run migration tests
+```
+
+### Release Pipeline
+```
+1. qk-validation-gate — full test suite
+2. qk-production-release — build + security gate
+```
+
+---
+
+## Ambiguity Resolution
+
+When 2+ skills match:
+
+| Situation | Resolution |
+|-----------|------------|
+| "fix" + UI component | `qk-bug-resolution` (fix takes priority over design) |
+| "refactor" + API | `qk-engineering-standard` if code quality focus, `qk-api-lifecycle` if contract change |
+| "add feature" + DB | Route `qk-feature-delivery` with `qk-data-lifecycle` in pipeline |
+| "optimize" without context | Ask: "DB performance or code quality?" |

package/.qk-ai-skill-os/skills/qk-production-release/SKILL.md

@@ -0,0 +1,290 @@
+---
+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
+
+[Placeholder for Confidence Model]
+
+
+---
+
+## Severity
+
+[Placeholder for Severity]
+
+
+---
+
+## Retry Policy
+
+[Placeholder for 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 |
+
+---
+
+