ai-developer-skill-os 7.0.2 → 7.5.0

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

@@ -1,40 +1,199 @@
----
-name: qk-project-health
-category: qa
-version: 7.0.0
-description: "Kiểm toán toàn diện Code Smells, Tech Debt, và Architecture."
----
-
-# qk-project-health
-
-## Scope
-- Technical Debt Auditing and System Health Monitoring (Evaluate)
-
-## Verbs
-- `[AUDIT]`: Evaluate the entire project's health.
-
-## Constraints
-```yaml
-must:
-  - "Identify deprecated packages and security vulnerabilities"
-  - "Map out technical debt explicitly"
-must_not:
-  - "Ignore compiler or strict-mode warnings"
-  - "Hide systemic architectural flaws"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Automated static analysis tools"
-  - "Actionable refactoring roadmaps"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Critical security vulnerabilities detected (CVSS High/Critical)"
-```
-
-## Output
-- Health report and Tech Debt mitigation plan.
+---
+name: qk-project-health
+category: qa
+version: 7.5.0
+description: "Kiểm toán toàn diện Code Smells, Tech Debt, Architecture — health score 0–100 với actionable roadmap."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [source-code]
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 100
+  max_shell_commands: 1
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-project-health — Complete Codebase Audit
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Project root is accessible
+
+---
+
+## Scope
+- ✅ Score 5 health dimensions (0–20 pts each = 100 total)
+- ✅ Identify deprecated packages and security vulnerabilities
+- ✅ Produce actionable refactoring roadmap
+
+## Non-Goals
+- ❌ Fix issues — report only
+- ❌ Hide systemic architectural flaws
+
+---
+
+## Health Scoring System
+
+| Dimension | Max Points | Key Checks |
+|-----------|-----------|------------|
+| Security | 20 | 0 critical CVEs, no hardcoded secrets, auth guards present |
+| Code Quality | 20 | Functions ≤ 30L, complexity ≤ 10, no God Files |
+| Architecture | 20 | Clean layers (UI/Logic/Data separated), no circular imports |
+| Dependencies | 20 | No deprecated packages, no unused deps, versions pinned |
+| Documentation | 20 | README complete, public APIs documented, DESIGN.md exists |
+
+**Total: 100 pts. Grades: A (90+) / B (75-89) / C (60-74) / D (<60)**
+
+---
+
+## Priority Order
+| P | Dimension | Never Skip? |
+|---|-----------|-------------|
+| P1 | Security | Yes |
+| P2 | Code Quality | Yes |
+| P3 | Architecture | Budget < 30% |
+| P4 | Dependencies | Budget < 50% |
+| P5 | Documentation | Budget < 60% |
+
+---
+
+## Workflow
+
+### Phase 1 — Quick Scan (P1+P2)
+1. `grep_search` for: hardcoded secrets, `eval(`, `any` types, `console.log`
+2. Sample 3 key files → check function lengths, file sizes
+3. Score Security (0–20) + Code Quality (0–20)
+
+### Phase 2 — Structure Scan (P3+P4)
+1. Read `package.json` — check outdated/deprecated packages
+2. Check import patterns for circular dependencies or layer violations
+3. Score Architecture (0–20) + Dependencies (0–20)
+
+### Phase 3 — Docs Scan (P5) + Report
+1. Check README, DESIGN.md, key function JSDoc
+2. Score Documentation (0–20)
+3. Generate full report + prioritized roadmap
+
+---
+
+## Evidence Format
+```
+[SEVERITY] Dimension: [SECURITY|QUALITY|ARCH|DEPS|DOCS]
+Finding:    [specific issue]
+Location:   [file:line OR package name]
+Confidence: HIGH
+Impact:     -N pts
+Fix:        [actionable suggestion]
+```
+
+---
+
+## Output Format
+```
+🏥 Project Health Report
+─────────────────────────────────────────────────
+Grade: [A|B|C|D] ([Score]/100)
+
+Scores:
+  Security:      [N/20]
+  Code Quality:  [N/20]
+  Architecture:  [N/20]
+  Dependencies:  [N/20]
+  Documentation: [N/20]
+
+Critical Issues (fix immediately):
+  [list CRITICAL findings]
+
+Refactoring Roadmap (priority order):
+  1. [Most impactful — estimated effort]
+  2. [Second — estimated effort]
+  3. [Third]
+
+Exit Code: [SUCCESS (A/B) | PARTIAL (C) | FAILED (D)]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Audit completed and report generated with scores | Normal completion |
+| PARTIAL | Audit completed but some directories skipped (token limit) | Large project |
+| BLOCKED | Project is empty or completely unreadable | Missing project |
+| FAILED | Cannot calculate score due to tool failure | Linter crashed |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Analyzed via AST, linters, or exhaustive search | Include in report as fact |
+| MEDIUM | Sampled a few files, assumed pattern holds | Note as "Project trend" |
+| LOW | Did not check | Do NOT include in report |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Security flaw or completely broken architecture | API keys committed, cyclical dependency |
+| HIGH | Major tech debt slowing down development | God objects, missing tests on core logic |
+| MEDIUM | Inconsistent patterns | Mixing fetch/axios, tabs/spaces |
+| LOW | Minor code smell | Magic numbers in UI |
+
+---
+
+## Retry Policy
+```
+Audit fails
+  └─ Token limit hit (project too large)
+       ├─ Ask user to narrow scope (e.g., audit only src/api/)
+       └─ Do NOT auto-retry full project scan
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Project unreadable or empty
+Missing:
+  - Source code
+Questions:
+  1. Thư mục mã nguồn chính nằm ở đâu? (ví dụ: src/, lib/)
+Recommended Assumptions:
+  - Scan typical directories (src, app, lib, test)
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": [],
+  "optional_fields": ["target_directory"]
+}
+```
+### Produces
+```json
+{
+  "to": "user or qk-system-evolution",
+  "output_fields": ["health_score", "critical_issues", "refactoring_roadmap", "exit_code"]
+}
+```
+
+---
+

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

@@ -1,40 +1,172 @@
----
-name: qk-project-memory
-category: core
-version: 7.0.0
-description: "Lưu trữ và truy xuất ngữ cảnh dự án dài hạn qua các phiên làm việc với độ chính xác cao."
----
-
-# qk-project-memory
-
-## Scope
-- Long-term context storage and retrieval (Plan & Collect)
-
-## Verbs
-- `[MEMORIZE]`: Store verified facts about the project.
-- `[RECALL]`: Retrieve facts strictly based on recorded memory.
-
-## Constraints
-```yaml
-must:
-  - "Verify facts against the actual codebase before storing them"
-  - "Timestamp and categorize memory entries"
-must_not:
-  - "Store assumptions or unverified AI hypotheses"
-  - "Overwrite fundamental architectural rules without explicit user consent"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Structured data formats (JSON/Markdown) for memory storage"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Memory conflicts with the core AGENTS.md rules"
-```
-
-## Output
-- Context retrieval results or stored memory artifacts.
+---
+name: qk-project-memory
+category: core
+version: 7.5.0
+description: "Lưu trữ và truy xuất ngữ cảnh dự án dài hạn — chỉ lưu fact đã xác minh, không lưu giả thuyết."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: low
+latency: fast
+risk: low
+side_effects: edit_files
+produces: [plan]
+consumes: [source-code, context-graph]
+token_budget:
+  max_files_read: 2
+  max_lines_per_read: 100
+  max_shell_commands: 0
+  stop_early: true
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-project-memory — Long-Term Context Store
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Project has a `.agents/memory/` directory OR user confirms creation
+
+---
+
+## Scope
+- ✅ Store verified facts about project (architecture, decisions, patterns)
+- ✅ Retrieve facts for current session context
+- ✅ Invalidate stale entries when code changes
+
+## Non-Goals
+- ❌ Store assumptions or unverified hypotheses
+- ❌ Overwrite architectural rules without explicit user consent
+- ❌ Store sensitive data (env vars, secrets)
+
+---
+
+## Memory Schema (Required Format)
+
+```json
+{
+  "id": "mem_[timestamp]",
+  "category": "architecture|pattern|decision|warning|preference",
+  "fact": "[Verified, specific statement]",
+  "evidence": "path/to/file.ts:LINE",
+  "confidence": "HIGH|MEDIUM",
+  "created_at": "ISO8601",
+  "expires_at": "ISO8601 OR null (permanent)",
+  "tags": ["auth", "database", "api"]
+}
+```
+
+---
+
+## Storage Path
+```
+.agents/memory/
+├── architecture.json    # System architecture facts
+├── patterns.json        # Established code patterns
+├── decisions.json       # Technical decisions made
+└── warnings.json        # Known risks or debt items
+```
+
+---
+
+## [MEMORIZE] Workflow
+1. Verify fact against actual codebase (grep_search or view_file)
+2. Confirm confidence is HIGH or MEDIUM
+3. Write to appropriate `.agents/memory/[category].json` file
+
+**Decision:** `IF confidence is LOW → do NOT store — collect more evidence`
+
+## [RECALL] Workflow
+1. Read relevant memory file
+2. Check `expires_at` — skip stale entries
+3. Return matching facts with their evidence references
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Fact stored/retrieved with verified evidence | HIGH/MEDIUM confidence |
+| PARTIAL | Fact stored but evidence is indirect (MEDIUM confidence) | Indirect source |
+| BLOCKED | Cannot verify fact against codebase | No evidence available |
+| FAILED | Memory file corrupted or schema mismatch | Structural error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Fact directly read from code (grep_search returned file:line) | Store immediately |
+| MEDIUM | Fact inferred from patterns (not direct file reference) | Store with note: "inferred" |
+| LOW | Assumption without code evidence | Do NOT store — collect more evidence first |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|----------|
+| CRITICAL | Storing incorrect architectural fact misleads all future work | Wrong auth pattern stored |
+| HIGH | Storing stale fact that conflicts with current code | Outdated API path remembered |
+| MEDIUM | Missing important fact causing repeated re-discovery | Auth pattern unknown |
+| LOW | Memory file not organized by category | All facts in one file |
+
+---
+
+## Evidence Format
+```
+[CONFIDENCE] path/to/file.ts:LINE
+Fact:       [what was stored]
+Category:   [architecture|pattern|decision|warning|preference]
+Expires:    [ISO8601 date | null]
+```
+
+---
+
+## Retry Policy
+```
+Fact unverifiable
+  └─ Read 1 more file for evidence
+       ├─ Evidence found → upgrade to MEDIUM/HIGH → store
+       └─ Still unverifiable → do NOT store
+            └─ Do NOT retry more than 1 additional evidence read
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Cannot verify fact against codebase
+Missing:
+  - Access to relevant source file
+  - Or explicit user confirmation
+Questions:
+  1. Bạn có thể xác nhận: [fact statement] là đúng không?
+Recommended Assumptions:
+  - Do NOT store until confirmed
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user or any skill",
+  "required_fields": ["fact_statement"],
+  "optional_fields": ["evidence_location", "expiry_date", "category"]
+}
+```
+### Produces
+```json
+{
+  "to": "any downstream skill",
+  "output_fields": ["recalled_facts", "confidence_levels", "evidence_refs", "exit_code"]
+}
+```
+
+---
+