ai-developer-skill-os 7.0.2 → 7.5.0

package/skills/qk-design-to-code/SKILL.md

@@ -1,46 +1,285 @@
----
-name: qk-design-to-code
-category: frontend
-version: 7.0.0
-description: "Chuyển đổi thiết kế từ Figma/Images thành các UI component hoàn chỉnh, chuẩn pixel."
----
-
-# qk-design-to-code
-
-## Scope
-- Converting Figma/UI designs into pixel-perfect frontend code (Execute)
-- Rejecting generic templates and enforcing bespoke, high-quality aesthetics.
-
-## Verbs
-- `[REDESIGN]`: Discard generic UI structure, keep data, and rebuild with strict Hallmark/Open Design principles.
-- `[BUILD]`: Generate UI adhering 100% to `DESIGN.md`.
-
-## Constraints
-```yaml
-must:
-  - Use the project's existing `DESIGN.md` design system / tokens ONLY
-  - Ensure responsive layouts and generous whitespace
-  - Include micro-interactions and smooth transitions
-must_not:
-  - Hardcode magic numbers for spacing/colors
-  - Invent new UI components if existing ones suffice
-  - Use generic "AI-slop" aesthetics (e.g., default Tailwind blue/red, cluttered layouts, 1px default borders)
-```
-
-## Policies
-```yaml
-prefer:
-  - Semantic HTML elements
-  - CSS Grid / Flexbox over absolute positioning
-  - High-end aesthetics (glassmorphism, organic shadows, exact typography)
-```
-
-## Escalation
-```yaml
-stop:
-  - "Design assets or requirements are ambiguous"
-  - "DESIGN.md is missing"
-```
-
-## Output
-- Frontend components and stylesheets (Anti-Slop compliant)
+---
+name: qk-design-to-code
+category: frontend
+version: 7.5.0
+description: "Chuyển thiết kế Figma/Image thành UI component chuẩn pixel — zero AI-slop, 100% DESIGN.md."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+
+cost: high
+latency: slow
+risk: low
+side_effects: edit_files
+produces: [code]
+consumes: [design-md, design-asset]
+
+token_budget:
+  max_files_read: 4
+  max_lines_per_read: 150
+  max_shell_commands: 0
+  stop_early: false
+
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+# qk-design-to-code — Pixel-Perfect Builder
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Preconditions
+- [ ] `DESIGN.md` exists with color tokens, spacing scale, typography
+- [ ] Design reference (Figma link, image, or wireframe description) provided
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "DESIGN.md missing or design reference not provided."
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Scope
+- ✅ Build UI from design reference using ONLY DESIGN.md tokens
+- ✅ Include all interactive states: hover, focus, active, disabled, loading
+- ✅ Responsive layouts (mobile + desktop)
+- ✅ Semantic HTML with ARIA roles
+
+## Non-Goals
+- ❌ Invent design tokens not in DESIGN.md
+- ❌ Use hardcoded hex colors, px sizes not from token system
+- ❌ Copy generic Tailwind/Bootstrap templates
+- ❌ Skip loading/error/empty states
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Priority Order
+
+| Priority | Task | Skip Threshold |
+|----------|------|----------------|
+| P1 | HTML structure + semantic markup | Never |
+| P2 | DESIGN.md token application (colors, spacing, typography) | Never |
+| P3 | Interactive states (hover, focus, active) | Budget < 30% |
+| P4 | Responsive breakpoints (mobile) | Budget < 50% |
+| P5 | Loading / error / empty states | Budget < 60% |
+| P6 | Animation / micro-interactions | Budget < 70% |
+| P7 | ARIA roles + keyboard navigation | Budget < 80% |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Workflow
+
+### Phase 1 — Extract Design System
+
+**Steps:**
+1. Read `DESIGN.md` → extract: colors (HSL), spacing scale, font families, border-radius, shadows, animation timing
+2. Map tokens to CSS variables or framework equivalents
+
+**Decision:**
+```
+IF DESIGN.md has all required tokens
+  → go to Phase 2
+
+ELSE IF some tokens missing
+  → Use reasonable fallback, note gap in output
+  → Confidence: MEDIUM
+
+ELSE IF DESIGN.md empty
+  → EXIT: BLOCKED
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 2 — Build Structure
+
+**Steps:**
+1. Create HTML structure (semantic: `article`, `section`, `nav`, `button`, NOT `div` soup)
+2. Apply layout: CSS Grid / Flexbox (NO absolute positioning unless unavoidable)
+3. Apply DESIGN.md tokens for colors, spacing, typography
+
+**Self-Check before next phase:**
+```
+✅ No hardcoded hex/rgb values (only CSS vars or DESIGN.md tokens)
+✅ No magic numbers for spacing (only from scale: 4, 8, 16, 24, 32...)
+✅ Semantic HTML elements used
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 3 — Interactive States
+
+**Steps:**
+1. Add hover, focus, active states for all interactive elements
+2. Add disabled state for form elements
+3. Use CSS transitions (duration from DESIGN.md, typically 150–300ms)
+
+**Self-Check:**
+```
+✅ Every button/link has hover + focus state
+✅ Focus visible (not outline: none without replacement)
+✅ Transition duration matches DESIGN.md
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+### Phase 4 — Self-Audit (Anti-Slop Check)
+
+**Checklist (must pass ALL):**
+- [ ] No hardcoded colors — only DESIGN.md tokens
+- [ ] No font-size in px without token — use rem/token
+- [ ] No `margin: auto` soup — use proper grid/flex
+- [ ] All interactive elements have hover + focus state
+- [ ] Mobile viewport works (no horizontal overflow)
+- [ ] No `!important` overrides (except resets)
+- [ ] No inline styles except dynamic values
+- [ ] Loading state implemented (skeleton or spinner)
+- [ ] Error state implemented (clear message)
+- [ ] Empty state implemented (helpful illustration/text)
+
+**Decision:**
+```
+IF all 10 anti-slop checks pass
+  → EXIT: SUCCESS
+
+ELSE IF 1–2 minor fails
+  → Fix immediately, EXIT: SUCCESS
+
+ELSE IF > 2 fails OR hardcoded colors found
+  → Fix all, re-audit, EXIT: PARTIAL if still one gap
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Confidence Model
+
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | DESIGN.md complete, design reference clear | Build directly |
+| MEDIUM | Some tokens missing, inferring from context | Note gaps, proceed |
+| LOW | Design reference too vague or DESIGN.md empty | EXIT: BLOCKED |
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Evidence Format (Self-Audit Violations)
+
+```
+[SEVERITY] path/to/Component.tsx:LINE
+Category:   [TOKEN|SEMANTIC|INTERACTION|RESPONSIVE|STATE|ARIA]
+Reason:     [specific anti-slop violation]
+Confidence: HIGH
+Fix:        [applied immediately]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Handoff Contract
+
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["design_reference", "design_md_path"],
+  "optional_fields": ["component_name", "framework"]
+}
+```
+
+### Produces
+```json
+{
+  "to": "qk-ui-audit (for verification)",
+  "output_fields": ["component_files", "tokens_used", "states_implemented", "exit_code"]
+}
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+## Output Format
+
+```
+🎨 Design → Code
+─────────────────────────────────────────────────
+Component:   [ComponentName]
+Tokens used: [list of DESIGN.md tokens applied]
+
+States implemented:
+  ✅ Default / ✅ Hover / ✅ Focus / ✅ Active
+  ✅ Loading / ✅ Error / ✅ Empty
+  ⚠️ [any state skipped — reason]
+
+Anti-Slop Audit:
+  ✅ [10/10 checks passed | N/10 — list failures]
+
+Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
+```
+
+skill_version: 7.5.0
+runtime_version: 1
+schema_version: 2
+---
+
+
+---
+
+## Escalation Rules
+
+
+---
+
+## Severity
+
+
+---
+
+## Retry Policy
+
+
+---
+## Exit Codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Component built, all 10 anti-slop checks passed | Production ready |
+| PARTIAL | Built but 1–2 minor gaps (e.g., animation skipped) | User review recommended |
+| BLOCKED | DESIGN.md or design reference missing | Cannot build |
+| FAILED | Anti-slop audit finds > 2 violations or hardcoded values | Rebuild required |
+
+---
+
+

package/skills/qk-docs/SKILL.md

@@ -1,40 +1,198 @@
----
-name: qk-docs
-category: documentation
-version: 7.0.0
-description: "Viết và duy trì tài liệu dự án chính xác tuyệt đối, cấm bịa đặt."
----
-
-# qk-docs
-
-## Scope
-- Technical documentation, Readme files, and inline comments (Execute)
-
-## Verbs
-- `[DOCUMENT]`: Synchronize documentation with the actual implementation.
-
-## Constraints
-```yaml
-must:
-  - "Ensure documentation matches the exact implementation in the codebase"
-  - "Update documentation whenever corresponding code is changed"
-must_not:
-  - "Hallucinate or guess API parameters not present in the code"
-  - "Write generic or useless comments (e.g., '// gets the user')"
-```
-
-## Policies
-```yaml
-prefer:
-  - "Self-documenting code over excessive inline comments"
-  - "Living documentation (e.g., Swagger/JSDoc) over isolated Markdown files"
-```
-
-## Escalation
-```yaml
-stop:
-  - "Documentation requests conflict with actual codebase implementation"
-```
-
-## Output
-- Accurate documentation files or inline comments.
+---
+name: qk-docs
+category: documentation
+version: 7.5.0
+description: "Viết và duy trì tài liệu chính xác tuyệt đối — phải match code thực tế, cấm bịa đặt."
+platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
+execution_mode: deterministic
+cost: low
+latency: fast
+risk: low
+side_effects: edit_files
+produces: [report]
+consumes: [source-code]
+token_budget:
+  max_files_read: 3
+  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-docs — Technical Writer & Documentation Maintainer
+
+> **Language rule:** Code, identifiers, file names ? English. Explanations, summaries ? Vietnamese.
+
+---
+
+## Preconditions
+- [ ] Target code file or module is specified
+
+```
+On missing precondition:
+  EXIT: BLOCKED
+  Message: "Chỉ định file cần viết docs."
+```
+
+---
+
+## Scope
+- ✅ Document ONLY what exists in code — never invent params/behavior
+- ✅ Update docs whenever corresponding code changes
+- ✅ Use living documentation (JSDoc/TSDoc/Swagger) over isolated Markdown
+
+## Non-Goals
+- ❌ Guess API params not in the code
+- ❌ Write generic/useless comments (`// gets the user`)
+- ❌ Write docs for code that hasn't been read yet
+
+---
+
+## Priority Order
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Read source code first (never write before reading) | Never |
+| P2 | Document public API (exported functions/classes) | Never |
+| P3 | Document complex logic with WHY (not WHAT) | Budget < 40% |
+| P4 | Update README if public interface changed | Budget < 60% |
+
+---
+
+## Workflow
+
+### Phase 1 — Read Code
+1. `view_file[targeted]` — read function/class signatures
+2. Identify: params, return type, side effects, error cases
+
+**Decision:** `IF code is not readable → EXIT: BLOCKED — read code first`
+
+### Phase 2 — Write Documentation
+1. JSDoc/TSDoc format for functions: `@param`, `@returns`, `@throws`
+2. Comment: WHY (not WHAT) — code already shows what
+3. Example usage for complex APIs
+
+### Phase 3 — Verify Accuracy
+1. Re-read written docs vs code → spot check each param name
+
+**Decision:**
+```
+IF docs match code exactly → EXIT: SUCCESS
+IF any param name or type mismatch → fix immediately
+```
+
+---
+
+## Documentation Templates
+
+### Function (JSDoc)
+```typescript
+/**
+ * [One sentence — what it does and WHY it exists]
+ *
+ * @param {Type} paramName - [description]
+ * @returns {Type} [description of return value]
+ * @throws {ErrorType} [when this error is thrown]
+ * @example
+ * const result = functionName(arg);
+ */
+```
+
+### README Section
+```markdown
+## [Feature Name]
+[What it does — user-facing description]
+
+### Usage
+[Code example]
+
+### Configuration
+| Option | Type | Default | Description |
+```
+
+---
+
+## Evidence Format
+```
+[SEVERITY] path/to/file.ts:LINE
+Issue:      [MISSING_PARAM | WRONG_TYPE | STALE_DOC | GENERIC_COMMENT]
+Confidence: HIGH
+Fix:        [specific correction]
+```
+
+---
+
+## Exit Codes
+| Code | Meaning | When |
+|------|---------|------|
+| SUCCESS | Docs written and verified against source code | Execution complete |
+| PARTIAL | Docs written but some parts inferred (not verified) | MEDIUM confidence |
+| BLOCKED | Target source file missing or inaccessible | Cannot read source |
+| FAILED | Documentation fundamentally misrepresents the code | Gross error |
+
+---
+
+## Confidence Model
+| Level | Condition | Action |
+|-------|-----------|--------|
+| HIGH | Target code read, behavior understood | Write docs definitively |
+| MEDIUM | Target code too large, inferred from types/tests | Write with disclaimer |
+| LOW | "Write docs for this feature" without pointing to code | EXIT: BLOCKED |
+
+---
+
+## Severity
+| Level | Definition | Example |
+|-------|-----------|---------|
+| CRITICAL | Docs instruct user to do something dangerous | Documenting destructive API without warnings |
+| HIGH | API params documented incorrectly | Says string instead of object |
+| MEDIUM | Missing docs for edge cases | Doesn't explain error throws |
+| LOW | Typo or poor formatting | Misaligned markdown table |
+
+---
+
+## Retry Policy
+```
+Doc verification fails
+  └─ Target code changed during doc writing
+       ├─ Re-read target code
+       └─ Do NOT retry more than 1 time
+```
+
+---
+
+## Escalation Rules
+```
+BLOCKED: Target source file missing
+Missing:
+  - Exact path to the code that needs documenting
+Questions:
+  1. File code nào bạn muốn viết doc? (Xin đường dẫn)
+  2. Mục tiêu của doc này là cho user hay cho developer nội bộ?
+Recommended Assumptions:
+  - Developer-facing JSDoc if inside source files
+```
+
+---
+
+## Handoff Contract
+### Consumes
+```json
+{
+  "from": "user",
+  "required_fields": ["target_file", "doc_type"],
+  "optional_fields": ["context"]
+}
+```
+### Produces
+```json
+{
+  "to": "user",
+  "output_fields": ["updated_files", "exit_code"]
+}
+```
+
+---
+