ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/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/.qk-ai-skill-os/skills/_archive_old_skills/qk-accessibility-audit/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: qk-accessibility-audit
+description: >-
+  Kiểm tra và sửa lỗi khả năng tiếp cận (a11y/WCAG). Đảm bảo hỗ trợ phím, screen reader và semantic HTML.
+version: 1.0.0
+category: frontend
+tags: [accessibility, a11y, aria, wcag, screen-reader, keyboard]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Accessibility (A11y) Audit
+
+> **Language rule:**
+> Use English for: code, identifiers, file names, architecture terms, technical decisions.
+> Use the user's language for: explanations, questions, summaries, and feedback.
+> The user may write in any language — detect and match it automatically.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User asks to "make this accessible", "fix a11y", or "audit accessibility"
+- Building complex interactive components (modals, dropdowns, tabs, sliders)
+- Preparing an app for production or public release
+- Project audit flags missing semantic HTML or ARIA issues
+
+---
+
+## Scope
+
+- ✅ **Keyboard Navigation:** Ensure all interactive elements are reachable via `Tab`, and operable via `Enter`/`Space`/Arrows. Focus management (trapping focus in modals).
+- ✅ **Screen Reader Support:** Add proper `aria-` attributes, `alt` text, and visually hidden text (`sr-only`).
+- ✅ **Semantic HTML:** Replace `div` soups with `<nav>`, `<main>`, `<article>`, `<button>`, etc.
+- ✅ **Color Contrast:** Verify text vs. background contrast meets WCAG AA (4.5:1 for normal text).
+- ✅ **Form Labels:** Ensure all inputs have associated `<label>`s or `aria-label`s.
+
+---
+
+## Non-goals
+
+- ❌ Do NOT completely redesign the UI visually (unless fixing a severe contrast issue, and even then, ask first).
+- ❌ Do NOT overuse ARIA. The first rule of ARIA is: "No ARIA is better than bad ARIA." Use semantic HTML first.
+
+---
+
+## Workflow
+
+### Phase 1 — Semantic HTML Check
+
+Scan the component for basic HTML semantics:
+- Are buttons actually `<button>` elements (not `<div onClick>`)?
+- Are links actually `<a>` elements with `href`s?
+- Do images have meaningful `alt` text (or `alt=""` if decorative)?
+- Are headings (`h1`-`h6`) in a logical, unbroken hierarchy?
+
+### Phase 2 — Keyboard & Focus Management
+
+- Can the user tab through the component logically?
+- Does every interactive element have a visible focus state (`:focus-visible`)?
+- For Modals/Dialogs: Is focus trapped inside when open? Is focus restored when closed?
+- For custom widgets (Tabs/Dropdowns): Implement correct arrow key navigation per WAI-ARIA authoring practices.
+
+### Phase 3 — Screen Reader (ARIA) Check
+
+- Do custom interactive elements have correct `role`s (e.g., `role="tablist"`)?
+- Is dynamic state communicated? (`aria-expanded`, `aria-selected`, `aria-invalid`, `aria-busy`).
+- Are icon-only buttons properly labeled? (`aria-label` or `<span className="sr-only">Label</span>`).
+- Are dynamic live regions used for important announcements (`aria-live="polite"` or `assertive`)?
+
+### Phase 4 — Contrast & Visuals
+
+- Check text colors against backgrounds.
+- Ensure form fields have visible borders or indicators.
+- Ensure information is not conveyed *only* by color (e.g., a red border for an error must also have error text).
+
+---
+
+## Decision Tree
+
+```
+Is the component a native HTML element (e.g., standard `<button>`)?
+  ├── Yes → Ensure it has accessible text/labels. No ARIA roles needed.
+  └── No  → (e.g., a custom `div` acting as a checkbox)
+              ├── Can it be refactored to use native HTML?
+              │     ├── Yes → Refactor to native HTML `<input type="checkbox">`
+              │     └── No  → Apply `role="checkbox"`, `tabIndex={0}`, `aria-checked`, and keyboard event handlers.
+```
+
+---
+
+## Output Format
+
+```
+♿ Accessibility Audit Report
+─────────────────────────────────────────────────
+Component:  [ComponentName]
+
+Issues Found & Fixed:
+  ✅ Semantic HTML: Replaced `<div onClick>` with `<button>`
+  ✅ Screen Readers: Added `aria-label` to icon-only close button
+  ✅ Keyboard: Added focus trap inside the Modal
+  ✅ Forms: Associated `<label htmlFor="email">` with Input
+
+⚠️ Remaining Warnings (Manual Check Required):
+  - Please verify color contrast of primary button in light mode (needs 4.5:1 ratio).
+
+🔗 Next Steps:
+  Code updated. Recommend testing with a screen reader (VoiceOver/NVDA).
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Semantic HTML preferred over ARIA
+- [ ] Keyboard navigation (Tab + Enter/Space) works correctly
+- [ ] Focus is visible on all interactive elements
+- [ ] Forms have proper labels
+- [ ] Icon-only buttons have accessible names
+

package/.qk-ai-skill-os/skills/_archive_old_skills/qk-agent-orchestrator/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: qk-agent-orchestrator
+description: >-
+  Phân tích yêu cầu, lên kế hoạch thực thi chi tiết và điều phối các tác vụ cho đúng skill. Không tự viết code.
+version: 1.0.0
+category: engineering
+tags: [orchestration, planning, workflow, task-decomposition]
+platforms: [antigravity, claude-code, kilo-code, cursor, windsurf]
+---
+
+# Agent Orchestrator
+
+> **Language rule:**
+> Use English for: code, identifiers, file names, architecture terms, technical decisions.
+> Use the user's language for: explanations, questions, summaries, and feedback.
+> The user may write in any language — detect and match it automatically.
+
+> ⚠️ **CRITICAL CONSTRAINT: This skill MUST NOT write any code.**
+> Its only job is to analyze, plan, and delegate.
+> If the orchestrator starts writing implementation code — it is violating its role.
+> Immediately stop and delegate to the appropriate skill instead.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- User describes a task without knowing where to start
+- User request spans multiple concerns (UI + API + state + tests)
+- Request is ambiguous and needs decomposition before action
+- User says: "help me plan", "what should I do first", "how do I approach this"
+
+---
+
+## Scope
+
+- ✅ Analyze the user's request
+- ✅ Identify which skills are needed
+- ✅ Define the correct execution order
+- ✅ Create a step-by-step plan
+- ✅ Delegate each step to the correct skill
+- ✅ Track overall progress
+
+---
+
+## Non-goals
+
+- ❌ Do NOT write implementation code
+- ❌ Do NOT modify files
+- ❌ Do NOT fix bugs directly (delegate to `bug-fix`)
+- ❌ Do NOT build UI directly (delegate to `ui-builder`)
+- ❌ Do NOT make architectural decisions unilaterally (delegate to `frontend-architecture`)
+
+---
+
+## Workflow
+
+### Phase 1 — Request Analysis
+
+Parse the user's request:
+
+1. **What** is being asked? (feature, fix, refactor, review, deploy?)
+2. **Where** does it belong? (frontend, backend, shared, infrastructure?)
+3. **What is the scope?** (single component, full feature, entire codebase?)
+4. **What is unknown?** List any ambiguities that need clarification.
+
+If critical information is missing → ask before planning.
+
+---
+
+### Phase 2 — Skill Selection
+
+Map the request to skills from the registry:
+
+| Request type | Recommended skill(s) |
+|---|---|
+| "I don't know what's wrong" | `project-audit` → `bug-fix` |
+| "Build a new page" | `frontend-architecture` → `design-system` → `ui-builder` |
+| "Add API call" | `context-manager` → `api-integration` |
+| "App is slow" | `project-audit` → `frontend-performance` |
+| "Upgrade dependencies" | `migration` |
+| "Write tests" | `frontend-testing` |
+
+Always check dependencies from `skills.json` — load dependent skills first.
+
+---
+
+### Phase 3 — Execution Plan
+
+Produce a numbered, ordered plan. Each step maps to one skill.
+
+Format:
+```
+Step 1: [skill-name] — [what it will do]
+Step 2: [skill-name] — [what it will do]
+Step 3: [skill-name] — [what it will do]
+```
+
+Mark dependencies explicitly:
+```
+Step 2 requires Step 1 to complete first.
+```
+
+---
+
+### Phase 4 — Delegation
+
+For each step in the plan:
+1. Announce which skill is being activated
+2. Pass relevant context to that skill
+3. Wait for skill output
+4. Confirm completion before moving to next step
+
+---
+
+### Phase 5 — Progress Tracking
+
+After each skill completes:
+- Mark step as ✅ done
+- Note any output or blockers
+- Adjust remaining plan if needed
+- Report overall progress to user
+
+---
+
+## Decision Tree
+
+```
+Is the request clear enough to plan?
+  ├── No  → Ask 1-3 clarifying questions, then plan
+  └── Yes → Does it span multiple concerns?
+              ├── Yes → Create multi-step plan with skill sequence
+              └── No  → Route directly to single skill
+```
+
+```
+Does a skill dependency exist?
+  ├── Yes → Run dependency skill first
+  └── No  → Run skill directly
+```
+
+---
+
+## Output Format
+
+```
+📋 Plan: [Brief description of what we're doing]
+
+Step 1: `[skill-name]` — [Purpose]
+Step 2: `[skill-name]` — [Purpose]  ← requires Step 1
+Step 3: `[skill-name]` — [Purpose]
+
+⏳ Starting with Step 1...
+```
+
+After each step:
+```
+✅ Step 1 complete: [Brief outcome]
+▶️  Moving to Step 2: `[skill-name]`
+```
+
+---
+
+## Validation Checklist
+
+Before finishing orchestration:
+
+- [ ] All planned steps completed
+- [ ] Each step was handled by the correct skill
+- [ ] No code was written by the orchestrator itself
+- [ ] User has been informed of final outcome
+- [ ] Next recommended actions provided if relevant
+
+---
+
+## Examples
+
+See `examples/` folder.
+