@hustle-together/api-dev-tools 3.6.5 → 3.9.2

package/hooks/update-ui-showcase.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for Write/Edit
+Purpose: Auto-create UI Showcase page when first component/page is created
+
+This hook monitors for new component or page registrations. When the first
+UI element is added to registry.json, it creates the UI Showcase page
+at src/app/ui-showcase/ if it doesn't exist.
+
+Version: 3.9.0
+
+Returns:
+  - {"continue": true} - Always continues
+  - May include "notify" about showcase creation
+"""
+import json
+import sys
+from pathlib import Path
+import shutil
+
+# State and registry files in .claude/ directory
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+REGISTRY_FILE = Path(__file__).parent.parent / "registry.json"
+
+
+def copy_showcase_templates(cwd):
+    """Copy UI showcase templates to src/app/ui-showcase/."""
+    # Source templates (installed by CLI)
+    templates_dir = Path(__file__).parent.parent / "templates" / "ui-showcase"
+
+    # Destination
+    showcase_dir = cwd / "src" / "app" / "ui-showcase"
+
+    # Create directory if needed
+    showcase_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy template files
+    templates_to_copy = [
+        ("page.tsx", "page.tsx"),
+        ("UIShowcase.tsx", "_components/UIShowcase.tsx"),
+        ("PreviewCard.tsx", "_components/PreviewCard.tsx"),
+        ("PreviewModal.tsx", "_components/PreviewModal.tsx"),
+    ]
+
+    created_files = []
+    for src_name, dest_name in templates_to_copy:
+        src_path = templates_dir / src_name
+        dest_path = showcase_dir / dest_name
+
+        # Create subdirectories if needed
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if src_path.exists() and not dest_path.exists():
+            shutil.copy2(src_path, dest_path)
+            created_files.append(str(dest_path.relative_to(cwd)))
+
+    return created_files
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+
+    # Only process Write/Edit operations
+    if tool_name not in ["Write", "Edit"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    workflow = state.get("workflow", "")
+
+    # Only apply for UI workflows
+    if workflow not in ["ui-create-component", "ui-create-page"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if completion phase is complete
+    active_element = state.get("active_element", "")
+    elements = state.get("elements", {})
+
+    if active_element and active_element in elements:
+        phases = elements[active_element].get("phases", {})
+    else:
+        phases = state.get("phases", {})
+
+    completion = phases.get("completion", {})
+    if completion.get("status") != "complete":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if showcase already exists
+    cwd = Path.cwd()
+    showcase_page = cwd / "src" / "app" / "ui-showcase" / "page.tsx"
+
+    if showcase_page.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if we have components or pages in registry
+    if not REGISTRY_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        registry = json.loads(REGISTRY_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    components = registry.get("components", {})
+    pages = registry.get("pages", {})
+
+    # Create showcase if we have at least one component or page
+    if components or pages:
+        created_files = copy_showcase_templates(cwd)
+
+        if created_files:
+            print(json.dumps({
+                "continue": True,
+                "notify": f"Created UI Showcase at /ui-showcase ({len(created_files)} files)"
+            }))
+        else:
+            print(json.dumps({"continue": True}))
+    else:
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.6.5",
-  "description": "Interview-driven, research-first API development workflow with continuous verification loops for Claude Code",
+  "version": "3.9.2",
+  "description": "Interview-driven, research-first API and UI development workflow with continuous verification loops for Claude Code",
   "main": "bin/cli.js",
   "bin": {
     "api-dev-tools": "./bin/cli.js"
@@ -23,10 +23,16 @@
     "claude",
     "claude-code",
     "api-development",
+    "ui-development",
+    "components",
+    "storybook",
+    "playwright",
     "tdd",
     "test-driven-development",
     "interview-driven",
     "api-testing",
+    "api-orchestration",
+    "combine",
     "documentation",
     "workflow",
     "automation"

package/templates/BRAND_GUIDE.md

@@ -0,0 +1,299 @@
+# Hustle Together Brand Guide
+
+> This file is used by `/hustle-ui-create` during Phase 3 (Design Research).
+> Update this guide to match your project's branding before creating components.
+
+## Core Colors
+
+### Hustle Brand Colors
+| Name | Hex | RGB | Usage |
+|------|-----|-----|-------|
+| **Hustle Red** | #BA0C2F | rgb(186, 12, 47) | Primary accent, buttons, links, focus rings |
+| **Hustle Red Hover** | #8A0923 | rgb(138, 9, 35) | Hover states |
+| **Hustle Red Light** | rgba(186, 12, 47, 0.1) | - | Backgrounds, badges |
+
+### Light Mode
+| Name | Hex | Usage |
+|------|-----|-------|
+| **Background** | #FFFFFF | Main background |
+| **Background Secondary** | #F8F8F8 | Cards, sections |
+| **Background Tertiary** | #F0F0F0 | Nested elements |
+| **Text** | #1A1A1A | Primary text |
+| **Text Muted** | #666666 | Secondary text |
+| **Border** | #E5E5E5 | Light borders |
+| **Border Strong** | #000000 | Boxy card borders |
+
+### Dark Mode
+| Name | Hex | Usage |
+|------|-----|-------|
+| **Background** | #050505 | Main background |
+| **Background Secondary** | #111111 | Cards, sections |
+| **Background Tertiary** | #1A1A1A | Nested elements |
+| **Text** | #F0F0F0 | Primary text |
+| **Text Muted** | #888888 | Secondary text |
+| **Border** | #333333 | Dark borders |
+
+### Status Colors
+| Name | Hex | Usage |
+|------|-----|-------|
+| **Success** | #22C55E | Completed, passed, positive |
+| **Warning** | #EAB308 | Caution, pending |
+| **Error** | #EF4444 | Failed, errors, destructive |
+| **Info** | #3B82F6 | Informational |
+
+## Typography
+
+### Font Stack
+```css
+/* Main font */
+--font-main: -apple-system, BlinkMacSystemFont, 'SF Pro Text', 'Segoe UI', Roboto, sans-serif;
+
+/* Monospace */
+--font-mono: 'SF Mono', Monaco, Inconsolata, 'Fira Code', monospace;
+```
+
+### Font Sizes
+- **xs:** 0.75rem (12px)
+- **sm:** 0.875rem (14px)
+- **base:** 1rem (16px)
+- **lg:** 1.125rem (18px)
+- **xl:** 1.25rem (20px)
+- **2xl:** 1.5rem (24px)
+- **3xl:** 1.875rem (30px)
+- **4xl:** 2.25rem (36px)
+- **5xl:** 3rem (48px)
+- **6xl:** 4rem (64px)
+
+### Font Weights
+- **Normal:** 400
+- **Medium:** 500
+- **Semibold:** 600
+- **Bold:** 700
+- **Extrabold:** 800
+
+### Line Heights
+- **Tight:** 1.1 (headings)
+- **Normal:** 1.5 (body)
+- **Relaxed:** 1.6 (paragraphs)
+
+## Spacing
+
+### Base Unit
+- **Base:** 4px (0.25rem)
+
+### Scale
+| Token | Value | Pixels |
+|-------|-------|--------|
+| 0 | 0 | 0 |
+| 1 | 0.25rem | 4px |
+| 2 | 0.5rem | 8px |
+| 3 | 0.75rem | 12px |
+| 4 | 1rem | 16px |
+| 5 | 1.25rem | 20px |
+| 6 | 1.5rem | 24px |
+| 8 | 2rem | 32px |
+| 10 | 2.5rem | 40px |
+| 12 | 3rem | 48px |
+| 16 | 4rem | 64px |
+
+### Common Usage
+- **Component Padding:** 16px (1rem)
+- **Card Padding:** 24px (1.5rem)
+- **Section Margin:** 32px (2rem)
+- **Page Padding:** 60px (desktop), 30px (mobile)
+
+## Component Styling
+
+### Design Philosophy
+**90s Boxy Style** - Clean, minimal, sharp edges with solid borders.
+
+### Border Radius
+- **Default:** 0 (boxy, no rounding)
+- **Soft:** 4px (subtle rounding for inputs only)
+- **Full:** 9999px (pills, avatars)
+
+### Border Width
+- **Cards:** 2px solid
+- **Inputs:** 2px solid (focus: Hustle Red)
+- **Subtle:** 1px solid
+
+### Shadows
+```css
+/* Float effect for cards */
+--shadow-float: 0 10px 30px -10px rgba(0, 0, 0, 0.1);
+
+/* Hover shadow */
+--shadow-hover: 4px 4px 0px 0px rgba(186, 12, 47, 0.2);
+
+/* No shadow for flat design */
+--shadow-none: none;
+```
+
+### Focus Ring
+```css
+/* Hustle Red focus ring */
+outline: 2px solid #BA0C2F;
+outline-offset: 2px;
+```
+
+### Transitions
+```css
+/* Standard transition */
+transition: all 0.2s ease;
+transition-property: color, background-color, border-color, opacity, transform, box-shadow;
+```
+
+## Buttons
+
+### Primary Button (Hustle Red)
+```css
+background: #BA0C2F;
+color: #ffffff;
+padding: 12px 24px;
+border: 2px solid #BA0C2F;
+border-radius: 0;
+font-weight: 700;
+```
+
+### Secondary Button
+```css
+background: #ffffff;
+color: #000000;
+padding: 12px 24px;
+border: 2px solid #000000;
+border-radius: 0;
+font-weight: 700;
+```
+
+### Ghost Button
+```css
+background: transparent;
+color: #000000;
+padding: 12px 24px;
+border: 2px solid #000000;
+border-radius: 0;
+font-weight: 700;
+```
+
+### Button Hover States
+- **Primary:** background: #8A0923
+- **Secondary:** border-color: #BA0C2F
+- **Ghost:** border-color: #BA0C2F
+
+### Button Sizes
+| Size | Padding | Font Size |
+|------|---------|-----------|
+| Small | 8px 16px | 12px |
+| Medium | 12px 24px | 14px |
+| Large | 16px 32px | 16px |
+
+## Form Elements
+
+### Input Fields
+```css
+background: #ffffff;
+border: 2px solid #000000;
+border-radius: 0;
+padding: 12px 16px;
+font-size: 14px;
+```
+
+### Input States
+- **Focus:** `border-color: #BA0C2F;`
+- **Error:** `border-color: #EF4444;`
+- **Disabled:** `background: #F5F5F5; opacity: 0.5;`
+
+### Labels
+```css
+display: block;
+margin-bottom: 8px;
+font-weight: 700;
+font-size: 14px;
+```
+
+## Cards
+
+### Default Card
+```css
+background: #ffffff;
+border: 2px solid #000000;
+border-radius: 0;
+padding: 24px;
+```
+
+### Card Hover
+```css
+border-color: #BA0C2F;
+box-shadow: 4px 4px 0px 0px rgba(186, 12, 47, 0.2);
+```
+
+### Card (Dark Mode)
+```css
+background: #111111;
+border: 2px solid #333333;
+```
+
+## Hero Headers
+
+### Animated Grid Hero
+- Height: 450px
+- Canvas-based 3D perspective grid animation
+- Hustle Red accent cells (#BA0C2F)
+- Fog/fade gradient overlay
+- Left-aligned content
+- Padding: 60px (desktop), 30px (mobile)
+
+## Dark Mode Implementation
+
+### CSS Custom Properties
+```css
+[data-theme="dark"] {
+  --bg: #050505;
+  --text: #f0f0f0;
+  --text-muted: #888888;
+  --border: #333333;
+  --surface-glass: rgba(20, 20, 20, 0.8);
+}
+```
+
+### Tailwind Classes
+Use `dark:` prefix for all dark mode styles:
+```html
+<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
+```
+
+## Voice & Tone
+
+### Writing Style
+- **Professional** but approachable
+- **Clear** and concise
+- **Technical precision** - no fluff
+- **No emojis** in code or documentation (unless requested)
+
+### UI Copy Guidelines
+- Use active voice
+- Keep button labels to 2-3 words
+- Error messages should explain how to fix the issue
+- Success messages should confirm the action taken
+
+## Accessibility Requirements
+
+### Color Contrast
+- **Normal Text:** Minimum 4.5:1 ratio (WCAG AA)
+- **Large Text:** Minimum 3:1 ratio
+- **Interactive Elements:** Minimum 3:1 ratio
+
+### Focus Indicators
+- All interactive elements must have visible focus states
+- Hustle Red (#BA0C2F) focus ring
+- Focus should not be removed or hidden
+
+### Touch Targets
+- Minimum size: 44px x 44px
+- Minimum spacing: 8px between targets
+
+---
+
+**Last Updated:** 2025-12-12
+**Brand Version:** 3.9.1
+**Design System:** Hustle Together

package/templates/CLAUDE-SECTION.md

@@ -1,4 +1,4 @@
-## API Development Workflow (v3.0)
+## Hustle API Development Workflow (v3.7.0)
 
 This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first API development.
 
@@ -6,12 +6,14 @@ This project uses **@hustle-together/api-dev-tools** for interview-driven, resea
 
 | Command | Purpose |
 |---------|---------|
-| `/api-create [endpoint]` | Complete 13-phase workflow |
-| `/api-interview [endpoint]` | Questions FROM research findings |
-| `/api-research [library]` | Adaptive propose-approve research |
-| `/api-verify [endpoint]` | Re-research and verify implementation |
-| `/api-env [endpoint]` | Check API keys |
-| `/api-status [endpoint]` | Track progress |
+| `/hustle-api-create [endpoint]` | Complete 13-phase workflow |
+| `/hustle-api-interview [endpoint]` | Questions FROM research findings |
+| `/hustle-api-research [library]` | Adaptive propose-approve research |
+| `/hustle-api-verify [endpoint]` | Re-research and verify implementation |
+| `/hustle-api-env [endpoint]` | Check API keys |
+| `/hustle-api-status [endpoint]` | Track progress |
+| `/hustle-api-continue [endpoint]` | Resume interrupted workflow |
+| `/hustle-api-sessions` | Browse saved session logs |
 
 ### 13-Phase Flow
 
@@ -42,43 +44,73 @@ Phase 13: COMPLETION         - Final verification, commit
 ### State Tracking
 
 All progress is tracked in `.claude/api-dev-state.json`:
-- Current phase and status for each
+- Current phase and status for each endpoint
 - Interview decisions (injected during implementation)
 - Research sources with freshness tracking
 - Turn count for re-grounding
+- Multi-API support with active endpoint pointer
 
 ### Research Cache
 
 Research is cached in `.claude/research/` with 7-day freshness:
 - `index.json` - Freshness tracking
 - `[api-name]/CURRENT.md` - Latest research
+- `[api-name]/sources.json` - Research sources
+- `[api-name]/interview.json` - Interview decisions
+- `[api-name]/schema.json` - Schema snapshot
 - Stale research (>7 days) triggers re-research prompt
 
-### Hooks (Automatic Enforcement)
-
-| Hook | When | Action |
-|------|------|--------|
-| `session-startup.py` | Session start | Inject state context |
-| `enforce-external-research.py` | API questions | Require research first |
-| `enforce-research.py` | Write/Edit | Block without research |
-| `enforce-interview.py` | Write/Edit | Inject interview decisions |
-| `verify-after-green.py` | Tests pass | Trigger Phase 9 |
-| `periodic-reground.py` | Every 7 turns | Re-inject context |
-| `api-workflow-check.py` | Stop | Block if incomplete |
+### Hooks (25 Total - Automatic Enforcement)
+
+| Hook | Event | Action |
+|------|-------|--------|
+| `session-startup.py` | SessionStart | Inject state context |
+| `detect-interruption.py` | SessionStart | Detect interrupted workflows |
+| `enforce-external-research.py` | UserPromptSubmit | Require research first |
+| `enforce-disambiguation.py` | PreToolUse | Phase 1 enforcement |
+| `enforce-scope.py` | PreToolUse | Phase 2 enforcement |
+| `enforce-research.py` | PreToolUse | Phase 3 enforcement |
+| `enforce-interview.py` | PreToolUse | Phase 4 - inject decisions |
+| `enforce-deep-research.py` | PreToolUse | Phase 5 enforcement |
+| `enforce-schema.py` | PreToolUse | Phase 6 enforcement |
+| `enforce-environment.py` | PreToolUse | Phase 7 enforcement |
+| `enforce-tdd-red.py` | PreToolUse | Phase 8 enforcement |
+| `verify-implementation.py` | PreToolUse | Phase 9 helper |
+| `enforce-verify.py` | PreToolUse | Phase 10 enforcement |
+| `enforce-refactor.py` | PreToolUse | Phase 11 enforcement |
+| `enforce-documentation.py` | PreToolUse | Phase 12 enforcement |
+| `enforce-questions-sourced.py` | PreToolUse | Validate questions from research |
+| `enforce-schema-from-interview.py` | PreToolUse | Validate schema from interview |
+| `track-tool-use.py` | PostToolUse | Log research, count turns |
+| `periodic-reground.py` | PostToolUse | Re-inject context every 7 turns |
+| `track-scope-coverage.py` | PostToolUse | Track implemented vs deferred |
+| `verify-after-green.py` | PostToolUse | Trigger Phase 10 after tests pass |
+| `cache-research.py` | PostToolUse | Create research cache files |
+| `generate-manifest-entry.py` | PostToolUse | Auto-generate API documentation |
+| `api-workflow-check.py` | Stop | Block if incomplete, generate output |
+| `session-logger.py` | Stop | Save session to api-sessions |
+
+### Auto-Generated Documentation
+
+When Phase 12 completes, `generate-manifest-entry.py` automatically creates:
+- **Comprehensive curl examples** (minimal, full, auth, enum variations, boundary values)
+- **Complete test cases** (success, validation, required fields, types, boundaries, arrays)
+- **Parameter documentation** with all possible values
+- **Ready-to-use entries** for `api-tests-manifest.json`
 
 ### Usage
 
 ```bash
 # Full automated workflow
-/api-create my-endpoint
+/hustle-api-create my-endpoint
 
 # Manual step-by-step
-/api-research [library]
-/api-interview [endpoint]
-/api-env [endpoint]
+/hustle-api-research [library]
+/hustle-api-interview [endpoint]
+/hustle-api-env [endpoint]
 /red
 /green
-/api-verify [endpoint]
+/hustle-api-verify [endpoint]
 /refactor
 /commit
 ```