@hustle-together/api-dev-tools 3.12.3 → 4.5.1

package/.skills/test-unit/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: test-unit
+description: Run Vitest unit tests with coverage and actionable reporting
+tools: Bash, Read, Glob, TodoWrite
+model: sonnet
+---
+
+# Test Unit Skill
+
+Run Vitest unit tests with detailed coverage reporting and actionable feedback.
+
+## When to Use
+
+- After implementing a feature (TDD Green phase)
+- Before committing changes
+- When debugging test failures
+- To check test coverage
+
+## Execution Steps
+
+### Step 1: Detect Test Configuration
+
+Check for test configuration:
+```bash
+# Check for vitest.config.ts or vite.config.ts
+ls -la vitest.config.* vite.config.* 2>/dev/null || echo "No config found"
+
+# Check package.json for test script
+cat package.json | grep -A5 '"scripts"' | grep test
+```
+
+### Step 2: Run Tests
+
+Execute the appropriate test command:
+
+```bash
+# If pnpm is available
+pnpm test
+
+# Or with coverage
+pnpm test:coverage
+
+# Or run specific file
+pnpm test -- path/to/file.test.ts
+```
+
+### Step 3: Parse Results
+
+After tests complete, analyze the output:
+
+1. **If all tests pass:**
+   ```
+   ✅ All tests passing
+
+   Summary:
+   - Tests: 42 passed
+   - Duration: 3.2s
+   - Coverage: 85%
+   ```
+
+2. **If tests fail:**
+   ```
+   ❌ Test failures detected
+
+   Failed Tests:
+   1. src/components/Button.test.tsx
+      - "should render with loading state"
+      - Expected: spinner to be visible
+      - Received: spinner not found
+
+   Suggested Fix:
+   - Check if isLoading prop is being passed
+   - Verify Spinner component is imported
+   ```
+
+### Step 4: Coverage Analysis
+
+If coverage is enabled, report:
+
+```
+Coverage Report:
+─────────────────────────────────────
+File                    | Stmts | Branch | Funcs | Lines
+─────────────────────────────────────
+src/lib/api.ts         | 92%   | 85%    | 100%  | 92%
+src/components/...     | 78%   | 70%    | 90%   | 78%
+─────────────────────────────────────
+
+⚠️ Files below 80% coverage:
+- src/utils/helpers.ts (65%)
+- src/hooks/useAuth.ts (72%)
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `[pattern]` | Test file pattern to match | All tests |
+| `--coverage` | Include coverage report | false |
+| `--watch` | Run in watch mode | false |
+| `--ui` | Open Vitest UI | false |
+
+## Examples
+
+```bash
+# Run all tests
+/test-unit
+
+# Run tests for specific file
+/test-unit Button
+
+# Run with coverage
+/test-unit --coverage
+
+# Watch mode for development
+/test-unit --watch
+```
+
+## Output Format
+
+Always end with a clear status:
+
+```
+═══════════════════════════════════════
+Unit Test Results: ✅ PASS / ❌ FAIL
+═══════════════════════════════════════
+Tests:    42 passed, 0 failed
+Duration: 3.2s
+Coverage: 85% (target: 80%)
+═══════════════════════════════════════
+```
+
+## Integration with TDD Workflow
+
+This skill is automatically invoked during:
+- Phase 9 (TDD Green) - After implementation
+- Phase 12 (Refactor) - After cleanup
+
+## See Also
+
+- `/test-e2e` - End-to-end tests
+- `/test-visual` - Visual regression tests
+- `/test-all` - Run all test suites

package/.skills/test-visual/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: test-visual
+description: Run Storybook visual and interaction tests with component coverage
+tools: Bash, Read, Glob, TodoWrite, Task
+model: sonnet
+---
+
+# Test Visual Skill
+
+Run visual regression tests using Storybook and Playwright across 7 viewports.
+
+## When to Use
+
+- After creating or modifying UI components
+- Before merging component changes
+- To detect unintended visual changes
+- To verify responsive design
+
+## Execution Steps
+
+### Step 1: Check Storybook Configuration
+
+```bash
+# Check for Storybook config
+ls .storybook/main.* 2>/dev/null
+
+# Check for test-runner
+cat package.json | grep -E "storybook|chromatic"
+```
+
+### Step 2: Build Storybook (if needed)
+
+```bash
+# Build static Storybook for testing
+pnpm storybook:build
+
+# Or run dev server
+pnpm storybook &
+```
+
+### Step 3: Run Visual Tests
+
+Execute visual regression tests:
+
+```bash
+# Run Storybook test runner
+pnpm test-storybook
+
+# Or with Playwright visual comparisons
+npx playwright test --project=visual
+```
+
+### Step 4: Test Across 7 Viewports
+
+For each component, capture screenshots at:
+
+| Viewport | Dimensions | Safe Areas |
+|----------|------------|------------|
+| Mobile Portrait | 375×667 | None |
+| Mobile Notch | 393×852 | Top: 47px, Bottom: 34px |
+| Mobile Landscape | 667×375 | None |
+| Tablet Portrait | 768×1024 | None |
+| Tablet Landscape | 1024×768 | None |
+| Small Desktop | 1280×720 | None |
+| Desktop | 1920×1080 | None |
+
+### Step 5: AI-Powered Analysis (Haiku)
+
+For each viewport screenshot, spawn a Haiku subagent to analyze:
+
+```
+Task({
+  subagent_type: "visual-analyzer",
+  model: "haiku",
+  prompt: `Analyze screenshot for:
+    1. Layout issues (overlapping, clipping)
+    2. Typography (readability, contrast)
+    3. Touch targets (min 44x44px)
+    4. Safe area compliance
+    5. Brand consistency
+
+    Return: {issues: [{type, severity, element, detail}]}`
+})
+```
+
+### Step 6: Report Results (Enhanced with Haiku Reasoning + Links)
+
+The report includes **Haiku's detailed reasoning** for any issues found, plus **clickable links** to screenshots and Storybook states:
+
+```
+═══════════════════════════════════════════════════════════════════════════════
+                         VISUAL TEST RESULTS: Button
+═══════════════════════════════════════════════════════════════════════════════
+
+Viewport Tests:
+┌──────────────────┬────────┬─────────────────────────────────────────────────┐
+│ Viewport         │ Status │ Details                                         │
+├──────────────────┼────────┼─────────────────────────────────────────────────┤
+│ Mobile Portrait  │ ✅ Pass │ No issues                                       │
+│ Mobile Notch     │ ⚠️ Warn │ Touch target below minimum                      │
+│ Mobile Landscape │ ✅ Pass │ No issues                                       │
+│ Tablet Portrait  │ ✅ Pass │ No issues                                       │
+│ Tablet Landscape │ ✅ Pass │ No issues                                       │
+│ Small Desktop    │ ✅ Pass │ No issues                                       │
+│ Desktop          │ ✅ Pass │ No issues                                       │
+└──────────────────┴────────┴─────────────────────────────────────────────────┘
+
+═══════════════════════════════════════════════════════════════════════════════
+                           HAIKU AI ANALYSIS
+═══════════════════════════════════════════════════════════════════════════════
+
+📱 Mobile Notch (393×852) - ⚠️ 1 Warning
+───────────────────────────────────────────────────────────────────────────────
+📸 Screenshot: file://__snapshots__/Button-mobile-notch.png
+📖 Storybook:  http://localhost:6006/?path=/story/components-button--primary
+
+Issue #1: Touch Target Too Small
+  Type:     touch_target
+  Severity: warning
+  Element:  Secondary action button (bottom right)
+
+  🤖 Haiku's Reasoning:
+  ┌─────────────────────────────────────────────────────────────────────────┐
+  │ "I measured the secondary button at approximately 36px height. Apple's  │
+  │ HIG recommends 44×44px minimum for touch targets to ensure reliable     │
+  │ tapping, especially on notch devices where users may be adjusting grip. │
+  │ The primary button meets the standard at 48px, but the secondary button │
+  │ falls short. This could lead to tap frustration on real devices."       │
+  └─────────────────────────────────────────────────────────────────────────┘
+
+  💡 Suggestion: Increase button height to 44px minimum
+  🔧 Fix: Add `min-h-[44px]` to secondary button variants
+
+───────────────────────────────────────────────────────────────────────────────
+
+🖥️ Desktop (1920×1080) - ✅ All Checks Pass
+───────────────────────────────────────────────────────────────────────────────
+📸 Screenshot: file://__snapshots__/Button-desktop.png
+📖 Storybook:  http://localhost:6006/?path=/story/components-button--primary
+
+  🤖 Haiku's Analysis:
+  ┌─────────────────────────────────────────────────────────────────────────┐
+  │ "Layout is clean with proper alignment. Typography contrast measured    │
+  │ at approximately 4.8:1 against the background, exceeding WCAG AA        │
+  │ requirements (4.5:1). All interactive elements are appropriately sized  │
+  │ for desktop interaction. Brand colors match the guide specification."   │
+  └─────────────────────────────────────────────────────────────────────────┘
+
+═══════════════════════════════════════════════════════════════════════════════
+                              SUMMARY
+═══════════════════════════════════════════════════════════════════════════════
+
+Category Results:
+───────────────────────────────────────
+✅ Layout:        7/7 viewports pass
+✅ Typography:    7/7 viewports pass
+⚠️ Touch Targets: 6/7 viewports pass (1 warning)
+✅ Safe Areas:    7/7 viewports pass
+✅ Brand:         7/7 viewports pass
+───────────────────────────────────────
+
+Quick Links:
+───────────────────────────────────────
+📸 All Screenshots: file://__snapshots__/
+📖 Storybook:       http://localhost:6006/?path=/story/components-button
+🧪 Playwright:      file://playwright-report/index.html
+📊 Coverage:        file://coverage/index.html
+
+───────────────────────────────────────
+Result: ⚠️ PASS WITH WARNINGS (1 warning, 0 critical)
+───────────────────────────────────────
+```
+
+## Handling Visual Diffs
+
+When visual differences are detected:
+
+```
+⚠️ Visual Differences Detected
+
+Component: Card
+Viewport: Desktop
+
+Changes:
+- Border radius changed from 4px to 8px
+- Shadow depth increased
+
+Expected: __snapshots__/Card-desktop-expected.png
+Actual:   __snapshots__/Card-desktop-actual.png
+Diff:     __snapshots__/Card-desktop-diff.png
+
+Actions:
+1. [u] Update baseline (accept change)
+2. [r] Reject change (fix code)
+3. [i] Ignore this viewport
+
+Choice? >
+```
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `[component]` | Component to test | All components |
+| `--update` | Update baselines | false |
+| `--viewport` | Specific viewport | All 7 |
+| `--ai` | Include AI analysis | true |
+
+## Examples
+
+```bash
+# Run all visual tests
+/test-visual
+
+# Test specific component
+/test-visual Button
+
+# Update baselines
+/test-visual --update
+
+# Single viewport
+/test-visual --viewport=mobile-portrait
+```
+
+## Output Format
+
+```
+═══════════════════════════════════════
+Visual Test Results: ✅ PASS / ❌ FAIL
+═══════════════════════════════════════
+Components: 12 tested
+Viewports:  7 each (84 total screenshots)
+AI Analysis: ✅ No issues found
+Duration:   28s
+═══════════════════════════════════════
+```
+
+## Autonomous Loop Completion (Ralph Wiggum Pattern)
+
+When running in autonomous mode (`--auto` flag or `/ralph-loop`), this skill supports
+self-terminating loops for iterative visual QA cycles.
+
+### Promise Signal
+
+After completing visual analysis and fixing all issues, output:
+
+```
+<promise>VISUAL_CLEAN</promise>
+```
+
+This signal is detected by the `completion-promise-detector.py` hook, which:
+1. Records the promise in `.claude/completion-promises.json`
+2. Allows graceful workflow termination
+3. Prevents infinite visual QA loops
+
+### When to Output the Promise
+
+Output `<promise>VISUAL_CLEAN</promise>` when:
+- All 7 viewports have been tested
+- All Haiku-detected issues have been fixed
+- Re-analysis confirms no remaining issues
+- Screenshots match expected baselines
+
+### Iterative Visual QA Loop
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   VISUAL QA LOOP (Ralph Wiggum)                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Capture screenshots (7 viewports)                           │
+│     └─ Spawn Haiku for AI analysis                              │
+│                                                                 │
+│  2. Issues found?                                               │
+│     └─ Fix layout, typography, touch targets, etc.              │
+│                                                                 │
+│  3. Re-capture and re-analyze                                   │
+│     └─ Still issues? → Loop back to step 2                      │
+│                                                                 │
+│  4. All viewports clean?                                        │
+│     └─ Output: <promise>VISUAL_CLEAN</promise>                  │
+│     └─ Hook detects → Workflow terminates gracefully            │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Credit:** Ralph Wiggum pattern by [Geoffrey Huntley](https://ghuntley.com/ralph/)
+
+## Integration
+
+Invoked during:
+- `/hustle-ui-create` Phase 11 (Visual Testing)
+- `/hustle-ui-create-page` Phase 11 (Visual Testing)
+
+## See Also
+
+- `/test-unit` - Unit tests
+- `/test-e2e` - E2E tests
+- `/test-debug` - Debug failures
+- `/ralph-loop` - Autonomous loop execution
+- [docs/AUTONOMOUS_LOOPS.md](../../docs/AUTONOMOUS_LOOPS.md) - Pattern documentation

package/.skills/token-report/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: token-report
+description: Generate token usage report by workflow phase
+tools: Bash, Read
+model: haiku
+---
+
+# Token Report Skill
+
+Generate an **estimated** token usage report showing approximate costs by workflow phase.
+
+> **Note:** Token counts are estimated based on ccusage session data correlated with
+> phase timestamps. Actual usage may vary by ±10%. For precise billing, check your
+> Anthropic dashboard.
+
+## When to Use
+
+- After completing an API workflow
+- To understand cost distribution across phases
+- For budget planning and optimization
+- When investigating expensive operations
+
+## Execution Steps
+
+### Step 1: Check ccusage Installation
+
+```bash
+which ccusage || npx ccusage --version
+```
+
+If not installed:
+```bash
+npm install -g ccusage
+```
+
+### Step 2: Read State File
+
+```bash
+cat .claude/api-dev-state.json | jq '.token_usage'
+```
+
+### Step 3: Get Current Session Usage
+
+```bash
+npx ccusage session --json
+```
+
+### Step 4: Generate Report
+
+```
+═══════════════════════════════════════════════════════
+           TOKEN USAGE REPORT (ESTIMATED)
+═══════════════════════════════════════════════════════
+
+Session Started: 2025-12-29 10:00:00
+Total Duration: 45 minutes
+
+Phase Breakdown:
+─────────────────────────────────────────────────────
+Phase                    Tokens      Cost      % Total
+─────────────────────────────────────────────────────
+1. Disambiguation         1,200     $0.01        2.7%
+2. Scope                  1,500     $0.02        3.3%
+3. Initial Research       8,400     $0.08       18.7%
+4. Interview              3,100     $0.03        6.9%
+5. Deep Research         12,500     $0.13       27.8%
+6. Schema                 2,800     $0.03        6.2%
+7. Environment              500     $0.01        1.1%
+8. TDD Red                4,200     $0.04        9.3%
+9. TDD Green              5,100     $0.05       11.3%
+10. Verify                3,200     $0.03        7.1%
+11. Code Review           1,500     $0.02        3.3%
+12. Refactor                800     $0.01        1.8%
+13. Documentation           200     $0.00        0.4%
+14. Completion              100     $0.00        0.2%
+─────────────────────────────────────────────────────
+TOTAL                    45,100     $0.45      100.0%
+═══════════════════════════════════════════════════════
+
+Cost Analysis:
+─────────────────────────────────────────────────────
+Most Expensive Phase: Deep Research (27.8%)
+Optimization Tip: Use targeted searches to reduce research tokens
+
+Research Phases: 40.5% of tokens
+Implementation Phases: 20.6% of tokens
+Verification Phases: 10.4% of tokens
+─────────────────────────────────────────────────────
+```
+
+## Output Interpretation
+
+| Metric | Good | Warning | Action |
+|--------|------|---------|--------|
+| Research % | < 40% | 40-60% | > 60% - Optimize queries |
+| Interview % | < 10% | 10-20% | > 20% - Reduce questions |
+| TDD % | 15-25% | 10-30% | < 10% - Insufficient testing |
+
+## Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--endpoint` | Specific endpoint to report | All |
+| `--format` | Output format (text/json) | text |
+| `--compare` | Compare with previous run | false |
+
+## Examples
+
+```bash
+# Full report
+/token-report
+
+# Specific endpoint
+/token-report --endpoint=users-create
+
+# JSON output for processing
+/token-report --format=json
+
+# Compare with last run
+/token-report --compare
+```
+
+## Integration
+
+This skill reads from:
+- `.claude/api-dev-state.json` - Phase timestamps and token data
+- ccusage logs - Session token counts
+
+## See Also
+
+- `/api-status` - Current workflow status
+- `/api-verify` - Verification phase