ai-developer-skill-os 7.5.0 → 7.5.1

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

@@ -1,198 +0,0 @@
----
-name: qk-docs
-category: documentation
-version: 7.5.0
-description: "Viết và duy trì tài liệu chính xác tuyệt đối — phải match code thực tế, cấm bịa đặt."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
-cost: low
-latency: fast
-risk: low
-side_effects: edit_files
-produces: [report]
-consumes: [source-code]
-token_budget:
-  max_files_read: 3
-  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-docs — Technical Writer & Documentation Maintainer
-
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
-
----
-
-## Preconditions
-- [ ] Target code file or module is specified
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Chỉ định file cần viết docs."
-```
-
----
-
-## Scope
-- ✅ Document ONLY what exists in code — never invent params/behavior
-- ✅ Update docs whenever corresponding code changes
-- ✅ Use living documentation (JSDoc/TSDoc/Swagger) over isolated Markdown
-
-## Non-Goals
-- ❌ Guess API params not in the code
-- ❌ Write generic/useless comments (`// gets the user`)
-- ❌ Write docs for code that hasn't been read yet
-
----
-
-## Priority Order
-| P | Task | Skip Threshold |
-|---|------|----------------|
-| P1 | Read source code first (never write before reading) | Never |
-| P2 | Document public API (exported functions/classes) | Never |
-| P3 | Document complex logic with WHY (not WHAT) | Budget < 40% |
-| P4 | Update README if public interface changed | Budget < 60% |
-
----
-
-## Workflow
-
-### Phase 1 — Read Code
-1. `view_file[targeted]` — read function/class signatures
-2. Identify: params, return type, side effects, error cases
-
-**Decision:** `IF code is not readable → EXIT: BLOCKED — read code first`
-
-### Phase 2 — Write Documentation
-1. JSDoc/TSDoc format for functions: `@param`, `@returns`, `@throws`
-2. Comment: WHY (not WHAT) — code already shows what
-3. Example usage for complex APIs
-
-### Phase 3 — Verify Accuracy
-1. Re-read written docs vs code → spot check each param name
-
-**Decision:**
-```
-IF docs match code exactly → EXIT: SUCCESS
-IF any param name or type mismatch → fix immediately
-```
-
----
-
-## Documentation Templates
-
-### Function (JSDoc)
-```typescript
-/**
- * [One sentence — what it does and WHY it exists]
- *
- * @param {Type} paramName - [description]
- * @returns {Type} [description of return value]
- * @throws {ErrorType} [when this error is thrown]
- * @example
- * const result = functionName(arg);
- */
-```
-
-### README Section
-```markdown
-## [Feature Name]
-[What it does — user-facing description]
-
-### Usage
-[Code example]
-
-### Configuration
-| Option | Type | Default | Description |
-```
-
----
-
-## Evidence Format
-```
-[SEVERITY] path/to/file.ts:LINE
-Issue:      [MISSING_PARAM | WRONG_TYPE | STALE_DOC | GENERIC_COMMENT]
-Confidence: HIGH
-Fix:        [specific correction]
-```
-
----
-
-## Exit Codes
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Docs written and verified against source code | Execution complete |
-| PARTIAL | Docs written but some parts inferred (not verified) | MEDIUM confidence |
-| BLOCKED | Target source file missing or inaccessible | Cannot read source |
-| FAILED | Documentation fundamentally misrepresents the code | Gross error |
-
----
-
-## Confidence Model
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Target code read, behavior understood | Write docs definitively |
-| MEDIUM | Target code too large, inferred from types/tests | Write with disclaimer |
-| LOW | "Write docs for this feature" without pointing to code | EXIT: BLOCKED |
-
----
-
-## Severity
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Docs instruct user to do something dangerous | Documenting destructive API without warnings |
-| HIGH | API params documented incorrectly | Says string instead of object |
-| MEDIUM | Missing docs for edge cases | Doesn't explain error throws |
-| LOW | Typo or poor formatting | Misaligned markdown table |
-
----
-
-## Retry Policy
-```
-Doc verification fails
-  └─ Target code changed during doc writing
-       ├─ Re-read target code
-       └─ Do NOT retry more than 1 time
-```
-
----
-
-## Escalation Rules
-```
-BLOCKED: Target source file missing
-Missing:
-  - Exact path to the code that needs documenting
-Questions:
-  1. File code nào bạn muốn viết doc? (Xin đường dẫn)
-  2. Mục tiêu của doc này là cho user hay cho developer nội bộ?
-Recommended Assumptions:
-  - Developer-facing JSDoc if inside source files
-```
-
----
-
-## Handoff Contract
-### Consumes
-```json
-{
-  "from": "user",
-  "required_fields": ["target_file", "doc_type"],
-  "optional_fields": ["context"]
-}
-```
-### Produces
-```json
-{
-  "to": "user",
-  "output_fields": ["updated_files", "exit_code"]
-}
-```
-
----
-

package/.qk-ai-skill-os/skills/qk-engineering-standard/SKILL.md

@@ -1,351 +0,0 @@
----
-name: qk-engineering-standard
-category: qa
-version: 7.5.0
-description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
-platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: deterministic
-
-cost: medium
-latency: medium
-risk: low
-side_effects: read_only
-produces: [report]
-consumes: [source-code]
-
-token_budget:
-  max_files_read: 5
-  max_lines_per_read: 150
-  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-engineering-standard — Code Quality Enforcer
-
-> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Preconditions
-- [ ] Target file(s) or module(s) are specified
-
-```
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Scope
-- ✅ Detect violations with exact file:line references
-- ✅ Classify by severity with concrete thresholds
-- ✅ Suggest minimal, targeted refactors
-
-## Non-Goals
-- ❌ Auto-fix code — report only (fixes go to qk-bug-resolution or qk-feature-delivery)
-- ❌ Rewrite architecture
-- ❌ Touch files outside the specified scope
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Concrete Thresholds (Non-Negotiable)
-
-```yaml
-function:
-  max_lines: 30              # Lines of code, excluding comments/blanks
-  max_cyclomatic_complexity: 10
-  max_parameters: 4
-
-file:
-  max_lines: 300
-  max_public_methods_per_class: 10  # God Class threshold
-
-dry:
-  violation_threshold: 3    # Same logic duplicated in ≥ 3 places
-
-separation_of_concerns:
-  violation: "File mixes UI rendering + API calls + State management"
-
-naming:
-  min_variable_name_length: 2  # Single-letter vars (except i,j,k in loops)
-  max_abbreviation_ratio: 0.3  # > 30% abbreviations in identifiers = violation
-
-dependency:
-  max_imports_per_file: 15  # Beyond this: likely a God File
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Priority Order
-
-| Priority | Check | Severity | Skip Threshold |
-|----------|-------|----------|----------------|
-| P1 | Security violations (hardcoded secrets, SQL injection) | CRITICAL | Never |
-| P2 | God Functions > 30 lines / complexity > 10 | HIGH | Budget < 30% |
-| P3 | God Files > 300 lines / God Classes | HIGH | Budget < 40% |
-| P4 | DRY violations (3+ duplicates) | MEDIUM | Budget < 50% |
-| P5 | Mixed concerns in single file | MEDIUM | Budget < 60% |
-| P6 | Naming convention violations | LOW | Budget < 70% |
-| P7 | Excessive imports / coupling | LOW | Budget < 80% |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Workflow
-
-### Phase 1 — Scan for Critical & High Violations
-
-**Steps:**
-1. `grep_search` — search for: hardcoded secrets, `console.log`, `eval(`, `any` types
-2. `view_file[targeted]` — read function definitions to count lines and parameters
-3. Log each violation with Evidence Format
-
-**Decision:**
-```
-IF CRITICAL violation found (e.g., hardcoded API key)
-  → Report immediately, mark EXIT: FAILED
-  → Still continue scanning (don't stop at first critical)
-
-IF function line count > 30 OR complexity > 10
-  → Log as [HIGH]
-
-IF file line count > 300
-  → Log as [HIGH] — God File suspected
-```
-
-**Exit When:**
-- All P1+P2+P3 checks done → go to Phase 2
-- Token budget < 30% → go to Phase 3 directly with PARTIAL flag
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-### Phase 2 — Scan for Medium & Low Violations
-
-**Steps:**
-1. `grep_search` — find duplicate logic patterns (copy-paste code)
-2. Check import counts per file
-3. Check naming conventions
-
-**Decision:**
-```
-IF same logic block appears ≥ 3 times
-  → Log as [MEDIUM] DRY violation
-
-IF file has > 15 imports
-  → Log as [LOW] — potential God File or tight coupling
-
-IF token budget < 50%
-  → Skip P6+P7, go to Phase 3
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-### Phase 3 — Score & Report
-
-**Steps:**
-1. Count violations by severity
-2. Calculate health score: start at 100, deduct per violation
-3. Generate report
-
-**Deduction Scale:**
-```
-CRITICAL: -25 pts each
-HIGH:     -10 pts each
-MEDIUM:   -5 pts each
-LOW:      -2 pts each
-```
-
-**Decision:**
-```
-IF score ≥ 80 AND no CRITICAL violations
-  → EXIT: SUCCESS
-
-IF score 60–79 OR any HIGH violations
-  → EXIT: PARTIAL — list fixes needed
-
-IF score < 60 OR any CRITICAL violations
-  → EXIT: FAILED — requires immediate action
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | Direct line count, exact pattern match | Report as violation |
-| MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
-| LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Severity
-
-| Level | Definition | Example |
-|-------|-----------|---------|
-| CRITICAL | Security risk or data integrity | Hardcoded secret, SQL injection via string concat |
-| HIGH | Technical debt that blocks scaling | Function 80 lines, God Class 15+ methods |
-| MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
-| LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Evidence Format
-
-```
-[SEVERITY] path/to/file.ts:LINE
-Rule:       [FUNCTION_LENGTH | COMPLEXITY | DRY | SOC | NAMING | GOD_CLASS | SECRET]
-Reason:     [specific measurement vs threshold]
-Confidence: [HIGH|MEDIUM|LOW]
-Fix:        [one-line suggestion]
-Deduction:  -N pts
-```
-
-**Example:**
-```
-[HIGH] src/services/order.service.ts:45
-Rule:       FUNCTION_LENGTH
-Reason:     Function `processOrder` is 87 lines (threshold: 30)
-Confidence: HIGH
-Fix:        Extract payment logic to `processPayment()`, shipping to `scheduleShipment()`
-Deduction:  -10 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 → skip and note in report as PARTIAL.
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Escalation Rules
-
-```
-BLOCKED: No target specified
-Missing:
-  - File path or module name to audit
-Questions:
-  1. Bạn muốn kiểm tra file nào hoặc toàn bộ module nào?
-  2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Handoff Contract
-
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["target_files_or_module"],
-  "optional_fields": ["custom_thresholds"]
-}
-```
-
-### Produces
-```json
-{
-  "to": "user",
-  "output_fields": ["health_score", "violations_list", "severity_counts", "exit_code"]
-}
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Output Format
-
-```
-⚙️ Engineering Standard Audit
-─────────────────────────────────────────────────
-Target:      [file or module]
-
-Health Score: [X/100]
-  CRITICAL violations: [N] (-Npts)
-  HIGH violations:     [N] (-Npts)
-  MEDIUM violations:   [N] (-Npts)
-  LOW violations:      [N] (-Npts)
-
-Violations (priority order):
-  [SEVERITY] file:LINE — Rule — reason — Fix — (-Xpts)
-
-Required Actions:
-  1. [Most critical fix]
-  2. [Second fix]
-
-Exit Code:   [SUCCESS | PARTIAL | FAILED]
-```
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Score ≥ 80, no CRITICAL | Code meets V7.5 standards |
-| PARTIAL | Score 60–79 or incomplete scan | Some categories skipped |
-| BLOCKED | No target specified | Cannot audit without scope |
-| FAILED | Score < 60 or CRITICAL found | Immediate action required |
-
-skill_version: 7.5.0
-runtime_version: 1
-schema_version: 2
----
-
-## References
-- Detailed thresholds with rationale: `references/thresholds.md`
-
----
-

package/.qk-ai-skill-os/skills/qk-engineering-standard/rules/backend.md

@@ -1,122 +0,0 @@
-# Backend Rules
-
-- Define rules here.
-
----
-
-## 🔄 [Merged from qk-backend-architecture]
-
-# Backend Architecture
-
-> **Language rule:**
-> Use English for: code, identifiers, file names, architecture terms, technical decisions.
-> Use the user's language for: explanations, questions, summaries, and feedback.
-> The user may write in any language — detect and match it automatically.
-
----
-
-## Trigger
-
-Activate this skill when:
-- Creating new backend API endpoints, services, or models
-- User asks "where should I put this business logic?"
-- Project audit flags mixed concerns (e.g., SQL queries inside a controller)
-- Inheriting or setting up a Node.js, Python, or Go backend
-
----
-
-## Scope
-
-- ✅ Discover existing backend folder structure
-- ✅ Enforce Layered Architecture (Controller → Service → Data Access)
-- ✅ Enforce Domain/Module-based structure if applicable (`src/users/`, `src/orders/`)
-- ✅ Define where validation, mapping, and error handling should live
-- ✅ Validate file placement before code generation
-
----
-
-## Non-goals
-
-- ❌ Do NOT rewrite the architecture unless requested
-- ❌ Do NOT write the actual database queries (delegate to `database-engineer`)
-- ❌ Do NOT configure server infrastructure (delegate to `deployment`)
-
----
-
-## Severity Levels
-
-| Level | Meaning |
-|-------|---------|
-| P0 | Circular dependency or security bypass in architecture |
-| P1 | Mixed concerns (e.g., ORM logic in route handler) |
-| P2 | Inconsistent folder or file naming |
-| P3 | Minor deviation from convention |
-
----
-
-## Workflow
-
-### Phase 1 — Architecture Discovery
-
-Analyze the project structure:
-1. **Classic MVC / Layered:** `controllers/`, `services/`, `models/`, `routes/`
-2. **Domain-Driven (Module):** `src/modules/user/{controller, service, repository}`
-3. **Framework-specific:** NestJS (`.controller.ts`, `.service.ts`), Django apps, Express monolithic.
-4. **Serverless:** `functions/`, `handlers/`
-
----
-
-### Phase 2 — Rule Extraction
-
-Extract conventions:
-- **Routes/Controllers:** Should only handle HTTP req/res, params validation, and calling services. No business logic.
-- **Services:** Pure business logic. Does not know about HTTP (`req`/`res`).
-- **Repositories/Data Access:** Only layer that interacts with the DB.
-- **Error Handling:** Centralized error middleware vs local try/catch.
-
----
-
-### Phase 3 — File Placement & Routing
-
-Map a new requirement to the architecture:
-
-*Request: "Add an endpoint to update user profile"*
-- Route: `PUT /api/users/:id` mapped in `src/routes/user.routes.ts`
-- Controller: `updateProfile(req, res)` in `src/controllers/user.controller.ts`
-- Service: `updateUserProfile(userId, data)` in `src/services/user.service.ts`
-
----
-
-## Decision Tree
-
-```
-Does the project group files by Layer or by Domain?
-  ├── Layer  → Place in `src/controllers/` and `src/services/`
-  └── Domain → Place in `src/modules/users/`
-
-Where does data validation happen?
-  ├── Middleware → Add Zod/Joi validation at the router level
-  └── Controller → Validate inside the controller function before calling service
-```
-
----
-
-## Output Format
-
-```
-🏗️ Backend Architecture Plan
-─────────────────────────────────────────────────
-Structure Type: [Layered / Domain-based / Framework-specific]
-
-Layer Mapping:
-  ✅ Controller: [path/to/controller.ts] — handles HTTP
-  ✅ Service:    [path/to/service.ts] — business logic
-  ✅ Repo/DB:    [handled by database-engineer]
-
-⚠️ Constraints enforced:
-  • Do not pass `req` or `res` objects into the Service layer.
-  • Validate all inputs at the Controller/Route level.
-
-🔗 Next Steps:
-  Proceeding to implement the layers.
-```

package/.qk-ai-skill-os/skills/qk-engineering-standard/rules/database.md

@@ -1,3 +0,0 @@
-# Database Rules
-
-- Define rules here.