ai-developer-skill-os 7.0.2 → 7.5.1

package/skills/qk-production-release/SKILL.md

@@ -1,41 +1,285 @@
----
-name: qk-production-release
-category: devops
-version: 7.0.0
-description: "Chuẩn bị codebase phát hành Production với các cổng kiểm duyệt an ninh tuyệt đối."
----
-
-# qk-production-release
-
-## Scope
-- Production builds, CI/CD pipelines, and Security gating (Execute)
-
-## Verbs
-- `[RELEASE]`: Prepare and sign off on a production-ready artifact.
-
-## Constraints
-```yaml
-must:
-  - "Run full suite of linters, tests, and security scans (Validation Gate) before release"
-  - "Minify and strip out all debug/console logs"
-must_not:
-  - "Release if ANY high-priority bug is unresolved"
-  - "Deploy with dev-environment secrets or configurations"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Automated CI/CD validation over manual checks"
-  - "Immutable build artifacts"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Tests fail during the release build"
-  - "Environment variables for production are missing"
-```
-
-## Output
-- Production-ready build artifacts and deployment scripts.
+---
+name: qk-production-release
+category: devops
+version: 7.5.1
+description: "Chuẩn bị release production với 8-gate checklist bắt buộc — không pass gate = không deploy."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: medium
+latency: slow
+risk: high
+side_effects: run_commands
+produces: [report, plan]
+consumes: [validation-gate-result, source-code]
+
+token_budget:
+  max_files_read: 3
+  max_lines_per_read: 100
+  max_shell_commands: 2
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-production-release — Release Gate
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] `qk-validation-gate` has been run and returned SUCCESS or PARTIAL
+- [ ] All HIGH priority bugs are resolved
+- [ ] Production environment variables are configured (not dev)
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "qk-validation-gate must pass before release. Run it first."
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Run 8-gate release checklist
+- ✅ Verify no dev artifacts in production build
+- ✅ Verify environment configuration
+
+## Non-Goals
+- ❌ Fix bugs — that's `qk-bug-resolution`
+- ❌ Deploy to infrastructure — that's DevOps/CI system
+- ❌ Skip any gate unless user explicitly overrides
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Gate | Block Release? |
+|----------|------|---------------|
+| P1 | Validation gate result (from qk-validation-gate) | YES — hard block |
+| P2 | No unresolved HIGH/CRITICAL bugs | YES — hard block |
+| P3 | No `console.log` / debug artifacts in src/ | YES — hard block |
+| P4 | .env.production exists (not .env.development) | YES — hard block |
+| P5 | Build succeeds in production mode | YES — hard block |
+| P6 | Bundle size within limit (< 500KB gzipped) | WARN only |
+| P7 | No dev dependencies in production build | YES — hard block |
+| P8 | CHANGELOG.md updated with release notes | WARN only |
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Release Checklist (Mandatory)
+
+```
+[ ] P1: qk-validation-gate: SUCCESS
+[ ] P2: 0 unresolved HIGH/CRITICAL bugs
+[ ] P3: grep -r "console.log\|debugger" src/ → empty
+[ ] P4: .env.production configured, NODE_ENV=production
+[ ] P5: npm run build (production mode) → exit 0
+[ ] P6: Bundle size ≤ 500KB gzipped (warn if exceeded)
+[ ] P7: npm audit --production → 0 critical/high
+[ ] P8: CHANGELOG.md has entry for this release
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Pre-flight Checks (P1–P4)
+
+**Steps:**
+1. Verify validation-gate result (check previous output or re-read)
+2. `grep_search` for `console.log`, `debugger`, `TODO:`, `FIXME:`
+3. Check for `.env.production` vs `.env.development` configuration
+
+**Decision:**
+```
+IF any P1–P4 check fails
+  → EXIT: FAILED immediately
+  → Report which gate failed and exact fix required
+
+IF all P1–P4 pass
+  → go to Phase 2
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Build & Size Gate (P5–P7)
+
+**Steps:**
+1. (If allowed) `npm run build` — 1 command used
+2. Check bundle size if measurable
+3. `npm audit --production` — 2nd command
+
+**Decision:**
+```
+IF build fails
+  → EXIT: FAILED
+
+IF bundle size > 500KB
+  → Note as WARNING, do not block
+
+IF production audit has critical/high
+  → EXIT: FAILED
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Release Report
+
+Generate signed release report with all gate results.
+
+**Decision:**
+```
+IF all hard-block gates pass
+  → EXIT: SUCCESS — safe to deploy
+
+IF only WARN gates failed (P6, P8)
+  → EXIT: PARTIAL — deploy with noted caveats
+
+IF any hard-block gate failed
+  → EXIT: FAILED — do NOT deploy
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format
+
+```
+[SEVERITY] Gate: [P1-P8 name]
+Check:      [what was checked]
+Result:     [PASS | FAIL | WARN]
+Threshold:  [what the rule is]
+Actual:     [what was found]
+Fix:        [what must be done before release]
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Escalation Rules
+
+```
+BLOCKED: qk-validation-gate not run
+Missing:
+  - Run qk-validation-gate first and share the result
+Questions:
+  1. Validation gate đã chạy chưa?
+  2. Có bug nào HIGH/CRITICAL chưa fix không?
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "qk-validation-gate",
+  "required_fields": ["gate_result", "coverage_percent"],
+  "optional_fields": ["bundle_size", "changelog_entry"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "CI/CD system or user",
+  "output_fields": ["release_checklist_result", "gates_passed", "gates_failed", "exit_code"]
+}
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🚀 Production Release Gate
+─────────────────────────────────────────────────
+Version:    [vX.Y.Z]
+Date:       [YYYY-MM-DD]
+
+Gate Results:
+  P1 Validation:    [✅ PASS | ❌ FAIL]
+  P2 Open Bugs:     [✅ 0 HIGH/CRITICAL | ❌ N unresolved]
+  P3 Debug Cleanup: [✅ Clean | ❌ N artifacts found]
+  P4 Environment:   [✅ Production config | ❌ Dev config detected]
+  P5 Build:         [✅ SUCCESS | ❌ FAILED]
+  P6 Bundle Size:   [✅ NKB | ⚠️ NKB > 500KB]
+  P7 Security:      [✅ Clean | ❌ N critical/high]
+  P8 Changelog:     [✅ Updated | ⚠️ Missing]
+
+Verdict:    [✅ SAFE TO DEPLOY | ❌ DO NOT DEPLOY — fix: list]
+Exit Code:  [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+skill_version: 7.5.1
+runtime_version: 1
+schema_version: 2
+---
+
+
+---
+
+## Confidence Model
+
+
+---
+
+## Severity
+
+
+---
+
+## Retry Policy
+
+
+---
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | All hard-block gates pass | Deploy approved |
+| PARTIAL | Hard gates pass, warnings exist | Deploy with noted caveats |
+| BLOCKED | Prerequisites missing | Run validation-gate first |
+| FAILED | Any hard gate failed | Do NOT deploy |
+
+---
+
+
+

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

@@ -1,38 +1,236 @@
----
-name: qk-project-bootstrap
-category: fullstack
-version: 7.0.0
-description: "Khởi tạo dự án mới với các best practices, linters, và cấu trúc thư mục chuẩn."
----
-
-# qk-project-bootstrap
-
-## Scope
-- Initializing new projects with best practices (Execute)
-
-## Constraints
-```yaml
-must:
-  - Setup linters, formatters, and standard directory structures
-  - Follow the organization's existing templates if available
-  - ALWAYS generate a `DESIGN.md` file in the project root to serve as the Brand Contract (Open Design standard). MUST prompt the user for design constraints if none are provided.
-must_not:
-  - Hardcode outdated dependency versions
-  - Skip adding basic README instructions
-```
-
-## Policies
-```yaml
-prefer:
-  - Standard tooling over custom scripts
-```
-
-## Escalation
-```yaml
-ask:
-  - To clarify preferred framework/language if not specified
-```
-
-## Output
-- Bootstrapped repository structure
-```
+---
+name: qk-project-bootstrap
+category: fullstack
+version: 7.5.1
+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.1
+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
+
+
+---
+
+## Evidence Format
+
+
+---
+
+## 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-ui-builder",
+  "output_fields": ["project_structure", "design_md_path", "tooling_config", "exit_code"]
+}
+```
+
+---
+
+
+
+