ai-developer-skill-os 7.5.1 → 8.1.4

package/framework/bias-library/fake-ui-slop.md

@@ -1,20 +0,0 @@
----
-id: fake-ui-slop
-type: bias
-description: LLM draws fake charts, images, or dashboard UI elements using generic div blocks instead of integrating real assets.
----
-
-Detection:
-- Did I use `<div class="bg-blue-500 w-full h-32">Fake Chart</div>`?
-- Did I forget to add placeholders for real images?
-
-Risk:
-- Unprofessional UI design.
-- Technical debt for the frontend developer.
-
-Correction:
-- Insert a comment like `<!-- TODO: Insert real image -->`.
-- Use high-quality placeholder services (e.g., picsum).
-
-Evidence:
-- Highlight the exact placeholder used.

package/framework/bias-library/hallucinated-tools.md

@@ -1,20 +0,0 @@
----
-id: hallucinated-tools
-type: bias
-description: LLM invents APIs, tools, or shell commands that do not exist in the current environment.
----
-
-Detection:
-- Did I attempt to call a CLI tool without verifying it is installed?
-- Did I invent a non-existent method on a standard library?
-
-Risk:
-- Execution failure.
-- Broken workflows.
-
-Correction:
-- Verify tools and APIs before using them.
-- Stick to standard, known commands.
-
-Evidence:
-- Provide documentation or link to the specific tool usage.

package/framework/bias-library/missing-ui-states.md

@@ -1,19 +0,0 @@
----
-id: missing-ui-states
-type: bias
-description: LLM writes frontend components assuming the "happy path" only, ignoring Loading, Error, and Empty states.
----
-
-Detection:
-- Did I write a fetch component without a loading spinner?
-- Did I forget to handle the case where the data array is empty?
-
-Risk:
-- Poor user experience.
-- UI crashes on undefined data.
-
-Correction:
-- Always implement Loading, Error, and Empty states for any asynchronous UI component.
-
-Evidence:
-- Point to the conditional rendering logic.

package/framework/bias-library/over-indexing.md

@@ -1,20 +0,0 @@
----
-id: over-indexing
-type: bias
-description: LLM recommends adding database indexes to every column to "improve performance", ignoring write penalties.
----
-
-Detection:
-- Did I suggest indexing a column with low cardinality (e.g., boolean status)?
-- Did I suggest indexing multiple columns without analyzing query patterns?
-
-Risk:
-- Slower INSERT/UPDATE operations.
-- Increased database storage costs.
-
-Correction:
-- Only recommend indexes for Foreign Keys or heavily filtered/sorted columns.
-- Suggest resolving N+1 queries first.
-
-Evidence:
-- Provide the exact slow query that justifies the index.

package/framework/bias-library/swallow-errors.md

@@ -1,19 +0,0 @@
----
-id: swallow-errors
-type: bias
-description: LLM wraps code in a try/catch block but leaves the catch block empty or just logs to console, effectively hiding fatal errors.
----
-
-Detection:
-- Did I write `catch (e) { console.error(e) }` without throwing or returning an error state?
-- Did I fail to surface the error to the UI?
-
-Risk:
-- Silent failures.
-- Extremely difficult debugging.
-
-Correction:
-- Always handle the error gracefully (e.g., return a unified error object or show a toast notification).
-
-Evidence:
-- Point to the specific error handling logic.

package/framework/bias-library/ui-only-security.md

@@ -1,17 +0,0 @@
----
-id: ui-only-security
-type: bias
-description: LLM hides a button on the UI for unauthorized users but forgets to secure the backend API endpoint.
----
-
-Detection:
-- Did I add a role check in the React component but not in the Node.js controller?
-
-Risk:
-- Critical security vulnerability (users can bypass UI and hit the API directly).
-
-Correction:
-- Security must always be enforced at the Backend/API layer first. UI hiding is just for UX.
-
-Evidence:
-- Point to the backend middleware or controller where the permission is checked.

package/framework/decision-primitives.md

@@ -1,48 +0,0 @@
-# 🧩 Bảng Tuần Hoàn: Decision Primitives (v6.0)
-
-Rule-Skins v6 không coi các Agent là những "con người ảo" (Personas), mà coi chúng là những **Cỗ máy Ra Quyết định (Decision Engines)**.
-Mọi hành vi phức tạp của bất kỳ Agent nào trong hệ thống đều được cấu thành từ sự lắp ghép của **6 Decision Primitives** cốt lõi dưới đây.
-
----
-
-## 1. 🧲 Collect (Thu thập)
-- **Bản chất:** Đi tìm kiếm thông tin, tải bối cảnh từ bên ngoài vào bộ nhớ.
-- **Trigger:** Thiếu context hoặc nhận một task yêu cầu đọc dữ liệu.
-- **Evidence Required:** Quyền truy cập repository, cấu trúc file, URL.
-- **Ví dụ Skills:** `qk-context-loader`, bước đầu của `qk-bug-resolution`.
-
-## 2. 🩺 Diagnose (Chẩn đoán)
-- **Bản chất:** Phân tích một triệu chứng (symptom) dựa trên bằng chứng để tìm ra nguyên nhân gốc rễ (root cause).
-- **Trigger:** Có lỗi (Bug report, error log, test failure).
-- **Evidence Required:** Stack trace, logs, test output.
-- **Ví dụ Skills:** `qk-bug-resolution`, `qk-project-health`.
-
-## 3. 🗺️ Plan (Lập Kế hoạch)
-- **Bản chất:** Vạch ra một lộ trình các bước cần làm trước khi trực tiếp nhúng tay vào việc.
-- **Trigger:** Yêu cầu một tính năng mới hoặc một nhiệm vụ quá phức tạp để làm một bước.
-- **Evidence Required:** Yêu cầu (Requirements), Specs, Architecture.
-- **Ví dụ Skills:** `qk-feature-delivery`, `qk-api-lifecycle`.
-
-## 4. ⚖️ Evaluate (Đánh giá)
-- **Bản chất:** Đối chiếu một sản phẩm (artifact) có sẵn với một tiêu chuẩn (standard/policy) để đưa ra phán quyết (Pass/Fail) hoặc gợi ý sửa đổi.
-- **Trigger:** Một đoạn code mới, một bản thiết kế, một PR.
-- **Evidence Required:** Artifact cần review, Guidelines, Linter rules.
-- **Ví dụ Skills:** `qk-engineering-standard`, `qk-validation-gate`, `qk-ui-audit`.
-
-## 5. 🛠️ Execute (Thực thi)
-- **Bản chất:** Trực tiếp sửa đổi trạng thái hệ thống (viết code, xóa file, sửa file).
-- **Trigger:** Đã có kế hoạch rõ ràng hoặc đã xác định xong lỗi.
-- **Evidence Required:** Codebase hiện tại, Kế hoạch.
-- **Ví dụ Skills:** `qk-feature-delivery` (bước sau), `qk-ui-builder`.
-
-## 6. 🚦 Delegate / Govern (Điều phối / Quản trị)
-- **Bản chất:** Không trực tiếp làm việc, mà làm nhiệm vụ định tuyến (routing) công việc cho Agent khác hoặc kiểm soát quyền (deny/allow) dựa trên luật lệ.
-- **Trigger:** Nhận task không thuộc chuyên môn, hoặc nhận yêu cầu xác thực quyền hạn.
-- **Evidence Required:** Danh sách các Skills khác, Policies (RBAC/ABAC).
-- **Ví dụ Skills:** `qk-orchestrator`, `qk-access-policy`.
-
----
-
-> **Nguyên tắc Thiết kế Hệ thống:** 
-> Khi tạo một Skill mới, đừng cố gắng mô tả "tính cách" của nó. Hãy tự hỏi: *Nó cần dùng những Primitives nào để hoàn thành nhiệm vụ?*
-

package/framework/dial-library/complexity-budget.md

@@ -1,13 +0,0 @@
----
-id: complexity-budget
-type: dial
-description: Defines the ceiling for architectural and code complexity.
----
-
-Levels:
-- **Level 1 (Prototype):** Hardcode data, skip tests, minimal validation. Goal is highest speed.
-- **Level 5 (Standard):** Monolith, basic SQL/ORM, Zod validation, essential error states.
-- **Level 10 (Enterprise):** Event-driven architecture, CQRS, strict rate limiting, 100% test coverage.
-
-Usage:
-- The AI must infer the current budget based on the Project Scale (MVP vs Enterprise) and stick to it. Never exceed the budget.

package/framework/dial-library/granularity.md

@@ -1,13 +0,0 @@
----
-id: granularity
-type: dial
-description: Defines the level of detail for access control policies.
----
-
-Levels:
-- **Level 1 (Coarse):** Role-based (Admin vs User).
-- **Level 5 (Fine-grained):** Attribute-based (Owner of the resource).
-- **Level 10 (Micro):** Field-level permissions (Can edit Title but not Price).
-
-Usage:
-- Adjust based on the project scale. For MVP, stick to Level 1.

package/framework/dial-library/optimization-strategy.md

@@ -1,13 +0,0 @@
----
-id: optimization-strategy
-type: dial
-description: Defines the approach to database and performance optimization.
----
-
-Levels:
-- **Level 1 (Query Fixes):** Resolve N+1 issues and add basic indexes.
-- **Level 5 (Caching):** Introduce Redis or Memcached for heavy read paths.
-- **Level 10 (Architecture):** CQRS, Read Replicas, Sharding.
-
-Usage:
-- Start at Level 1. Never jump to Level 5 or 10 without explicit bottleneck evidence.

package/framework/dial-library/strictness.md

@@ -1,13 +0,0 @@
----
-id: strictness
-type: dial
-description: Defines how rigidly the AI enforces patterns and rules.
----
-
-Levels:
-- **Level 1 (Lenient):** Fix only syntax errors and fatal bugs. Ignore bad architecture.
-- **Level 5 (Balanced):** Suggest improvements but don't rewrite entire files.
-- **Level 10 (Draconian):** Fail immediately on any Linter warning. Enforce strict SOLID principles.
-
-Usage:
-- Adjust based on the user's intent. If they just want a quick fix, lower the strictness. If they ask for an audit, raise it.

package/framework/rule-library/delegation-only.md

@@ -1,9 +0,0 @@
----
-id: delegation-only
-type: rule
-description: Restricts the skill from making direct system modifications.
----
-
-Condition:
-- The skill must ONLY plan, analyze, and dispatch instructions to sub-skills.
-- It must NEVER write code, execute CLI commands, or modify files directly.

package/framework/rule-library/minimal-diff.md

@@ -1,9 +0,0 @@
----
-id: minimal-diff
-type: rule
-description: Ensure the smallest possible change footprint.
----
-
-Condition:
-- Must only modify lines directly related to the task.
-- Reformatting, restructuring, or touching unrelated files is strictly forbidden.

package/framework/skill-schema.md

@@ -1,310 +0,0 @@
-# Skill Schema V7.5 — Runtime Standard Specification
-
-> **Mục đích:** Đây là "lint rules" chính thức cho mọi skill trong bộ V7.5.
-> Bất kỳ skill nào không pass spec này đều **phải được fix trước khi publish**.
-
----
-
-## Frontmatter Required Fields
-
-```yaml
-# REQUIRED — tất cả fields sau đây bắt buộc phải có
-name: string               # qk-[skill-name]
-category: enum             # core|frontend|backend|fullstack|security|qa|maintenance|devops|utilities
-version: semver            # 7.5.x
-description: string        # one sentence, ends without period
-platforms: array           # [antigravity, claude-code, cursor, windsurf, kilo-code]
-execution_mode: string     # deterministic | exploratory
-skill_version: semver      # same as version
-runtime_version: integer   # 1 (current runtime contract version)
-schema_version: integer    # 2 (current schema version)
-cost: enum                 # low | medium | high
-latency: enum              # fast | medium | slow
-risk: enum                 # low | medium | high
-side_effects: enum         # edit_files | run_commands | read_only | none
-produces: array            # [code, report, schema, plan, tokens]
-consumes: array            # [context-graph, design-md, stack-trace, json-payload, none]
-token_budget:
-  max_files_read: integer  # 1–10
-  max_lines_per_read: integer  # 50–200
-  max_shell_commands: integer  # 0–5
-  stop_early: boolean
-exit_codes: array          # must include: [SUCCESS, BLOCKED, FAILED, PARTIAL]
-```
-
-**Lint Rule:** Bất kỳ field nào thiếu → FAIL frontmatter check.
-
----
-
-## 11 Required Body Sections
-
-Dưới đây là 11 sections bắt buộc trong body mỗi SKILL.md, theo thứ tự.
-**Special skills** (redirect, help) được miễn một số section — xem `special_skill_exemptions` cuối file.
-
-### Section 1: Language Rule Header
-```
-> **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese (match user language).
-```
-**Lint Rule:** Phải có ngay sau heading `# qk-[name]`.
-
----
-
-### Section 2: Preconditions
-```markdown
-## Preconditions
-- [ ] [Condition 1]
-- [ ] [Condition N]
-
-\`\`\`
-On missing precondition:
-  EXIT: BLOCKED
-  Message: "[specific message]"
-\`\`\`
-```
-**Lint Rules:**
-- Phải có ít nhất 1 precondition
-- Phải có code block với `EXIT: BLOCKED` và `Message:`
-- Không được chỉ có "Repository accessible" — phải specific
-
----
-
-### Section 3: Scope + Non-Goals
-```markdown
-## Scope
-- ✅ [What it DOES]
-
-## Non-Goals
-- ❌ [Anti-pattern — with reason]
-```
-**Lint Rules:**
-- Scope: ≥ 2 items
-- Non-Goals: ≥ 3 items
-- At least one Non-Goal must be about tool usage (never create scripts / never read entire files)
-
----
-
-### Section 4: Priority Order
-```markdown
-## Priority Order
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1       | ...  | Never          |
-```
-**Lint Rules:**
-- Minimum 3 priorities
-- P1 must have "Never" skip threshold
-- At least one Px must have a percentage threshold (e.g., "Budget < 50%")
-
----
-
-### Section 5: Workflow with Decision Trees
-```markdown
-## Workflow
-
-### Phase N — [Name]
-**Steps:**
-1. [step]
-
-**Decision:**
-\`\`\`
-IF [condition] → [action]
-ELSE → [action]
-\`\`\`
-
-**Exit When:**
-- [condition] → go to Phase N+1 | EXIT: [code]
-```
-**Lint Rules:**
-- Minimum 2 phases
-- Each phase MUST have at least one `Decision:` block
-- Each phase MUST have `Exit When:` conditions
-- No phase can have only "steps" without decisions
-
----
-
-### Section 6: Confidence Model
-```markdown
-## Confidence Model
-| Level  | Condition | Action |
-|--------|-----------|--------|
-| HIGH   | ...       | ...    |
-| MEDIUM | ...       | ...    |
-| LOW    | ...       | EXIT: BLOCKED |
-```
-**Lint Rules:**
-- Must have all 3 levels: HIGH, MEDIUM, LOW
-- LOW must always lead to either BLOCKED or user confirmation
-
----
-
-### Section 7: Severity
-```markdown
-## Severity
-| Level    | Definition | Example |
-|----------|-----------|---------|
-| CRITICAL | ...       | ...     |
-| HIGH     | ...       | ...     |
-| MEDIUM   | ...       | ...     |
-| LOW      | ...       | ...     |
-```
-**Lint Rules:**
-- Must have all 4 levels: CRITICAL, HIGH, MEDIUM, LOW
-- Each level must have a concrete Example column
-
----
-
-### Section 8: Evidence Format
-```markdown
-## Evidence Format
-\`\`\`
-[SEVERITY] path/to/file.ts:LINE
-[Field]:    [value]
-Confidence: [HIGH|MEDIUM|LOW]
-Fix:        [suggestion]
-\`\`\`
-```
-**Lint Rules:**
-- Must include `[SEVERITY]` tag with file:LINE format
-- Must include `Confidence:` field
-- Must include `Fix:` field
-- Must include a filled example below the template
-
----
-
-### Section 9: Retry Policy
-```markdown
-## Retry Policy
-\`\`\`
-[trigger]
-  └─ [action]
-       ├─ [outcome A]
-       └─ [outcome B] → [escalation]
-            └─ Do NOT retry more than N times
-\`\`\`
-```
-**Lint Rules:**
-- Must have explicit max retry count (≤ 3)
-- Must specify what happens after max retries (ESCALATE or FAILED)
-- Read-only skills may have simplified retry: "Audit is read-only — no retry needed."
-
----
-
-### Section 10: Escalation Rules
-```markdown
-## Escalation Rules
-\`\`\`
-BLOCKED: [specific reason]
-Missing:
-  - [artifact or info needed]
-Questions:
-  1. [specific question]
-Recommended Assumptions (if proceeding):
-  - [assumption]
-\`\`\`
-```
-**Lint Rules:**
-- Must have structured format: BLOCKED, Missing, Questions, Recommended Assumptions
-- Cannot be just "ask user" or "STOP"
-- Must have at least 1 specific question
-
----
-
-### Section 11: Handoff Contract
-```markdown
-## Handoff Contract
-### Consumes
-\`\`\`json
-{ "from": "...", "required_fields": [...], "optional_fields": [...] }
-\`\`\`
-### Produces
-\`\`\`json
-{ "to": "...", "output_fields": [...] }
-\`\`\`
-```
-**Lint Rules:**
-- Both Consumes and Produces must be present
-- `required_fields` must be a non-empty array
-- `to` in Produces must reference a real skill name or "user"
-
----
-
-### Section 12: Exit Codes Table
-```markdown
-## Exit Codes
-| Code    | Meaning | When |
-|---------|---------|------|
-| SUCCESS | ...     | ...  |
-| PARTIAL | ...     | ...  |
-| BLOCKED | ...     | ...  |
-| FAILED  | ...     | ...  |
-```
-**Lint Rules:**
-- Must have all 4 codes: SUCCESS, PARTIAL, BLOCKED, FAILED
-- Each must have "When" column with specific trigger condition
-
----
-
-### Section 13: Compliance Block (NEW — End of File)
-```markdown
-## Compliance
-| Check                | Status |
-|----------------------|--------|
-| Runtime Standard     | 11/11  |
-| Frontmatter Complete | ✅     |
-| References Valid     | ✅     |
-| Decision Trees       | PASS   |
-| Thresholds Defined   | PASS   |
-| schema_version       | 2      |
-| runtime_version      | 1      |
-```
-**Lint Rules:**
-- Must be the LAST section in every skill
-- Must be auto-generated or manually updated on each change
-- "References Valid" = all `references/*.md` files actually exist
-
----
-
-## Reference Files Rule
-
-If a SKILL.md mentions `references/[file].md`, that file MUST exist.
-
-```
-LINT ERROR: qk-ui-audit references "references/anti-slop-checklist.md" — FILE NOT FOUND
-```
-
----
-
-## Special Skill Exemptions
-
-Some skills have reduced requirements:
-
-| Skill Type | Exempted Sections |
-|-----------|-------------------|
-| Redirect skill (`qk-policy-engine`) | Sections 2-12 optional — must have redirect target |
-| Help/Discovery skill (`qk-help`) | Sections 5-11 optional — must have skill list |
-
----
-
-## Lint Scoring
-
-```
-Total sections: 13 (including Compliance block)
-Frontmatter: Pass/Fail (binary)
-
-Score = (sections_present / 13) × 100
-
-Grade:
-  100%  → COMPLIANT ✅
-  90%+  → MINOR ISSUES ⚠️
-  70%+  → NEEDS WORK ❌
-  <70%  → NON-COMPLIANT 🔴
-```
-
----
-
-## Version History
-
-| schema_version | runtime_version | Changes |
-|---------------|-----------------|---------|
-| 1             | 1               | Initial V7.0 (YAML constraints only) |
-| 2             | 1               | V7.5 Runtime Standard (11 sections + metadata) |

package/knowledge/backend/nodejs.md

@@ -1,52 +0,0 @@
----
-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

@@ -1,81 +0,0 @@
----
-id: react-knowledge-base
-domain: frontend
-tags: [react, hooks, components, state]
-priority: high
----
-
-# React Knowledge Base
-
-## State Management Rules
-- Use `useState` for strictly local UI state (e.g., dropdown toggle).
-- 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());
-});
-```