@hustle-together/api-dev-tools 3.12.16 → 4.5.3

package/hooks/run-code-review.py

@@ -1,31 +1,35 @@
 #!/usr/bin/env python3
 """
-Phase 11: AI Code Review Hook
+Phase 11: AI Code Review Hook (Ralph Wiggum Loop Pattern)
 
-Triggers Greptile AI code review after Phase 10 (Verify) and BEFORE Phase 12 (Refactor).
-This ensures issues are caught early and can be fixed during the refactor phase,
-rather than after PR creation when it's too late.
+Triggers Greptile AI code review and LOOPS until all issues are fixed.
+This ensures code quality before proceeding to refactor phase.
 
-Hook Type: PostToolUse (triggers after tests pass in Phase 9/10)
+Hook Type: PostToolUse (triggers after tests pass)
 
-Greptile API:
-    POST https://api.greptile.com/v2/query
-    - Analyzes code changes against entire codebase context
-    - Returns issues with file:line references
-    - Provides actionable fix suggestions
+Ralph Wiggum Pattern:
+    1. Run Greptile review
+    2. If issues found → inject context for agent to fix
+    3. Agent fixes issues
+    4. Tests re-run → hook triggers again
+    5. Re-review with Greptile
+    6. Loop until clean OR max iterations
+    7. Emit <promise>REVIEW_CLEAN</promise>
 
 Environment Variables:
     GREPTILE_API_KEY: Your Greptile API key (get from https://app.greptile.com)
     GITHUB_TOKEN: GitHub Personal Access Token with repo access
     CODE_REVIEW_ENABLED: Set to 'true' to enable (default: true)
+    CODE_REVIEW_MAX_ITERATIONS: Max review cycles (default: 5)
 
-Version: 1.1.0
+Version: 2.0.0
 """
 import os
 import sys
 import json
 import subprocess
 from pathlib import Path
+from datetime import datetime
 
 # Add lib directory to path for imports
 HOOK_DIR = Path(__file__).parent
@@ -44,6 +48,10 @@ try:
 except ImportError:
     GREPTILE_AVAILABLE = False
 
+# State file for tracking review loops
+REVIEW_STATE_FILE = ".claude/code-review-state.json"
+MAX_ITERATIONS = int(os.environ.get("CODE_REVIEW_MAX_ITERATIONS", "5"))
+
 
 def get_git_diff() -> tuple:
     """Get the current git diff and changed files."""
@@ -98,7 +106,44 @@ def get_repo_info() -> tuple:
     return None, None
 
 
-def load_state() -> dict:
+def load_review_state() -> dict:
+    """Load code review loop state."""
+    state_file = Path.cwd() / REVIEW_STATE_FILE
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {
+        "iteration": 0,
+        "issues_found": [],
+        "status": "pending",
+        "started_at": None,
+        "last_review_at": None
+    }
+
+
+def save_review_state(state: dict):
+    """Save code review loop state."""
+    state_file = Path.cwd() / REVIEW_STATE_FILE
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        state_file.write_text(json.dumps(state, indent=2))
+    except IOError:
+        pass
+
+
+def clear_review_state():
+    """Clear review state after successful completion."""
+    state_file = Path.cwd() / REVIEW_STATE_FILE
+    if state_file.exists():
+        try:
+            state_file.unlink()
+        except IOError:
+            pass
+
+
+def load_workflow_state() -> dict:
     """Load current workflow state."""
     state_file = Path.cwd() / ".claude" / "api-dev-state.json"
     if state_file.exists():
@@ -109,21 +154,22 @@ def load_state() -> dict:
     return {}
 
 
-def update_state_with_review(review_summary: dict):
-    """Update state file with code review results."""
+def update_workflow_state_with_review(review_summary: dict, iteration: int):
+    """Update workflow state file with code review results."""
     state_file = Path.cwd() / ".claude" / "api-dev-state.json"
-    state = load_state()
+    state = load_workflow_state()
 
     # Add or update code_review phase
     if "phases" not in state:
         state["phases"] = {}
 
     state["phases"]["code_review"] = {
-        "status": "complete",
+        "status": "in_progress" if review_summary.get("issue_count", 0) > 0 else "complete",
+        "iteration": iteration,
         "score": review_summary.get("score", 0),
         "issues_found": review_summary.get("issue_count", 0),
         "suggestions": review_summary.get("suggestion_count", 0),
-        "reviewed_at": __import__("datetime").datetime.now().isoformat()
+        "reviewed_at": datetime.now().isoformat()
     }
 
     try:
@@ -140,7 +186,7 @@ def should_run_review(hook_input: dict) -> bool:
 
     tool_name = hook_input.get("tool_name", "")
 
-    # Run after tests pass (Phase 9/10) - triggers before refactoring
+    # Run after tests pass (Phase 9/10)
     if tool_name == "Bash":
         tool_input = hook_input.get("tool_input", {})
         command = tool_input.get("command", "")
@@ -160,8 +206,40 @@ def should_run_review(hook_input: dict) -> bool:
     return False
 
 
+def format_issues_for_context(issues: list) -> str:
+    """Format issues as context for the agent to fix."""
+    if not issues:
+        return ""
+
+    lines = [
+        "",
+        "=" * 60,
+        "CODE REVIEW ISSUES TO FIX (Ralph Wiggum Loop)",
+        "=" * 60,
+        "",
+        "The following issues were found by Greptile code review.",
+        "Please fix ALL issues, then run tests again.",
+        "The review will re-run automatically after tests pass.",
+        "",
+        "ISSUES:",
+    ]
+
+    for i, issue in enumerate(issues, 1):
+        lines.append(f"  {i}. {issue}")
+
+    lines.extend([
+        "",
+        "After fixing all issues, run: pnpm test",
+        "Review will loop until all issues are resolved.",
+        "=" * 60,
+        ""
+    ])
+
+    return "\n".join(lines)
+
+
 def main():
-    """Main hook entry point."""
+    """Main hook entry point with Ralph Wiggum loop pattern."""
     # Read hook input
     try:
         hook_input = json.loads(sys.stdin.read())
@@ -190,6 +268,28 @@ def main():
         }))
         return
 
+    # Load current review loop state
+    review_state = load_review_state()
+
+    # Increment iteration
+    review_state["iteration"] += 1
+    iteration = review_state["iteration"]
+
+    # Check max iterations
+    if iteration > MAX_ITERATIONS:
+        print(json.dumps({
+            "continue": True,
+            "message": f"Code review max iterations ({MAX_ITERATIONS}) reached. Proceeding with warnings.\n\n<promise>REVIEW_CLEAN</promise>"
+        }))
+        clear_review_state()
+        return
+
+    # Track start time on first iteration
+    if iteration == 1:
+        review_state["started_at"] = datetime.now().isoformat()
+
+    review_state["last_review_at"] = datetime.now().isoformat()
+
     # Get repository info
     repo_owner, repo_name = get_repo_info()
     if not repo_owner or not repo_name:
@@ -204,11 +304,12 @@ def main():
     if not diff_content:
         print(json.dumps({
             "continue": True,
-            "message": "No changes detected - skipping code review"
+            "message": "No changes detected - code review complete.\n\n<promise>REVIEW_CLEAN</promise>"
         }))
+        clear_review_state()
         return
 
-    # Run the review
+    # Run the Greptile review
     result = review_changes(
         repo_owner=repo_owner,
         repo_name=repo_name,
@@ -223,22 +324,68 @@ def main():
         }))
         return
 
-    # Parse and display results
+    # Parse results
     summary = get_review_summary(result)
-    update_state_with_review(summary)
+    update_workflow_state_with_review(summary, iteration)
 
     # Format for display
     display_output = format_review_for_display(summary)
 
-    # Determine if we should block based on critical issues
-    has_critical = summary.get("score", 10) < 5
+    # Check if issues found
+    issue_count = summary.get("issue_count", 0)
+    issues = summary.get("issues", [])
+
+    if issue_count == 0:
+        # All clean! Emit promise and proceed
+        review_state["status"] = "complete"
+        save_review_state(review_state)
+
+        output = f"""
+{display_output}
+
+================================================================================
+REVIEW LOOP COMPLETE (Iteration {iteration}/{MAX_ITERATIONS})
+================================================================================
+All code review checks passed!
+Proceeding to next phase.
+
+<promise>REVIEW_CLEAN</promise>
+"""
+        print(json.dumps({
+            "continue": True,
+            "message": output
+        }))
+        clear_review_state()
+        return
+
+    # Issues found - save state and block for fixes
+    review_state["status"] = "needs_fixing"
+    review_state["issues_found"] = issues
+    save_review_state(review_state)
+
+    # Format issues as context for agent
+    issues_context = format_issues_for_context(issues)
+
+    output = f"""
+{display_output}
+
+================================================================================
+REVIEW LOOP - ITERATION {iteration}/{MAX_ITERATIONS}
+================================================================================
+{issue_count} issue(s) found. Fix them and run tests again.
+Review will re-run automatically after tests pass.
+{issues_context}
+"""
 
+    # Block workflow - agent needs to fix issues
     print(json.dumps({
-        "continue": not has_critical,
-        "message": display_output,
+        "continue": False,  # Block until fixed
+        "message": output,
         "review_score": summary.get("score", 0),
-        "issues_count": summary.get("issue_count", 0),
-        "action_required": has_critical
+        "issues_count": issue_count,
+        "iteration": iteration,
+        "action_required": True,
+        "next_action": "Fix the issues above, then run tests again"
     }))
 
 

package/hooks/session-logger.py

@@ -23,6 +23,13 @@ from datetime import datetime
 from pathlib import Path
 import shutil
 
+# Import shared utilities for NTFY
+try:
+    from hook_utils import send_ntfy_notification
+    HAS_NTFY = True
+except ImportError:
+    HAS_NTFY = False
+
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 SESSIONS_DIR = Path(__file__).parent.parent / "api-sessions"
 RESEARCH_DIR = Path(__file__).parent.parent / "research"
@@ -270,12 +277,31 @@ def main():
     try:
         session_dir = save_session(endpoint, endpoint_data, state)
 
+        # Send NTFY notification on session end
+        if HAS_NTFY:
+            status = endpoint_data.get("status", "unknown")
+            if status == "complete":
+                send_ntfy_notification(
+                    title=f"✅ Session Complete: {endpoint}",
+                    message=f"Completed {len(completed)}/13 phases. Session saved.",
+                    priority="default",
+                    tags=["white_check_mark", "robot"]
+                )
+            else:
+                send_ntfy_notification(
+                    title=f"📋 Session Ended: {endpoint}",
+                    message=f"Completed {len(completed)}/13 phases. Status: {status}",
+                    priority="low",
+                    tags=["clipboard", "robot"]
+                )
+
         output = {
             "hookSpecificOutput": {
                 "sessionSaved": True,
                 "endpoint": endpoint,
                 "sessionDir": str(session_dir),
-                "phasesCompleted": len(completed)
+                "phasesCompleted": len(completed),
+                "notificationSent": HAS_NTFY
             }
         }
 

package/hooks/session-startup.py

@@ -18,6 +18,12 @@ Updated in v3.6.7:
   - Support multi-API state structure (endpoints object)
   - Read research index from .claude/research/index.json file
   - Calculate freshness from timestamps
+
+Updated in v4.5.0:
+  - Ensure .claude/ directories exist on session start
+  - Create registry.json from template if not exists
+  - Log session_start event to workflow logs
+  - Detect --dry-run and --resume flags
 """
 import json
 import sys
@@ -25,6 +31,20 @@ import os
 from datetime import datetime
 from pathlib import Path
 
+# Import shared utilities
+try:
+    from hook_utils import (
+        ensure_directories,
+        ensure_registry,
+        log_workflow_event,
+        load_state as utils_load_state,
+        save_state as utils_save_state,
+        get_project_dir
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
@@ -99,6 +119,93 @@ def calculate_days_old(timestamp_str):
         return 0
 
 
+def setup_session():
+    """
+    Initialize session: create directories, registry, log session start.
+    Called at the beginning of every session (v4.5.0).
+
+    Returns:
+        dict: Setup results with directories created, registry status
+    """
+    results = {
+        "directories_created": [],
+        "registry_created": False,
+        "session_logged": False
+    }
+
+    if not UTILS_AVAILABLE:
+        return results
+
+    # Ensure directories exist
+    try:
+        results["directories_created"] = ensure_directories()
+    except Exception:
+        pass
+
+    # Ensure registry exists
+    try:
+        success, created = ensure_registry()
+        results["registry_created"] = created
+    except Exception:
+        pass
+
+    # Log session start event
+    try:
+        log_workflow_event("session_start", {
+            "directories_created": results["directories_created"],
+            "registry_created": results["registry_created"]
+        })
+        results["session_logged"] = True
+    except Exception:
+        pass
+
+    return results
+
+
+def detect_flags(input_data):
+    """
+    Detect --dry-run, --resume, and other flags from conversation context.
+    Sets flags in state for other hooks to use (v4.5.0).
+
+    Args:
+        input_data: Hook input from stdin
+
+    Returns:
+        dict: Detected flags
+    """
+    flags = {
+        "dry_run": False,
+        "resume": None,
+        "parallel": False
+    }
+
+    if not UTILS_AVAILABLE:
+        return flags
+
+    # The conversation context might contain flags
+    # Note: In SessionStart, we have limited context - flags are typically
+    # detected by skills reading the user's initial message
+    # This function prepares the state structure for flag detection
+
+    try:
+        state = utils_load_state()
+
+        # Initialize flags structure if not present
+        if "flags" not in state:
+            state["flags"] = {
+                "dry_run": False,
+                "resume": None,
+                "parallel": False
+            }
+            utils_save_state(state)
+
+        flags = state.get("flags", flags)
+    except Exception:
+        pass
+
+    return flags
+
+
 def main():
     # Read hook input from stdin
     try:
@@ -108,6 +215,12 @@ def main():
 
     cwd = input_data.get("cwd", os.getcwd())
 
+    # v4.5.0: Initialize session (directories, registry, logging)
+    setup_results = setup_session()
+
+    # v4.5.0: Detect and store flags
+    flags = detect_flags(input_data)
+
     # Check if state file exists
     if not STATE_FILE.exists():
         # No active workflow - just continue without injection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.12.16",
+  "version": "4.5.3",
   "description": "Interview-driven, research-first API development toolkit with 14-phase TDD workflow, enforcement hooks, and 23 Agent Skills for cross-platform AI agents",
   "main": "bin/cli.js",
   "bin": {

package/templates/.skills/hustle-interview/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: hustle-interview
+description: Comprehensive project interview for /hustle-build orchestrator - establishes project-wide defaults stored in registry
+version: 1.0.0
+---
+
+# Hustle Interview - Project Configuration
+
+This skill conducts a comprehensive interview to understand the project scope and establish defaults that persist in the registry for all future workflows.
+
+## When to Use
+
+- First time using /hustle-build on a project
+- When orchestrator_defaults in registry.json are empty/null
+- When user wants to reconfigure project defaults
+
+## Interview Sections
+
+### Section 1: Project Overview
+
+Ask about:
+1. **Project Type**: What kind of application? (SaaS, E-commerce, Dashboard, Marketing, Blog, Custom)
+2. **Target Audience**: Who uses this? (Developers, Business users, General public, Internal team)
+3. **Scale**: Expected users/traffic? (MVP/Prototype, Small <1k, Medium <10k, Large >10k)
+
+### Section 2: Technical Stack Confirmation
+
+Verify and record:
+1. **Framework**: Next.js version (App Router or Pages Router?)
+2. **Styling**: Tailwind CSS, CSS Modules, Styled Components, Emotion, Vanilla CSS?
+3. **State Management**: React Context, Zustand, Redux, Jotai, None?
+4. **Database**: Supabase, Firebase, Prisma+PostgreSQL, MongoDB, None?
+
+### Section 3: Error Handling Philosophy
+
+Ask ONE question with options:
+- **try-catch-rethrow**: Traditional try/catch with custom error classes
+- **error-boundary**: React error boundaries with fallback UI
+- **result-type**: Rust-style Result<T, E> pattern (neverthrow library)
+- **error-codes**: Return error codes with lookup table
+
+Store choice in: `registry.orchestrator_defaults.error_handling.style`
+
+### Section 4: Authentication Pattern
+
+Ask ONE question with options:
+- **jwt**: JSON Web Tokens (stateless, API-friendly)
+- **session**: Server-side sessions (traditional, secure)
+- **api-key**: API key authentication (for services/integrations)
+- **oauth**: OAuth 2.0 / OpenID Connect (social login)
+- **none**: No authentication needed
+
+Store choice in: `registry.orchestrator_defaults.authentication.method`
+
+### Section 5: Logging & Observability
+
+Ask ONE question with options:
+- **verbose**: Log everything (development mode)
+- **standard**: Log errors + warnings + key events
+- **minimal**: Log errors only
+- **none**: No logging (not recommended)
+
+Store choice in: `registry.orchestrator_defaults.logging.level`
+
+### Section 6: API Versioning Strategy
+
+Ask ONE question with options:
+- **url-prefix**: `/api/v1/`, `/api/v2/` (most common)
+- **header**: `Accept: application/vnd.api.v1+json`
+- **query-param**: `?version=1`
+- **none**: No versioning (single version)
+
+Store choice in: `registry.orchestrator_defaults.api_versioning.strategy`
+
+### Section 7: Testing Preferences
+
+Ask about:
+1. **Coverage threshold**: What % code coverage is required? (50%, 70%, 80%, 90%)
+2. **Visual viewports**: Which devices matter most? (Confirm all 7 or subset)
+3. **E2E browsers**: Chrome only, or Chrome + Firefox + Safari?
+
+Store in: `registry.orchestrator_defaults.testing`
+
+### Section 8: Platform Targets
+
+Ask ONE question:
+- **web-only**: Just web browser (PWA optional)
+- **web-plus-desktop**: Web + Tauri for Windows/Mac/Linux
+- **web-plus-mobile**: Web + Capacitor for iOS/Android
+- **full-cross-platform**: Web + Desktop + Mobile
+
+Store choice in: `registry.orchestrator_defaults.platform_targets`
+
+Note: If desktop/mobile selected, prompt for setup during first build.
+
+### Section 9: Styling Approach
+
+Already captured in Section 2, but confirm:
+- **tailwind**: Utility-first CSS (default for Hustle)
+- **css-modules**: Scoped CSS with .module.css
+- **styled-components**: CSS-in-JS with tagged templates
+- **emotion**: CSS-in-JS with object styles
+- **vanilla**: Plain CSS files
+
+Store in: `registry.orchestrator_defaults.styling.approach`
+
+## Output
+
+After interview completes:
+
+1. Update `.claude/registry.json` with all choices
+2. Display summary of all decisions
+3. Confirm with user before saving
+4. Note that these can be changed anytime with `/hustle-interview`
+
+## Example Summary Output
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║                    PROJECT CONFIGURATION                       ║
+╠═══════════════════════════════════════════════════════════════╣
+║ Project Type:      SaaS Dashboard                             ║
+║ Framework:         Next.js 15 (App Router)                    ║
+║ Styling:           Tailwind CSS                               ║
+║ State:             Zustand                                    ║
+║ Database:          Supabase                                   ║
+╠───────────────────────────────────────────────────────────────╣
+║ Error Handling:    Result Type (neverthrow)                   ║
+║ Authentication:    JWT                                        ║
+║ Logging:           Standard                                   ║
+║ API Versioning:    URL Prefix (/api/v1/)                      ║
+╠───────────────────────────────────────────────────────────────╣
+║ Coverage Target:   80%                                        ║
+║ Visual Viewports:  All 7                                      ║
+║ E2E Browsers:      Chrome + Firefox + WebKit                  ║
+║ Platform Target:   Web Only                                   ║
+╚═══════════════════════════════════════════════════════════════╝
+
+These settings will be used for ALL future /hustle-build workflows.
+Run /hustle-interview anytime to change them.
+```
+
+## Registry Integration
+
+The skill MUST update the registry file after user confirmation:
+
+```json
+{
+  "orchestrator_defaults": {
+    "project_type": "saas",
+    "error_handling": { "style": "result-type" },
+    "authentication": { "method": "jwt" },
+    "logging": { "level": "standard" },
+    "api_versioning": { "strategy": "url-prefix" },
+    "testing": {
+      "coverage_threshold": 80,
+      "visual_viewports": ["all"],
+      "e2e_browsers": ["chromium", "firefox", "webkit"]
+    },
+    "platform_targets": "web-only",
+    "styling": { "approach": "tailwind" },
+    "configured_at": "2025-12-29T12:00:00Z",
+    "configured_by": "hustle-interview"
+  }
+}
+```
+
+## Re-running the Interview
+
+Users can run `/hustle-interview` anytime to:
+- View current settings
+- Modify specific settings
+- Reset all settings
+- Export settings (for team sharing)