ai-developer-skill-os 8.2.1 → 8.3.0

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

@@ -4,7 +4,7 @@
 
 ---
 
-## 🔄 [Merged from qk-frontend-architecture]
+## Referenced by: qk-frontend-architecture (file-placement subset)
 
 # Frontend Architecture
 

package/.agents/skills/qk-fe-api-integration/SKILL.md

@@ -140,7 +140,7 @@ On missing precondition:
 **Decision:**
 ```
 IF wrapper/client found (e.g., apiClient.ts, axiosInstance.ts)
-  → Use it. NEVER bypass with raw fetch/axios.
+  → Use it. Ưu tiên bọc (wrap) bằng TanStack Query (useQuery/useMutation) nếu có thể. NEVER bypass with raw fetch/axios in components.
   → Confidence: HIGH → go to Phase 2
 
 ELSE IF no wrapper found
@@ -157,20 +157,22 @@ ELSE IF conflicting patterns found (mix of fetch + axios + rtk)
 
 ---
 
-### Phase 2 — Generate Types
+### Phase 2 — Generate Types & Validation
 
 **Steps:**
-1. Parse provided JSON payload → extract all fields with types
-2. Generate TypeScript interface (Request + Response)
-3. Flag any field that could be `null` or optional
+1. Parse provided JSON payload → extract all fields
+2. Generate **Zod schema** (`z.object({...})`) for runtime validation
+3. Export TypeScript interface via inferred Zod type (`export type Response = z.infer<typeof schema>`)
+4. Flag any field that could be `null` or optional with `.nullable()` or `.optional()`
 
 **Decision:**
 ```
 IF all fields clearly typed from JSON
+  → Khởi tạo Zod schema chính xác.
   → Confidence: HIGH → go to Phase 3
 
 ELSE IF some fields ambiguous (null | undefined)
-  → Mark as optional (?:) + add comment "// verify with backend"
+  → Mark as optional in Zod (`.optional()`) + add comment "// verify with backend"
   → Confidence: MEDIUM → go to Phase 3
 
 ELSE IF nested objects contain mixed null/non-null patterns
@@ -182,10 +184,11 @@ ELSE IF nested objects contain mixed null/non-null patterns
 ### Phase 3 — Implement Service + UI Binding
 
 **Steps:**
-1. Create/update service file (API calls only — no UI logic)
-2. Bind to component: implement Loading state (skeleton/spinner)
-3. Bind Success state: render data using generated types
-4. Bind Error state: handle HTTP errors per table below
+1. Create/update service file: Viết API fetcher function.
+2. Viết Custom Hook bọc fetcher function bằng **TanStack Query** (`useQuery` hoặc `useMutation`).
+3. Bind to component: Dùng các states từ hook (`isLoading`, `isPending`, `isError`, `data`) thay vì tự tạo `useEffect`.
+4. Bind Error state: handle HTTP errors per table below.
+5. Kiểm duyệt ranh giới an toàn (R-SEC-04): Validate dữ liệu API trả về bằng Zod Schema ở (2) trước khi render.
 
 **HTTP Error Handling (mandatory for ALL integrations):**
 ```
@@ -356,25 +359,3 @@ Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
 
 ---
 
-Consume backend API safely in frontend: identify existing client, generate types, implement service layer, and bind to UI with proper states.
-Triggered when user needs to integrate a backend API endpoint into a frontend application. Requires JSON payload sample and knowledge of existing API client patterns.
-- JSON payload sample (request/response)
-- API endpoint specification
-- Existing API client path (if any)
-- Component to bind (if specified)
-- Context graph (for existing patterns)
-1. **Identify:** Find existing API client or confirm need for new one
-2. **Generate:** Create TypeScript interfaces from JSON payload
-3. **Implement:** Build service layer with proper HTTP methods
-4. **Bind:** Connect to UI with Loading/Success/Error states
-5. **Audit:** Verify no hardcoded URLs, no API in JSX, proper error handling
-- NEVER bypass existing wrapper with raw fetch/axios
-- MUST generate strict TypeScript interfaces (no `any`)
-- MUST handle all 3 UI states: Loading, Success, Error
-- MUST NOT exceed token_budget (max 3 files, 100 lines each, 1 shell command)
-- MUST stop early if confidence threshold reached
-- Zero-Trust: Use existing client pattern, never invent new one without approval
-- Type Safety: All API responses must have explicit TypeScript types
-- Error Handling: All HTTP errors must be handled per mandatory table
-- Separation: Service layer only — no API calls in presentational components
----

package/.agents/skills/qk-feature-delivery/SKILL.md

@@ -55,7 +55,8 @@ knowledge_scope:
     - requirement-analysis
   references:
     - testing
-    - security-rules
+    - security
+    - anti-patterns
     - design-system
 
 # ── V8: Verification ───────────────────────────────────────
@@ -104,281 +105,112 @@ On missing precondition:
 ---
 
 ## Scope
-- ✅ Deliver a complete, verifiable feature end-to-end (FE + BE + API)
-- ✅ Adhere to project architecture from context graph
-- ✅ Adhere to DESIGN.md for any UI components
-- ✅ Self-audit before marking done
+- ✅ Read requirements and design docs (Context Loading)
+- ✅ Implement feature adhering to R-C-09 (Anti-slop) and R-SEC-04 (Zero-Trust)
+- ✅ Write unit/integration tests as required
+- ✅ Run self-audit using qk-validation-gate before finishing
 
 ## Non-Goals
-- ❌ Mix refactoring into feature work
-- ❌ Add dependencies without asking user first
-- ❌ Emit generic AI-slop UI or unverified logic
-- ❌ Ignore backward compatibility on existing APIs
-- ❌ Proceed with ambiguous requirements without user confirmation
-- ❌ Break existing API contracts — version or deprecate instead
+- ❌ Skip validation gate
+- ❌ Bypass R-SEC-04 (Zero-Trust) input validation
+- ❌ Write 'spaghetti' code or giant God Files
 
 ---
 
 ## Priority Order
-
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | Core feature logic (happy path) | Never |
-| P2 | Error/loading/empty UI states | Budget < 30% |
-| P3 | Edge cases and validation | Budget < 50% |
-| P4 | Regression prevention (existing tests) | Budget < 60% |
-| P5 | Backend contract validation (API schema, DB migrations) | Budget < 60% |
-| P6 | Documentation + comments | Budget < 70% |
+| P | Task | Skip Threshold |
+|---|------|----------------|
+| P1 | Load and read requirements & design | Never |
+| P2 | Context Graph verification (dependencies) | Never |
+| P3 | Implementation (Code) | Never |
+| P4 | Testing & Validation Gate | Never |
+| P5 | Documentation | Budget < 30% |
 
 ---
 
-## ⚡ FAST PATH (Đọc trước — quyết định ngay)
-
-```
-FAST PATH: Áp dụng nếu task đơn giản (sửa ≤ 1 file, không API mới, không migration DB)
-  → BỎ QUA qk-context-loader
-  → BỎ QUA Phase 1 clarification nếu requirement đã rõ
-  → ĐI THẲNG vào Phase 3 — Implementation
-  → Tiết kiệm 2-3 turn hỏi đáp không cần thiết
-
-VÍ DỤ FAST PATH:
-  ✅ "Sửa label trên button này thành X"
-  ✅ "Thêm validation email vào form"
-  ✅ "Fix bug: hàm này trả về null"
-
-KHÔNG DÙNG FAST PATH:
-  ❌ Tính năng mới span nhiều file (≥ 3 files)
-  ❌ Thay đổi API contract
-  ❌ Migration database
-```
-
 ## Workflow
 
-### Phase 1 — Requirements Clarification
-
-**Steps:**
-1. Parse user request → extract: what, where, acceptance criteria
-2. Check ambiguity: Can I implement this without assumptions?
+### Phase 1 — Context Loading
+1. Read feature spec / requirements.
+2. Read `DESIGN.md` if UI is involved.
+3. Verify dependency graph via `qk-context-loader`.
 
 **Decision:**
-```
-IF requirements are specific (what + where + expected behavior)
-  → Confidence: HIGH → go to Phase 2
+IF context is clear → go to Phase 2
+ELSE → EXIT: BLOCKED — ask user
 
-ELSE IF 1–2 ambiguous points
-  → ASK USER clarifying questions
-  → Confidence: MEDIUM → WAIT for user response
-  → Do NOT proceed to Phase 2 until clarified
+### Phase 2 — Implementation (Code)
+1. Write code in isolated steps.
+2. **BẮT BUỘC tuân thủ R-C-09 (Zero Slop) và R-SEC-04 (Zero Trust).**
+3. Keep functions < 30 lines, avoid God Files.
 
-ELSE IF core requirement unclear
-  → EXIT: BLOCKED — ask clarifying questions
-```
-
-**Exit When:**
-- Requirements understood → go to Phase 2
-
----
+### Phase 3 — Testing
+1. Write unit tests / integration tests.
+2. Run test commands to verify.
 
-### Phase 2 — Context Loading
-
-**Steps:**
-1. If logic work: read context graph from `qk-context-loader` output
-2. Identify: entry point, affected modules, existing patterns to reuse
-3. If UI work: read `DESIGN.md` → extract tokens for this component
-4. Document rollback plan — which files to revert if feature fails
+### Phase 4 — Validation Gate (Self-Audit)
+1. Hand off to `qk-validation-gate` or run linters.
+2. Fix any reported violations immediately.
 
 **Decision:**
-```
-IF context graph available
-  → Use it, proceed to Phase 3
-
-ELSE IF no context graph but simple task
-  → Simple task = modifies ≤ 1 file, no new dependencies, no new API contracts
-  → grep_search for entry point → minimal manual map
-  → Confidence: MEDIUM → proceed to Phase 3
-
-ELSE IF complex task without context graph
-  → EXIT: BLOCKED — run qk-context-loader first
-```
-
----
-
-### Phase 3 — Implementation
-
-**Steps (in order):**
-1. Create/modify files using `replace_file_content` / `multi_replace_file_content`
-2. Follow existing code patterns (from context graph)
-3. For UI: use DESIGN.md tokens only — no hardcoded colors/sizes
-4. Implement backend error handling: try/catch, transaction rollback, input validation
-5. Handle all 3 UI states: Loading + Success + Error
-
-**Exit When:**
-- Happy path implemented → go to Phase 4
-- Blocked by missing dependency → EXIT: BLOCKED, ask user
-
----
-
-### Phase 4 — Self-Audit
-
-**Steps:**
-1. Re-read the code written (targeted view, ≤ 150 lines)
-2. Check against: backward compat, DESIGN.md compliance, error states
-3. Verify test coverage meets project threshold (default: ≥ 80%)
-
-**Decision:**
-```
-IF all checks pass
-  → EXIT: SUCCESS
-
-ELSE IF minor issues found (missing error state, style token)
-  → Fix immediately, EXIT: SUCCESS
-
-ELSE IF significant issue (breaks existing API, wrong architecture)
-  → Fix, note change in output, EXIT: FAILED — do not ship breaking changes as PARTIAL
-
-ELSE IF missing backend error handling
-  → Fix immediately, EXIT: SUCCESS
-```
+IF validation passes → EXIT: SUCCESS
+IF validation fails → Fix and retry
 
 ---
 
 ## Confidence Model
-
 | Level | Condition | Action |
 |-------|-----------|--------|
-| HIGH | Context graph available, DESIGN.md read, requirements clear | Implement directly |
-| MEDIUM | Some assumptions made (≤ 2) | Note assumptions in output |
-| LOW | Unclear requirements or missing context OR assumptions > 2 | EXIT: BLOCKED |
+| HIGH | Requirements clear, tests pass, validation clean | Report SUCCESS |
+| MEDIUM | Specs ambiguous, some assumptions made | Ask user to review |
+| LOW | Lacking specs or API contracts | EXIT: BLOCKED |
 
 ---
 
-## Severity (for self-audit findings)
-
+## Severity
 | Level | Definition |
 |-------|-----------|
-| CRITICAL | Feature breaks existing functionality |
-| HIGH | Missing required states (error/loading) or missing backend error handling |
-| MEDIUM | Not following DESIGN.md or project patterns |
-| LOW | Missing comments or minor style issue |
+| CRITICAL | Broken functionality, security risk |
+| HIGH | Missing tests, validation gate failed |
+| MEDIUM | Minor UX issues |
+| LOW | Code style issues |
 
 ---
 
-## Evidence Format (Self-Audit)
-
+## Evidence Format
 ```
-[SEVERITY] path/to/file.ts:LINE
-Issue:      [what was found]
+[SEVERITY] path/to/file.ts
+Action:     [What was implemented/fixed]
 Confidence: HIGH
-Fix:        [applied immediately OR noted for follow-up]
-```
-
----
-
-## Escalation Rules
-
-```
-BLOCKED: [specific reason]
-Missing:
-  - [What's needed — context graph / DESIGN.md / clear requirements]
-Questions:
-  1. [Specific clarifying question]
-  2. [Second question if needed]
-Recommended Assumptions (if proceeding):
-  - [Safe assumption 1]
-  - [Safe assumption 2 — note these will be in output]
+Validation: [PASS | FAIL]
 ```
 
 ---
 
 ## Handoff Contract
-
 ### Consumes
 ```json
 {
-  "from": "qk-context-loader + user",
-  "required_fields": ["feature_description", "context_graph"],
-  "optional_fields": ["design_md_path", "acceptance_criteria"]
+  "from": "user or qk-product-specification",
+  "required_fields": ["feature_spec", "acceptance_criteria"]
 }
 ```
-
 ### Produces
 ```json
 {
   "to": "qk-validation-gate",
-  "output_fields": ["changed_files", "assumptions_made", "self_audit_result", "exit_code"]
+  "output_fields": ["implemented_files", "test_status", "exit_code"]
 }
 ```
 
 ---
 
-## Output Format
-
-```
-🚀 Feature Delivery
-─────────────────────────────────────────────────
-Feature:     [feature name]
-Confidence:  [HIGH | MEDIUM]
-
-Implementation:
-  ✅ [file:line — what was added/changed]
-  ✅ [file:line — what was added/changed]
-
-Assumptions made:
-  - [assumption 1 — safe/risky]
-
-Self-Audit:
-  ✅ Backward compatible
-  ✅ Error/Loading states handled
-  ✅ DESIGN.md tokens used
-  ✅ Backend error handling implemented
-  ⚠️ [Any noted issue]
-
-Exit Code:   [SUCCESS | PARTIAL | BLOCKED | FAILED]
-```
-
----
-
 ## Exit Codes
-
 | Code | Meaning | When |
 |------|---------|------|
-| SUCCESS | Feature complete, self-audit passed | All states handled, patterns followed |
-| PARTIAL | Feature works but with minor gaps | Medium confidence, some skipped |
-| BLOCKED | Cannot proceed — missing context/design/requirements | Stop and ask user |
-| FAILED | Cannot implement — breaks existing system | Architectural conflict or API break |
-
----
-
-Deliver a complete, verifiable feature end-to-end (FE + BE + API) while adhering to project architecture and DESIGN.md.
-This skill is the primary execution skill for building new features. It requires clear requirements, context graph for architecture understanding, and DESIGN.md for UI work.
-- Feature description with acceptance criteria
-- Context graph (from qk-context-loader)
-- DESIGN.md path (if UI involved)
-- Existing codebase patterns
-- User approval for new dependencies
-1. **Clarify:** Parse requirements, identify ambiguities, ask user if needed
-2. **Load:** Read context graph and DESIGN.md tokens
-3. **Implement:** Build feature following existing patterns
-4. **Audit:** Self-audit for backward compat, error states, DESIGN.md compliance
-- MUST have context graph OR explicit confirmation for simple tasks
-- MUST have DESIGN.md tokens if UI is involved
-- MUST handle all 3 UI states: Loading, Success, Error
-- MUST NOT exceed token_budget (max 5 files, 150 lines each, 2 shell commands)
-- MUST NOT break existing API contracts without versioning
-- Zero-Trust: No assumptions without user confirmation
-- Backward Compat: Never break existing public APIs
-- Design First: UI must use DESIGN.md tokens only
-- Error Handling: Backend must have try/catch, validation, rollback
-## Retry Policy
-```
-Fix applied
-  └─ Static verification (re-read fixed section)
-       ├─ PASS → EXIT: SUCCESS
-       └─ Issue detected → attempt 1 correction
-            └─ Re-verify
-                 ├─ PASS → EXIT: SUCCESS
-                 └─ FAIL → EXIT: PARTIAL + report both attempts
-                      └─ Do NOT attempt 3rd fix — ESCALATE to user
-```
+| SUCCESS | Feature completed, tests pass, validation clean | Normal |
+| PARTIAL | Feature mostly done, some minor issues | Budget hit |
+| BLOCKED | Missing requirements or design | Cannot start |
+| FAILED | Implementation fundamentally broken | Tests/Validation failed |
 
 ---