ai-developer-skill-os 7.0.2 → 7.5.1

package/.agents/skills/qk-api-lifecycle/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: qk-api-lifecycle
+category: fullstack
+version: 7.5.0
+description: "Thiết kế, triển khai API endpoints với Zero-Trust — contract trước, code sau."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: medium
+risk: medium
+side_effects: edit_files
+produces: [code, report]
+consumes: [context-graph, user-description]
+
+token_budget:
+  max_files_read: 3
+  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-api-lifecycle — API Design & Implementation
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] API purpose and resource name are defined
+- [ ] Request/response shape is specified (or sample JSON provided)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần định nghĩa: resource name + expected request/response shape trước khi code."
+```
+
+---
+
+## Scope
+- ✅ Define OpenAPI/Swagger contract BEFORE writing code
+- ✅ Implement endpoint strictly to contract
+- ✅ Validate all inputs, handle all error cases
+- ✅ Ensure backward compatibility
+
+## Non-Goals
+- ❌ Introduce breaking changes without versioning
+- ❌ Bypass auth checks
+- ❌ Guess external API shapes without evidence
+
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Contract definition (TypeScript types) | Never |
+| P2 | Success response + correct status code | Never |
+| P3 | Input validation middleware | Never |
+| P4 | Error responses (400, 401, 404, 422, 500) | Budget < 30% |
+| P5 | Documentation (JSDoc or OpenAPI annotation) | Budget < 60% |
+
+---
+
+## Workflow
+
+### Phase 1 — Contract Definition
+1. Define TypeScript interfaces for Request + Response
+2. Specify HTTP method, route, status codes
+3. Document error cases
+
+**Decision:**
+```
+IF contract is clear → go to Phase 2
+ELSE → EXIT: BLOCKED — define contract first
+```
+
+### Phase 2 — Implementation
+1. Build route handler strictly matching contract
+2. Add input validation (zod/yup/class-validator)
+3. Handle all error cases with correct HTTP status
+
+### Phase 3 — Verification
+1. Read implemented code vs defined contract
+2. Verify: method, route, response shape, error codes match
+
+**Decision:**
+```
+IF contract and implementation match → EXIT: SUCCESS
+ELSE → fix gaps, EXIT: PARTIAL
+```
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Contract defined, implementation matches | Report SUCCESS |
+| MEDIUM | Contract inferred from context | Note assumption |
+| LOW | No contract, guessing from usage | EXIT: BLOCKED |
+
+---
+
+## Evidence Format
+```
+[SEVERITY] src/routes/[resource].ts:LINE
+Issue:      [mismatch between contract and implementation]
+Confidence: HIGH
+Fix:        [specific change needed]
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{ "from": "user", "required_fields": ["resource_name", "request_shape", "response_shape"] }
+```
+### Produces
+```json
+{ "to": "qk-validation-gate", "output_fields": ["route_file", "types_file", "contract_doc", "exit_code"] }
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Contract defined, implemented, verified | Implementation matches contract |
+| PARTIAL | Implemented but missing error cases or docs | Core logic done, edge cases missing |
+| BLOCKED | No contract defined — cannot code | Missing payload/schema |
+| FAILED | Implementation breaks existing contract | Backward incompatibility |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Broken contract on public API | Renamed `userId` to `id` in response |
+| HIGH | Missing input validation | SQL Injection or crash on null input |
+| MEDIUM | Returning 500 for validation errors | Not using 400/422 |
+| LOW | Missing JSDoc | Undocumented route |
+
+---
+
+## Retry Policy
+```
+Contract verification fails
+  └─ Implementation does not match contract
+       ├─ Fix route handler to match contract
+       └─ Do NOT retry more than 1 time
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: No contract defined
+Missing:
+  - Request payload structure
+  - Response payload structure
+Questions:
+  1. Payload gửi lên (Request) có những field gì?
+  2. Payload trả về (Response) có cấu trúc thế nào?
+Recommended Assumptions:
+  - Default JSON response with `{ data, message }` wrapper
+```
+
+---
+

package/.agents/skills/qk-bug-resolution/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: qk-bug-resolution
+category: maintenance
+version: 7.5.0
+description: "Sửa lỗi (bugs) bằng chu trình khép kín: Quan sát → Giả thuyết → Bằng chứng → Sửa."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: medium
+risk: medium
+side_effects: edit_files
+produces: [code, report]
+consumes: [stack-trace, error-message, user-description, context-graph]
+
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 150
+  max_shell_commands: 2
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-bug-resolution — Diagnose & Repair
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
+
+---
+
+## Preconditions
+- [ ] A specific symptom is provided (error message, wrong behavior, crash)
+- [ ] The affected file or feature area is identifiable
+- [ ] Reproduction steps or stack trace provided
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần thêm thông tin: [error message / stack trace / bước tái hiện lỗi]"
+```
+
+---
+
+## Scope
+- ✅ Diagnose existing defects with concrete evidence
+- ✅ Apply minimal targeted patches directly to source files
+- ✅ Verify fix with evidence (static or runtime)
+
+## Non-Goals
+- ❌ Refactor code outside the buggy area
+- ❌ Create Node.js/Python/shell scripts to apply patches — edit source files directly
+- ❌ Read entire files > 150 lines — use `grep_search` or targeted `view_file[StartLine:EndLine]`
+- ❌ Run shell commands > 2 times per cycle
+- ❌ Guess root cause without concrete evidence
+- ❌ Mark as done without verifying the fix
+- ❌ Proceed with MEDIUM confidence — only HIGH confidence is acceptable for fix
+- ❌ Use `?.` or `!` to silence errors instead of fixing root cause
+
+---
+
+## Priority Order
+
+| Priority | Check | Skip Threshold |
+|----------|-------|----------------|
+| P1 | Identify exact file:line of failure | Never |
+| P2 | Trace data flow to root cause | Budget < 30% → EXIT: BLOCKED |
+| P3 | Check adjacent code for similar bugs | Budget < 50% |
+| P4 | Suggest regression test | Budget < 70% |
+
+---
+
+## Workflow
+
+### Phase 1 — Triage (Read Only)
+
+**Steps:**
+1. `grep_search` — search for error message, function name, or symptom keyword
+2. `view_file[StartLine:EndLine]` — read ONLY the relevant section (≤ 150 lines)
+3. Identify the exact file and approximate line of failure
+
+**Exit When:**
+- Exact file:line identified → go to Phase 2
+- `max_files_read` (3) reached without exact identification → EXIT: BLOCKED
+
+**Decision:**
+```
+IF stack trace provided
+  → Parse top frame inside project code → go to Phase 2
+
+ELSE IF error message provided
+  → grep_search for error string → go to Phase 2
+
+ELSE
+  → EXIT: BLOCKED — ask for reproduction steps
+```
+
+**On Blocked:**
+```
+EXIT: BLOCKED
+Missing: Reproduction steps or error output
+Questions:
+  1. Lỗi xảy ra ở bước nào? (URL / action / input)
+  2. Error message hoặc stack trace cụ thể là gì?
+Recommended Assumptions: none — cannot proceed without this
+```
+
+---
+
+### Phase 2 — Root Cause Analysis
+
+**Steps:**
+1. Read the identified file section (`view_file[StartLine:EndLine]`, ≤ 150 lines)
+2. Trace: What condition triggers the failure?
+3. Check context graph for blast radius assessment
+4. Assign confidence level
+
+**Common Root Cause Categories:**
+- Logic error (wrong condition, wrong operator)
+- Null / undefined / missing data
+- Async timing or race condition
+- Type mismatch or stale state
+- API contract change
+
+**Decision:**
+```
+IF root cause found with direct evidence (file:line + stack trace confirms)
+  → Confidence: HIGH → go to Phase 3
+
+ELSE IF root cause still unclear after reading identified file
+  → Read 1 more file (budget check)
+  → Still unclear → EXIT: BLOCKED
+
+ELSE IF root cause inferred from pattern (no direct evidence)
+  → EXIT: BLOCKED — cannot fix without concrete evidence
+```
+
+---
+
+### Phase 3 — Apply Fix (Direct Edit Only)
+
+**Steps:**
+1. Apply fix using `replace_file_content` or `multi_replace_file_content`
+   - **NEVER** create a helper script to do the patching
+   - Keep the change minimal — smallest diff that resolves the issue
+2. Re-read the fixed section to confirm correctness (static verification)
+3. Run shell command ONLY if runtime verification is strictly required (counts toward max 2)
+
+**Exit When:**
+- Fix applied and verified statically → EXIT: SUCCESS
+- Fix applied but runtime verification needed and command budget exhausted → EXIT: FAILED — cannot verify
+
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct evidence — exact file:line + stack trace confirms it | Proceed with fix |
+| MEDIUM | Inferred from code patterns, similar bugs nearby | EXIT: BLOCKED — collect more evidence |
+| LOW | Assumption without code evidence | STOP — ask user before applying fix |
+
+---
+
+## Severity
+
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Data loss / security / app crash | Hardcoded secret, unhandled null crash on login |
+| HIGH | Core feature broken, blocking users | API returns 500, form submission fails |
+| MEDIUM | Degraded UX, workaround exists | Wrong label, minor calculation off |
+| LOW | Cosmetic, non-blocking | Console.log left in code |
+
+---
+
+## Evidence Format
+
+```
+[SEVERITY] path/to/file.ts:LINE
+Reason:     [why this causes the bug]
+Impact:     [which modules/users are affected]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [what was changed]
+```
+
+**Example:**
+```
+[HIGH] src/services/auth.service.ts:87
+Reason:     Missing null check on `user.profile` — crashes when profile is not yet loaded
+Impact:     Affects all login flows; 100% of users hitting this path
+Confidence: HIGH
+Fix:        Added `user.profile?.email ?? ''` guard
+```
+
+---
+
+## Retry Policy
+
+```
+Fix applied
+  └─ Static verification (re-read fixed section)
+       ├─ PASS → EXIT: SUCCESS
+       └─ Issue detected → attempt 1 correction
+            └─ Re-verify
+                 ├─ PASS → EXIT: SUCCESS
+                 └─ FAIL → EXIT: FAILED + report both attempts
+                      └─ Do NOT attempt 3rd fix — ESCALATE to user
+```
+
+---
+
+## Escalation Rules
+
+```
+BLOCKED: [Specific reason]
+Missing:
+  - [Stack trace / error message / reproduction steps]
+Questions:
+  1. Lỗi xuất hiện khi nào? (action/URL/input cụ thể)
+  2. Lỗi có tái hiện được không?
+Recommended Assumptions (if proceeding without full info):
+  - [Safe assumption based on available context]
+```
+
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["symptom_description", "context_graph"],
+  "optional_fields": ["stack_trace", "error_message", "affected_file"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["changed_files", "root_cause", "impact", "severity", "confidence", "exit_code"]
+}
+```
+
+---
+
+## Output Format
+
+```
+🐛 Bug Report
+─────────────────────────────────────────────────
+Symptom:     [What broke + how to reproduce]
+Root cause:  [file:line — exact reason]
+Severity:    [CRITICAL | HIGH | MEDIUM | LOW]
+Confidence:  [HIGH | MEDIUM | LOW]
+Impact:      [Which modules/users affected]
+
+🔧 Fix Applied
+─────────────────────────────────────────────────
+File:        [path/to/file.ts]
+Change:      [What changed and why it's minimal]
+
+✅ Verification
+─────────────────────────────────────────────────
+Static:      [Re-read section — looks correct]
+Runtime:     [PASS | SKIPPED — reason]
+
+Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Bug fixed and verified | Fix applied + static/runtime check passed |
+| PARTIAL | Fix applied, verification inconclusive | Budget exhausted or environment inaccessible |
+| BLOCKED | Cannot diagnose without more info | Missing stack trace / reproduction steps |
+| FAILED | Fix attempted, issue persists after 2 retries OR budget exhausted without verification | Complex race condition or architectural issue |
+
+---
+
+Diagnose and fix a specific bug with minimal, targeted changes while preserving all existing behavior.
+This skill is triggered when a user reports a specific defect with a stack trace, error message, or reproduction steps. It requires concrete evidence before any code modification.
+- Symptom description (error message, wrong behavior, crash)
+- Stack trace or reproduction steps
+- Affected file or feature area (if known)
+- Context graph (for blast radius assessment)
+1. **Observe:** Read error output, stack trace, and affected code section
+2. **Hypothesize:** Identify potential root causes based on evidence
+3. **Verify:** Confirm root cause with direct file:line evidence
+4. **Fix:** Apply minimal patch using direct edit only
+5. **Verify:** Re-read fixed code and confirm correctness
+- MUST have exact file:line before proceeding to fix
+- MUST NOT guess root cause without direct evidence
+- MUST keep changes minimal — smallest diff that resolves the issue
+- MUST NOT exceed token_budget (max 3 files, 150 lines each, 2 shell commands)
+- MUST verify fix before marking done
+- Zero-Trust: No fix without HIGH confidence (direct evidence)
+- Minimal Change: Fix only the bug, no refactoring
+- Backward Compat: Preserve all existing public API behavior
+- Evidence First: Every finding must use Evidence Format with file:line
+---

package/.agents/skills/qk-context-loader/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: qk-context-loader
+category: utilities
+version: 7.5.0
+description: "Tải context và vẽ dependency graph chính xác trước khi code — ngăn hallucination kiến trúc."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: low
+latency: fast
+risk: low
+side_effects: read_only
+produces: [context-graph]
+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-context-loader — Dependency Graph Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] Entry point file or module name is specified
+- [ ] Repository is accessible
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng chỉ định entry point (file hoặc module cần map)."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Trace imports/exports from entry point
+- ✅ Build topological dependency graph (max depth 3)
+- ✅ Identify risk level per module
+
+## Non-Goals
+- ❌ Modify any code
+- ❌ Load `node_modules` or vendor directories
+- ❌ Guess file names — only follow explicit imports
+- ❌ Load entire repo (max 5 files)
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | Trace direct imports of entry point | Never |
+| P2 | Trace 2nd-level dependencies | Budget < 40% |
+| P3 | Identify shared/risky modules | Budget < 60% |
+| P4 | Annotate with risk levels | Budget < 70% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Entry Point Analysis
+
+**Steps:**
+1. `grep_search` — search for import/export statements in entry file
+2. `view_file[StartLine:EndLine]` — read import block only (first ~30 lines)
+3. List direct dependencies
+
+**Decision:**
+```
+IF entry file found and imports readable
+  → go to Phase 2
+
+ELSE IF entry file not found
+  → EXIT: BLOCKED — ask for correct path
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Graph Traversal (Max Depth 3)
+
+**Steps:**
+1. For each direct dependency → `grep_search` for its imports
+2. Build adjacency list: `{ file → [imports] }`
+3. Stop at depth 3 OR max_files_read reached
+
+**Decision:**
+```
+IF depth 3 reached OR max_files_read (5) hit
+  → EXIT: PARTIAL — note graph is truncated at depth N
+
+IF circular dependency detected
+  → Flag as [HIGH RISK] in output
+  → Continue building rest of graph
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Risk Assessment & Output
+
+**Steps:**
+1. Identify: shared modules (imported by 3+ files) = HIGH risk to change
+2. Identify: entry points with many dependents = CRITICAL to change carefully
+3. Generate graph in standard JSON + Markdown format
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format (Mandatory Schema)
+
+```json
+{
+  "entry": "src/modules/auth/auth.service.ts",
+  "depth_reached": 3,
+  "truncated": false,
+  "nodes": [
+    {
+      "file": "src/modules/auth/auth.service.ts",
+      "imports": ["src/common/jwt.util.ts", "src/users/users.repository.ts"],
+      "exports": ["AuthService"],
+      "risk_level": "high",
+      "imported_by_count": 4
+    }
+  ],
+  "risks": [
+    {
+      "file": "src/common/jwt.util.ts",
+      "reason": "Imported by 6 modules — changes here have wide blast radius",
+      "risk_level": "critical"
+    }
+  ]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[RISK] path/to/file.ts
+Reason:     [why this file is risky to change]
+Imported by: [N files]
+Exports:    [key exports]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["entry_point"],
+  "optional_fields": ["max_depth", "exclude_patterns"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-feature-delivery | qk-bug-resolution | qk-data-lifecycle | qk-api-lifecycle",
+  "output_fields": ["dependency_graph_json", "risk_summary", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Full graph built within depth limit | All imports traced |
+| PARTIAL | Graph truncated at token/depth limit | Note where it was cut |
+| BLOCKED | Entry point not found or inaccessible | Ask for correct path |
+| FAILED | Cannot determine architecture (circular imports, obfuscated code) | Report and escalate |
+
+---
+