ai-developer-skill-os 7.0.2 → 7.5.1

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

@@ -0,0 +1,351 @@
+---
+name: qk-engineering-standard
+category: qa
+version: 7.5.0
+description: "Ép buộc SOLID, DRY, Clean Code với ngưỡng số liệu cụ thể — không có rule mơ hồ."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: medium
+risk: low
+side_effects: read_only
+produces: [report]
+consumes: [source-code]
+
+token_budget:
+  max_files_read: 5
+  max_lines_per_read: 150
+  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-engineering-standard — Code Quality Enforcer
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] Target file(s) or module(s) are specified
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Vui lòng chỉ định file hoặc module cần kiểm tra."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Detect violations with exact file:line references
+- ✅ Classify by severity with concrete thresholds
+- ✅ Suggest minimal, targeted refactors
+
+## Non-Goals
+- ❌ Auto-fix code — report only (fixes go to qk-bug-resolution or qk-feature-delivery)
+- ❌ Rewrite architecture
+- ❌ Touch files outside the specified scope
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Concrete Thresholds (Non-Negotiable)
+
+```yaml
+function:
+  max_lines: 30              # Lines of code, excluding comments/blanks
+  max_cyclomatic_complexity: 10
+  max_parameters: 4
+
+file:
+  max_lines: 300
+  max_public_methods_per_class: 10  # God Class threshold
+
+dry:
+  violation_threshold: 3    # Same logic duplicated in ≥ 3 places
+
+separation_of_concerns:
+  violation: "File mixes UI rendering + API calls + State management"
+
+naming:
+  min_variable_name_length: 2  # Single-letter vars (except i,j,k in loops)
+  max_abbreviation_ratio: 0.3  # > 30% abbreviations in identifiers = violation
+
+dependency:
+  max_imports_per_file: 15  # Beyond this: likely a God File
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Check | Severity | Skip Threshold |
+|----------|-------|----------|----------------|
+| P1 | Security violations (hardcoded secrets, SQL injection) | CRITICAL | Never |
+| P2 | God Functions > 30 lines / complexity > 10 | HIGH | Budget < 30% |
+| P3 | God Files > 300 lines / God Classes | HIGH | Budget < 40% |
+| P4 | DRY violations (3+ duplicates) | MEDIUM | Budget < 50% |
+| P5 | Mixed concerns in single file | MEDIUM | Budget < 60% |
+| P6 | Naming convention violations | LOW | Budget < 70% |
+| P7 | Excessive imports / coupling | LOW | Budget < 80% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Scan for Critical & High Violations
+
+**Steps:**
+1. `grep_search` — search for: hardcoded secrets, `console.log`, `eval(`, `any` types
+2. `view_file[targeted]` — read function definitions to count lines and parameters
+3. Log each violation with Evidence Format
+
+**Decision:**
+```
+IF CRITICAL violation found (e.g., hardcoded API key)
+  → Report immediately, mark EXIT: FAILED
+  → Still continue scanning (don't stop at first critical)
+
+IF function line count > 30 OR complexity > 10
+  → Log as [HIGH]
+
+IF file line count > 300
+  → Log as [HIGH] — God File suspected
+```
+
+**Exit When:**
+- All P1+P2+P3 checks done → go to Phase 2
+- Token budget < 30% → go to Phase 3 directly with PARTIAL flag
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Scan for Medium & Low Violations
+
+**Steps:**
+1. `grep_search` — find duplicate logic patterns (copy-paste code)
+2. Check import counts per file
+3. Check naming conventions
+
+**Decision:**
+```
+IF same logic block appears ≥ 3 times
+  → Log as [MEDIUM] DRY violation
+
+IF file has > 15 imports
+  → Log as [LOW] — potential God File or tight coupling
+
+IF token budget < 50%
+  → Skip P6+P7, go to Phase 3
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Score & Report
+
+**Steps:**
+1. Count violations by severity
+2. Calculate health score: start at 100, deduct per violation
+3. Generate report
+
+**Deduction Scale:**
+```
+CRITICAL: -25 pts each
+HIGH:     -10 pts each
+MEDIUM:   -5 pts each
+LOW:      -2 pts each
+```
+
+**Decision:**
+```
+IF score ≥ 80 AND no CRITICAL violations
+  → EXIT: SUCCESS
+
+IF score 60–79 OR any HIGH violations
+  → EXIT: PARTIAL — list fixes needed
+
+IF score < 60 OR any CRITICAL violations
+  → EXIT: FAILED — requires immediate action
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Direct line count, exact pattern match | Report as violation |
+| MEDIUM | Inferred cyclomatic complexity without tool | Note estimate |
+| LOW | Architectural smell inferred from structure | Mark as "suspected — verify manually" |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Severity
+
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Security risk or data integrity | Hardcoded secret, SQL injection via string concat |
+| HIGH | Technical debt that blocks scaling | Function 80 lines, God Class 15+ methods |
+| MEDIUM | DRY or SoC violation, fixable in < 1 hour | Same validation logic in 3 components |
+| LOW | Style/naming issue, non-blocking | Single-letter variable `x` outside loop |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[SEVERITY] path/to/file.ts:LINE
+Rule:       [FUNCTION_LENGTH | COMPLEXITY | DRY | SOC | NAMING | GOD_CLASS | SECRET]
+Reason:     [specific measurement vs threshold]
+Confidence: [HIGH|MEDIUM|LOW]
+Fix:        [one-line suggestion]
+Deduction:  -N pts
+```
+
+**Example:**
+```
+[HIGH] src/services/order.service.ts:45
+Rule:       FUNCTION_LENGTH
+Reason:     Function `processOrder` is 87 lines (threshold: 30)
+Confidence: HIGH
+Fix:        Extract payment logic to `processPayment()`, shipping to `scheduleShipment()`
+Deduction:  -10 pts
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Retry Policy
+```
+Audit is read-only — no retry needed.
+If file is inaccessible → skip and note in report as PARTIAL.
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Escalation Rules
+
+```
+BLOCKED: No target specified
+Missing:
+  - File path or module name to audit
+Questions:
+  1. Bạn muốn kiểm tra file nào hoặc toàn bộ module nào?
+  2. Có ngưỡng cụ thể nào bạn muốn thay đổi không? (mặc định: 30 lines/function)
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user or qk-orchestrator",
+  "required_fields": ["target_files_or_module"],
+  "optional_fields": ["custom_thresholds"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["health_score", "violations_list", "severity_counts", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+⚙️ Engineering Standard Audit
+─────────────────────────────────────────────────
+Target:      [file or module]
+
+Health Score: [X/100]
+  CRITICAL violations: [N] (-Npts)
+  HIGH violations:     [N] (-Npts)
+  MEDIUM violations:   [N] (-Npts)
+  LOW violations:      [N] (-Npts)
+
+Violations (priority order):
+  [SEVERITY] file:LINE — Rule — reason — Fix — (-Xpts)
+
+Required Actions:
+  1. [Most critical fix]
+  2. [Second fix]
+
+Exit Code:   [SUCCESS | PARTIAL | FAILED]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Score ≥ 80, no CRITICAL | Code meets V7.5 standards |
+| PARTIAL | Score 60–79 or incomplete scan | Some categories skipped |
+| BLOCKED | No target specified | Cannot audit without scope |
+| FAILED | Score < 60 or CRITICAL found | Immediate action required |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## References
+- Detailed thresholds with rationale: `references/thresholds.md`
+
+---
+

package/.agents/skills/qk-engineering-standard/rules/backend.md

@@ -0,0 +1,122 @@
+# Backend Rules
+
+- Define rules here.
+
+---
+
+## 🔄 [Merged from qk-backend-architecture]
+
+# Backend Architecture
+
+> **Language rule:**
+> Use English for: code, identifiers, file names, architecture terms, technical decisions.
+> Use the user's language for: explanations, questions, summaries, and feedback.
+> The user may write in any language — detect and match it automatically.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- Creating new backend API endpoints, services, or models
+- User asks "where should I put this business logic?"
+- Project audit flags mixed concerns (e.g., SQL queries inside a controller)
+- Inheriting or setting up a Node.js, Python, or Go backend
+
+---
+
+## Scope
+
+- ✅ Discover existing backend folder structure
+- ✅ Enforce Layered Architecture (Controller → Service → Data Access)
+- ✅ Enforce Domain/Module-based structure if applicable (`src/users/`, `src/orders/`)
+- ✅ Define where validation, mapping, and error handling should live
+- ✅ Validate file placement before code generation
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the architecture unless requested
+- ❌ Do NOT write the actual database queries (delegate to `database-engineer`)
+- ❌ Do NOT configure server infrastructure (delegate to `deployment`)
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Circular dependency or security bypass in architecture |
+| P1 | Mixed concerns (e.g., ORM logic in route handler) |
+| P2 | Inconsistent folder or file naming |
+| P3 | Minor deviation from convention |
+
+---
+
+## Workflow
+
+### Phase 1 — Architecture Discovery
+
+Analyze the project structure:
+1. **Classic MVC / Layered:** `controllers/`, `services/`, `models/`, `routes/`
+2. **Domain-Driven (Module):** `src/modules/user/{controller, service, repository}`
+3. **Framework-specific:** NestJS (`.controller.ts`, `.service.ts`), Django apps, Express monolithic.
+4. **Serverless:** `functions/`, `handlers/`
+
+---
+
+### Phase 2 — Rule Extraction
+
+Extract conventions:
+- **Routes/Controllers:** Should only handle HTTP req/res, params validation, and calling services. No business logic.
+- **Services:** Pure business logic. Does not know about HTTP (`req`/`res`).
+- **Repositories/Data Access:** Only layer that interacts with the DB.
+- **Error Handling:** Centralized error middleware vs local try/catch.
+
+---
+
+### Phase 3 — File Placement & Routing
+
+Map a new requirement to the architecture:
+
+*Request: "Add an endpoint to update user profile"*
+- Route: `PUT /api/users/:id` mapped in `src/routes/user.routes.ts`
+- Controller: `updateProfile(req, res)` in `src/controllers/user.controller.ts`
+- Service: `updateUserProfile(userId, data)` in `src/services/user.service.ts`
+
+---
+
+## Decision Tree
+
+```
+Does the project group files by Layer or by Domain?
+  ├── Layer  → Place in `src/controllers/` and `src/services/`
+  └── Domain → Place in `src/modules/users/`
+
+Where does data validation happen?
+  ├── Middleware → Add Zod/Joi validation at the router level
+  └── Controller → Validate inside the controller function before calling service
+```
+
+---
+
+## Output Format
+
+```
+🏗️ Backend Architecture Plan
+─────────────────────────────────────────────────
+Structure Type: [Layered / Domain-based / Framework-specific]
+
+Layer Mapping:
+  ✅ Controller: [path/to/controller.ts] — handles HTTP
+  ✅ Service:    [path/to/service.ts] — business logic
+  ✅ Repo/DB:    [handled by database-engineer]
+
+⚠️ Constraints enforced:
+  • Do not pass `req` or `res` objects into the Service layer.
+  • Validate all inputs at the Controller/Route level.
+
+🔗 Next Steps:
+  Proceeding to implement the layers.
+```

package/.agents/skills/qk-engineering-standard/rules/database.md

@@ -0,0 +1,3 @@
+# Database Rules
+
+- Define rules here.

package/.agents/skills/qk-engineering-standard/rules/frontend.md

@@ -0,0 +1,152 @@
+# Frontend Rules
+
+- Define rules here.
+
+---
+
+## 🔄 [Merged from qk-frontend-architecture]
+
+# Frontend Architecture
+
+> **Language rule:**
+> Use English for: code, identifiers, file names, architecture terms, technical decisions.
+> Use the user's language for: explanations, questions, summaries, and feedback.
+> The user may write in any language — detect and match it automatically.
+
+---
+
+## Trigger
+
+Activate this skill when:
+- About to create new files or components
+- User asks "where should I put this file?" or "how should I organize this?"
+- Moving or refactoring code across different modules
+- Inheriting an unfamiliar frontend project
+
+---
+
+## Scope
+
+- ✅ Discover the existing frontend folder structure
+- ✅ Define where new components, hooks, services, and types should be placed
+- ✅ Enforce separation of concerns (e.g., UI vs. Business Logic vs. Data)
+- ✅ Identify architectural patterns in use (e.g., Feature-based, Layer-based)
+- ✅ Validate file placement before execution by other skills
+
+---
+
+## Non-goals
+
+- ❌ Do NOT rewrite the entire project architecture unless explicitly asked
+- ❌ Do NOT generate code (delegate to `component-generator` or `ui-builder`)
+- ❌ Do NOT enforce personal preferences over established project conventions
+
+---
+
+## Severity Levels
+
+| Level | Meaning |
+|-------|---------|
+| P0 | Architectural violation that breaks the build or creates circular dependencies |
+| P1 | File placed in completely wrong layer (e.g., API logic in UI component) |
+| P2 | Inconsistent folder or file naming |
+| P3 | Minor deviation from convention |
+
+---
+
+## Workflow
+
+### Phase 1 — Structure Discovery
+
+*(Relies on `context-manager` if already loaded)*
+
+Analyze the root source directory (e.g., `src/`, `app/`):
+1. **Layer-based:** `components/`, `hooks/`, `services/`, `utils/`, `types/`
+2. **Feature-based:** `features/auth/`, `features/products/`
+3. **Framework-specific:** `app/` (Next.js App Router), `pages/` (Next.js Pages Router, Nuxt)
+4. **Domain-driven:** `domains/user/`, `domains/payment/`
+5. **FSD (Feature Sliced Design):** `app/`, `processes/`, `pages/`, `widgets/`, `features/`, `entities/`, `shared/`
+
+---
+
+### Phase 2 — Rule Extraction
+
+Based on discovery, define the project's rules for:
+- **Components:** Are they flat? Grouped by feature? Atomic design?
+- **Hooks:** Shared in `src/hooks/` or collocated with components?
+- **State:** Global store vs. feature stores?
+- **API/Services:** Where are HTTP calls made?
+- **Types:** Centralized `types/` or collocated?
+- **Naming Conventions:** PascalCase, camelCase, kebab-case, `index.ts` usage?
+
+---
+
+### Phase 3 — File Placement Decision
+
+When a new feature/component is requested, map it to the structure:
+
+**Input:** "Create a User Profile card that fetches user data."
+**Decision:**
+- UI Component: `src/features/user/components/UserProfileCard.tsx`
+- API Hook: `src/features/user/api/useUser.ts`
+- Types: `src/features/user/types/index.ts`
+
+---
+
+### Phase 4 — Enforcement & Validation
+
+Before passing control to a generation skill (like `ui-builder`), ensure the plan adheres to the rules.
+
+- [ ] Does it mix concerns? (e.g., putting an API call directly in a shared UI button)
+- [ ] Does it violate import boundaries? (e.g., a shared component importing from a specific feature)
+- [ ] Is the naming consistent?
+
+---
+
+## Decision Tree
+
+```
+Is the project using a Feature-based structure?
+  ├── Yes → Place feature-specific code in `features/<feature-name>/`
+  └── No  → Use Layer-based structure (`components/`, `hooks/`, etc.)
+
+Is the code shared across multiple domains/features?
+  ├── Yes → Place in `shared/` or global `components/` / `hooks/`
+  └── No  → Collocate with the specific domain/feature
+
+Are there existing examples of this type of file?
+  ├── Yes → Copy their placement and naming pattern
+  └── No  → Propose a standard location and ask user to confirm
+```
+
+---
+
+## Output Format
+
+```
+🏗️ Frontend Architecture Plan
+─────────────────────────────────────────────────
+Structure Type: [Feature-based / Layer-based / FSD / etc.]
+Naming:         [PascalCase for components, camelCase for functions]
+
+File Placement:
+  📄 [path/to/new/file1.tsx] — [Why it goes here]
+  📄 [path/to/new/file2.ts]  — [Why it goes here]
+
+⚠️ Constraints enforced:
+  • [Constraint 1, e.g., "API calls must be in hooks, not components"]
+  • [Constraint 2, e.g., "Shared UI components cannot import from features/"]
+
+🔗 Next Steps:
+  Delegating to `[skill-name]` to generate the files.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Structure type identified correctly
+- [ ] File placement follows existing conventions
+- [ ] Naming matches project standards
+- [ ] Separation of concerns maintained
+- [ ] Plan ready to be executed by generation skills

package/.agents/skills/qk-engineering-standard/rules/security.md

@@ -0,0 +1,3 @@
+# Security Rules
+
+- Define rules here.

package/.agents/skills/qk-engineering-standard/rules/testing.md

@@ -0,0 +1,3 @@
+# Testing Rules
+
+- Define rules here.