ai-developer-skill-os 7.0.2 → 7.5.0

package/.agents/skills/qk-ai-builder/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: qk-ai-builder
+category: core
+version: 7.5.0
+description: "Thiết kế AI logic, Prompts, RAG pipelines với bảo mật chống Injection — structured output bắt buộc."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: high
+side_effects: edit_files
+produces: [code, schema]
+consumes: [user-description]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 100
+  max_shell_commands: 0
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-ai-builder — AI Integration Designer
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] AI task is defined: what input → what output
+- [ ] LLM provider is specified (OpenAI, Anthropic, Gemini, local)
+
+---
+
+## Scope
+- ✅ Design strict, deterministic system prompts
+- ✅ Sanitize user inputs before LLM (Anti-Injection)
+- ✅ Validate LLM output before using in business logic
+- ✅ Structured output (JSON schema) over raw text
+
+## Non-Goals
+- ❌ Open-ended chat prompts without system boundaries
+- ❌ Trust LLM output for critical logic without validation
+- ❌ Use raw user input directly in prompts
+
+---
+
+## System Prompt Template (Required Structure)
+
+```
+[ROLE]
+You are a [specific role]. You [specific expertise].
+
+[TASK]
+Your task is to [exact task description].
+
+[CONSTRAINTS]
+- Always [constraint 1]
+- Never [constraint 2]
+- If [edge case] → [specific action]
+
+[OUTPUT FORMAT]
+Return ONLY valid JSON matching this schema:
+{
+  "field1": "string",
+  "field2": number,
+  "confidence": "high|medium|low"
+}
+
+[EXAMPLES]
+Input: [example]
+Output: {"field1": "...", "field2": 0, "confidence": "high"}
+```
+
+---
+
+## Anti-Injection Checklist
+```
+[ ] User input is wrapped in XML tags: <user_input>{input}</user_input>
+[ ] System instructions are separate from user content
+[ ] Input is validated/sanitized before injection (no raw HTML/JS)
+[ ] Max token limit set for user input
+[ ] Output is parsed as JSON (not eval'd)
+[ ] Confidence field in output triggers human review if "low"
+```
+
+---
+
+## RAG Pipeline Pattern
+```
+User Query
+  └─ Sanitize + embed query
+       └─ Vector search (top-K = 5)
+            └─ Re-rank by relevance
+                 └─ Build prompt: [System] + [Retrieved Context] + [User Query]
+                      └─ LLM call
+                           └─ Validate output schema
+                                └─ Return to user
+```
+
+---
+
+
+---
+
+## Priority Order
+
+
+---
+
+## Workflow
+
+
+---
+
+## Output Format
+
+
+---
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Prompt designed with all required sections, anti-injection applied | All checks passed |
+| PARTIAL | Prompt works but missing examples or output validation | Medium confidence result |
+| BLOCKED | Task or output format not defined clearly enough | Cannot design without clear spec |
+| FAILED | Prompt design has security vulnerability (direct injection risk) | Security gate failure |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Task clearly defined, output format specified, examples provided | Build directly |
+| MEDIUM | Task clear but output format ambiguous | Note assumption, add validation layer |
+| LOW | Task too vague ("make an AI assistant") | EXIT: BLOCKED — define specific task |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Prompt injection attack possible | User input directly in system prompt |
+| HIGH | LLM output used without validation in business logic | JSON parse without schema check |
+| MEDIUM | Missing examples leads to inconsistent output | No few-shot examples in prompt |
+| LOW | Output format not explicitly stated | Returns text instead of JSON |
+
+---
+
+## Evidence Format
+```
+[SEVERITY] src/prompts/[name].ts:LINE
+Issue:      [specific vulnerability or gap]
+Confidence: HIGH
+Fix:        [specific change]
+```
+
+**Example:**
+```
+[CRITICAL] src/prompts/chat.ts:34
+Issue:      User input `${userMessage}` injected directly in system prompt — injection risk
+Confidence: HIGH
+Fix:        Wrap in <user_input>{userMessage}</user_input> XML tags
+```
+
+---
+
+## Retry Policy
+```
+LLM output validation fails
+  └─ Retry with stronger output format instruction (add explicit JSON schema)
+       ├─ PASS on retry → EXIT: SUCCESS, note "required stronger schema enforcement"
+       └─ FAIL on retry → EXIT: PARTIAL — add human review gate
+            └─ Do NOT auto-retry more than 1 time — risk of infinite loop
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: AI task not specific enough to design prompt
+Missing:
+  - Specific task description (what input → what output)
+  - Output format specification (JSON schema or text structure)
+Questions:
+  1. Input cụ thể là gì? (user text, document, structured data)
+  2. Output cần trả về dạng gì? (JSON với field gì / plain text)
+Recommended Assumptions (if proceeding):
+  - Structured JSON output with confidence field
+  - Deny-by-default: reject off-topic requests in system prompt
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["task_description", "input_type", "output_format"],
+  "optional_fields": ["examples", "llm_provider", "max_tokens"]
+}
+```
+### Produces
+```json
+{
+  "to": "user or qk-validation-gate",
+  "output_fields": ["system_prompt", "output_schema", "anti_injection_checklist", "exit_code"]
+}
+```
+
+---
+
+

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
+---