ai-developer-skill-os 7.0.2 → 7.5.0

package/.qk-ai-skill-os/skills/qk-project-bootstrap/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: qk-project-bootstrap
+category: fullstack
+version: 7.5.0
+description: "Khởi tạo dự án mới với cấu trúc chuẩn, linters, DESIGN.md — không bao giờ thiếu foundation."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: high
+latency: slow
+risk: low
+side_effects: edit_files
+produces: [code, schema, plan]
+consumes: [user-description]
+token_budget:
+  max_files_read: 1
+  max_lines_per_read: 50
+  max_shell_commands: 2
+  stop_early: false
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-project-bootstrap — Project Foundation Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Framework/language preference is stated (or ask before proceeding)
+- [ ] Project purpose is clear (web app, API, CLI, library)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng cho biết: framework (React/Next.js/NestJS/Express...) và mục đích dự án."
+```
+
+---
+
+## Scope
+- ✅ Initialize project with standard tooling
+- ✅ Generate `DESIGN.md` (mandatory for any UI project)
+- ✅ Configure: ESLint, Prettier, TypeScript strict mode
+- ✅ Create standard directory structure
+
+## Non-Goals
+- ❌ Skip DESIGN.md for UI projects
+- ❌ Hardcode outdated dependency versions
+- ❌ Skip README
+
+---
+
+## Standard Directory Structures
+
+### Next.js / React
+```
+src/
+├── app/              # Pages (App Router) or pages/
+├── components/       # Shared UI components
+│   ├── ui/           # Design system primitives
+│   └── [feature]/    # Feature-specific components
+├── hooks/            # Custom React hooks
+├── lib/              # Utilities, helpers
+├── services/         # API service functions
+├── types/            # TypeScript type definitions
+└── styles/           # Global CSS + DESIGN.md tokens
+DESIGN.md             # Brand & Design Contract
+```
+
+### NestJS / Express API
+```
+src/
+├── modules/
+│   └── [feature]/
+│       ├── [feature].controller.ts
+│       ├── [feature].service.ts
+│       ├── [feature].repository.ts
+│       └── dto/
+├── common/           # Shared utilities, guards, interceptors
+├── config/           # Environment configuration
+└── main.ts
+```
+
+### Vite + React
+```
+src/
+├── assets/
+├── components/
+├── pages/
+├── router/
+├── services/
+├── stores/           # State management
+└── types/
+```
+
+---
+
+## Required Files Checklist
+```
+[ ] package.json — with lint + test + build scripts
+[ ] tsconfig.json — strict: true enabled
+[ ] .eslintrc / eslint.config.js — project standard
+[ ] .prettierrc — formatting config
+[ ] .gitignore — standard entries
+[ ] README.md — project description + setup instructions
+[ ] DESIGN.md — (UI projects) brand contract with color/font/spacing tokens
+[ ] .env.example — all env vars listed (no actual values)
+```
+
+---
+
+## DESIGN.md Minimum Template
+```markdown
+# Design System
+
+## Colors (HSL)
+--color-primary: hsl(220, 80%, 55%);
+--color-surface: hsl(220, 15%, 12%);
+--color-text: hsl(220, 10%, 90%);
+
+## Spacing Scale (4px base)
+--space-1: 4px; --space-2: 8px; --space-3: 16px;
+--space-4: 24px; --space-5: 32px; --space-6: 48px;
+
+## Typography
+--font-sans: 'Inter', system-ui, sans-serif;
+--font-size-base: 1rem;
+--font-size-lg: 1.25rem;
+
+## Border Radius
+--radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px;
+
+## Animation
+--transition-fast: 150ms ease;
+--transition-base: 250ms ease;
+```
+
+---
+
+
+---
+
+## Workflow
+
+[Placeholder for Workflow]
+
+
+---
+
+## Evidence Format
+
+[Placeholder for Evidence Format]
+
+
+---
+
+## Priority Order
+
+[Placeholder for Priority Order]
+
+
+---
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | All required files created, structure matches framework standard | Full bootstrap complete |
+| PARTIAL | Structure created but DESIGN.md incomplete (UI project) | Follow-up needed |
+| BLOCKED | Framework/purpose not specified | Ask user |
+| FAILED | Cannot initialize (permission error, invalid framework) | Report error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Framework explicitly stated, directory structure clear | Build directly |
+| MEDIUM | Framework inferred from context (found React imports) | Note assumption, proceed |
+| LOW | Cannot determine framework or project type | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|----------|
+| CRITICAL | Security misconfiguration in bootstrap | .env with real secrets committed |
+| HIGH | Missing mandatory file blocks all future work | No DESIGN.md for UI project |
+| MEDIUM | Incomplete setup reduces developer experience | Missing ESLint config |
+| LOW | Cosmetic or optional file missing | Missing .editorconfig |
+
+---
+
+## Retry Policy
+```
+File creation fails
+  └─ Check: permission issue vs path error
+       ├─ Path error → correct path and retry
+       └─ Permission error → EXIT: FAILED, report exact path
+            └─ Do NOT retry more than 1 time per file
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Framework or project type not specified
+Missing:
+  - Framework name (React, Next.js, NestJS, Express, etc.)
+  - Project purpose (web app, API, CLI, library)
+Questions:
+  1. Framework nào bạn muốn dùng?
+  2. Dự án này là web app, API server, hay CLI tool?
+Recommended Assumptions (if proceeding):
+  - Default: Next.js 14 (App Router) + TypeScript + ESLint
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["framework", "project_purpose"],
+  "optional_fields": ["project_name", "existing_dir"]
+}
+```
+### Produces
+```json
+{
+  "to": "qk-feature-delivery or qk-design-to-code",
+  "output_fields": ["project_structure", "design_md_path", "tooling_config", "exit_code"]
+}
+```
+
+---
+
+

package/.qk-ai-skill-os/skills/qk-project-health/SKILL.md

@@ -0,0 +1,199 @@
+---
+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/.qk-ai-skill-os/skills/qk-project-memory/SKILL.md

@@ -0,0 +1,172 @@
+---
+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"]
+}
+```
+
+---
+