@hustle-together/api-dev-tools 1.7.1 → 1.9.0

package/hooks/enforce-interview.py

@@ -6,10 +6,18 @@ Purpose: Block proceeding to schema/TDD if interview has no USER answers
 This hook ensures Claude actually asks the user questions and records
 their answers, rather than self-answering the interview.
 
+v1.8.0 MAJOR UPDATE: Now requires STRUCTURED questions with multiple-choice
+options derived from research phase findings.
+
 It checks:
-  1. Interview status is "complete"
-  2. There are actual questions with answers
-  3. Answers don't look auto-generated (contain user-specific details)
+  1. Research phase is complete (questions must be based on research)
+  2. Interview status is "complete"
+  3. Questions used AskUserQuestion tool with STRUCTURED OPTIONS
+  4. At least MIN_STRUCTURED_QUESTIONS have multiple-choice or typed options
+  5. Answers don't look auto-generated (contain user-specific details)
+
+The goal: Questions like Claude Code shows - with numbered options and
+"Type something" at the end, all based on research findings.
 
 Returns:
   - {"permissionDecision": "allow"} - Let the tool run
@@ -23,7 +31,10 @@ from pathlib import Path
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 
 # Minimum questions required for a valid interview
-MIN_QUESTIONS = 3
+MIN_QUESTIONS = 5  # Increased - need comprehensive interview
+
+# Minimum questions that MUST have structured options (multiple-choice)
+MIN_STRUCTURED_QUESTIONS = 3
 
 # Phrases that indicate self-answered (not real user input)
 SELF_ANSWER_INDICATORS = [
@@ -33,6 +44,12 @@ SELF_ANSWER_INDICATORS = [
     "typical use case",
     "standard implementation",
     "common pattern",
+    "i'll assume",
+    "assuming",
+    "probably",
+    "most likely",
+    "default to",
+    "usually",
 ]
 
 
@@ -81,40 +98,84 @@ Run /api-create [endpoint-name] to begin the interview-driven workflow."""
         sys.exit(0)
 
     phases = state.get("phases", {})
+    research = phases.get("research_initial", {})
     interview = phases.get("interview", {})
     interview_status = interview.get("status", "not_started")
     interview_desc = interview.get("description", "").lower()
     questions = interview.get("questions", [])
+    research_queries = state.get("research_queries", [])
+
+    # Check 0: Research must be complete FIRST (questions based on research)
+    research_status = research.get("status", "not_started")
+    if research_status != "complete":
+        sources_count = len(research.get("sources", []))
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ BLOCKED: Research phase must complete BEFORE interview.
+
+Research status: {research_status}
+Sources consulted: {sources_count}
+Research queries: {len(research_queries)}
+
+═══════════════════════════════════════════════════════════
+⚠️  COMPLETE RESEARCH FIRST - THEN ASK QUESTIONS
+═══════════════════════════════════════════════════════════
+
+The interview questions MUST be based on research findings:
+1. Use Context7 to get SDK/API documentation
+2. Use WebSearch (2-3 searches) for official docs
+3. THEN generate interview questions with STRUCTURED OPTIONS
+   based on what you discovered
+
+Example: If research found 5 available models, ask:
+  "Which model should this endpoint use?"
+  1. gpt-4o (fastest, cheapest)
+  2. claude-sonnet-4-20250514 (best reasoning)
+  3. gemini-pro (multimodal)
+  4. Type something else...
+
+Research INFORMS the options. No research = no good options."""
+        }))
+        sys.exit(0)
 
     # Check 1: Interview must be complete
     if interview_status != "complete":
+        # Build example based on actual research
+        research_based_example = _build_research_based_example(research_queries)
+
         print(json.dumps({
             "permissionDecision": "deny",
             "reason": f"""❌ BLOCKED: Interview phase not complete.
 
 Current status: {interview_status}
 AskUserQuestion calls: {interview.get('user_question_count', 0)}
+Structured questions: {interview.get('structured_question_count', 0)}
 
 ═══════════════════════════════════════════════════════════
-⚠️  YOU MUST STOP AND ASK THE USER QUESTIONS NOW
+⚠️  USE STRUCTURED QUESTIONS WITH OPTIONS
 ═══════════════════════════════════════════════════════════
 
-Use the AskUserQuestion tool to ask EACH of these questions ONE AT A TIME:
+Based on your research, ask questions using AskUserQuestion with
+the 'options' parameter to provide multiple-choice selections:
 
-1. "What is the primary purpose of this endpoint?"
-2. "Who will use it and how?"
-3. "What parameters are essential vs optional?"
+{research_based_example}
 
-WAIT for the user's response after EACH question before continuing.
+REQUIRED FORMAT for AskUserQuestion:
+- question: "Your question text"
+- options: [
+    {{"value": "option1", "label": "Option 1 description"}},
+    {{"value": "option2", "label": "Option 2 description"}},
+    {{"value": "custom", "label": "Type something..."}}
+  ]
 
-DO NOT:
-❌ Make up answers yourself
-❌ Assume what the user wants
-❌ Mark the interview as complete without asking
-❌ Try to write any code until you have real answers
+You need at least {MIN_STRUCTURED_QUESTIONS} structured questions with options.
+Current: {interview.get('structured_question_count', 0)}
 
-The system is tracking your AskUserQuestion calls. You need at least 3
-actual calls with user responses to proceed."""
+DO NOT:
+❌ Ask open-ended questions without options
+❌ Make up options not based on research
+❌ Skip the AskUserQuestion tool
+❌ Self-answer questions"""
         }))
         sys.exit(0)
 
@@ -128,11 +189,11 @@ Questions recorded: {len(questions)}
 Minimum required: {MIN_QUESTIONS}
 
 You must ask the user more questions about their requirements.
-DO NOT proceed without understanding the user's actual needs."""
+Use AskUserQuestion with structured options based on your research."""
         }))
         sys.exit(0)
 
-    # Check 2.5: Verify AskUserQuestion tool was actually used
+    # Check 3: Verify AskUserQuestion tool was actually used
     user_question_count = interview.get("user_question_count", 0)
     tool_used_count = sum(1 for q in questions if q.get("tool_used", False))
 
@@ -146,14 +207,43 @@ Minimum required: {MIN_QUESTIONS}
 
 You MUST use the AskUserQuestion tool to ask the user directly.
 Do NOT make up answers or mark the interview as complete without
-actually asking the user and receiving their responses.
+actually asking the user and receiving their responses."""
+        }))
+        sys.exit(0)
 
-The system tracks when AskUserQuestion is used. Self-answering
-will be detected and blocked."""
+    # Check 4: Verify structured questions were used
+    structured_count = interview.get("structured_question_count", 0)
+    questions_with_options = sum(1 for q in questions if q.get("has_options", False))
+    actual_structured = max(structured_count, questions_with_options)
+
+    if actual_structured < MIN_STRUCTURED_QUESTIONS:
+        print(json.dumps({
+            "permissionDecision": "deny",
+            "reason": f"""❌ Not enough STRUCTURED questions with options.
+
+Structured questions (with options): {actual_structured}
+Minimum required: {MIN_STRUCTURED_QUESTIONS}
+
+You MUST use AskUserQuestion with the 'options' parameter to
+provide multiple-choice answers based on your research.
+
+Example:
+  AskUserQuestion(
+    question="Which AI provider should this endpoint support?",
+    options=[
+      {{"value": "openai", "label": "OpenAI (GPT-4o)"}},
+      {{"value": "anthropic", "label": "Anthropic (Claude)"}},
+      {{"value": "google", "label": "Google (Gemini)"}},
+      {{"value": "all", "label": "All of the above"}},
+      {{"value": "custom", "label": "Type something else..."}}
+    ]
+  )
+
+This gives the user clear choices based on what you researched."""
         }))
         sys.exit(0)
 
-    # Check 3: Look for self-answer indicators
+    # Check 5: Look for self-answer indicators
     for indicator in SELF_ANSWER_INDICATORS:
         if indicator in interview_desc:
             print(json.dumps({
@@ -162,22 +252,103 @@ will be detected and blocked."""
 
 Detected: "{indicator}" in interview description.
 
-You MUST actually ask the user questions using AskUserQuestion.
-Self-answering the interview defeats its purpose.
-
-Reset the interview phase and ask the user directly:
-  1. What do you want this endpoint to do?
-  2. Which providers/models should it support?
-  3. What parameters matter most to you?
+You MUST actually ask the user questions using AskUserQuestion
+with structured options. Self-answering defeats the purpose.
 
-Wait for their real answers before proceeding."""
+Reset the interview and ask with options based on research."""
             }))
             sys.exit(0)
 
-    # All checks passed
-    print(json.dumps({"permissionDecision": "allow"}))
+    # All checks passed - inject interview decisions as context reminder
+    decisions = interview.get("decisions", {})
+
+    if decisions:
+        # Build a reminder of what the user decided
+        decision_summary = _build_decision_summary(decisions)
+
+        # Allow but inject context about user decisions
+        print(json.dumps({
+            "permissionDecision": "allow",
+            "message": f"""✅ Interview complete. REMEMBER THE USER'S DECISIONS:
+
+{decision_summary}
+
+Your implementation MUST align with these choices.
+The state file tracks these for consistency verification."""
+        }))
+    else:
+        print(json.dumps({"permissionDecision": "allow"}))
+
     sys.exit(0)
 
 
+def _build_decision_summary(decisions: dict) -> str:
+    """Build a human-readable summary of user decisions from the interview."""
+    if not decisions:
+        return "No key decisions recorded."
+
+    lines = []
+    decision_labels = {
+        "provider": "AI Provider",
+        "purpose": "Primary Purpose",
+        "response_format": "Response Format",
+        "required_params": "Required Parameters",
+        "optional_params": "Optional Parameters",
+        "error_handling": "Error Handling",
+        "api_key_handling": "API Key Handling",
+        "external_services": "External Services",
+    }
+
+    for key, data in decisions.items():
+        label = decision_labels.get(key, key.replace("_", " ").title())
+        response = data.get("response", "")
+        value = data.get("value", "")
+
+        if value:
+            lines.append(f"• {label}: {value}")
+        elif response:
+            # Truncate long responses
+            short_response = response[:80] + "..." if len(response) > 80 else response
+            lines.append(f"• {label}: {short_response}")
+
+    return "\n".join(lines) if lines else "No key decisions recorded."
+
+
+def _build_research_based_example(research_queries: list) -> str:
+    """Build an example question based on actual research queries."""
+    if not research_queries:
+        return """Example (generic - do research first!):
+  "What is the main use case for this endpoint?"
+  1. Data retrieval
+  2. Data transformation
+  3. AI processing
+  4. Type something..."""
+
+    # Extract terms from research to suggest relevant options
+    all_terms = []
+    for query in research_queries[-5:]:  # Last 5 queries
+        terms = query.get("terms", [])
+        all_terms.extend(terms)
+
+    # Deduplicate and get top terms
+    unique_terms = list(dict.fromkeys(all_terms))[:4]
+
+    if unique_terms:
+        options_example = "\n  ".join([
+            f"{i+1}. {term.title()}" for i, term in enumerate(unique_terms)
+        ])
+        return f"""Example based on your research:
+  "Which of these should be the primary focus?"
+  {options_example}
+  {len(unique_terms)+1}. Type something else..."""
+
+    return """Example:
+  "What capability is most important?"
+  1. Option based on research finding 1
+  2. Option based on research finding 2
+  3. Option based on research finding 3
+  4. Type something..."""
+
+
 if __name__ == "__main__":
     main()

package/hooks/track-tool-use.py

@@ -60,7 +60,9 @@ def main():
         interview = phases.setdefault("interview", {
             "status": "not_started",
             "questions": [],
-            "user_question_count": 0
+            "user_question_count": 0,
+            "structured_question_count": 0,
+            "decisions": {}  # Track key decisions for consistency checking
         })
 
         # Track the question
@@ -68,13 +70,71 @@ def main():
         user_count = interview.get("user_question_count", 0) + 1
         interview["user_question_count"] = user_count
 
+        # Check if this question has structured options (multiple-choice)
+        options = tool_input.get("options", [])
+        has_options = len(options) > 0
+
+        # Track structured questions count
+        if has_options:
+            structured_count = interview.get("structured_question_count", 0) + 1
+            interview["structured_question_count"] = structured_count
+
+        # IMPORTANT: Capture the user's response from tool_output
+        # PostToolUse runs AFTER the tool completes, so we have the response
+        user_response = None
+        selected_value = None
+
+        # tool_output contains the user's response
+        if isinstance(tool_output, str):
+            user_response = tool_output
+        elif isinstance(tool_output, dict):
+            user_response = tool_output.get("response", tool_output.get("result", str(tool_output)))
+
+        # Try to match response to an option value
+        if has_options and user_response:
+            response_lower = user_response.lower().strip()
+            for opt in options:
+                opt_value = opt.get("value", "").lower()
+                opt_label = opt.get("label", "").lower()
+                # Check if response matches value or label
+                if opt_value in response_lower or response_lower in opt_label or opt_label in response_lower:
+                    selected_value = opt.get("value")
+                    break
+
         question_entry = {
             "question": tool_input.get("question", ""),
             "timestamp": datetime.now().isoformat(),
-            "tool_used": True  # Proves AskUserQuestion was actually called
+            "tool_used": True,  # Proves AskUserQuestion was actually called
+            "has_options": has_options,
+            "options_count": len(options),
+            "options": [opt.get("label", opt.get("value", "")) for opt in options[:5]] if options else [],
+            "user_response": user_response[:500] if user_response else None,  # Capture actual response
+            "selected_value": selected_value  # Matched option value if applicable
         }
         questions.append(question_entry)
 
+        # Track key decisions in a summary dict for easy reference during implementation
+        decisions = interview.setdefault("decisions", {})
+        question_text = tool_input.get("question", "").lower()
+
+        # Categorize common decision types
+        if "provider" in question_text or "ai provider" in question_text:
+            decisions["provider"] = {"response": user_response, "value": selected_value}
+        elif "purpose" in question_text or "primary purpose" in question_text:
+            decisions["purpose"] = {"response": user_response, "value": selected_value}
+        elif "format" in question_text or "response format" in question_text:
+            decisions["response_format"] = {"response": user_response, "value": selected_value}
+        elif "parameter" in question_text and "required" in question_text:
+            decisions["required_params"] = {"response": user_response, "value": selected_value}
+        elif "parameter" in question_text and "optional" in question_text:
+            decisions["optional_params"] = {"response": user_response, "value": selected_value}
+        elif "error" in question_text:
+            decisions["error_handling"] = {"response": user_response, "value": selected_value}
+        elif "api key" in question_text or "key" in question_text:
+            decisions["api_key_handling"] = {"response": user_response, "value": selected_value}
+        elif "service" in question_text or "external" in question_text:
+            decisions["external_services"] = {"response": user_response, "value": selected_value}
+
         # Update interview status
         if interview.get("status") == "not_started":
             interview["status"] = "in_progress"
@@ -82,6 +142,16 @@ def main():
 
         interview["last_activity"] = datetime.now().isoformat()
 
+        # Log for visibility
+        if has_options:
+            interview["last_structured_question"] = {
+                "question": tool_input.get("question", "")[:100],
+                "options_count": len(options),
+                "user_response": user_response[:100] if user_response else None,
+                "selected_value": selected_value,
+                "timestamp": datetime.now().isoformat()
+            }
+
         # Save and exit
         STATE_FILE.write_text(json.dumps(state, indent=2))
         print(json.dumps({"continue": True}))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
   "main": "bin/cli.js",
   "bin": {