ai-developer-skill-os 7.0.2 → 7.5.1

package/skills/qk-docs/SKILL.md

@@ -1,40 +1,199 @@
----
-name: qk-docs
-category: documentation
-version: 7.0.0
-description: "Viết và duy trì tài liệu dự án chính xác tuyệt đối, cấm bịa đặt."
----
-
-# qk-docs
-
-## Scope
-- Technical documentation, Readme files, and inline comments (Execute)
-
-## Verbs
-- `[DOCUMENT]`: Synchronize documentation with the actual implementation.
-
-## Constraints
-```yaml
-must:
-  - "Ensure documentation matches the exact implementation in the codebase"
-  - "Update documentation whenever corresponding code is changed"
-must_not:
-  - "Hallucinate or guess API parameters not present in the code"
-  - "Write generic or useless comments (e.g., '// gets the user')"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Self-documenting code over excessive inline comments"
-  - "Living documentation (e.g., Swagger/JSDoc) over isolated Markdown files"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Documentation requests conflict with actual codebase implementation"
-```
-
-## Output
-- Accurate documentation files or inline comments.
+---
+name: qk-docs
+category: documentation
+version: 7.5.1
+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.1
+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/skills/qk-engineering-standard/SKILL.md

@@ -1,42 +1,352 @@
----
-name: qk-engineering-standard
-category: qa
-version: 7.0.0
-description: "Ép buộc áp dụng SOLID, DRY, Clean Code, và chống Spaghetti code."
----
-
-# qk-engineering-standard
-
-## Scope
-- Code Quality, Architecture, and Standards Enforcement (Audit)
-
-## Verbs
-- `[ENFORCE]`: Reject code that violates engineering standards.
-
-## Constraints
-```yaml
-must:
-  - "Enforce SOLID principles and DRY"
-  - "Keep cyclomatic complexity low (Functions must do ONE thing)"
-  - "Enforce strict naming conventions"
-must_not:
-  - "Allow spaghetti code or mega-functions"
-  - "Merge logic that mixes UI, State, and Network in one file"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Composition over inheritance"
-  - "Early returns and guard clauses"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Cyclomatic complexity exceeds acceptable thresholds"
-  - "Code violates V7 Anti-Slop architectural rules"
-```
-
-## Output
-- Refactored code or Audit rejection report.
+---
+name: qk-engineering-standard
+category: qa
+version: 7.5.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+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.1
+runtime_version: 1
+schema_version: 2
+---
+
+## References
+- Detailed thresholds with rationale: `references/thresholds.md`
+
+---
+
+