@hustle-together/api-dev-tools 1.0.0

package/hooks/api-workflow-check.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Hook: Stop
+Purpose: Check if all required phases are complete before allowing stop
+
+This hook runs when Claude tries to stop/end the conversation.
+It checks api-dev-state.json to ensure critical workflow phases completed.
+
+Returns:
+  - {"decision": "approve"} - Allow stopping
+  - {"decision": "block", "reason": "..."} - Prevent stopping with explanation
+"""
+import json
+import sys
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+# Phases that MUST be complete before stopping
+# These are the critical phases - others are optional
+REQUIRED_PHASES = [
+    ("research_initial", "Initial research (Context7/WebSearch)"),
+    ("tdd_red", "TDD Red phase (failing tests written)"),
+    ("tdd_green", "TDD Green phase (tests passing)"),
+]
+
+# Phases that SHOULD be complete (warning but don't block)
+RECOMMENDED_PHASES = [
+    ("interview", "User interview"),
+    ("schema_creation", "Schema creation"),
+    ("documentation", "Documentation updates"),
+]
+
+
+def main():
+    # If no state file, we're not in an API workflow - allow stop
+    if not STATE_FILE.exists():
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        # Corrupted state, allow stop
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+
+    # Check if workflow was even started
+    research = phases.get("research_initial", {})
+    if research.get("status") == "not_started":
+        # Workflow not started, allow stop
+        print(json.dumps({"decision": "approve"}))
+        sys.exit(0)
+
+    # Check required phases
+    incomplete_required = []
+    for phase_key, phase_name in REQUIRED_PHASES:
+        phase = phases.get(phase_key, {})
+        status = phase.get("status", "not_started")
+        if status != "complete":
+            incomplete_required.append(f"  - {phase_name} ({status})")
+
+    # Check recommended phases
+    incomplete_recommended = []
+    for phase_key, phase_name in RECOMMENDED_PHASES:
+        phase = phases.get(phase_key, {})
+        status = phase.get("status", "not_started")
+        if status != "complete":
+            incomplete_recommended.append(f"  - {phase_name} ({status})")
+
+    # Block if required phases incomplete
+    if incomplete_required:
+        reason_parts = ["❌ API workflow has REQUIRED phases incomplete:\n"]
+        reason_parts.extend(incomplete_required)
+
+        if incomplete_recommended:
+            reason_parts.append("\n\n⚠️ Also recommended but not complete:")
+            reason_parts.extend(incomplete_recommended)
+
+        reason_parts.append("\n\nTo continue:")
+        reason_parts.append("  1. Complete required phases above")
+        reason_parts.append("  2. Use /api-status to see detailed progress")
+        reason_parts.append("  3. Or manually mark phases complete in .claude/api-dev-state.json")
+
+        print(json.dumps({
+            "decision": "block",
+            "reason": "\n".join(reason_parts)
+        }))
+        sys.exit(0)
+
+    # Warn about recommended phases but allow
+    if incomplete_recommended:
+        # Allow but the reason will be shown to user
+        print(json.dumps({
+            "decision": "approve",
+            "message": f"""⚠️ API workflow completing with optional phases pending:
+{chr(10).join(incomplete_recommended)}
+
+Consider running /api-status to review what was skipped."""
+        }))
+        sys.exit(0)
+
+    # All phases complete
+    print(json.dumps({
+        "decision": "approve",
+        "message": "✅ API workflow completed successfully!"
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-research.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""
+Hook: PreToolUse for Write/Edit
+Purpose: Block writing API code if research phase not complete
+
+This hook runs BEFORE Claude can write or edit files in /api/ directories.
+It checks the api-dev-state.json file to ensure research was completed first.
+
+Returns:
+  - {"permissionDecision": "allow"} - Let the tool run
+  - {"permissionDecision": "deny", "reason": "..."} - Block with explanation
+"""
+import json
+import sys
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def main():
+    # Read hook input from stdin (Claude Code passes tool info as JSON)
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # If we can't parse input, allow (fail open for safety)
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Get the file path being written/edited
+    file_path = tool_input.get("file_path", "")
+
+    # Only enforce for API route files
+    # Check for both /api/ and /api-test/ patterns
+    if "/api/" not in file_path and "/api-test/" not in file_path:
+        # Not an API file, allow without checking
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Also skip for test files - tests should be written before research completes
+    # (TDD Red phase)
+    if ".test." in file_path or "/__tests__/" in file_path:
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Skip for documentation/config files
+    if file_path.endswith(".md") or file_path.endswith(".json"):
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": """❌ API development state not initialized.
+
+Before writing API implementation code, you must:
+  1. Run /api-create [endpoint-name] to start the workflow
+  OR
+  2. Run /api-research [library-name] to research dependencies
+
+This ensures you're working with current documentation, not outdated training data."""
+        }))
+        sys.exit(0)
+
+    # Load and check state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        # Corrupted state file, allow but warn
+        print(json.dumps({"permissionDecision": "allow"}))
+        sys.exit(0)
+
+    # Check research phase status
+    phases = state.get("phases", {})
+    research = phases.get("research_initial", {})
+    research_status = research.get("status", "not_started")
+
+    if research_status != "complete":
+        sources_count = len(research.get("sources", []))
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ Cannot write API implementation code yet.
+
+RESEARCH PHASE INCOMPLETE
+Current status: {research_status}
+Sources consulted: {sources_count}
+
+REQUIRED ACTIONS:
+  1. Complete research phase first
+  2. Run: /api-research [library-name]
+  3. Ensure Context7 or WebSearch has been used
+
+WHY THIS MATTERS:
+  - Implementation must match CURRENT API documentation
+  - Training data may be outdated
+  - All parameters must be discovered before coding
+
+Once research is complete, you can proceed with implementation."""
+        }))
+        sys.exit(0)
+
+    # Research complete, allow writing
+    print(json.dumps({"permissionDecision": "allow"}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/track-tool-use.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for WebSearch, WebFetch, Context7 MCP
+Purpose: Track all research activity in the state file
+
+This hook runs AFTER Claude uses research tools (WebSearch, WebFetch, Context7).
+It logs each research action to api-dev-state.json for:
+  - Auditing what research was done
+  - Verifying prerequisites before allowing implementation
+  - Providing visibility to the user
+
+Returns:
+  - {"continue": true} - Always continues (logging only, no blocking)
+"""
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# State file is in .claude/ directory (sibling to hooks/)
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # Can't parse, just continue
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    tool_output = input_data.get("tool_output", {})
+
+    # Only track research-related tools
+    research_tools = ["WebSearch", "WebFetch", "mcp__context7"]
+    is_research_tool = any(t in tool_name for t in research_tools)
+
+    if not is_research_tool:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Load or create state file
+    if STATE_FILE.exists():
+        try:
+            state = json.loads(STATE_FILE.read_text())
+        except json.JSONDecodeError:
+            state = create_initial_state()
+    else:
+        state = create_initial_state()
+
+    # Get or create research phase
+    phases = state.setdefault("phases", {})
+    research = phases.setdefault("research_initial", {
+        "status": "in_progress",
+        "sources": [],
+        "started_at": datetime.now().isoformat()
+    })
+
+    # Update status if not started
+    if research.get("status") == "not_started":
+        research["status"] = "in_progress"
+        research["started_at"] = datetime.now().isoformat()
+
+    # Get sources list
+    sources = research.setdefault("sources", [])
+
+    # Create source entry based on tool type
+    timestamp = datetime.now().isoformat()
+
+    if "context7" in tool_name.lower():
+        source_entry = {
+            "type": "context7",
+            "tool": tool_name,
+            "input": sanitize_input(tool_input),
+            "timestamp": timestamp,
+            "success": True
+        }
+        # Extract library info if available
+        if "libraryName" in tool_input:
+            source_entry["library"] = tool_input["libraryName"]
+        if "libraryId" in tool_input:
+            source_entry["library_id"] = tool_input["libraryId"]
+
+    elif tool_name == "WebSearch":
+        source_entry = {
+            "type": "websearch",
+            "query": tool_input.get("query", ""),
+            "timestamp": timestamp,
+            "success": True
+        }
+
+    elif tool_name == "WebFetch":
+        source_entry = {
+            "type": "webfetch",
+            "url": tool_input.get("url", ""),
+            "timestamp": timestamp,
+            "success": True
+        }
+
+    else:
+        # Generic research tool
+        source_entry = {
+            "type": "other",
+            "tool": tool_name,
+            "timestamp": timestamp,
+            "success": True
+        }
+
+    # Add to sources list
+    sources.append(source_entry)
+
+    # Update last activity timestamp
+    research["last_activity"] = timestamp
+    research["source_count"] = len(sources)
+
+    # Check if we have enough sources to consider research "complete"
+    # More robust criteria:
+    # - At least 2 sources total (prevents single accidental search from completing)
+    # - At least one of: Context7 docs fetch, WebFetch of docs page
+    # - At least one search (WebSearch or Context7 resolve)
+    context7_count = sum(1 for s in sources if s.get("type") == "context7")
+    websearch_count = sum(1 for s in sources if s.get("type") == "websearch")
+    webfetch_count = sum(1 for s in sources if s.get("type") == "webfetch")
+    total_sources = len(sources)
+
+    # Minimum threshold: 2+ sources with at least one being docs-related
+    has_docs = webfetch_count >= 1 or context7_count >= 1
+    has_search = websearch_count >= 1 or context7_count >= 1
+    sufficient = total_sources >= 2 and has_docs and has_search
+
+    # Auto-complete research if sufficient sources
+    if sufficient:
+        if research.get("status") == "in_progress":
+            research["status"] = "complete"
+            research["completed_at"] = timestamp
+            research["completion_reason"] = "sufficient_sources"
+            research["completion_summary"] = {
+                "total_sources": total_sources,
+                "context7_calls": context7_count,
+                "web_searches": websearch_count,
+                "doc_fetches": webfetch_count
+            }
+
+    # Save state file
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Return success
+    print(json.dumps({"continue": True}))
+    sys.exit(0)
+
+
+def create_initial_state():
+    """Create initial state structure"""
+    return {
+        "version": "1.0.0",
+        "created_at": datetime.now().isoformat(),
+        "phases": {
+            "scope": {"status": "not_started"},
+            "research_initial": {"status": "not_started", "sources": []},
+            "interview": {"status": "not_started"},
+            "research_deep": {"status": "not_started", "sources": []},
+            "schema_creation": {"status": "not_started"},
+            "environment_check": {"status": "not_started"},
+            "tdd_red": {"status": "not_started"},
+            "tdd_green": {"status": "not_started"},
+            "tdd_refactor": {"status": "not_started"},
+            "documentation": {"status": "not_started"}
+        },
+        "verification": {
+            "all_sources_fetched": False,
+            "schema_matches_docs": False,
+            "tests_cover_params": False,
+            "all_tests_passing": False
+        }
+    }
+
+
+def sanitize_input(tool_input):
+    """Remove potentially sensitive data from input before logging"""
+    sanitized = {}
+    for key, value in tool_input.items():
+        # Skip API keys or tokens
+        if any(sensitive in key.lower() for sensitive in ["key", "token", "secret", "password"]):
+            sanitized[key] = "[REDACTED]"
+        else:
+            sanitized[key] = value
+    return sanitized
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hustle-together/api-dev-tools",
+  "version": "1.0.0",
+  "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
+  "main": "bin/cli.js",
+  "bin": {
+    "api-dev-tools": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "hooks/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js --scope=project"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "api-development",
+    "tdd",
+    "test-driven-development",
+    "interview-driven",
+    "api-testing",
+    "documentation",
+    "workflow",
+    "automation"
+  ],
+  "author": "Hustle Together",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hustle-together/api-dev-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hustle-together/api-dev-tools/issues"
+  },
+  "homepage": "https://github.com/hustle-together/api-dev-tools#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/templates/api-dev-state.json

@@ -0,0 +1,65 @@
+{
+  "version": "1.0.0",
+  "created_at": null,
+  "endpoint": null,
+  "library": null,
+  "phases": {
+    "scope": {
+      "status": "not_started",
+      "description": "Initial scope understanding"
+    },
+    "research_initial": {
+      "status": "not_started",
+      "sources": [],
+      "description": "Context7/WebSearch research for live documentation"
+    },
+    "interview": {
+      "status": "not_started",
+      "questions": [],
+      "description": "Structured interview about requirements"
+    },
+    "research_deep": {
+      "status": "not_started",
+      "sources": [],
+      "description": "Deep dive based on interview answers"
+    },
+    "schema_creation": {
+      "status": "not_started",
+      "schema_file": null,
+      "description": "Zod schema creation from research"
+    },
+    "environment_check": {
+      "status": "not_started",
+      "keys_verified": [],
+      "keys_missing": [],
+      "description": "API key and environment verification"
+    },
+    "tdd_red": {
+      "status": "not_started",
+      "test_file": null,
+      "test_count": 0,
+      "description": "Write failing tests first"
+    },
+    "tdd_green": {
+      "status": "not_started",
+      "implementation_file": null,
+      "description": "Minimal implementation to pass tests"
+    },
+    "tdd_refactor": {
+      "status": "not_started",
+      "description": "Code cleanup while keeping tests green"
+    },
+    "documentation": {
+      "status": "not_started",
+      "files_updated": [],
+      "description": "Update manifests, OpenAPI, examples"
+    }
+  },
+  "verification": {
+    "all_sources_fetched": false,
+    "schema_matches_docs": false,
+    "tests_cover_params": false,
+    "all_tests_passing": false,
+    "coverage_percent": null
+  }
+}

package/templates/settings.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-research.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "WebSearch|WebFetch|mcp__context7.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/track-tool-use.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/api-workflow-check.py"
+          }
+        ]
+      }
+    ]
+  }
+}