ai-developer-skill-os 7.0.2 → 7.5.1

package/.agents/docs/SPEC.md

@@ -0,0 +1,87 @@
+# AI Developer Skill OS - Specification (v7.5)
+
+This document defines the strict contract and schema for all `SKILL.md` files in the AI Developer Skill OS. Every active skill MUST comply with this specification. The frontmatter is frozen to ensure cross-platform compatibility and deterministic agent behavior.
+
+## 1. Frontmatter Contract (YAML)
+
+Every `SKILL.md` must begin with this exact YAML structure. Do not add, remove, or rename fields.
+
+```yaml
+---
+name: qk-[skill-name]
+category: [core|frontend|backend|fullstack|security|qa|maintenance|devops|utilities]
+version: X.Y.Z
+description: "[One sentence — what this skill 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]
+---
+```
+
+### Field Definitions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | YES | Skill identifier, must start with `qk-` |
+| `category` | enum | YES | Primary domain: `core`, `frontend`, `backend`, `fullstack`, `security`, `qa`, `maintenance`, `devops`, `utilities` |
+| `version` | semver | YES | Semantic version of this skill |
+| `description` | string | YES | One-sentence summary of the skill's purpose |
+| `platforms` | array | YES | Supported AI platforms. Valid values: `antigravity`, `claude-code`, `cursor`, `windsurf`, `kilo-code` |
+| `execution_mode` | string | YES | Must be `deterministic` for all v7.5 skills |
+| `cost` | enum | YES | Token/compute cost: `low`, `medium`, `high` |
+| `latency` | enum | YES | Expected execution speed: `fast`, `medium`, `slow` |
+| `risk` | enum | YES | Risk level of side effects: `low`, `medium`, `high` |
+| `side_effects` | enum | YES | What the skill modifies: `edit_files`, `run_commands`, `read_only`, `none` |
+| `produces` | array | YES | Output artifacts: `report`, `code`, `schema`, `plan`, `tokens` |
+| `consumes` | array | YES | Required inputs: `context-graph`, `design-md`, `stack-trace`, `json-payload`, `none` |
+| `token_budget.max_files_read` | int | YES | Maximum files to read before stopping |
+| `token_budget.max_lines_per_read` | int | YES | Maximum lines per file read operation |
+| `token_budget.max_shell_commands` | int | YES | Maximum shell commands allowed |
+| `token_budget.stop_early` | bool | YES | Whether to stop when confidence threshold is reached |
+| `exit_codes` | array | YES | Valid exit codes for this skill |
+
+## 2. Skill Body Structure (Markdown)
+
+The body of the `SKILL.md` file MUST contain the following sections in order:
+
+1. **Header:** Skill title and language rule
+2. **Preconditions:** Checklist of required inputs/state before execution
+3. **Scope:** What the skill explicitly does (✅) and does not do (❌)
+4. **Priority Order:** P1–P4 checks with skip thresholds for token budget management
+5. **Workflow:** Phased execution steps with explicit decision trees and exit conditions
+6. **Confidence Model:** HIGH/MEDIUM/LOW confidence levels with actions
+7. **Severity:** CRITICAL/HIGH/MEDIUM/LOW severity definitions with examples
+8. **Evidence Format:** Mandatory template for all findings
+9. **Retry Policy:** Retry logic with maximum attempt limits
+10. **Escalation Rules:** Structured BLOCKED response format
+11. **Handoff Contract:** JSON schema for `Consumes` and `Produces`
+12. **Output Format:** Mandatory output template
+13. **Exit Codes:** Table mapping codes to meanings
+
+## 3. Naming Conventions
+
+- Skill files: `skills/qk-[skill-name]/SKILL.md`
+- Registry entry: `qk-[skill-name]`
+- All code, identifiers, and file names: English only
+- Explanations and reports: Vietnamese (match user language)
+
+## 4. Compliance Enforcement
+
+- All skills MUST pass `npm run lint` (which validates frontmatter against this spec)
+- The `## Compliance` table at the bottom of each `SKILL.md` is deprecated and MUST be removed
+- CI pipeline enforces schema compliance automatically

package/.agents/docs/adr/0001-intent-based-architecture.md

@@ -0,0 +1,19 @@
+# 1. Intent-Based Architecture
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+As the framework grew from 5 to 20+ skills, managing individual tool permissions and specific verification overrides within each `SKILL.md` became a maintenance nightmare (violating DRY). Agents were also suffering from "context bloat" because they had to read sprawling, repetitive rules across different skills.
+
+## Decision
+We transitioned from a "Rule-Based" architecture to an "Intent-Based" architecture. 
+- Skills no longer define their own verification exceptions or tool usage logic. 
+- Instead, skills declare their `behavior` and `intent` via frozen YAML metadata. 
+- The OS Kernel (`AGENTS.md`) intercepts these intents and automatically applies the correct global routing and execution constraints based on the categorized behavior.
+
+## Consequences
+- **Positive:** Massive reduction in skill file size. Easier to scale to 100+ skills. Centralized logic in the Kernel. Agent routing is drastically improved due to clear `intent` mapping.
+- **Negative:** Less granular control over unique outliers, but this enforces better standardization.

package/.agents/docs/adr/0002-kernel-freeze.md

@@ -0,0 +1,21 @@
+# 2. Kernel Freeze
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+The Global Policy file (`AGENTS.md`), which acts as the OS Kernel, was continuously expanding. Policies like Language, Decision, Engineering, Output, Tool Efficiency, Context Budget, and Escapation were all piled into a single document, threatening to balloon past 1,000 lines. A bloated kernel leads to Agent Hallucinations (due to context window pressure) and conflicting priorities.
+
+## Decision
+We officially "Freeze" the Kernel (`AGENTS.md`) at v4.0.0. The file is strictly rewritten to under 100 lines using absolute Rules (MUST/MUST NOT) and Guidelines (Prefer/Avoid). 
+Moving forward, no new policies will be added to the Kernel. All future expansions must occur at the higher layers:
+- New Capabilities
+- New Skills
+- New Knowledge documents
+- New Templates
+
+## Consequences
+- **Positive:** The baseline ruleset is locked, highly token-efficient, and easily digestible by any LLM. The framework achieves enterprise stability.
+- **Negative:** Feature requests that require global policy shifts will be rejected by default unless they fundamentally rewrite the OS paradigm.

package/.agents/docs/adr/0003-risk-based-verification.md

@@ -0,0 +1,20 @@
+# 3. Risk-based Verification
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+Previously, Verification Levels were hardcoded into the Skill Classification (e.g., Development skills automatically forced Level 2 Verification, meaning test suites were run regardless of the actual change). This caused conflicting behavior. For example, fixing a typo in a comment using the `qk-bug-resolution` skill would still trigger a test run, wasting time and resources. 
+
+## Decision
+We completely decoupled Verification Levels from Skill Classifications. 
+Skills now only define their "Preferred Evidence Strategy". The actual depth of verification is determined strictly by the **Risk-based Verification Policy** in the Kernel (`AGENTS.md`).
+- Level 0 (Low Risk): Comments, typos (Static Analysis only).
+- Level 2 (Medium Risk): Logic changes (Targeted tests).
+- Level 3 (High Risk): Auth, DB (Full validation).
+
+## Consequences
+- **Positive:** Agents no longer blindly run tests for trivial changes. Verification scales with the danger of the code being modified, vastly improving speed and token efficiency.
+- **Negative:** Agents must use logic to evaluate the "Risk" of their own changes before deciding whether to run a test.

package/.agents/docs/adr/0004-progressive-evidence.md

@@ -0,0 +1,19 @@
+# 4. Progressive Evidence Collection
+
+Date: 2026-07-02
+
+## Status
+Accepted
+
+## Context
+AI Agents frequently fall into "hallucination loops" or "over-exploration loops", running commands like `ls`, `tree`, or reading entire project directories just to find one file. This burns through context windows rapidly and leads to poor reasoning.
+
+## Decision
+We implemented a strict **Progressive Evidence Collection** pipeline inside the OS Kernel (`AGENTS.md`):
+- **Context Budget:** Agents must start by reading 1 file, then 3 files, then a directory. They must never read the whole project unless explicitly required.
+- **Sufficient Confidence:** Agents must stop collecting evidence the moment they reach an 80% confidence threshold to proceed. 
+- **Evidence Priority:** User input > Existing context > Source code > Types > Logs > Runtime > External knowledge.
+
+## Consequences
+- **Positive:** Drastically reduced unnecessary `run_command` usage. Agents act much more like senior developers who pinpoint issues via stack traces instead of blindly searching the filesystem.
+- **Negative:** Requires rigorous enforcement in the Kernel to prevent agents from falling back to old habits.

package/.agents/docs/skill-classification.md

@@ -0,0 +1,25 @@
+# Skill Classifications (Intent-Based Policies)
+
+Skills are classified into behavioral groups that define their **Primary Objective** and **Preferred Evidence Strategy**.
+
+*Note: Actual verification depth is NOT determined by the skill itself, but must strictly follow the **Risk-based Verification Policy** defined in `AGENTS.md`.*
+
+## 1. Static Analysis Skills
+*e.g., Code Review, Project Health, Architecture, Documentation*
+- **Primary Goal:** Audit, analyze, or document without altering system behavior.
+- **Preferred Behavior:** Prefer static analysis (`read_file`, `grep_search`). Do not execute code or run test suites unless explicitly requested to validate the audit.
+
+## 2. Development Skills
+*e.g., Feature Delivery, Refactor, Bug Resolution*
+- **Primary Goal:** Modify existing behavior or implement new features safely.
+- **Preferred Behavior:** Apply localized changes. Gather targeted evidence. Avoid speculative full-project validation; verify only what is affected.
+
+## 3. Validation Skills
+*e.g., Validation Gate, CI Check, Release*
+- **Primary Goal:** Ensure code quality, security, and build stability before release.
+- **Preferred Behavior:** Exhaustive scanning. Running automated checks and full builds is encouraged to satisfy the validation gate.
+
+## 4. Maintenance Skills
+*e.g., System Evolution, Dependency Update*
+- **Primary Goal:** Upgrade system foundations safely with a rollback strategy.
+- **Preferred Behavior:** Inspect changelogs and compatibility carefully before updating. Run full system verifications post-update to ensure stability.

package/.agents/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/.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"]
+}
+```
+
+---
+
+