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

package/.claude/test-orchestrator-state.json

@@ -0,0 +1,20 @@
+{
+  "turn_count": 0,
+  "started_at": "2025-12-31T19:42:00.000Z",
+  "test_directory": "/Users/alfonso/test-api-dev-tools-auto",
+  "current_command": "/api-create",
+  "current_endpoint": "weather-api",
+  "current_phase": "initialization",
+  "commands_tested": {
+    "/api-create": {
+      "status": "IN PROGRESS",
+      "endpoint": "weather-api",
+      "started_at": "2025-12-31T19:42:00.000Z",
+      "phases_complete": 0,
+      "retries": 0
+    }
+  },
+  "total_retries": 0,
+  "reground_history": [],
+  "auto_answer_bot_pid": null
+}

package/.claude/test-orchestrator.sh

@@ -0,0 +1,271 @@
+#!/bin/bash
+#
+# Test Orchestrator - Master test runner for all 5 commands
+#
+# This script:
+# 1. Creates isolated test directory
+# 2. Installs api-dev-tools package
+# 3. Copies .env.example for API keys
+# 4. Runs each command with auto-answer bot
+# 5. Validates completion with completion-detector
+# 6. Retries on failure (with research for solutions)
+# 7. Updates WORKFLOW_CHECKLIST.md with results
+#
+# Usage:
+#   ./test-orchestrator.sh
+#
+# Version: 1.0.0
+
+set -e  # Exit on error
+
+# Configuration
+TEST_DIR="$HOME/test-api-dev-tools-auto"
+SOURCE_DIR="/Users/alfonso/Documents/GitHub/api-dev-tools"
+ENV_EXAMPLE="$SOURCE_DIR/.env.example"
+NTFY_TOPIC="test_api_devtools_alerts"
+MAX_RETRIES=5
+PYTHON3="python3"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Logging
+log() {
+    echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[$(date +'%H:%M:%S')]${NC} ✅ $1"
+}
+
+log_error() {
+    echo -e "${RED}[$(date +'%H:%M:%S')]${NC} ❌ $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[$(date +'%H:%M:%S')]${NC} ⚠️  $1"
+}
+
+# NTFY notification
+send_ntfy() {
+    local message="$1"
+    local title="${2:-Test Orchestrator}"
+    local priority="${3:-3}"
+
+    curl -s \
+        -H "Title: $title" \
+        -H "Priority: $priority" \
+        -d "$message" \
+        "https://ntfy.sh/$NTFY_TOPIC" > /dev/null 2>&1 || true
+}
+
+# Setup test environment
+setup_test_environment() {
+    log "Setting up test environment at $TEST_DIR..."
+
+    # Remove old test directory if exists
+    if [ -d "$TEST_DIR" ]; then
+        log_warning "Removing old test directory..."
+        rm -rf "$TEST_DIR"
+    fi
+
+    # Create new test directory
+    mkdir -p "$TEST_DIR"
+    cd "$TEST_DIR"
+
+    # Initialize git (required for api-dev-tools)
+    git init
+    git config user.email "test@example.com"
+    git config user.name "Test Orchestrator"
+
+    # Create basic Next.js structure
+    log "Creating Next.js project structure..."
+    npm init -y > /dev/null 2>&1
+
+    # Copy .env.example
+    if [ -f "$ENV_EXAMPLE" ]; then
+        log "Copying .env.example..."
+        cp "$ENV_EXAMPLE" "$TEST_DIR/.env"
+        log_success ".env file copied"
+    else
+        log_error ".env.example not found at $ENV_EXAMPLE"
+        log_warning "Continuing without .env file - some features may not work"
+    fi
+
+    # Install api-dev-tools (from local source for now)
+    log "Installing api-dev-tools from local source..."
+
+    # Build the package first
+    cd "$SOURCE_DIR"
+    npm run build > /dev/null 2>&1 || log_warning "Build may have warnings"
+
+    cd "$TEST_DIR"
+
+    # Install dependencies
+    npm install --save-dev "$SOURCE_DIR" > /dev/null 2>&1 || {
+        log_error "Failed to install api-dev-tools"
+        exit 1
+    }
+
+    log_success "Test environment setup complete"
+
+    send_ntfy "Test environment created at $TEST_DIR" "🔧 Setup Complete" 3
+}
+
+# Run auto-answer bot in background
+start_auto_answer_bot() {
+    log "Starting auto-answer bot..."
+
+    $PYTHON3 "$SOURCE_DIR/.claude/test-auto-answer-bot.py" "$TEST_DIR" > /dev/null 2>&1 &
+    AUTO_ANSWER_PID=$!
+
+    log_success "Auto-answer bot started (PID: $AUTO_ANSWER_PID)"
+}
+
+# Stop auto-answer bot
+stop_auto_answer_bot() {
+    if [ ! -z "$AUTO_ANSWER_PID" ]; then
+        log "Stopping auto-answer bot..."
+        kill $AUTO_ANSWER_PID 2>/dev/null || true
+        log_success "Auto-answer bot stopped"
+    fi
+}
+
+# Test a single command
+test_command() {
+    local command="$1"
+    local endpoint="$2"
+    local command_type="$3"
+    local retry=0
+
+    log "Testing command: $command $endpoint"
+
+    while [ $retry -lt $MAX_RETRIES ]; do
+        log "Attempt $((retry + 1))/$MAX_RETRIES..."
+
+        # Start auto-answer bot
+        start_auto_answer_bot
+
+        # Run the command (this will be done via Claude Code in actual implementation)
+        # For now, we'll log what would happen
+        log_warning "TODO: Implement command execution via Claude Code"
+
+        # Check completion
+        $PYTHON3 "$SOURCE_DIR/.claude/test-completion-detector.py" "$TEST_DIR" "$command_type" > /tmp/completion-result.json
+
+        if [ $? -eq 0 ]; then
+            log_success "$command completed successfully!"
+            stop_auto_answer_bot
+
+            send_ntfy "✅ $command PASSED on attempt $((retry + 1))" "Test Success" 4
+
+            return 0
+        else
+            log_error "$command failed. Analyzing..."
+
+            # Show completion status
+            cat /tmp/completion-result.json
+
+            retry=$((retry + 1))
+
+            if [ $retry -lt $MAX_RETRIES ]; then
+                log_warning "Retrying..."
+            fi
+
+            stop_auto_answer_bot
+        fi
+    done
+
+    log_error "$command failed after $MAX_RETRIES attempts"
+    send_ntfy "❌ $command FAILED after $MAX_RETRIES attempts" "Test Failure" 5
+
+    return 1
+}
+
+# Main test suite
+run_full_test_suite() {
+    log "Starting full test suite..."
+    send_ntfy "Starting full test suite (5 commands)" "🚀 Test Suite Started" 4
+
+    local commands_passed=0
+    local commands_failed=0
+
+    # Test 1: /api-create
+    if test_command "/api-create" "test-weather-api" "api-create"; then
+        commands_passed=$((commands_passed + 1))
+    else
+        commands_failed=$((commands_failed + 1))
+    fi
+
+    # Test 2: /hustle-ui-create
+    if test_command "/hustle-ui-create" "TestCard" "hustle-ui-create"; then
+        commands_passed=$((commands_passed + 1))
+    else
+        commands_failed=$((commands_failed + 1))
+    fi
+
+    # Test 3: /hustle-ui-create-page
+    if test_command "/hustle-ui-create-page" "test-dashboard" "hustle-ui-create-page"; then
+        commands_passed=$((commands_passed + 1))
+    else
+        commands_failed=$((commands_failed + 1))
+    fi
+
+    # Test 4: /hustle-combine
+    if test_command "/hustle-combine" "test-combined" "hustle-combine"; then
+        commands_passed=$((commands_passed + 1))
+    else
+        commands_failed=$((commands_failed + 1))
+    fi
+
+    # Test 5: /hustle-build
+    if test_command "/hustle-build" "simple dashboard" "hustle-build"; then
+        commands_passed=$((commands_passed + 1))
+    else
+        commands_failed=$((commands_failed + 1))
+    fi
+
+    # Final summary
+    log ""
+    log "=========================================="
+    log "          TEST SUITE COMPLETE"
+    log "=========================================="
+    log_success "Passed: $commands_passed/5"
+    log_error "Failed: $commands_failed/5"
+    log "=========================================="
+
+    send_ntfy "Test Suite Complete: $commands_passed/5 passed, $commands_failed/5 failed" "🏁 Tests Done" 5
+
+    if [ $commands_failed -eq 0 ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Cleanup on exit
+cleanup() {
+    log "Cleaning up..."
+    stop_auto_answer_bot
+}
+
+trap cleanup EXIT
+
+# Main execution
+main() {
+    log "=========================================="
+    log "   API Dev Tools - Test Orchestrator"
+    log "=========================================="
+    log ""
+
+    setup_test_environment
+    run_full_test_suite
+
+    exit $?
+}
+
+main "$@"

package/.skills/api-create/SKILL.md

@@ -4,19 +4,92 @@ description: Complete API development workflow using interview-driven, research-
 license: MIT
 compatibility: Requires Claude Code with MCP servers (Context7 for docs, GitHub for PRs), Python 3.9+ for enforcement hooks, pnpm 10.11.0+ for package management, Vitest for testing
 metadata:
-  version: "3.0.0"
+  version: "4.0.0"
   category: "development"
   tags: ["api", "tdd", "workflow", "research", "interview", "verification", "testing"]
   author: "Hustle Together"
 allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
 ---
 
-# API Create - Comprehensive API Development Workflow v3.0
+# API Create - Comprehensive API Development Workflow v4.0
 
-**Usage:** `/api-create [endpoint-name]`
+**Usage:** `/api-create [endpoint-name] [--auto] [--resume [workflow-id]]`
 
 **Purpose:** Orchestrates the complete API development workflow using interview-driven, research-first, test-first methodology with continuous verification loops.
 
+## Arguments
+
+- `[endpoint-name]` - Name of the API endpoint to create
+- `--auto` - Fully autonomous mode, auto-answers all questions with comprehensive defaults
+- `--resume [workflow-id]` - Resume an interrupted workflow from its last phase
+
+---
+
+## Auto Mode (`--auto`)
+
+When `--auto` flag is used:
+
+1. **No Interactive Questions:**
+   - All questions auto-answered with comprehensive defaults
+   - Uses `.claude/hustle-build-defaults.json` for configured answers
+   - Falls back to "most comprehensive" option when no default exists
+
+2. **Comprehensive Selection Logic:**
+   - Always selects options that include ALL available features
+   - Always enables ALL testing levels
+   - Always generates ALL documentation
+   - Prefers "Yes" over "No" for optional features
+
+3. **Error Handling:**
+   - Test failures: Retry 3x, then log and continue
+   - Verification gaps: Log gap, continue (will review later)
+   - Missing API keys: Log warning, continue if possible
+
+4. **Logging:**
+   - All decisions logged to `.claude/workflow-logs/api-create/[workflow-id].json`
+   - Review with `/api-create-review [workflow-id]`
+
+**Example:**
+```bash
+/api-create brandfetch --auto
+```
+
+---
+
+## Resume Mode (`--resume`)
+
+When `--resume [workflow-id]` is used:
+
+1. Load state from `.claude/api-dev-state.json`
+2. Find the last incomplete phase
+3. Continue from that point
+4. Preserve all previous decisions
+
+**Example:**
+```bash
+/api-create --resume wf-brandfetch-2025-12-28
+```
+
+---
+
+## Orchestrated Mode
+
+When running as part of `/hustle-build`:
+
+1. `orchestrated: true` flag is set in state
+2. `shared_decisions` are pre-filled from orchestrator interview
+3. Questions covered by shared_decisions are SKIPPED
+4. Only workflow-specific questions are asked
+
+Check for orchestration at startup:
+```python
+if state.get("orchestrated"):
+    # Skip questions in shared_decisions_applied
+    skip_questions = state.get("shared_decisions_applied", [])
+```
+
+---
+
 ## ⚠️ CRITICAL: MANDATORY USER INTERACTION
 
 **YOU MUST USE THE `AskUserQuestion` TOOL AT EVERY CHECKPOINT.**
@@ -542,6 +615,18 @@ TodoWrite([
 │                                                           │
 │ Run /commit to create semantic commit.                    │
 │ Run /pr to create pull request.                           │
+│                                                           │
+│ ═══════════════════════════════════════════════════════  │
+│ ✅ API CREATED: [endpoint-name]                           │
+│                                                           │
+│ 📍 Quick Links:                                           │
+│   • Test it:     /api-showcase                            │
+│   • API Docs:    /docs/api/[endpoint-name]                │
+│   • Run tests:   pnpm test:api [endpoint-name]            │
+│   • TypeDoc:     pnpm typedoc                             │
+│                                                           │
+│ 📊 Dashboard:    /hustle-dev-dashboard                    │
+│ ═══════════════════════════════════════════════════════  │
 └───────────────────────────────────────────────────────────┘
 ```
 

package/.skills/docs-sync/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: docs-sync
+description: Synchronize documentation after code changes. Updates existing docs, creates new ones for features, and ensures README links.
+license: MIT
+compatibility: Requires Claude Code with hooks
+metadata:
+  version: "1.0.0"
+  category: "documentation"
+  tags: ["docs", "readme", "sync", "maintenance"]
+  author: "Hustle Together"
+allowed-tools: Read Write Edit Glob Grep
+---
+
+# Docs Sync - Documentation Synchronization Skill
+
+Ensures documentation stays in sync with code changes. Run after implementing features, fixing gaps, or adding new capabilities.
+
+## Usage
+
+```bash
+/docs-sync                    # Analyze and sync all docs
+/docs-sync [feature-name]     # Sync docs for specific feature
+/docs-sync --check            # Check what needs updating (no writes)
+```
+
+## What This Skill Does
+
+### 1. Analyze Recent Changes
+
+First, examine what changed:
+- Read git diff or recent file modifications
+- Identify new hooks, skills, agents, or features
+- Detect removed or deprecated functionality
+
+### 2. Update Existing Documentation
+
+For each affected area, update the relevant doc:
+
+| Change Type | Doc to Update |
+|-------------|---------------|
+| New hook | `docs/HOOKS.md` |
+| New skill | `docs/SKILLS.md` |
+| New agent | `docs/AGENTS.md` |
+| Orchestrator change | `docs/ORCHESTRATOR.md` |
+| Re-grounding change | `docs/REGROUNDING.md` |
+| Gap fixed | `docs/GAP_ANALYSIS.md` |
+| Best practice added | `docs/CLAUDE_CODE_BEST_PRACTICES.md` |
+
+### 3. Create New Documentation
+
+If a feature warrants its own doc:
+
+1. Create `docs/[FEATURE_NAME].md`
+2. Use the standard header template (see below)
+3. Add link to README.md Core Reference table
+
+### 4. Ensure Problem/Solution Headers
+
+Every doc MUST have this header format:
+
+```markdown
+# [Document Title]
+
+**Version:** X.X.X
+**Last Updated:** YYYY-MM-DD
+
+> **The Problem**
+>
+> [Clear description of the pain point this addresses]
+
+> **The Solution**
+>
+> [How this document/feature solves the problem]
+
+---
+```
+
+### 5. Update README Links
+
+Add any new docs to the appropriate section in README.md:
+
+```markdown
+### Core Reference
+
+| Document | Purpose |
+| -------- | ------- |
+| **[docs/NEW_DOC.md](./docs/NEW_DOC.md)** | Brief description |
+```
+
+---
+
+## Document Header Template
+
+Use this exact format for all documentation:
+
+```markdown
+# [Title]
+
+**Version:** [version]
+**Last Updated:** [date]
+
+> **The Problem**
+>
+> [Describe the specific pain point, frustration, or gap this addresses.
+> Be concrete - what goes wrong without this? What do users struggle with?]
+
+> **The Solution**
+>
+> [Explain how this document/feature solves the problem.
+> What improvements does it provide? What's the benefit?]
+
+---
+
+## Table of Contents
+...
+```
+
+---
+
+## Execution Steps
+
+### Step 1: Identify Changes
+
+```bash
+# Check what files changed recently
+git diff --name-only HEAD~5
+# Or check specific areas
+ls -la hooks/
+ls -la .skills/
+ls -la docs/
+```
+
+Look for:
+- New `.py` files in `hooks/`
+- New folders in `.skills/`
+- New `.md` files in `.claude/agents/`
+- Modified core files
+
+### Step 2: Categorize Updates Needed
+
+Create a checklist:
+
+```markdown
+## Documentation Updates Needed
+
+### Existing Docs to Update
+- [ ] docs/HOOKS.md - Add [hook name]
+- [ ] docs/SKILLS.md - Add [skill name]
+- [ ] docs/GAP_ANALYSIS.md - Mark [gap] as fixed
+
+### New Docs to Create
+- [ ] docs/[FEATURE].md - New feature documentation
+
+### README Updates
+- [ ] Add link to [new doc]
+```
+
+### Step 3: Update Each Document
+
+For each doc that needs updating:
+
+1. **Read current content**
+2. **Add/update the Problem/Solution header if missing**
+3. **Add new sections for new features**
+4. **Update version and date**
+5. **Ensure See Also section includes related docs**
+
+### Step 4: Create New Documents
+
+For genuinely new features that need their own doc:
+
+1. Create file with header template
+2. Write comprehensive content
+3. Add to README Core Reference table
+4. Cross-link from related docs
+
+### Step 5: Verify Links
+
+Check all links work:
+- Internal doc links (`[text](./OTHER_DOC.md)`)
+- README links to docs
+- See Also sections
+
+---
+
+## Problem/Solution Examples
+
+### Good Example (REGROUNDING.md)
+
+```markdown
+> **The Problem**
+>
+> LLMs suffer from "context dilution" - as conversations grow longer,
+> the original instructions (CLAUDE.md, system prompts) get pushed to
+> the "middle" of the context where attention is weakest. Claude starts
+> forgetting the endpoint name, re-asking answered questions, and
+> recreating existing components.
+
+> **The Solution**
+>
+> The Re-Grounding System injects a comprehensive state reminder every
+> 7 turns, pushing critical context to the END where attention is
+> strongest. This includes current phase, key decisions, existing
+> registry elements, and deferred features - preventing the "lost in
+> the middle" problem.
+```
+
+### Good Example (ORCHESTRATOR.md)
+
+```markdown
+> **The Problem**
+>
+> Building complex features requires multiple workflows (APIs, components,
+> pages) that depend on each other. Running them manually means answering
+> the same questions repeatedly, managing dependency order yourself, and
+> manually wiring completed elements together.
+
+> **The Solution**
+>
+> The Orchestrator decomposes natural language requests into workflows,
+> orders them by dependency, shares decisions across all sub-workflows
+> (ask once, apply everywhere), and automatically wires completed
+> elements with proper imports and types.
+```
+
+---
+
+## Checklist Before Completing
+
+- [ ] All affected docs have Problem/Solution headers
+- [ ] New features are documented
+- [ ] README links are updated
+- [ ] Version numbers are bumped
+- [ ] Dates are updated
+- [ ] See Also sections cross-reference related docs
+- [ ] GAP_ANALYSIS.md reflects current state
+
+---
+
+## Output
+
+After running this skill, report:
+
+```markdown
+## Documentation Sync Complete
+
+### Updated
+- docs/HOOKS.md - Added auto-format hook
+- docs/GAP_ANALYSIS.md - Marked 3 gaps as fixed
+
+### Created
+- docs/NEW_FEATURE.md - New feature documentation
+
+### README
+- Added link to NEW_FEATURE.md
+
+### Headers Added
+- docs/SKILLS.md - Added Problem/Solution header
+- docs/AGENTS.md - Added Problem/Solution header
+```