novahiz 0.1.0

package/skills/apple-hig-expert/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: apple-hig-expert
+description: "Audits and designs iOS/macOS/watchOS/visionOS interfaces against the Apple Human Interface Guidelines, including the Liquid Glass design language (announced WWDC25, shipped with iOS 26/macOS Tahoe, Sept 2025). Use when reviewing an Apple-platform mockup or app for HIG compliance, checking contrast or tap-target sizes, or designing native-feeling Apple UI (e.g., 'audit my iOS app against the HIG', 'is this text readable on Liquid Glass?')."
+license: MIT
+metadata:
+  version: 1.1.0
+  author: Alireza Rezvani
+  category: design
+  updated: 2026-06-11
+---
+
+# Apple HIG Expert
+
+Design and audit apps against the Apple Human Interface Guidelines (HIG, [developer.apple.com/design/human-interface-guidelines](https://developer.apple.com/design/human-interface-guidelines)), including the **Liquid Glass** design language. HIG content evolves with each OS release — when a claim matters, verify against the live HIG pages cited in `references/`.
+
+## Before Starting
+
+If `product-context.md` or `ios-design-context.md` exists, read it before asking questions. Then gather:
+
+1. **Platform target**: iOS, macOS, watchOS, or visionOS?
+2. **Current state**: new design or auditing an existing mockup/code?
+3. **App category**: utility, productivity, game, social, etc.
+
+## Modes
+
+- **Mode 1 — Design from scratch**: pick the platform navigation paradigm and layout primitives first (see `references/platform-specifics.md`), then apply typography and semantic color (`references/visual-design.md`).
+- **Mode 2 — HIG audit**: fill in `templates/hig-audit-template.md`, run `scripts/hig_checker.py` on every measurable element, and deliver a scored report (see Worked example below).
+
+## The Compliance Tool
+
+`scripts/hig_checker.py` (stdlib-only) has three subcommands:
+
+```bash
+# 1. Contrast ratio (WCAG formula; pass >= 4.5:1 for normal text)
+python3 scripts/hig_checker.py contrast "#8E8E93" "#FFFFFF"
+# -> Contrast Ratio: 3.26 [FAILED]
+
+# 2. Tap-target size (pass >= 44x44 pt per HIG)
+python3 scripts/hig_checker.py target 32 32
+# -> Tap Target: 32x32 [FAILED]
+
+# 3. Batch audit from JSON -> scorecard (starts at 100, -10 per violation)
+python3 scripts/hig_checker.py batch audit.json
+```
+
+Batch input shape:
+
+```json
+{
+  "checks": [
+    {"type": "contrast", "name": "caption-on-card", "fg": "#8E8E93", "bg": "#FFFFFF"},
+    {"type": "target", "name": "close-button", "w": 32, "h": 32}
+  ]
+}
+```
+
+**Scorecard rubric:** the batch score starts at 100 and subtracts 10 per failed check; violations are listed by element name. 90-100 = ship, 70-80 = fix before release, below 70 = systematic rework. Checks the tool cannot measure (VoiceOver labels, Dynamic Type behavior, Reduce Transparency) are assessed manually via the audit template and tagged with confidence.
+
+## Worked example: iOS settings-screen audit
+
+**Input:** mockup with body text `#1C1C1E` and captions `#8E8E93` on white cards, a 32x32 pt close button, and a 343x50 pt primary CTA.
+
+**Run:**
+
+```bash
+python3 scripts/hig_checker.py batch audit.json
+```
+
+**Output (real):**
+
+```json
+{
+  "score": 80,
+  "violations": [
+    "Contrast 3.26 fails for caption-on-card",
+    "Target 32x32 small for close-button"
+  ]
+}
+```
+
+**Findings → fixes (bottom line first):**
+
+> **HIG score 80/100 — two fixes before release.**
+> 1. Captions fail contrast (3.26 < 4.5). Use `.secondaryLabel` (semantic color) instead of hardcoded `#8E8E93`, or darken to ≥ `#6E6E73` on white. 🟢 verified by tool.
+> 2. Close button is 32x32 pt (< 44x44 minimum). Keep the glyph small but expand the hit region to 44x44 with padding/`contentShape`. 🟢 verified by tool.
+> 3. Manual check: the card uses an ultra-thin material over a photo background — re-test caption contrast against the *busiest* underlying region and with Reduce Transparency on. 🟡 needs device test.
+
+## Core Design Principles
+
+1. **Liquid Glass** — translucent material hierarchy (announced at WWDC25, June 2025; shipped Sept 2025 across iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, visionOS 26). In SwiftUI, apply it via the `glassEffect` view modifier; keep hierarchy between content and controls. See `references/visual-design.md`.
+2. **Accessibility first** — VoiceOver labels on every element, 44x44 pt minimum targets, 4.5:1 contrast for normal text (3:1 large text), Dynamic Type support. See `references/accessibility.md`.
+3. **Platform ergonomics** — tab bars/thumb reach on iOS, sidebars + menu bar + shortcuts on macOS, ornaments + gaze states on visionOS, glanceable vertical layouts on watchOS. See `references/platform-specifics.md`.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked: low contrast over translucent layers; interactive elements under 44 pt; icon buttons with no accessibility label; density overload (no breathing room between glass layers).
+
+## Communication
+
+- **Bottom line first** — compliance status before details.
+- **What + Why + How** — "Expand the hit region (What) because 32 pt targets fail the HIG minimum (Why); pad to 44x44 via contentShape (How)."
+- **Confidence tagging** — 🟢 tool-verified / 🟡 needs device test / 🔴 assumed.
+
+## Related Skills
+
+- **ui-design-system**: token-based component systems (not platform HIG rules).
+- **ux-researcher-designer**: persona/research validation (not visual styling).
+- **landing-page-generator**: web marketing pages, not native apps.

package/skills/apple-hig-expert/references/accessibility.md

@@ -0,0 +1,55 @@
+# Accessibility Compliance Guide
+
+Accessibility isn't a feature; it's a foundational standard. Apple's design philosophy requires apps to be fully usable by everyone, regardless of their physical or cognitive abilities.
+
+## The 4 Pillars of Accessibility
+
+### 1. Perceivable
+Information and UI components must be presentable to users in ways they can perceive.
+- **VoiceOver**: Provide meaningful accessibility labels and hints. Avoid "Button 1". Use "Submit Order" with hint "Double tap to place your order."
+- **Visuals**: Don't rely on color alone to convey meaning (e.g., use icons + color for errors).
+
+### 2. Operable
+User interface components and navigation must be operable.
+- **Tap Targets**: 44x44 points minimum.
+- **Motor Control**: Support Switch Control and AssistiveTouch.
+
+### 3. Understandable
+Information and the operation of the user interface must be understandable.
+- **Predictability**: Use standard Apple UI patterns (Tab Bars, Sidebars) so users already know how they work.
+
+### 4. Robust
+Content must be robust enough to be interpreted by a wide variety of user agents, including assistive technologies.
+
+## Technical Requirements (2026)
+
+### Dynamic Type
+Apps must respond to system-wide font size changes.
+- **Scaling Layouts**: Use Auto Layout or SwiftUI `VStack`/`HStack` that wrap content when fonts get large.
+- **No Clipped Text**: Text should never be truncated unnecessarily.
+
+### Contrast Ratios
+- **Normal Text**: 4.5:1 minimum against its background.
+- **Large Text**: 3:1 minimum.
+- **Liquid Glass Exception**: Be extremely careful with translucency (vibrancy). If a background is too busy, reduce transparency for accessibility.
+
+### Haptics & Audio
+- Provide haptic feedback for primary actions (success, failure, selection change).
+- Ensure all audio content has captions or visual equivalents.
+
+## Checklist for Designers
+
+- [ ] Does the app work in Grayscale mode?
+- [ ] Are all buttons at least 44pt tall?
+- [ ] Is every icon labeled for VoiceOver?
+- [ ] Does the layout remain usable at the largest Dynamic Type size?
+- [ ] Have you tested with "Reduce Transparency" enabled in system settings?
+
+
+## Sources
+
+- Apple HIG — Accessibility: https://developer.apple.com/design/human-interface-guidelines/accessibility
+- Apple HIG — Buttons (44x44 pt minimum hit region): https://developer.apple.com/design/human-interface-guidelines/buttons
+- Apple HIG — Typography (Dynamic Type text styles): https://developer.apple.com/design/human-interface-guidelines/typography
+- Apple Accessibility for developers: https://developer.apple.com/accessibility/
+- WCAG 2.x contrast minimums (4.5:1 / 3:1), which the HIG color guidance mirrors: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html

package/skills/apple-hig-expert/references/platform-specifics.md

@@ -0,0 +1,48 @@
+# Platform Specific Guidelines
+
+While Apple aims for a unified aesthetic (Liquid Glass), each platform has unique ergonomics and hardware constraints.
+
+## iOS (iPhone)
+Designed for one-handed operation and touch-first input.
+- **Bottom Navigation**: Primary controls should be reachable by the thumb at the bottom (Tab Bars, Toolbars).
+- **Safe Area**: Avoid placing UI near the Dynamic Island or the home indicator.
+- **Dynamic Island**: Use Live Activities and the Dynamic Island for high-value background status (e.g., timers, delivery status).
+
+## macOS (Desktop)
+Designed for precision cursor input and multitasking.
+- **Sidebars**: Use for primary navigation.
+- **Menu Bar**: Always provide standard File, Edit, and View menus.
+- **Windowing**: Support multi-window environments and Split View.
+- **Keyboard Shortcuts**: Every primary action must have a `Cmd` + [Key] equivalent.
+
+## visionOS (Spatial Computing)
+Designed for eyes (gaze) and hands (gestures).
+- **Windows**: Have a physical presence in space. They cast shadows and reflect light.
+- **Ornaments**: Floating controls that attach to the edge of a window.
+- **Gaze-Contingent Feedback**: Elements should react (subtle hover state) when the user looks at them.
+- **Z-Axis**: Use depth to prioritize content. Closer items are more important.
+
+## watchOS (Wrist)
+Designed for "Glances" — 2 to 5 second interactions.
+- **Vertical Layout**: Scroll everything vertically using the Digital Crown.
+- **Complications**: Design for the watch face to provide high-value data at a glance.
+- **Full-Bleed Images**: Use the entire screen to reduce the perception of bezels.
+
+## Platform Differences Table
+
+| Feature | iOS | macOS | visionOS |
+|---------|-----|-------|----------|
+| **Navigation** | Tab Bar / Nav Bar | Sidebar / Menu Bar | Ornaments / Sidebars |
+| **Input** | Touch / Voice | Mouse / Trackpad / Keys | Eyes (Gaze) / Hands |
+| **Typical Dist.** | 6 - 12 inches | 18 - 30 inches | Infinite (Arm's length) |
+| **Aesthetic** | High density | High precision | Spatially grounded |
+
+
+## Sources
+
+- Apple HIG — Designing for iOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-ios
+- Apple HIG — Designing for macOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-macos
+- Apple HIG — Designing for visionOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-visionos
+- Apple HIG — Designing for watchOS: https://developer.apple.com/design/human-interface-guidelines/designing-for-watchos
+- Apple HIG — Ornaments (visionOS): https://developer.apple.com/design/human-interface-guidelines/ornaments
+- Apple HIG — Live Activities / Dynamic Island: https://developer.apple.com/design/human-interface-guidelines/live-activities

package/skills/apple-hig-expert/references/visual-design.md

@@ -0,0 +1,69 @@
+# Visual Design Guide (Liquid Glass 2026)
+
+This guide covers the visual language of the Apple ecosystem, centered on the **Liquid Glass** design language — announced at WWDC25 (June 9, 2025) and shipped in September 2025 with iOS 26, iPadOS 26, macOS Tahoe, watchOS 26, tvOS 26, and visionOS 26. In SwiftUI it is applied with the `glassEffect` view modifier.
+
+## Core Aesthetic: Liquid Glass
+
+Liquid Glass evolves the "Glassmorphism" trend into a more dynamic and physically grounded style.
+
+### 1. Materials and Translucency
+Materials provide background blurs and vibrancy.
+- **Ultra-Thin**: Use for secondary elements like tab bars or small floating buttons.
+- **Thin**: Use for standard menu and sidebar backgrounds.
+- **Thick**: Use for static high-level containers like macOS window backgrounds.
+
+### 2. Vibrancy
+Vibrancy isn't just transparency; it’s a filter that pulls primary colors from the background to make text more readable.
+- **Vibrant Primary**: For headlines and body text.
+- **Vibrant Secondary**: For captions and secondary info.
+
+## Color Palette
+
+### Semantic Colors
+Always use Apple's semantic color system (`systemBlue`, `systemRed`) rather than hardcoded hex values to support:
+- Light / Dark Mode.
+- High Contrast Mode.
+- Dynamic color adjustments in 2026 systems.
+
+### 2. Gradients
+Liquid Glass uses subtle, non-distracting gradients to imply surface curvature.
+
+## Typography: San Francisco
+
+Apple uses the **San Francisco (SF)** family across all platforms.
+
+| Variant | Platform | Usage |
+|---------|----------|-------|
+| **SF Pro** | iOS, macOS | System standard for performance and legibility. |
+| **SF Compact** | watchOS | Optimized for small screens (the Camera app uses SF Compact Rounded as of iOS 26). |
+| **SF Mono** | Dev tools | Monospaced variant for code. |
+| **New York** | All | Serif companion family for editorial contexts. |
+
+Only the families on [developer.apple.com/fonts](https://developer.apple.com/fonts/) (SF Pro, SF Compact, SF Mono, SF Arabic/Hebrew and other language extensions, New York) are available to developers. "SF Camera" was an internal face used in Apple's Camera app, never a public download — do not specify it in design systems.
+
+### Dynamic Type
+You MUST support Dynamic Type.
+- Use system text styles (e.g., `Title 1`, `Body`, `Caption 1`).
+- Design for scale; UI should remain usable when font size is at 300%.
+
+## Spacing and Grid
+
+### The 8pt Rule
+All spacing should be increments of 8 (8pt, 16pt, 24pt, 32pt).
+- **Margins**: Typically 16pt or 24pt for standard layouts.
+- **Tap Targets**: 44pt minimum vertical height.
+
+### Margin Logic
+- **iOS**: Match the Dynamic Island or Safe Area insets.
+- **watchOS**: Maximize the bezel-less display by using rounded corner layouts.
+
+
+## Sources
+
+- Apple HIG — Materials: https://developer.apple.com/design/human-interface-guidelines/materials
+- Apple HIG — Typography: https://developer.apple.com/design/human-interface-guidelines/typography
+- Apple HIG — Color: https://developer.apple.com/design/human-interface-guidelines/color
+- Apple HIG — Layout: https://developer.apple.com/design/human-interface-guidelines/layout
+- Apple Fonts (official SF/New York downloads): https://developer.apple.com/fonts/
+- "Meet Liquid Glass" (WWDC25 session 219): https://developer.apple.com/videos/play/wwdc2025/219/
+- Apple Newsroom, June 9 2025 — new software design announcement: https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/

package/skills/apple-hig-expert/scripts/hig_checker.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Apple HIG Compliance Checker
+Quantitative checks for tap targets, contrast, and typography.
+"""
+
+import sys
+import argparse
+import json
+import math
+
+def calculate_luminance(hex_color):
+    """Calculates relative luminance for a given hex color."""
+    hex_color = hex_color.lstrip('#')
+    if len(hex_color) != 6:
+        return 0
+    
+    r, g, b = [int(hex_color[i:i+2], 16) / 255.0 for i in (0, 2, 4)]
+    
+    def adjust(c):
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+    
+    return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b)
+
+def check_contrast(fg, bg):
+    """Checks contrast ratio between foreground and background."""
+    l1 = calculate_luminance(fg)
+    l2 = calculate_luminance(bg)
+    
+    if l1 < l2:
+        l1, l2 = l2, l1
+        
+    ratio = (l1 + 0.05) / (l2 + 0.05)
+    return round(ratio, 2)
+
+def main():
+    parser = argparse.ArgumentParser(description="Apple HIG Compliance Checker")
+    subparsers = parser.add_subparsers(dest="command", help="Compliance command")
+    
+    # Contrast command
+    contrast_parser = subparsers.add_parser("contrast", help="Check contrast ratio")
+    contrast_parser.add_argument("fg", help="Foreground Hex (e.g. #FFFFFF)")
+    contrast_parser.add_argument("bg", help="Background Hex (e.g. #000000)")
+    
+    # Target command
+    target_parser = subparsers.add_parser("target", help="Check tap target size")
+    target_parser.add_argument("width", type=int, help="Width in points")
+    target_parser.add_argument("height", type=int, help="Height in points")
+    
+    # Batch command
+    batch_parser = subparsers.add_parser("batch", help="Batch check from JSON")
+    batch_parser.add_argument("file", help="Path to JSON file")
+    
+    args = parser.parse_args()
+    
+    results = {"score": 100, "violations": []}
+    
+    if args.command == "contrast":
+        ratio = check_contrast(args.fg, args.bg)
+        status = "PASSED" if ratio >= 4.5 else "FAILED"
+        print(f"Contrast Ratio: {ratio} [{status}]")
+        if status == "FAILED":
+            print("Recommendation: Increase contrast to at least 4.5:1 for accessibility.")
+            
+    elif args.command == "target":
+        if args.width < 44 or args.height < 44:
+            print(f"Tap Target: {args.width}x{args.height} [FAILED]")
+            print("Recommendation: Minimum tap target size is 44x44 points per Apple HIG.")
+        else:
+            print(f"Tap Target: {args.width}x{args.height} [PASSED]")
+            
+    elif args.command == "batch":
+        try:
+            with open(args.file, 'r') as f:
+                data = json.load(f)
+                # Sample batch processing
+                for item in data.get("checks", []):
+                    if item['type'] == 'contrast':
+                        r = check_contrast(item['fg'], item['bg'])
+                        if r < 4.5:
+                            results["violations"].append(f"Contrast {r} fails for {item.get('name', 'element')}")
+                            results["score"] -= 10
+                    elif item['type'] == 'target':
+                        if item['w'] < 44 or item['h'] < 44:
+                            results["violations"].append(f"Target {item['w']}x{item['h']} small for {item.get('name', 'element')}")
+                            results["score"] -= 10
+                            
+            print(json.dumps(results, indent=2))
+        except Exception as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+            
+    else:
+        parser.print_help()
+
+if __name__ == "__main__":
+    main()

package/skills/apple-hig-expert/templates/hig-audit-template.md

@@ -0,0 +1,83 @@
+# Apple HIG Audit Scorecard
+
+**App Name:** [Name]
+**Platform:** [iOS / macOS / visionOS / watchOS]
+**Auditor:** [Name]
+**Date:** YYYY-MM-DD
+
+---
+
+## 1. Visual Design & Aesthetic (0-20 pts)
+Score: /20
+
+- [ ] **Liquid Glass Compliance**: Does it use translucency and layers effectively?
+- [ ] **Typography**: Is San Francisco used? Are text styles semantic?
+- [ ] **Color**: Are semantic colors used (Light/Dark mode support)?
+- [ ] **Spacing**: Is the 8pt grid followed?
+
+**Notes:**
+
+---
+
+## 2. Navigation & Layout (0-20 pts)
+Score: /20
+
+- [ ] **Platform Native**: Does it use native paradigms (Tab Bar, Sidebar, etc.)?
+- [ ] **Reachability**: (iOS only) Are primary actions at the bottom?
+- [ ] **Safe Areas**: Are items clear of Dynamic Island / Home Indicator?
+- [ ] **Information Density**: Is there enough white space (Deference)?
+
+**Notes:**
+
+---
+
+## 3. Accessibility (0-30 pts)
+Score: /30
+
+- [ ] **VoiceOver**: All elements have labels and hints?
+- [ ] **Tap Targets**: All buttons min 44x44pt?
+- [ ] **Dynamic Type**: Does the layout scale without clipping?
+- [ ] **Contrast**: Min 4.5:1 ratio for text?
+
+**Notes:**
+
+---
+
+## 4. Interaction & Motion (0-20 pts)
+Score: /20
+
+- [ ] **Feel**: Are animations fluid and spring-based?
+- [ ] **Feedback**: Are haptics used appropriately for actions?
+- [ ] **Predictability**: Do standard gestures (swipe, pinch) work as expected?
+
+**Notes:**
+
+---
+
+## 5. Platform Features (0-10 pts)
+Score: /10
+
+- [ ] **Native Integration**: Does it use Dynamic Island, Live Activities, or Complications?
+- [ ] **Shortcuts**: (macOS) Comprehensive keyboard shortcuts?
+
+**Notes:**
+
+---
+
+## Final Score: /100
+
+### 🟢 85-100: App Store Ready
+Highly compliant. Ready for official review or featuring.
+
+### 🟡 70-84: Needs Polish
+Functional and native, but missing critical design finesse or accessibility details.
+
+### 🔴 <70: High Risk
+Significant violations. Likely to be rejected by App Store review or provide poor UX.
+
+---
+
+## Primary Recommendations:
+1. [Recommendation 1]
+2. [Recommendation 2]
+3. [Recommendation 3]

package/skills/clean-code/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: clean-code
+description: "This skill embodies the principles of \"Clean Code\" by Robert C. Martin (Uncle Bob). Use it to transform \"code that works\" into \"code that is clean.\""
+risk: safe
+source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
+date_added: "2026-02-27"
+---
+
+# Clean Code Skill
+
+This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
+
+## 🧠 Core Philosophy
+> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch
+
+## When to Use
+Use this skill when:
+- **Writing new code**: To ensure high quality from the start.
+- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
+- **Refactoring legacy code**: To identify and remove code smells.
+- **Improving team standards**: To align on industry-standard best practices.
+
+## 1. Meaningful Names
+- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
+- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
+- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
+- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
+- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
+- **Method Names**: Use verbs (`postPayment`, `deletePage`).
+
+## 2. Functions
+- **Small!**: Functions should be shorter than you think.
+- **Do One Thing**: A function should do only one thing, and do it well.
+- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
+- **Descriptive Names**: `isPasswordValid` is better than `check`.
+- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
+- **No Side Effects**: Functions shouldn't secretly change global state.
+
+## 3. Comments
+- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.
+- **Explain Yourself in Code**: 
+  ```python
+  # Check if employee is eligible for full benefits
+  if employee.flags & HOURLY and employee.age > 65:
+  ```
+  vs
+  ```python
+  if employee.isEligibleForFullBenefits():
+  ```
+- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
+- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
+
+## 4. Formatting
+- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
+- **Vertical Density**: Related lines should be close to each other.
+- **Distance**: Variables should be declared near their usage.
+- **Indentation**: Essential for structural readability.
+
+## 5. Objects and Data Structures
+- **Data Abstraction**: Hide the implementation behind interfaces.
+- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
+- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
+
+## 6. Error Handling
+- **Use Exceptions instead of Return Codes**: Keeps logic clean.
+- **Write Try-Catch-Finally First**: Defines the scope of the operation.
+- **Don't Return Null**: It forces the caller to check for null every time.
+- **Don't Pass Null**: Leads to `NullPointerException`.
+
+## 7. Unit Tests
+- **The Three Laws of TDD**:
+  1. Don't write production code until you have a failing unit test.
+  2. Don't write more of a unit test than is sufficient to fail.
+  3. Don't write more production code than is sufficient to pass the failing test.
+- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+## 8. Classes
+- **Small!**: Classes should have a single responsibility (SRP).
+- **The Stepdown Rule**: We want the code to read like a top-down narrative.
+
+## 9. Smells and Heuristics
+- **Rigidity**: Hard to change.
+- **Fragility**: Breaks in many places.
+- **Immobility**: Hard to reuse.
+- **Viscosity**: Hard to do the right thing.
+- **Needless Complexity/Repetition**.
+
+## 🛠️ Implementation Checklist
+- [ ] Is this function smaller than 20 lines?
+- [ ] Does this function do exactly one thing?
+- [ ] Are all names searchable and intention-revealing?
+- [ ] Have I avoided comments by making the code clearer?
+- [ ] Am I passing too many arguments?
+- [ ] Is there a failing test for this change?
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/code-reviewer/README.md

@@ -0,0 +1,92 @@
+# code-reviewer
+
+Code review automation for TypeScript, JavaScript, Python, Go, Swift, Kotlin, C#, .NET, Java, C, C++, Rust, Ruby, PHP, and Dart/Flutter. Analyzes PRs for complexity and risk, checks code quality for SOLID violations and code smells, and generates review reports.
+
+The full skill spec is [`SKILL.md`](./SKILL.md). This README is a quick reference for the 3 bundled scripts.
+
+---
+
+## How to use
+
+### Quick install check
+
+```bash
+python scripts/pr_analyzer.py --help
+python scripts/code_quality_checker.py --help
+python scripts/review_report_generator.py --help
+```
+
+All three scripts are stdlib-only — no `pip install` required.
+
+### Example 1 — review a pull request
+
+```bash
+# From inside the repo you want to analyze:
+python /path/to/skills/code-reviewer/scripts/pr_analyzer.py . --base main --head HEAD
+```
+
+Outputs: complexity score (1-10), risk categorization (critical / high / medium / low), prioritized review order, commit-message validation.
+
+### Example 2 — score a directory's code quality
+
+```bash
+python scripts/code_quality_checker.py /path/to/code
+
+# Filter by language
+python scripts/code_quality_checker.py /path/to/code --language csharp
+
+# Machine-readable
+python scripts/code_quality_checker.py /path/to/code --json
+```
+
+Outputs: quality score (0-100), letter grade, detected code smells, SOLID violations.
+
+### Example 3 — combine into a review report
+
+```bash
+python scripts/review_report_generator.py /path/to/repo --format markdown --output review.md
+```
+
+Outputs: review verdict (approve / request changes / block), score, prioritized action items.
+
+---
+
+## Examples bundled with the skill
+
+| File | Purpose |
+|------|---------|
+| [`assets/sample_csharp_smells.cs`](./assets/sample_csharp_smells.cs) | C# file with every C#-specific pattern this skill detects, labelled inline |
+| [`assets/sample_csharp_clean.cs`](./assets/sample_csharp_clean.cs) | Same code refactored per `rules/universal.md` + `languages/csharp.md` |
+| [`assets/sample_java_smells.java`](./assets/sample_java_smells.java) | Java file with every Java-specific pattern this skill detects, labelled inline |
+| [`assets/sample_java_clean.java`](./assets/sample_java_clean.java) | Same code refactored per `rules/universal.md` + `languages/java.md` |
+| [`assets/sample_c_smells.c`](./assets/sample_c_smells.c) | C file with every C-specific pattern this skill detects, labelled inline |
+| [`assets/sample_c_clean.c`](./assets/sample_c_clean.c) | Same code refactored per `rules/universal.md` + `languages/c.md` |
+| [`expected_outputs/*.json`](./expected_outputs/) | Expected `code_quality_checker.py --json` output for each fixture |
+
+Use them as a regression-detection harness:
+
+```bash
+python scripts/code_quality_checker.py assets/sample_java_smells.java --json > /tmp/check.json
+diff /tmp/check.json expected_outputs/sample_java_smells_quality.json
+# silence means the detector still behaves as documented
+```
+
+---
+
+## What it detects
+
+See [`SKILL.md`](./SKILL.md) for the full pattern list, severity tiers, and references. Quick summary:
+
+- **PR Analyzer** (`scripts/pr_analyzer.py`): hardcoded secrets / connection strings, SQL injection, debug statements (`console.*` / `System.out` / `printStackTrace`), analyzer suppressions (ESLint / Roslyn / `@SuppressWarnings`), `any` / `dynamic` overuse, TODO/FIXME, `unsafe` blocks, null-forgiving `!`, `async void`, blocking on `Task`.
+- **Code Quality Checker** (`scripts/code_quality_checker.py`): long methods, large files, god classes, deep nesting, too many parameters, high cyclomatic complexity, swallowed exceptions, missing `await`, undisposed `IDisposable`, `new HttpClient()` in method body, unused `using` directives. Language-specific smell packs for C# (`async void`, blocking on `Task`), Java (empty catch, `printStackTrace`, swallowed `InterruptedException`, unclosed resources, per-call `ObjectMapper` / `Gson`), and C (banned functions `gets`/`strcpy`/`strcat`/`sprintf`/`vsprintf`, format-string vulnerability `printf(var)`, unbounded `scanf("%s")`, malloc-without-NULL-check, free-without-zeroing, `system()` with non-literal argument).
+- **Review Report Generator** (`scripts/review_report_generator.py`): combines the above into a single markdown or JSON verdict.
+
+---
+
+## Review rules
+
+Rules are split so every review loads exactly two files — the cross-language
+baseline plus one language guide (see the dispatch table in [`SKILL.md`](./SKILL.md)):
+
+- [`rules/universal.md`](./rules/universal.md) — cross-language rules: security, async/concurrency, resource management, exception handling, performance
+- [`languages/`](./languages/) — one self-contained guide per language (`python`, `typescript`, `go`, `swift`, `kotlin`, `csharp`, `java`, `c`, `cpp`, `rust`, `ruby`, `php`, `dart`), each with Security / Async / Resource Management / Exception Handling / Performance / Idioms sections