ai-developer-skill-os 7.0.2 → 7.5.0

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

@@ -0,0 +1,238 @@
+---
+name: qk-[skill-name]
+category: [core|frontend|backend|fullstack|security|qa|maintenance|devops|utilities]
+version: 7.5.0
+description: "[One sentence — what it does]"
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+# Orchestrator routing metadata
+cost: [low|medium|high]
+latency: [fast|medium|slow]
+risk: [low|medium|high]
+side_effects: [edit_files|run_commands|read_only|none]
+produces: [report|code|schema|plan|tokens]
+consumes: [context-graph|design-md|stack-trace|json-payload|none]
+
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 150
+  max_shell_commands: 2
+  stop_early: true
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+---
+
+# qk-[skill-name]
+
+> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese (match user language).
+
+---
+
+## Preconditions
+Before executing, verify ALL exist. STOP with `BLOCKED` if any is missing.
+
+- [ ] [Precondition 1 — e.g., "Repository is accessible"]
+- [ ] [Precondition 2 — e.g., "DESIGN.md exists in project root"]
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "[Precondition X] not found. Please provide: [what]"
+```
+
+---
+
+## Scope
+- ✅ [What this skill explicitly DOES]
+- ✅ [What this skill explicitly DOES]
+
+## Non-Goals
+- ❌ [Anti-pattern 1] — because [why]
+- ❌ [Anti-pattern 2]
+- ❌ Never create helper scripts (Node.js/Python/shell) to apply patches — edit files directly
+- ❌ Never read entire files > 150 lines — use targeted reads (StartLine:EndLine)
+
+---
+
+## Priority Order
+When token budget is insufficient, execute checks in this order:
+
+| Priority | Check | Skip Threshold |
+|----------|-------|----------------|
+| P1 | [Most critical — never skip] | Never |
+| P2 | [High priority] | Budget < 30% |
+| P3 | [Medium priority] | Budget < 50% |
+| P4 | [Low priority — always optional] | Budget < 70% |
+
+---
+
+## Workflow
+
+### Phase 1 — [Name: e.g., Triage]
+
+**Steps:**
+1. [Concrete step — specify tool: `grep_search` / `view_file[L1:L50]` / `run_command`]
+2. [Next step]
+
+**Exit When (stop this phase, move to next):**
+- [Condition A — e.g., "Root cause identified"]
+- [Condition B — e.g., "`max_files_read` reached"]
+
+**On Blocked:**
+```
+EXIT: BLOCKED
+Missing: [what specific info is needed]
+Questions:
+  1. [Specific question to user]
+```
+
+---
+
+### Phase 2 — [Name: e.g., Analyze]
+
+**Steps:**
+1. [Step]
+
+**Decision:**
+```
+IF [condition met]
+  → proceed to Phase 3
+ELSE IF [edge case]
+  → EXIT: PARTIAL — note: [what was missed]
+ELSE
+  → ESCALATE
+```
+
+---
+
+### Phase 3 — [Name: e.g., Execute]
+
+**Steps:**
+1. Apply fix using `replace_file_content` or `multi_replace_file_content` — NEVER via scripts
+2. [Verification step]
+
+**Exit When:**
+- Fix applied and verified → EXIT: SUCCESS
+- Fix applied but unverifiable → EXIT: PARTIAL
+
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct evidence (file:line, stack trace, exact match) | Proceed |
+| MEDIUM | Inferred from patterns or similar code | Note assumption, proceed carefully |
+| LOW | Assumption without evidence | STOP — ask user before proceeding |
+
+---
+
+## Severity
+
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Data loss / security breach / app down | Hardcoded secret, SQL injection |
+| HIGH | Core feature broken, blocking users | Null crash, broken API |
+| MEDIUM | Degraded UX, workaround exists | Cyclomatic > 10, missing loading state |
+| LOW | Style/cosmetic, non-blocking | Missing comment, minor inconsistency |
+
+---
+
+## Evidence Format
+
+Every finding MUST use this format:
+```
+[SEVERITY] path/to/file.ts:LINE
+Reason:     [why this is a violation or finding]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [one-line suggestion]
+```
+
+**Example:**
+```
+[HIGH] src/auth.service.ts:132
+Reason:     Function length 64 lines exceeds threshold of 30
+Confidence: HIGH
+Fix:        Extract token validation to `validateToken()`
+```
+
+---
+
+## Retry Policy
+
+```
+Action fails
+  └─ Attempt auto-fix (if fix is deterministic)
+       └─ Re-run verification
+            ├─ PASS → EXIT: SUCCESS
+            └─ FAIL (2nd time) → EXIT: PARTIAL + report
+                 └─ Do NOT retry more than 2 times
+                      └─ 3rd failure → ESCALATE to user
+```
+
+---
+
+## Escalation Rules
+
+When blocked, **never just "STOP"** — return structured response:
+
+```
+BLOCKED: [Reason — specific, not vague]
+Missing:
+  - [Specific artifact or information needed]
+Questions:
+  1. [Specific question]
+  2. [Specific question]
+Recommended Assumptions (if you want me to proceed anyway):
+  - [Safe assumption 1]
+  - [Safe assumption 2]
+```
+
+---
+
+## Handoff Contract
+
+### Consumes (Input from upstream)
+```json
+{
+  "from": "[skill-name or 'user']",
+  "required_fields": ["field1", "field2"],
+  "optional_fields": ["field3"]
+}
+```
+
+### Produces (Output for downstream)
+```json
+{
+  "to": "[skill-name or 'user']",
+  "output_fields": ["changed_files", "summary", "confidence", "exit_code"]
+}
+```
+
+---
+
+## Output Format
+
+```
+[SKILL_NAME] Result
+─────────────────────────────────────────────────
+Status:      [SUCCESS | PARTIAL | BLOCKED | FAILED]
+Confidence:  [HIGH | MEDIUM | LOW]
+
+[Section specific to this skill]
+
+Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning | Orchestrator Action |
+|------|---------|---------------------|
+| SUCCESS | All checks passed, task complete | Continue pipeline |
+| PARTIAL | Task done with degraded quality or skipped P3/P4 checks | Notify user, continue |
+| BLOCKED | Missing precondition or ambiguous requirement | STOP, ask user |
+| FAILED | Task failed after 2 retry attempts | STOP, report error |
+

package/.qk-ai-skill-os/skills/qk-access-policy/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: qk-access-policy
+category: security
+version: 7.5.0
+description: "Quản lý RBAC, ABAC — định nghĩa role matrix trước, implement middleware sau."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: medium
+latency: medium
+risk: high
+side_effects: edit_files
+produces: [code, report]
+consumes: [user-description]
+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-access-policy — Access Control Designer
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] User roles and protected resources are defined
+- [ ] Auth system (JWT, session, OAuth) is identified
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Cần định nghĩa: danh sách roles + resources cần bảo vệ."
+```
+
+---
+
+## Scope
+- ✅ Define explicit Role-Permission Matrix before coding
+- ✅ Implement middleware/guards based strictly on the matrix
+- ✅ Separate auth (who are you?) from authz (what can you do?)
+
+## Non-Goals
+- ❌ Grant wildcard (*) permissions
+- ❌ Mix authentication logic with authorization logic
+- ❌ Hardcode role checks in business logic (use middleware/guards)
+
+---
+
+## Priority Order
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Define Role-Permission Matrix | Never |
+| P2 | Implement deny-by-default middleware | Never |
+| P3 | Add role guards to routes/controllers | Budget < 30% |
+| P4 | Add audit logging for auth failures | Budget < 60% |
+
+---
+
+## Role-Permission Matrix Format (Required)
+
+```
+Resource          | admin | manager | user | guest
+─────────────────────────────────────────────────
+GET /resource     |   ✅   |    ✅    |  ✅  |   ✅
+POST /resource    |   ✅   |    ✅    |  ❌  |   ❌
+DELETE /resource  |   ✅   |    ❌    |  ❌  |   ❌
+```
+
+---
+
+## Workflow
+
+### Phase 1 — Matrix Definition
+1. List all roles and resources from requirements
+2. Create Role-Permission Matrix (table format above)
+3. Identify conflicts or contradictions
+
+**Decision:** `IF matrix has contradiction → EXIT: BLOCKED — resolve ambiguity`
+
+### Phase 2 — Implementation
+1. Create deny-by-default guard/middleware
+2. Apply guards to routes using matrix
+3. Add auth failure logging
+
+### Phase 3 — Verification
+1. Read matrix vs implementation — spot check 3 routes
+
+---
+
+## Evidence Format
+```
+[SEVERITY] src/middleware/auth.ts:LINE
+Rule:       [WILDCARD | MISSING_GUARD | SOC_VIOLATION | HARDCODED_ROLE]
+Reason:     [specific issue]
+Confidence: HIGH
+Fix:        [specific change]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Matrix defined, middleware implemented, deny-by-default applied | Implementation complete |
+| PARTIAL | Implemented but missing audit logging or some routes unguarded | Post-verification minor gaps |
+| BLOCKED | Roles or resources undefined — cannot create matrix | Missing inputs |
+| FAILED | Contradiction in matrix or auth/authz mixed | Architectural violation |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Roles and resources explicitly defined | Build matrix and implement |
+| MEDIUM | Roles inferred from codebase | Build matrix, ask user to verify |
+| LOW | Authentication strategy unknown | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Route unguarded due to missing middleware | Anyone can access DELETE /users |
+| HIGH | Hardcoded roles in business logic | `if (user.role === 'admin')` in service layer |
+| MEDIUM | Wildcard permissions granted | `user` can access `*` |
+| LOW | Audit log missing for auth failure | Unlogged 403 error |
+
+---
+
+## Retry Policy
+```
+Route verification fails
+  └─ Route unguarded
+       ├─ Add missing guard to route
+       └─ Do NOT retry more than 1 time per route
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Roles or resources undefined
+Missing:
+  - List of user roles
+  - List of protected resources
+Questions:
+  1. Hệ thống có những role nào? (ví dụ: admin, user, manager)
+  2. Những API/Route nào cần bảo vệ?
+Recommended Assumptions:
+  - Deny-by-default for all non-public routes
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["roles", "resources"],
+  "optional_fields": ["auth_strategy"]
+}
+```
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["role_matrix", "middleware_files", "guarded_routes", "exit_code"]
+}
+```
+
+---
+

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

@@ -0,0 +1,221 @@
+---
+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
+
+[Placeholder for Priority Order]
+
+
+---
+
+## Workflow
+
+[Placeholder for Workflow]
+
+
+---
+
+## Output Format
+
+[Placeholder for 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"]
+}
+```
+
+---
+
+