@hustle-together/api-dev-tools 2.0.7 → 3.0.0

package/hooks/periodic-reground.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (for periodic re-grounding)
+Purpose: Inject context reminders every N turns to prevent context dilution
+
+This hook tracks turn count and periodically injects a summary of:
+  - Current endpoint and phase
+  - Key decisions from interview
+  - Research cache status
+  - Important file locations
+
+The goal is to keep Claude grounded during long sessions where
+the original CLAUDE.md context may get diluted.
+
+Configuration:
+  - REGROUND_INTERVAL: Number of turns between re-grounding (default: 7)
+
+Returns:
+  - {"continue": true} with optional additionalContext on reground turns
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+# Configuration
+REGROUND_INTERVAL = 7  # Re-ground every N turns
+
+# 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:
+        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)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Increment turn count
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
+    # Check if we should re-ground
+    should_reground = turn_count % REGROUND_INTERVAL == 0
+
+    if should_reground and state.get("endpoint"):
+        # Build re-grounding context
+        context_parts = []
+        context_parts.append(f"## Re-Grounding Reminder (Turn {turn_count})")
+        context_parts.append("")
+
+        endpoint = state.get("endpoint", "unknown")
+        context_parts.append(f"**Active Endpoint:** {endpoint}")
+
+        # Get current phase
+        phases = state.get("phases", {})
+        phase_order = [
+            "disambiguation", "scope", "research_initial", "interview",
+            "research_deep", "schema_creation", "environment_check",
+            "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation"
+        ]
+
+        current_phase = None
+        completed_phases = []
+        for phase_name in phase_order:
+            phase = phases.get(phase_name, {})
+            status = phase.get("status", "not_started")
+            if status == "complete":
+                completed_phases.append(phase_name)
+            elif status == "in_progress" and not current_phase:
+                current_phase = phase_name
+
+        if not current_phase:
+            # Find first not_started phase
+            for phase_name in phase_order:
+                phase = phases.get(phase_name, {})
+                if phase.get("status", "not_started") == "not_started":
+                    current_phase = phase_name
+                    break
+
+        context_parts.append(f"**Current Phase:** {current_phase or 'documentation'}")
+        context_parts.append(f"**Completed:** {', '.join(completed_phases) if completed_phases else 'None'}")
+
+        # Key decisions summary
+        interview = phases.get("interview", {})
+        decisions = interview.get("decisions", {})
+        if decisions:
+            context_parts.append("")
+            context_parts.append("**Key Decisions:**")
+            for key, value in list(decisions.items())[:5]:  # Limit to 5 key decisions
+                response = value.get("value", value.get("response", "N/A"))
+                if response:
+                    context_parts.append(f"  - {key}: {str(response)[:50]}")
+
+        # Research freshness warning
+        research_index = state.get("research_index", {})
+        if endpoint in research_index:
+            entry = research_index[endpoint]
+            days_old = entry.get("days_old", 0)
+            if days_old > 7:
+                context_parts.append("")
+                context_parts.append(f"**WARNING:** Research is {days_old} days old. Consider re-researching.")
+
+        # File reminders
+        context_parts.append("")
+        context_parts.append("**Key Files:** .claude/api-dev-state.json, .claude/research/")
+
+        # Add to reground history
+        reground_history = state.setdefault("reground_history", [])
+        reground_history.append({
+            "turn": turn_count,
+            "timestamp": datetime.now().isoformat(),
+            "phase": current_phase
+        })
+        # Keep only last 10 reground events
+        state["reground_history"] = reground_history[-10:]
+
+        # Save state
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+
+        # Output with context injection
+        output = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": "\n".join(context_parts)
+            }
+        }
+        print(json.dumps(output))
+    else:
+        # Just update turn count and continue
+        STATE_FILE.write_text(json.dumps(state, indent=2))
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session-startup.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionStart
+Purpose: Inject current state and context at the beginning of each session
+
+This hook runs when Claude Code starts a new session or resumes.
+It reads the api-dev-state.json and injects a summary into Claude's context,
+helping to re-ground Claude on:
+  - Current endpoint being developed
+  - Which phases are complete/in-progress
+  - Key decisions from interviews
+  - Research cache location and freshness
+
+Returns:
+  - JSON with additionalContext to inject into Claude's context
+"""
+import json
+import sys
+import os
+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"
+RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        input_data = {}
+
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        # No active workflow - just continue without injection
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if there's an active workflow
+    endpoint = state.get("endpoint")
+    if not endpoint:
+        # No active endpoint - just continue
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Build context summary
+    context_parts = []
+    context_parts.append("## API Development Session Context")
+    context_parts.append("")
+    context_parts.append(f"**Active Endpoint:** {endpoint}")
+
+    # Get phase status
+    phases = state.get("phases", {})
+    completed = []
+    in_progress = []
+    not_started = []
+
+    phase_order = [
+        "disambiguation", "scope", "research_initial", "interview",
+        "research_deep", "schema_creation", "environment_check",
+        "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation"
+    ]
+
+    for phase_name in phase_order:
+        phase = phases.get(phase_name, {})
+        status = phase.get("status", "not_started")
+        if status == "complete":
+            completed.append(phase_name)
+        elif status == "in_progress":
+            in_progress.append(phase_name)
+        else:
+            not_started.append(phase_name)
+
+    context_parts.append("")
+    context_parts.append("**Phase Status:**")
+    if completed:
+        context_parts.append(f"  - Completed: {', '.join(completed)}")
+    if in_progress:
+        context_parts.append(f"  - In Progress: {', '.join(in_progress)}")
+
+    # Current phase (first in_progress or first not_started)
+    current_phase = in_progress[0] if in_progress else (not_started[0] if not_started else "documentation")
+    context_parts.append(f"  - Current: **{current_phase}**")
+
+    # Key decisions from interview
+    interview = phases.get("interview", {})
+    decisions = interview.get("decisions", {})
+    if decisions:
+        context_parts.append("")
+        context_parts.append("**Key Interview Decisions:**")
+        for key, value in decisions.items():
+            response = value.get("response", value.get("value", "N/A"))
+            if response:
+                context_parts.append(f"  - {key}: {str(response)[:100]}")
+
+    # Research cache info
+    research_index = state.get("research_index", {})
+    if endpoint in research_index:
+        entry = research_index[endpoint]
+        days_old = entry.get("days_old", 0)
+        context_parts.append("")
+        context_parts.append("**Research Cache:**")
+        context_parts.append(f"  - Location: .claude/research/{endpoint}/CURRENT.md")
+        context_parts.append(f"  - Last Updated: {entry.get('last_updated', 'Unknown')}")
+        if days_old > 7:
+            context_parts.append(f"  - WARNING: Research is {days_old} days old. Consider re-researching.")
+
+    # Turn count for re-grounding awareness
+    turn_count = state.get("turn_count", 0)
+    if turn_count > 0:
+        context_parts.append("")
+        context_parts.append(f"**Session Info:** Turn {turn_count} of previous session")
+
+    # Important file locations
+    context_parts.append("")
+    context_parts.append("**Key Files:**")
+    context_parts.append("  - State: .claude/api-dev-state.json")
+    context_parts.append("  - Research: .claude/research/")
+    context_parts.append("  - Manifest: src/app/api-test/api-tests-manifest.json (if exists)")
+
+    # Workflow reminder
+    context_parts.append("")
+    context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
+    context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
+
+    # Build the output
+    additional_context = "\n".join(context_parts)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": additional_context
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/track-tool-use.py

@@ -1,13 +1,16 @@
 #!/usr/bin/env python3
 """
-Hook: PostToolUse for WebSearch, WebFetch, Context7 MCP
-Purpose: Track all research activity in the state file
+Hook: PostToolUse for WebSearch, WebFetch, Context7 MCP, AskUserQuestion
+Purpose: Track all research activity and turn counts 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
+  - Tracking turn counts for periodic re-grounding
+
+Version: 3.0.0
 
 Returns:
   - {"continue": true} - Always continues (logging only, no blocking)
@@ -20,6 +23,9 @@ from pathlib import Path
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 
+# Re-grounding interval (also used by periodic-reground.py)
+REGROUND_INTERVAL = 7
+
 
 def main():
     # Read hook input from stdin
@@ -52,6 +58,14 @@ def main():
     else:
         state = create_initial_state()
 
+    # ========================================
+    # TURN COUNTING (for periodic re-grounding)
+    # ========================================
+    # Increment turn count on every tracked tool use
+    turn_count = state.get("turn_count", 0) + 1
+    state["turn_count"] = turn_count
+    state["last_turn_timestamp"] = datetime.now().isoformat()
+
     # Get phases
     phases = state.setdefault("phases", {})
 
@@ -281,30 +295,108 @@ def main():
 
 
 def create_initial_state():
-    """Create initial state structure"""
+    """Create initial state structure (v3.0.0)"""
     return {
-        "version": "1.1.0",
+        "version": "3.0.0",
         "created_at": datetime.now().isoformat(),
+        "endpoint": None,
+        "library": None,
+        "session_id": None,
+        "turn_count": 0,
+        "last_turn_timestamp": None,
+        "research_queries": [],
+        "prompt_detections": [],
         "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"}
+            "disambiguation": {
+                "status": "not_started",
+                "clarified": None,
+                "search_variations": [],
+                "description": "Pre-research disambiguation to clarify ambiguous requests"
+            },
+            "scope": {
+                "status": "not_started",
+                "confirmed": False,
+                "description": "Initial scope understanding and confirmation"
+            },
+            "research_initial": {
+                "status": "not_started",
+                "sources": [],
+                "summary_approved": False,
+                "description": "Context7/WebSearch research for live documentation"
+            },
+            "interview": {
+                "status": "not_started",
+                "questions": [],
+                "user_question_count": 0,
+                "structured_question_count": 0,
+                "decisions": {},
+                "description": "Structured interview about requirements (generated FROM research)"
+            },
+            "research_deep": {
+                "status": "not_started",
+                "sources": [],
+                "proposed_searches": [],
+                "approved_searches": [],
+                "skipped_searches": [],
+                "description": "Deep dive based on interview answers (adaptive, not shotgun)"
+            },
+            "schema_creation": {
+                "status": "not_started",
+                "schema_file": None,
+                "schema_approved": False,
+                "description": "Zod schema creation from research"
+            },
+            "environment_check": {
+                "status": "not_started",
+                "keys_verified": [],
+                "keys_missing": [],
+                "confirmed": False,
+                "description": "API key and environment verification"
+            },
+            "tdd_red": {
+                "status": "not_started",
+                "test_file": None,
+                "test_count": 0,
+                "test_matrix_approved": False,
+                "description": "Write failing tests first"
+            },
+            "tdd_green": {
+                "status": "not_started",
+                "implementation_file": None,
+                "all_tests_passing": False,
+                "description": "Minimal implementation to pass tests"
+            },
+            "verify": {
+                "status": "not_started",
+                "gaps_found": 0,
+                "gaps_fixed": 0,
+                "intentional_omissions": [],
+                "re_research_done": False,
+                "description": "Re-research after Green to verify implementation matches docs"
+            },
+            "tdd_refactor": {
+                "status": "not_started",
+                "description": "Code cleanup while keeping tests green"
+            },
+            "documentation": {
+                "status": "not_started",
+                "files_updated": [],
+                "manifest_updated": False,
+                "openapi_updated": False,
+                "research_cached": False,
+                "description": "Update manifests, OpenAPI, cache research"
+            }
         },
         "verification": {
             "all_sources_fetched": False,
             "schema_matches_docs": False,
             "tests_cover_params": False,
-            "all_tests_passing": False
+            "all_tests_passing": False,
+            "coverage_percent": None,
+            "post_green_verification": False
         },
-        "research_queries": [],
-        "prompt_detections": []
+        "research_index": {},
+        "reground_history": []
     }
 
 

package/hooks/verify-after-green.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse (after test runs)
+Purpose: Trigger Phase 9 (Verify) after tests pass - force re-research
+
+This hook detects when tests pass (TDD Green phase complete) and:
+  1. Reminds Claude to re-research the original documentation
+  2. Compares implemented features to documented features
+  3. Requires user confirmation before proceeding
+
+The goal is to catch cases where Claude implemented from memory
+instead of from the researched documentation.
+
+Triggers on: Bash commands containing "test" that exit successfully
+
+Returns:
+  - {"continue": true} with additionalContext prompting verification
+"""
+import json
+import sys
+import os
+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:
+        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 trigger on Bash commands
+    if tool_name != "Bash":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if this is a test command
+    command = tool_input.get("command", "")
+    is_test_command = any(test_keyword in command.lower() for test_keyword in [
+        "pnpm test", "npm test", "vitest", "jest", "pytest", "test:run"
+    ])
+
+    if not is_test_command:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if tests passed (exit code 0 or output indicates success)
+    output_text = ""
+    if isinstance(tool_output, str):
+        output_text = tool_output
+    elif isinstance(tool_output, dict):
+        output_text = tool_output.get("output", tool_output.get("stdout", ""))
+
+    # Look for success indicators
+    tests_passed = any(indicator in output_text.lower() for indicator in [
+        "tests passed", "all tests passed", "test suites passed",
+        "✓", "passed", "0 failed", "pass"
+    ]) and not any(fail in output_text.lower() for fail in [
+        "failed", "error", "fail"
+    ])
+
+    if not tests_passed:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Tests passed - check state file
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    phases = state.get("phases", {})
+    tdd_green = phases.get("tdd_green", {})
+    verify = phases.get("verify", {})
+
+    # Check if we're in TDD Green phase
+    if tdd_green.get("status") != "in_progress":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if verify phase already done
+    if verify.get("status") == "complete":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Mark TDD Green as complete
+    tdd_green["status"] = "complete"
+    tdd_green["all_tests_passing"] = True
+    tdd_green["completed_at"] = datetime.now().isoformat()
+
+    # Start verify phase
+    verify["status"] = "in_progress"
+    verify["started_at"] = datetime.now().isoformat()
+
+    # Save state
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    # Build verification prompt
+    endpoint = state.get("endpoint", "the endpoint")
+
+    context_parts = []
+    context_parts.append("## Phase 9: Implementation Verification Required")
+    context_parts.append("")
+    context_parts.append("Tests are passing. Before proceeding, you MUST verify your implementation:")
+    context_parts.append("")
+    context_parts.append("**Required Actions:**")
+    context_parts.append("1. Re-read the original API documentation (use Context7 or WebSearch)")
+    context_parts.append("2. Compare EVERY documented parameter/feature to your implementation")
+    context_parts.append("3. Report any discrepancies in this format:")
+    context_parts.append("")
+    context_parts.append("```")
+    context_parts.append("| Feature          | In Docs | Implemented | Status          |")
+    context_parts.append("|------------------|---------|-------------|-----------------|")
+    context_parts.append("| param_name       | Yes     | Yes         | Match           |")
+    context_parts.append("| missing_param    | Yes     | No          | MISSING         |")
+    context_parts.append("| extra_param      | No      | Yes         | EXTRA (OK)      |")
+    context_parts.append("```")
+    context_parts.append("")
+    context_parts.append("**After comparison, ask the user:**")
+    context_parts.append("- Fix gaps? [Y] - Loop back to Red phase")
+    context_parts.append("- Skip (intentional omissions)? [n] - Document and proceed")
+    context_parts.append("")
+    context_parts.append("DO NOT proceed to Refactor until verification is complete.")
+
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "PostToolUse",
+            "additionalContext": "\n".join(context_parts)
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "2.0.7",
-  "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
+  "version": "3.0.0",
+  "description": "Interview-driven, research-first API development workflow with continuous verification loops for Claude Code",
   "main": "bin/cli.js",
   "bin": {
     "api-dev-tools": "./bin/cli.js"