ai-developer-skill-os 7.5.1 → 8.1.5

package/.agents/reports/skill-audit.md

@@ -0,0 +1,215 @@
+# Skill Audit Report
+
+## qk-access-policy
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-agent-observability
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 100/100**
+
+## qk-ai-builder
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-api-lifecycle
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-bug-resolution
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-context-loader
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-data-lifecycle
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-db-optimizer
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-design-system-engineering
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 100/100**
+
+## qk-devops-platform
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 100/100**
+
+## qk-docs
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-engineering-standard
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-fe-api-integration
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-feature-delivery
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-frontend-architecture
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ✅
+**Boundary Health Score: 100/100**
+
+## qk-help
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-orchestrator
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 0/100**
+
+## qk-product-specification
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ✅
+**Boundary Health Score: 100/100**
+
+## qk-production-release
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-project-bootstrap
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-project-health
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-project-memory
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-security-audit
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ✅
+**Boundary Health Score: 100/100**
+
+## qk-system-evolution
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-test-engineering
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 100/100**
+
+## qk-ui-audit
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-ui-builder
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-ui-system-builder
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-validation-gate
+- `owns`: ❌
+- `does_not_own`: ❌
+- `conflicts_with`: ❌
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 20/100**
+
+## qk-web-quality-gate
+- `owns`: ✅
+- `does_not_own`: ✅
+- `conflicts_with`: ✅
+- `delegates_to`: ➖ (Optional)
+**Boundary Health Score: 100/100**
+
+
+**Total Scanned:** 30
+**Total Passed (>=80):** 8

package/.agents/rules/coding.md

@@ -0,0 +1,102 @@
+---
+version: 8.0.0
+description: "Rules governing code writing, editing, and review tasks."
+domain: rules
+applies_to: [skills-with-side_effects-edit_files]
+---
+
+# Coding Rules — Code Quality Policy
+
+> **Câu hỏi domain này trả lời:** *Agent nên viết và sửa code như thế nào?*
+
+---
+
+## R-C-01: Edit Source Files Directly
+
+**MUST** edit source files directly. Do NOT:
+- Create wrapper scripts to apply patches.
+- Generate intermediary files then ask user to run them.
+- Use `sed`, `awk`, or shell substitution to patch files.
+
+---
+
+## R-C-02: Targeted Reads Only
+
+**MUST** use targeted reads. Do NOT read entire files > 200 lines.
+
+```
+grep_search → find the relevant section
+view_file[StartLine:EndLine] → read only that section
+```
+
+---
+
+## R-C-03: SOLID Thresholds (Enforceable)
+
+| Metric | Threshold | Action if violated |
+|---|---|---|
+| Function length | ≤ 40 lines | Extract sub-function |
+| File length | ≤ 300 lines | Consider splitting module |
+| Function params | ≤ 4 | Use object/config param |
+| Nesting depth | ≤ 3 | Extract early return or helper |
+| Cyclomatic complexity | ≤ 10 | Simplify conditions |
+
+---
+
+## R-C-04: Naming Conventions
+
+- **Functions/methods:** `camelCase`, verb prefix (`getUser`, `buildPayload`, `validateInput`)
+- **Classes/types:** `PascalCase`
+- **Constants:** `UPPER_SNAKE_CASE`
+- **Files:** `kebab-case` (e.g., `user-service.ts`)
+- **Booleans:** `is`, `has`, `can` prefix (`isLoading`, `hasError`)
+
+---
+
+## R-C-05: No Magic Numbers
+
+Do NOT embed literal values in logic:
+
+```typescript
+// ❌ Bad
+if (retryCount > 3) { ... }
+
+// ✅ Good
+const MAX_RETRIES = 3;
+if (retryCount > MAX_RETRIES) { ... }
+```
+
+---
+
+## R-C-06: Error Handling — Fix, Don't Suppress
+
+```typescript
+// ❌ Never
+try { ... } catch (_) {}
+const value = data!.field;
+const value = data?.field ?? defaultValue; // OK only if intentional
+
+// ✅ Always
+try { ... } catch (err) { 
+  logger.error(err); 
+  throw new AppError('Context message', { cause: err }); 
+}
+```
+
+---
+
+## R-C-07: DRY — Extract When Duplicated ≥ 2 Times
+
+If the same logic appears in 2+ places:
+- Extract to a shared function/utility.
+- Reference the single source.
+- Do NOT inline-copy.
+
+---
+
+## R-C-08: Verification After Every Edit
+
+After any code change:
+1. Re-read the edited section to verify correctness.
+2. Check for syntax errors (mentally or with lint if available).
+3. Consider: does this change affect any callers or dependents?

package/.agents/rules/command-safety.md

@@ -0,0 +1,21 @@
+# Command Safety Rule
+
+Bảo vệ hệ thống khỏi các lệnh nguy hiểm (Destructive Commands). 
+
+## Mức độ Rủi ro (Risk Classification)
+
+### 🔴 Nguy hiểm cấp độ 1 (CẤM HOẶC BẮT BUỘC CONFIRM TỪ USER)
+Tuyệt đối không chạy tự động các lệnh sau. Phải có sự đồng ý rõ ràng từ user:
+- `rm -rf /`, `rm -rf *`, `rm -rf node_modules` (trừ khi chắc chắn context).
+- Xóa database: `drop database`, `drop table`, `TRUNCATE`.
+- Lệnh Git phá hủy lịch sử: `git reset --hard`, `git push --force`.
+- Lệnh liên quan đến hạ tầng: `terraform destroy`, `aws nuke`.
+
+### 🟡 Nguy hiểm cấp độ 2 (CẦN KIỂM TRA TRƯỚC)
+Có thể chạy nhưng phải verify kỹ file path và scope:
+- Các lệnh thao tác file hàng loạt: `find . -name "*.js" -delete`.
+- Lệnh cài đặt ảnh hưởng toàn cầu: `npm install -g`, `pip install`.
+- Khởi động lại service hệ thống: `systemctl restart`.
+
+## Action Plan
+Trước khi đề xuất chạy một command thuộc nhóm Nguy hiểm, hãy dừng lại và yêu cầu xác nhận.

package/.agents/rules/global.md

@@ -0,0 +1,135 @@
+---
+version: 8.0.0
+description: "Agent behavior policies applied globally across all capabilities."
+domain: rules
+applies_to: all
+---
+
+# Global Rules — Agent Behavior Policy
+
+> **Câu hỏi domain này trả lời:** *Agent nên hành xử thế nào?*
+
+---
+
+## R-G-01: Decision Before Action
+
+**MUST** create a plan before executing any task with complexity ≥ medium.
+
+```
+Receive request
+  ↓
+Classify complexity (fast-path or full workflow)
+  ↓
+If medium/high: outline steps first
+  ↓
+Execute step by step
+  ↓
+Verify each step before next
+```
+
+**Violation:** Starting to write code before understanding the full scope.
+
+---
+
+## R-G-02: Evidence Before Conclusion
+
+**MUST** have concrete evidence before stating a finding or applying a fix.
+
+- Do NOT guess root cause without reading the relevant code.
+- Do NOT assume a bug is fixed without verification.
+- Do NOT report "done" without checking the output.
+
+**Minimum evidence:** File path + line number + quoted code.
+
+---
+
+## R-G-03: Minimal Footprint
+
+**MUST** touch only what is necessary for the task.
+
+- Do NOT refactor code outside the task scope.
+- Do NOT "improve" unrelated files while working.
+- Do NOT run commands with broad side effects (e.g., `rm -rf`, `git reset --hard`) without explicit user confirmation.
+
+---
+
+## R-G-04: Token Budget Discipline
+
+**MUST** respect the `token_budget` defined in each skill's frontmatter.
+
+- Read files in targeted chunks (`view_file[start:end]`), never entire large files.
+- Use `grep_search` for pattern discovery, not full-file reads.
+- Stop reading when sufficient evidence is found (`stop_early: true`).
+- Never read: `node_modules/`, `dist/`, `.git/`, binary files.
+
+---
+
+## R-G-05: Retrieval Path (AI-Native)
+
+When starting a task, the agent MUST follow this retrieval sequence:
+
+```
+1. Read registry/skills-index.yml → identify candidate skills
+2. Read candidate SKILL.md(s) → confirm intent + preconditions
+3. Load referenced workflow → understand execution steps
+4. Load referenced rules (this file + coding.md if needed)
+5. Execute
+```
+
+Do NOT load all skills. Do NOT scan the entire repository.
+
+---
+
+## R-G-06: Exit Code Protocol
+
+Every skill execution MUST terminate with one of:
+
+| Code | Meaning |
+|---|---|
+| `SUCCESS` | Task completed and verified |
+| `BLOCKED` | Precondition not met — request more info |
+| `FAILED` | Execution failed after max retries |
+| `PARTIAL` | Partially completed — output + reason |
+
+Never silently terminate. Always report exit code and reason.
+
+---
+
+## R-G-07: Language Policy
+
+- **Code, identifiers, filenames, YAML keys:** English only.
+- **Explanations, summaries, reports to user:** Vietnamese (match user's language).
+- **SKILL.md body headings:** English.
+
+---
+
+## R-G-08: No Silent Errors
+
+**NEVER** use `?.`, `!`, `try/catch {}` (empty catch), or type casting to suppress errors.
+
+Fix root cause. If root cause is unclear → report as BLOCKED with evidence.
+
+---
+
+## R-G-09: Legacy Skill Handling
+
+Agent **MUST** prefer stable skills.
+
+Legacy skills **MAY** be selected only when:
+1. No stable candidate exists
+2. User explicitly requests legacy behavior
+3. Migration incomplete
+
+Legacy skills **MUST NOT** outrank stable skills.
+
+---
+
+## R-G-10: Ambiguity Resolution
+
+Agent **MUST NOT** execute when:
+`selection confidence < threshold`
+
+Agent **SHOULD**:
+1. Ask clarification
+2. Present top candidates
+3. Explain missing information

package/.agents/rules/priorities.yml

@@ -0,0 +1,24 @@
+priority:
+  safety:
+    weight: 100
+    description: "Command safety and destructive action guards"
+
+  security:
+    weight: 100
+    description: "Security audits and safe dependencies"
+
+  governance:
+    weight: 90
+    description: "Architecture boundaries and system evolution"
+
+  quality:
+    weight: 80
+    description: "Anti-slop, UX best practices, performance"
+
+  coding:
+    weight: 70
+    description: "Engineering standards, SOLID, DRY"
+
+  style:
+    weight: 40
+    description: "Formatting, naming conventions"

package/.agents/rules/safety.md

@@ -0,0 +1,84 @@
+---
+version: 8.0.0
+description: "Risk management rules for agent actions with side effects."
+domain: rules
+applies_to: [skills-with-risk-medium, skills-with-risk-high]
+---
+
+# Safety Rules — Risk Management Policy
+
+> **Câu hỏi domain này trả lời:** *Agent nên dừng lại và hỏi khi nào?*
+
+---
+
+## R-S-01: Risk Escalation Matrix
+
+| Risk Level | Side Effects | Required Action |
+|---|---|---|
+| `low` | read_only, none | Proceed autonomously |
+| `medium` | edit_files | Proceed, but report what was changed |
+| `high` | edit_files + architecture impact | Confirm with user before executing |
+| `critical` | destructive, breaking change | BLOCKED — MUST get explicit confirmation |
+
+---
+
+## R-S-02: Breaking Changes — Always Confirm
+
+**MUST** stop and confirm before:
+- Renaming a public API, function, or exported symbol.
+- Deleting files (not creating).
+- Changing database schema (DROP, ALTER with data loss risk).
+- Modifying authentication or authorization logic.
+- Changing environment variables or config values.
+
+**Format for confirmation:**
+```
+⚠️ BREAKING CHANGE DETECTED
+Action: [what you're about to do]
+Affected: [files, APIs, services]
+Risk: [what could break]
+Proceed? (yes/no)
+```
+
+---
+
+## R-S-03: Shell Commands — Minimal and Safe
+
+**Allowed:** read-only commands (`grep`, `ls`, `cat`, `git log`, `git status`)
+**Requires caution:** `git commit`, `git push`, `npm install`
+**BLOCKED without explicit request:** `git reset --hard`, `rm -rf`, `DROP TABLE`, `chmod 777`
+
+Max shell commands per skill cycle: defined in `token_budget.max_shell_commands`.
+
+---
+
+## R-S-04: Confidential Data
+
+**NEVER** read, log, or output:
+- `.env` files (only read specific keys if task explicitly requires it)
+- API keys, secrets, passwords
+- Personal user data (PII)
+
+If a file contains credentials, use `grep` for the specific key only.
+
+---
+
+## R-S-05: Rollback Awareness
+
+For `risk: high` tasks, **MUST** identify rollback strategy before executing:
+
+```
+What will change: [specific files/systems]
+How to rollback: [git revert / manual steps]
+Checkpoint: [git commit hash or backup location]
+```
+
+---
+
+## R-S-06: Partial Output Protocol
+
+If a task cannot complete fully (PARTIAL exit):
+1. Report what WAS completed successfully.
+2. Report exactly what remains.
+3. Provide the next step for the user.
+4. Do NOT leave files in an inconsistent state.

package/.agents/rules/security.md

@@ -0,0 +1,13 @@
+# Security Rule
+
+Tránh tạo ra lỗ hổng bảo mật trong quá trình phát triển (Security khác với Safety - tránh làm hỏng hệ thống).
+
+## Nguyên tắc cốt lõi
+1. **Không commit Secret**: Tuyệt đối không hardcode API key, token, credentials, password vào mã nguồn. Nếu cần test, dùng `.env.example` hoặc placeholder.
+2. **Không trust External Input**: Bất kỳ dữ liệu nào đến từ user, API bên ngoài, tham số URL đều phải được validate và sanitize trước khi sử dụng (đặc biệt trong truy vấn DB, prompt LLM, hoặc render ra DOM).
+3. **Tuân thủ Least Privilege**: Khi cấu hình quyền, luôn cấp quyền tối thiểu cần thiết để hoàn thành công việc.
+
+## Anti-Patterns (CẤM)
+- Cấm in ra console hoặc log các thông tin nhạy cảm.
+- Cấm bypass SSL/TLS verification (`rejectUnauthorized: false`).
+- Cấm sử dụng trực tiếp string template cho SQL queries, phải dùng parameterized queries hoặc ORM an toàn.

package/.agents/rules/skill-quality.md

@@ -0,0 +1,14 @@
+# Skill Quality Rule
+
+Tiêu chuẩn định nghĩa, duy trì và loại bỏ skill trong V8.
+
+## Tiêu chuẩn tồn tại (Survival Standard)
+Mỗi skill khi được add hoặc duy trì phải thỏa mãn:
+1. **Decision Boundary Rõ Ràng**: Skill không được overlap scope với skill khác. Một task cụ thể chỉ nên resolve về đúng một skill duy nhất.
+2. **Metadata Đầy Đủ**: Bắt buộc tuân thủ schema V8 (có `intent`, `trigger`, `verification`, `workflow`).
+3. **Giá Trị Bền Vững**: Không tạo skill cho những snippet cấu hình đơn giản. Skill phải đại diện cho một "capability" (năng lực xử lý) có tính mở rộng.
+
+## Quy trình Audit Skill
+- **Đánh giá định kỳ**: Các skill sẽ được rà soát để đảm bảo không bị phình (bloat).
+- **Phát hiện trùng lặp**: Nếu phát hiện 2 skill có chung mục đích, cần tiến hành gộp (merge) lại và phân định ranh giới (ví dụ: chia implementation và governance).
+- **Loại bỏ**: Nếu skill không còn giá trị sử dụng hoặc đã được cover bởi core logic, đánh dấu `status: deprecated`. Không xóa ngay lập tức để giữ backward compatibility.