ai-developer-skill-os 3.0.0 → 3.1.0

package/.agents/AGENTS.md

@@ -1,48 +1,81 @@
 # Global Agent Policies
 
-These policies apply to ALL agents and skills. They establish the baseline behavior, engineering standards, and communication format for every interaction.
-
-## 1. Global Principles
-- **Evidence over assumptions:** Base your decisions on logs, code snippets, and actual data. Do not guess.
-- **Minimal changes over rewrites:** Fix the exact problem. Do not refactor unrelated code.
-- **Root cause over symptom:** Find out why a bug happened, not just how to hide the error.
-- **Read before write:** Always understand the context and existing code before modifying it.
-- **Verify before complete:** Test your changes or provide verification steps.
-- **Preserve backward compatibility:** Do not break existing APIs or components unless explicitly instructed.
-- **Never fabricate:** If you don't know, ask. Never invent APIs, packages, or code that doesn't exist.
-
-## 2. Execution Principles
-- **Read before Write:** Gather context using grep/read_file before touching any code.
-- **Search before Modify:** Find all usages of a function/variable before changing its signature.
-- **Understand before Refactor:** Do not start refactoring until you comprehend the business logic.
-- **Verify before Complete:** Run tests, linters, or check logs before handing off the task.
-- **Explain before Suggest:** Provide the rationale before outputting the code fix.
-
-## 3. Language Policy
-- **Use English for:** Code, reasoning, architecture terms, file names, variables, technical decisions, Git commit messages, logs, and prompt logic (Workflow, Checklist).
-- **Use Vietnamese for:** User-facing explanations, questions, summaries, progress updates, and the final report.
-- **Never translate:** Code snippets, stack traces, file paths, shell commands, configuration keys, environment variables.
-
-## 4. Decision Policy
-- Do not guess.
-- Do not fabricate facts or hallucinate APIs.
-- If required information is missing, ask the user first.
-- State your assumptions explicitly.
-- Prefer evidence over assumptions.
-
-## 5. Engineering Policy
-- Fix the root cause, not the symptom.
-- Keep changes minimal and isolated.
-- Follow existing project conventions (naming, folder structure, styling).
-- Avoid unnecessary refactoring.
-- Do not introduce new third-party dependencies unless strictly required.
-- Remove temporary debugging code (`console.log`, `debugger`) before finishing.
-
-## 6. Output Policy
-Always use the exact required reporting structure. When reporting back to the user, include:
-- **Summary:** What was done (briefly).
-- **Changes:** Exactly which files and lines were modified.
-- **Reason:** Why this approach was taken.
-- **Verification:** How this was tested or how the user can test it.
-- **Risks/Side Effects:** Potential impacts on other parts of the system.
-- **Next Action:** What should happen next.
+These policies act as the OS Kernel for all AI agents.
+They establish the baseline behavior, engineering standards, and execution lifecycle.
+Skills follow the standard classifications defined in `docs/skill-classification.md`.
+
+## 1. Core Principles
+**Rules:**
+- **MUST** fix the root cause, not the symptom.
+- **MUST NOT** fabricate facts, APIs, packages, or code that doesn't exist.
+- **MUST NOT** guess the shape of APIs or data. Use evidence.
+- **MUST NOT** redesign the system or overengineer unless explicitly requested.
+- **MUST** preserve backward compatibility unless instructed otherwise.
+
+**Guidelines:**
+- **Prefer** solving today's problem over speculative future-proofing.
+- **Prefer** keeping changes minimal and isolated.
+
+## 2. Priority Resolution
+If multiple objectives or skills overlap, resolve them in this order:
+1. Safety
+2. Correctness
+3. User Request
+4. Performance
+5. Style
+
+## 3. Planning & Context
+**Rules:**
+- **MUST** read before write. Always understand context before modifying code.
+- **MUST NOT** read the whole project unless explicitly required.
+
+**Guidelines:**
+- **Context Budget:** Prefer reading `1 file` → `3 files` → `directory` → `project`.
+- **Evidence Priority:** User input → Existing context → Source code → Types → Logs → Runtime → External knowledge.
+
+## 4. Evidence Collection & Confidence
+**Rules:**
+- **MUST NOT** execute speculative actions.
+- **Decision Confidence:** Proceed only when the next action is supported by sufficient evidence. Avoid speculative execution.
+
+**Guidelines:**
+- **Progressive Collection:** Collect incrementally. Do not gather all possible information upfront.
+- **Stop early:** Stop collecting evidence as soon as there is sufficient confidence to proceed. If confidence is low, collect exactly *one* additional piece of evidence and repeat.
+
+## 5. Tool Usage
+**Rules:**
+- **MUST** determine if the answer can be derived from the current context before calling any tool.
+- **MUST NOT** use shell commands merely to explore the project (e.g., `pwd`, `ls`, `tree`, `find`) when structure is known.
+
+**Guidelines:**
+- **Order of Preference:** Current context → `read_file` → `grep_search` → `search_code` → `run_command`.
+- **Batch Commands:** Batch related operations (e.g., `git status && git diff`).
+- **Command Budget:** Maximum 3 shell commands before producing an initial diagnosis.
+
+## 6. Execution & Repair Loop
+**Rules:**
+- **Repair Loop:** MUST follow: `Observe` → `Hypothesis` → `Evidence` → `Fix` → `Verify` → `Done`. Do NOT jump directly from Observe to Fix.
+- **Escalation Policy:** If 2 consecutive attempts fail (e.g., build fail, permission denied): Stop. Explain the blocker. Request user confirmation before continuing.
+- **Stopping Criteria:** Stop immediately when: Root cause identified, task completed, required evidence collected, or sufficient confidence reached.
+
+**Guidelines:**
+- **Cost Policy:** Optimize for: Correctness > Minimal Changes > Minimal Context > Minimal Tool Usage > Minimal Runtime.
+
+## 7. Verification
+**Rules:**
+- **MUST** use the lowest verification level sufficient for the task.
+- **MUST NOT** run build/test unless required by the task or needed for verification.
+
+**Guidelines:**
+- **Risk-based Verification:**
+  - **Level 0 (Low Risk):** Comment, typo, string changes. Static analysis only.
+  - **Level 1:** Read source code.
+  - **Level 2 (Medium Risk):** Logic changes. Run targeted test.
+  - **Level 3 (High Risk):** Auth, payment, database. Run full validation.
+
+## 8. Output Policy
+**Rules:**
+- **MUST** use English for: Code, reasoning, architecture terms, file names, variables, technical decisions, Git commit messages, logs, and prompt logic (Workflow, Checklist).
+- **MUST** use Vietnamese for: User-facing explanations, questions, summaries, progress updates, and the final report.
+- **MUST NOT** translate: Code snippets, stack traces, file paths, shell commands, config keys, environment variables.
+- **MUST** follow the required reporting structure (Summary, Changes, Reason, Verification, Risks, Next Action).

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to the **AI Developer Skill OS** project will be documented
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.1] - 2026-07-02
+
+### Changed
+- Updated skills.json version từ 1.0.1 → 3.0.1 để phản án version skills chính
+- Thay đổi status các skill từ `planned` → `ready` 
+- Cập nhật `qk-bug-fix` → `qk-bug-resolution` với version 3.0.0
+
+### Added
+- Thêm `knowledge/backend/nodejs.md` - tài liệu kiến trúc backend Node.js
+- Thêm categories registry cho dễ phân loại skills
+
+### Fixed
+- Sửa lỗi `qk-projects-bootstrap` → `qk-project-bootstrap` typo trong categories
+
 ## [1.0.1] - 2026-07-01
 ### Fixed
 - Standardized Language rule across all 23 SKILL.md files for consistency.

package/README.md

@@ -1,20 +1,27 @@
 # 🚀 AI Developer Skill OS (ai-developer-skill-os) v3.0
 
-> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini).
+> Một hệ điều hành (AI-OS) và Nền tảng Kiến trúc Kỹ thuật (Engineering Platform) tối thượng dành cho AI Coding Agents (Claude Code, Cursor, Windsurf, Gemini, Kilo).
 
 Thay vì cung cấp các "công cụ rời rạc" (Toolbox) hoặc những prompt cồng kềnh, **AI Developer Skill OS v3.0** được thiết kế lại hoàn toàn theo chuẩn **Enterprise-ready Agentic Framework**. Nó biến Agent của bạn thành một **Senior Engineer / Chief Architect** thực thụ với khả năng tự suy luận bằng Tiếng Anh, nhưng lại báo cáo thân thiện bằng Tiếng Việt.
 
 ---
 
+## ✨ Tính năng chính
+- **23 Skills chuẩn Enterprise** cho Frontend, Backend, Engineering
+- **Kiến trúc 5 tầng** giúp tối ưu Context Window
+- **Pipeline tự động**: analyze → implement → validate → complete
+- **Decision Tree** cho từng skill, đưa ra quyết định chuẩn xác
+- **Knowledge RAG on-demand** - chỉ tải kiến thức khi cần thiết
+
 ## 🏗️ Kiến Trúc 5 Tầng (The 5-Tier Architecture)
 
 Hệ thống được thiết kế decoupled (phân tách) hoàn hảo để chống tràn Context Window và tối ưu khả năng suy luận của LLM:
 
-### 1. Global Policy (`.agents/AGENTS.md`)
-Chứa các bộ luật thép toàn cục (Agent-wide rules):
-- **Language Policy:** Suy luận kỹ thuật bằng Tiếng Anh, giao tiếp với người dùng bằng Tiếng Việt.
-- **Execution Principles:** `Read before Write`, `Verify before Complete`.
-- **Engineering Policy:** Trị bệnh tận gốc (Fix root cause), giữ nguyên chuẩn cũ.
+### 1. OS Kernel (`.agents/AGENTS.md`)
+The core of the system is a lightweight, heavily optimized OS Kernel that dictates agent behavior across all tasks.
+- **Intent-Based Policies:** Skills are classified into 4 groups (Static Analysis, Development, Validation, Maintenance) rather than micromanaged with individual exceptions.
+- **Progressive Evidence Collection:** Agents collect context incrementally (1 file → 3 files) and stop at a 80% Confidence Threshold, eliminating "hallucination loops".
+- **Risk-based Verification:** Tests and builds are only run based on the risk level of the change, strictly guided by the Cost and Escalation policies.
 
 ### 2. Core Templates (`templates/`)
 Chứa các format báo cáo chuẩn (như `bug-report.md`, `feature-report.md`, `review-report.md`). AI không cần "học lại" cách viết báo cáo, giúp đầu ra luôn nhất quán 100%.

package/docs/GOVERNANCE.md

@@ -0,0 +1,40 @@
+# Project Governance
+
+This document serves as the "Constitution" for the AI Developer Skill OS. It dictates how the project evolves, when core files can be modified, and how versions are incremented.
+
+## 1. Core Philosophy
+**Architecture-first, features-second.**
+Before submitting any Pull Request, ask yourself:
+1. *Does this change require modifying the OS Kernel (`AGENTS.md`)?*
+2. *If not, can this be solved at the Skill, Knowledge, or Template layer?*
+
+If the problem can be solved in a Skill, Knowledge document, or Template, **do not touch the Kernel**.
+
+## 2. When to modify `AGENTS.md` (The Kernel)
+The Kernel is **frozen**. Modifications to `AGENTS.md` are strictly prohibited unless:
+- The change introduces a fundamentally new paradigm for ALL agents (e.g., a completely new approach to token management).
+- A critical, framework-breaking hallucination loop is discovered that cannot be solved via Skill guidelines.
+- **Requirement:** Any modification to `AGENTS.md` MUST be accompanied by a new Architecture Decision Record (ADR).
+
+## 3. When to create an ADR (Architecture Decision Record)
+ADRs (located in `docs/adr/`) must be created when:
+- Modifying `AGENTS.md` or `SPEC.md`.
+- Introducing a new lifecycle phase to the pipeline.
+- Deprecating an existing core feature or standard tool.
+
+## 4. Definition of a "Breaking Change"
+A change is considered **Breaking** if it:
+- Alters the required YAML frontmatter contract in `SPEC.md`.
+- Changes the fundamental routing logic or expected `behavior` / `intent` mappings.
+- Removes an existing global policy that downstream agents rely on.
+
+## 5. Versioning Strategy (Semantic Versioning)
+We strictly adhere to SemVer based on the framework's architecture, not just content.
+- **MAJOR (e.g., v4.0.0 to v5.0.0):** Breaking changes to the Kernel (`AGENTS.md`), Metadata Contract (`SPEC.md`), or fundamental routing.
+- **MINOR (e.g., v4.0.0 to v4.1.0):** Adding new Capabilities, new default Skills, new Knowledge docs, or new Templates. 
+- **PATCH (e.g., v4.0.0 to v4.0.1):** Fixing typos in docs, updating README, or minor bug fixes within an individual skill's SOP.
+
+## 6. PR Review Process
+1. **Architecture Compliance:** Does the PR violate the Kernel Freeze? Are all skills compliant with `SPEC.md`?
+2. **Documentation Consistency:** Are the changes reflected in `CHANGELOG.md`?
+3. **No Redundancy:** Ensure the PR does not re-introduce tool usage rules or verification overrides into individual skills.

package/docs/SPEC.md

@@ -0,0 +1,37 @@
+# AI Developer Skill OS - Specification (v4)
+
+This document defines the strict contract and schema for developing Custom Skills in the AI Developer Skill OS. The metadata frontmatter is frozen to ensure cross-platform compatibility (Cursor, Claude Code, Windsurf, Gemini).
+
+## 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]
+version: X.Y.Z
+updated: YYYY-MM-DD
+description: Brief summary of what this skill accomplishes.
+behavior: static-analysis | development | validation | maintenance
+intent: review-code | fix-bug | implement-feature | validate | maintain
+priority: low | medium | high | critical
+tags: [tag1, tag2]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: Natural language phrase that activates this skill.
+inputs: [Required inputs]
+outputs: [Expected outputs]
+allowed_tools: [Tool1, Tool2]
+pipeline: [analyze, plan, implement, validate, complete]
+---
+```
+
+## 2. Skill Body Structure (Markdown)
+
+The body of the `SKILL.md` file MUST contain the following sections:
+
+1. **Goal:** The core objective of the skill.
+2. **Chain of Thought (SOP):** The exact step-by-step reasoning the agent must follow.
+3. **Constraints & Rules:** Hard boundaries and limits for this specific skill.
+4. **Handoff Pipeline (Optional):** How this skill transitions to the next phase (e.g. passing to validation).
+
+*Note: Skill documents MUST NOT declare Verification Levels or override Tool Efficiency policies. Those are exclusively managed by the Global Kernel (`AGENTS.md`).*

package/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/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/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/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/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/knowledge/backend/nodejs.md

@@ -0,0 +1,52 @@
+---
+id: nodejs-knowledge-base
+domain: backend
+tags: [nodejs, express, api, middleware]
+priority: high
+---
+
+# Node.js Backend Knowledge Base
+
+## Architecture Patterns
+- **Controller Layer:** Handle HTTP requests/responses, input validation, delegate to Service
+- **Service Layer:** Business logic, data transformation, transaction management  
+- **Repository Layer:** Direct database queries, ORM interactions
+- **Middleware:** Auth guards, logging, rate limiting, error handling
+
+## Express Best Practices
+```ts
+// Controller pattern - thin, delegates to service
+export async function createUser(req: Request, res: Response) {
+  const result = await userService.create(req.body);
+  res.status(201).json(result);
+}
+
+// Service pattern - business logic
+export async function create(userData: UserDto) {
+  // Validation
+  const validated = userSchema.parse(userData);
+  // Transaction
+  return db.user.create({ data: validated });
+}
+
+// Middleware pattern - reusable
+export const requireAuth = (req: Request, res: Response, next: NextFunction) => {
+  const user = verifyToken(req.headers.authorization);
+  if (!user) return res.status(401).json({ error: 'Unauthorized' });
+  req.user = user;
+  next();
+};
+```
+
+## Error Handling
+- Never throw raw Errors. Use custom error classes.
+- Always catch async errors in middleware.
+- Return consistent error format: `{ error: string, code?: string }`
+
+## Security Checklist
+- Use helmet middleware for security headers
+- Validate all inputs with Zod/Joi
+- Never commit .env files
+- Use parameterized queries to prevent SQL injection
+- Rate limit public endpoints
+- Log security events (failed logins, permission denied)

package/knowledge/frontend/react.md

@@ -12,16 +12,70 @@ priority: high
 - Use `useContext` or global stores (Zustand/Redux) when prop drilling exceeds 3 levels.
 - Never store derived data in state. Compute it on the fly during render.
 - Never store API responses in Redux if a Server State tool (React Query/SWR) is available.
+- For forms: Use React Hook Form + Zod for validation, NOT useState for each field.
 
 ## Hooks Best Practices
 - **useEffect:** Avoid using `useEffect` for data transformation or syncing state. Only use it for actual side effects (subscriptions, API calls, manual DOM mutations).
 - **useMemo / useCallback:** Only use when passing props to heavily memoized child components or when the computation is extremely expensive. Do not use them blindly.
 - **Custom Hooks:** Extract complex logic out of UI components into custom hooks. Prefix them with `use` (e.g., `useUserAuth`).
+- **Custom Hook Pattern:**
+  ```ts
+  // useApi.ts - Generic API hook
+  export function useApi<T>(url: string) {
+    const [data, setData] = useState<T | null>(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    
+    useEffect(() => {
+      fetchData();
+    }, [url]);
+  }
+  ```
 
 ## Component Boundaries
 - Follow Single Responsibility Principle. A component should either handle logic (Container) or handle rendering UI (Presentational), ideally not both if it's complex.
 - Keep files under 300 lines. If a file is larger, break it down.
+- **Component Hierarchy:**
+  - `components/shared/` - Reusable, no business logic
+  - `features/<domain>/components/` - Feature-specific components
+  - `layouts/` - Page layouts and wrappers
 
 ## Performance Gotchas
 - Stale Closures: Always include all reactive variables in the dependency array of `useEffect` or `useCallback`.
 - Keys in Lists: Always use unique IDs for `key` props. Never use array indices unless the list is completely static.
+- **Re-render Detection:**
+  ```ts
+  // Use console.log inside component to detect renders
+  // Wrap child in React.memo if unnecessary re-renders occur
+  export const MemoizedChild = React.memo(ChildComponent);
+  ```
+
+## Error Handling Patterns
+```ts
+// API Error Boundary
+class ErrorBoundary extends React.Component {
+  state = { hasError: false };
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+}
+
+// Hook error handling
+const { data, error, isLoading } = useQuery(['key'], fetchFn);
+if (error) return <ErrorMessage error={error} />;
+if (isLoading) return <LoadingSpinner />;
+```
+
+## Testing Patterns
+```tsx
+// Component test with React Testing Library
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+test('handles user interaction', async () => {
+  render(<LoginForm />);
+  const button = screen.getByRole('button', { name: /login/i });
+  await userEvent.click(button);
+  await waitFor(() => expect(mockSubmit).toHaveBeenCalled());
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
   "main": "bin/install.js",
   "bin": {

package/skills/qk-bug-resolution/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Fix bugs and prevent regressions.
 category: engineering
+behavior: development
+intent: fix-bug
 priority: high
 tags: [bug, debug, regression]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -33,7 +35,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Provide steps to test the fix.
    - Ensure backward compatibility.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **No Guesses:** Do not assume the shape of an API response. Print it or read the type definitions first.
 - **Minimal Fix:** Always prefer a 1-line fix over a 100-line refactor, unless the architecture is fundamentally broken.
 - **Clean Up:** Remove any `console.log()` or debugger statements introduced during the debugging process.

package/skills/qk-engineering-standard/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Enforce SOLID, DRY, Clean Code, and Naming conventions.
 category: standard
+behavior: static-analysis
+intent: review-code
 priority: critical
 tags: [clean-code, architecture, refactoring, solid]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -32,7 +34,7 @@ pipeline: [analyze, review, implement, validate, complete]
 4. **Verify (Validation):**
    - Ensure the refactoring did NOT change the business logic or behavior of the app (Regression check).
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Code is for Humans:** Write code that junior developers can easily understand. Avoid overly clever or obscure syntax.
 - **Scope Limit:** Do NOT refactor the entire project if the user only asked to review one file. Limit the scope to the current task context.
 - **Preserve Behavior:** Refactoring must strictly preserve backward compatibility.

package/skills/qk-feature-delivery/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Develop new features end-to-end (Frontend & Backend).
 category: engineering
+behavior: development
+intent: implement-feature
 priority: high
 tags: [feature, development, e2e, ui, api]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -32,7 +34,7 @@ pipeline: [analyze, implement, engineering-standard, validate, complete]
    - Check if the UI is responsive.
    - Ensure the API handles edge cases (empty states, loading, error).
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Contract First:** Always define the Type/Interface contract before writing the implementation logic.
 - **Component Reusability:** Do not create a new Button or Input if a Shared Component already exists in `src/components/shared/`.
 - **DRY (Don't Repeat Yourself):** Extract inline styles or duplicate logic into hooks/utilities.

package/skills/qk-production-release/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Prepare the codebase for a production release (Build, CI/CD, Security).
 category: operations
+behavior: validation
+intent: validate
 priority: high
 tags: [deploy, release, build, production]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -29,7 +31,7 @@ pipeline: [analyze, review, implement, validate, complete]
 4. **Complete (Deployment Plan):**
    - Provide a manual checklist for the user to execute the final deployment.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **No Rogue Deploys:** Never run commands like `firebase deploy` or `vercel --prod` without explicit, undeniable user approval.
 - **Secret Safety:** Never hardcode URLs. Ensure they are injected via ENV.
 

package/skills/qk-project-health/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Comprehensive audit of Code Smells, Tech Debt, and Architecture.
 category: architecture
+behavior: static-analysis
+intent: review-code
 priority: medium
 tags: [audit, architecture, tech-debt, code-smell]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -30,7 +32,7 @@ pipeline: [analyze, review, validate, complete]
 4. **Complete (Roadmap):**
    - Generate a prioritized Refactor Roadmap (High, Medium, Low).
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Audit Only - No Touch:** Do not modify any code. You are diagnosing, not performing surgery.
 - **Evidence Based:** Provide concrete metrics (e.g., "Folder `components` has 45 files, making it hard to navigate").
 

package/skills/qk-system-evolution/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Safely upgrade dependencies, migrate frameworks, and manage rollbacks.
 category: operations
+behavior: maintenance
+intent: maintain
 priority: high
 tags: [upgrade, migration, devops, dependencies]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -33,7 +35,7 @@ pipeline: [analyze, plan, implement, validate, complete]
    - Reinstall dependencies cleanly (`npm ci` or `yarn install`).
    - Run the build process to ensure the system compiles.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Safety First:** Never run `npm update` blindly across all packages. Update only what was requested.
 - **Lockfiles:** Do not delete `package-lock.json` or `yarn.lock` unless resolving extreme merge conflicts.
 - **Always Rollback:** If the system produces >50 compilation errors after an upgrade and you cannot fix them in 1 turn, immediately trigger the Rollback Plan.

package/skills/qk-ui-audit/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Audit UI for Consistency, Accessibility, Responsive, and Performance.
 category: validation
+behavior: static-analysis
+intent: review-code
 priority: medium
 tags: [ui, audit, frontend, a11y, responsive]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -32,7 +34,7 @@ pipeline: [analyze, review, validate, complete]
 4. **Complete (Report):**
    - Calculate a rough score (0-100) based on violations.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Audit Only:** Do not modify the code automatically unless the user explicitly requests you to apply the fixes.
 - **Evidence Based:** Point out the exact line number where the violation occurs.
 

package/skills/qk-validation-gate/SKILL.md

@@ -4,6 +4,8 @@ version: 3.0.0
 updated: 2026-07-02
 description: Mandatory Quality Gate (Test, Lint, Security).
 category: validation
+behavior: validation
+intent: validate
 priority: critical
 tags: [ci, testing, linting, security, gatekeeper]
 platforms: [claude-code, cursor, windsurf, gemini-cli]
@@ -30,7 +32,7 @@ pipeline: [analyze, validate, complete]
    - If minor lint errors exist, attempt an auto-fix (`npm run lint --fix`).
    - If tests fail, report the exact failure to the user. Do NOT pretend it passed.
 
-## 🛡️ 2. Constraints & Rules
+## 🛡️ 3. Constraints & Rules
 - **Zero Tolerance:** A failed test or a TypeScript error means the Gate is FAILED. Do not ignore errors.
 - **No Force:** Never use `--force` or `--no-verify` flags.
 - **Real Execution:** You MUST run the actual CLI commands using `run_command` and wait for the output.

package/skills.json

@@ -1,7 +1,7 @@
 {
-  "version": "1.0.1",
+  "version": "3.0.1",
   "name": "AI Developer Skill OS",
-  "description": "Multi-agent skill package for AI coding agents — Engineering + Frontend + Backend",
+  "description": "Enterprise-ready Agentic Framework for AI Coding Agents — Engineering + Frontend + Backend",
   "language": "en",
   "author": "Quang Khánh",
   "homepage": "https://github.com/phamquangkhanh2999/ai-developer-skill-os.git",
@@ -27,7 +27,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Tra cứu danh sách toàn bộ kỹ năng (skills) hiện có và đọc các mẹo kết hợp để code hiệu quả."
     },
     {
@@ -53,7 +53,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "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."
     },
     {
@@ -78,7 +78,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Xác định các file cần thiết, tóm tắt kiến trúc và quản lý bộ nhớ ngữ cảnh để tránh tràn bộ nhớ."
     },
     {
@@ -108,13 +108,13 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Kiểm toán toàn bộ dự án để phát hiện bug ẩn, rủi ro bảo mật, vấn đề hiệu năng và nợ kỹ thuật trước khi sửa code."
     },
     {
-      "name": "qk-bug-fix",
-      "path": "skills/qk-bug-fix/SKILL.md",
-      "version": "2.0.0",
+      "name": "qk-bug-resolution",
+      "path": "skills/qk-bug-resolution/SKILL.md",
+      "version": "3.0.0",
       "category": "engineering",
       "priority": "P0",
       "trigger": [
@@ -136,7 +136,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "migrating",
+      "status": "ready",
       "description": "Chẩn đoán và sửa lỗi an toàn. Tái hiện lỗi, tìm nguyên nhân gốc rễ và áp dụng bản sửa lỗi tối thiểu, có kiểm chứng."
     },
     {
@@ -164,7 +164,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Tái cấu trúc và dọn dẹp mã nguồn để dễ bảo trì hơn mà không làm thay đổi logic hoạt động bên ngoài."
     },
     {
@@ -192,7 +192,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "migrating",
+      "status": "ready",
       "description": "Chuyển đổi tài liệu API (curl, swagger...) thành code tích hợp frontend chuẩn xác, có type an toàn và xử lý lỗi."
     },
     {
@@ -221,7 +221,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Nâng cấp dependency, chuyển đổi framework và thay thế thư viện một cách an toàn với chiến lược không downtime."
     },
     {
@@ -247,7 +247,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Viết commit message chuẩn Conventional Commits, mô tả Pull Request, Changelog và Release Notes chuyên nghiệp."
     },
     {
@@ -274,7 +274,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Phân tích cấu trúc thư mục frontend và quyết định vị trí đặt file chuẩn xác theo kiến trúc hiện tại."
     },
     {
@@ -302,7 +302,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Ép buộc sử dụng design system, component library và token hiện có, ngăn chặn việc viết HTML/CSS rác."
     },
     {
@@ -332,7 +332,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Xây dựng các màn hình và layout phức tạp từ yêu cầu, tái sử dụng component và đảm bảo responsive."
     },
     {
@@ -359,7 +359,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Tạo các UI Component độc lập, tái sử dụng được, có type an toàn và tuân thủ chuẩn design system."
     },
     {
@@ -388,7 +388,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Xác định và triển khai chiến lược quản lý state phù hợp (Zustand, Redux, React Query, Local State)."
     },
     {
@@ -418,7 +418,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Xây dựng Form chuẩn xác với quản lý trạng thái, validate dữ liệu (Zod, Yup) và xử lý hiển thị lỗi."
     },
     {
@@ -448,7 +448,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Tạo các bảng dữ liệu admin với đầy đủ tính năng phân trang, sắp xếp, lọc và thao tác thêm/sửa/xóa (CRUD)."
     },
     {
@@ -475,7 +475,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Chẩn đoán và sửa các lỗi đặc thù frontend như Hydration error, infinite re-render, stale closure và vỡ CSS."
     },
     {
@@ -504,7 +504,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Viết Unit, Component và E2E test bằng Jest, Vitest, RTL, Cypress. Tập trung vào hành vi người dùng."
     },
     {
@@ -532,7 +532,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Tối ưu hóa hiệu năng frontend: giảm kích thước bundle, chặn re-render thừa, lazy load và cải thiện Web Vitals."
     },
     {
@@ -560,7 +560,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "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."
     },
     {
@@ -587,7 +587,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Kiểm soát cấu trúc backend, ép buộc tuân thủ mô hình Layer (Controller/Service/Repository) và vị trí file."
     },
     {
@@ -617,7 +617,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Thiết kế database schema, viết script migration và tối ưu truy vấn cho SQL/NoSQL bằng ORM (Prisma, Drizzle...)."
     },
     {
@@ -646,7 +646,7 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Triển khai tính năng đăng nhập (JWT, OAuth), phân quyền (RBAC) và bảo vệ app khỏi các lỗ hổng OWASP."
     },
     {
@@ -673,19 +673,15 @@
         "cursor",
         "windsurf"
       ],
-      "status": "planned",
+      "status": "ready",
       "description": "Cấu hình CI/CD pipelines, tạo Dockerfile và thiết lập môi trường để deploy lên Vercel, AWS hoặc VPS."
     }
   ],
-  "entries": [
-    {
-      "path": "skills/qk-"
-    },
-    {
-      "path": "skills/qk-"
-    },
-    {
-      "path": "skills/qk-"
-    }
-  ]
+  "categories": {
+    "orchestration": ["qk-orchestrator", "qk-context-loader", "qk-policy-engine", "qk-access-policy"],
+    "engineering": ["qk-feature-delivery", "qk-api-lifecycle", "qk-data-lifecycle", "qk-design-to-code", "qk-system-evolution", "qk-project-bootstrap"],
+    "validation": ["qk-validation-gate", "qk-engineering-standard", "qk-ui-audit", "qk-project-health", "qk-bug-resolution"],
+    "ops": ["qk-production-release", "qk-ai-builder", "qk-project-bootstrap", "qk-docs", "qk-documentation-system", "qk-project-memory"],
+    "knowledge": ["knowledge/frontend/react.md", "knowledge/backend/nodejs.md"]
+  }
 }

package/templates/skill-template.md

@@ -0,0 +1,38 @@
+---
+name: qk-[skill-name]
+version: 1.0.0
+updated: YYYY-MM-DD
+description: Brief, action-oriented description of what this skill does.
+category: engineering # general category
+behavior: static-analysis # static-analysis | development | validation | maintenance
+intent: review-code # review-code | fix-bug | implement-feature | validate | maintain
+priority: medium # low | medium | high | critical
+tags: [tag1, tag2]
+platforms: [claude-code, cursor, windsurf, gemini-cli]
+trigger: Natural language trigger phrase.
+inputs: [List of required inputs]
+outputs: [Expected output format]
+allowed_tools: [read_file, write_to_file]
+pipeline: [analyze, plan, implement, validate, complete]
+---
+
+# 🛠️ qk-[skill-name] - Standard Operating Procedure
+
+> **Goal:** [State the primary objective of this skill clearly]
+
+## 🔄 1. Chain of Thought (SOP)
+1. **Analyze:**
+   - Step 1...
+2. **Plan:**
+   - Step 2...
+3. **Implement:**
+   - Step 3...
+4. **Verify:**
+   - Step 4...
+
+## 🛡️ 2. Constraints & Rules
+- **Rule 1:** [Hard constraint 1]
+- **Rule 2:** [Hard constraint 2]
+
+## 🤝 3. Handoff Pipeline (Optional)
+- Pass to `qk-validation-gate` upon completion if necessary.