ai-developer-skill-os 7.0.2 → 7.5.0

package/skills/qk-access-policy/SKILL.md

@@ -1,39 +1,179 @@
----
-name: qk-access-policy
-category: security
-version: 7.0.0
-description: "Quản lý RBAC, ABAC và thiết lập ranh giới bảo mật nghiêm ngặt."
----
-
-# qk-access-policy
-
-## Scope
-- Role-Based and Attribute-Based Access Control configuration (Plan & Execute)
-
-## Verbs
-- `[CONFIGURE]`: Setup explicit role hierarchies and access lists.
-
-## Constraints
-```yaml
-must:
-  - "Explicitly define roles and permissions in a Matrix"
-  - "Validate user identity before granting role-based access"
-must_not:
-  - "Grant wildcard (*) permissions unless absolutely mandated by system architecture"
-  - "Mix authentication logic with authorization logic"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Attribute-Based Access Control (ABAC) for complex business logic"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Access Matrix is contradictory or undefined"
-```
-
-## Output
-- RBAC/ABAC configurations and middleware.
+---
+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/skills/qk-ai-builder/SKILL.md

@@ -1,40 +1,215 @@
----
-name: qk-ai-builder
-category: core
-version: 7.0.0
-description: "Thiết kế AI Logic, Prompts, RAG pipelines với bảo mật chống Injection."
----
-
-# qk-ai-builder
-
-## Scope
-- AI integration, Prompt Engineering, and RAG architectures (Plan & Execute)
-
-## Verbs
-- `[PROMPT]`: Design strict and deterministic prompts.
-
-## Constraints
-```yaml
-must:
-  - "Include explicit constraints and negative constraints (must_not) in all prompts"
-  - "Sanitize user inputs before feeding them to LLMs (Anti-Injection)"
-must_not:
-  - "Create open-ended 'chat' prompts without strict system boundaries"
-  - "Trust LLM output for critical logic without a validation step"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Few-shot prompting with clear examples"
-  - "Structured output (JSON) over raw text for API interactions"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Prompt architecture lacks validation or security boundaries"
-```
-
-## Output
-- Prompts, RAG pipelines, and AI integration logic.
+---
+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/skills/qk-api-lifecycle/SKILL.md

@@ -1,46 +1,176 @@
----
-name: qk-api-lifecycle
-category: fullstack
-version: 7.0.0
-description: "Thiết kế, triển khai, và tích hợp các API endpoints với kỷ luật Zero-Trust."
----
-
-# qk-api-lifecycle
-
-## Scope
-- API design, endpoints, contracts, and lifecycle management (Plan & Execute)
-- Zero-Trust validation of API schemas.
-
-## Verbs
-- `[DEFINE]`: Create strict API contracts before implementation.
-- `[IMPLEMENT]`: Build endpoints strictly adhering to the defined contract.
-
-## Constraints
-```yaml
-must:
-  - "Define clear request/response contracts (OpenAPI/Swagger) BEFORE coding"
-  - "Ensure backward compatibility on existing endpoints"
-  - "Validate all incoming data against the strict schema"
-must_not:
-  - "Introduce breaking changes without versioning"
-  - "Bypass authentication or authorization checks"
-  - "Hallucinate or guess external API shapes without evidence"
-```
-
-## Policies
-```yaml
-prefer:
-  - "RESTful resource naming conventions"
-  - "Meaningful HTTP status codes"
-  - "Strict type-checking and validation over loose parsing"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Required API contracts or models are missing"
-  - "Major breaking change detected on production APIs"
-```
-
-## Output
-- API endpoints, controllers, and strict documentation.
+---
+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
+```
+
+---
+