@hustle-together/api-dev-tools 1.7.0 → 1.8.0

package/commands/api-interview.md

@@ -1,120 +1,223 @@
-# API Interview - Structured API Discovery
+# API Interview - Research-Based Structured Discovery
 
 **Usage:** `/api-interview [endpoint-name]`
 
-**Purpose:** Conduct structured interview to understand API endpoint purpose, usage, and requirements before any implementation.
+**Purpose:** Conduct structured interview with MULTIPLE-CHOICE questions derived from research findings to understand API endpoint purpose, usage, and requirements before any implementation.
+
+## v1.8.0 REQUIREMENT: Structured Questions with Options
+
+**CRITICAL:** All interview questions MUST:
+1. Be based on COMPLETED research (Context7 + WebSearch)
+2. Use AskUserQuestion tool with the `options` parameter
+3. Provide multiple-choice selections derived from research findings
+4. Include a "Type something else..." option for custom input
+
+**Example of CORRECT structured question:**
+```
+AskUserQuestion(
+  question="Which AI provider should this endpoint support?",
+  options=[
+    {"value": "openai", "label": "OpenAI (GPT-4o, GPT-4-turbo)"},
+    {"value": "anthropic", "label": "Anthropic (Claude Sonnet, Opus)"},
+    {"value": "google", "label": "Google (Gemini Pro, Flash)"},
+    {"value": "all", "label": "All providers (multi-provider support)"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+This gives users clear choices from RESEARCHED capabilities, not guesses.
 
 ## Interview Methodology
 
 Based on Anthropic Interviewer approach with three phases:
 
+### Phase 0: PREREQUISITE - Research (MANDATORY)
+**You CANNOT start the interview until research is complete.**
+
+Before asking ANY questions:
+1. Use Context7 to get SDK/API documentation
+2. Use WebSearch (2-3 searches) for official docs
+3. Gather all available options, parameters, models, providers
+4. Build your question options FROM this research
+
+Example research flow:
+```
+1. mcp__context7__resolve-library-id("vercel ai sdk")
+2. mcp__context7__get-library-docs(libraryId)
+3. WebSearch("Vercel AI SDK providers models 2025")
+4. WebSearch("Vercel AI SDK streaming options parameters")
+```
+
+**Research informs options. No research = no good options = interview blocked.**
+
 ### Phase 1: Planning (Internal)
 - Review endpoint name and context
-- Identify key areas to explore
+- Review research findings (what providers, models, parameters exist?)
+- Build structured question options from research
 - Prepare follow-up questions
 
-### Phase 2: Interviewing (User Interaction)
-Ask structured questions to understand:
+### Phase 2: Interviewing (User Interaction with Structured Options)
+
+**EVERY question uses AskUserQuestion with options parameter.**
 
 #### A. Purpose & Context
-1. **What problem does this API endpoint solve?**
-   - What's the business/technical need?
-   - What happens without this endpoint?
-
-2. **Who are the primary users?**
-   - Frontend developers? End users? Other systems?
-   - What's their technical level?
-
-3. **What triggers usage of this API?**
-   - User action? Scheduled task? Event-driven?
-   - How frequently is it called?
-
-#### B. Real-World Usage Scenarios
-4. **Walk me through a typical request:**
-   - What data does the user provide?
-   - What do they expect back?
-   - What happens with the response?
-
-5. **What are the most common use cases?** (Ask for 3-5 examples)
-   - Common scenario 1: ___
-   - Common scenario 2: ___
-   - Edge scenario: ___
-
-6. **Show me an example request/response you envision:**
-   - Request body/params
-   - Expected response
-   - Error cases
-
-#### C. Technical Requirements
-7. **What parameters are absolutely REQUIRED?**
-   - Can the API work without them?
-   - What happens if they're missing?
-
-8. **What parameters are OPTIONAL?**
-   - What defaults make sense?
-   - How do they modify behavior?
-
-9. **What are valid value ranges/formats?**
-   - Type constraints (string, number, enum)?
-   - Length/size limits?
-   - Format requirements (email, URL, date)?
-
-10. **Are there parameter dependencies?**
-    - If X is provided, must Y also be provided?
-    - Mutually exclusive options?
-
-#### D. Dependencies & Integration
-11. **What external services does this use?**
-    - AI providers (OpenAI, Anthropic, Google)?
-    - Third-party APIs (Firecrawl, Brave Search)?
-    - Database (Supabase)?
-
-12. **What API keys are required?**
-    - Where are they configured?
-    - Are there fallback options?
-    - Can users provide their own keys?
-
-13. **What AI models/providers are involved?**
-    - Specific models (GPT-4, Claude Sonnet)?
-    - Why those models?
-    - Are there alternatives?
-
-14. **Are there rate limits, quotas, or costs?**
-    - Per-request costs?
-    - Rate limiting needed?
-    - Cost tracking required?
-
-#### E. Error Handling & Edge Cases
-15. **What can go wrong?**
-    - Invalid input?
-    - External service failures?
-    - Timeout scenarios?
-
-16. **How should errors be communicated?**
-    - HTTP status codes?
-    - Error message format?
-    - User-facing vs. technical errors?
-
-17. **What are boundary conditions?**
-    - Very large inputs?
-    - Empty/null values?
-    - Concurrent requests?
-
-18. **What should be validated before processing?**
-    - Input validation rules?
-    - Authentication/authorization?
-    - Resource availability?
-
-#### F. Documentation & Resources
-19. **Where is official documentation?**
-    - Link to external API docs
-    - SDK documentation
-    - Code examples
-
-20. **Are there similar endpoints for reference?**
-    - In this codebase?
-    - In other projects?
-    - Industry examples?
+
+**Question 1: Primary Purpose**
+```
+AskUserQuestion(
+  question="What is the primary purpose of this endpoint?",
+  options=[
+    {"value": "data_retrieval", "label": "Retrieve/query data"},
+    {"value": "data_transform", "label": "Transform/process data"},
+    {"value": "ai_generation", "label": "AI content generation"},
+    {"value": "ai_analysis", "label": "AI analysis/classification"},
+    {"value": "integration", "label": "Third-party integration"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 2: Primary Users**
+```
+AskUserQuestion(
+  question="Who are the primary users of this endpoint?",
+  options=[
+    {"value": "frontend", "label": "Frontend developers (React, Vue, etc.)"},
+    {"value": "backend", "label": "Backend services (server-to-server)"},
+    {"value": "mobile", "label": "Mobile app developers"},
+    {"value": "enduser", "label": "End users directly (browser)"},
+    {"value": "automation", "label": "Automated systems/bots"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 3: Usage Trigger**
+```
+AskUserQuestion(
+  question="What triggers a call to this endpoint?",
+  options=[
+    {"value": "user_action", "label": "User action (button click, form submit)"},
+    {"value": "page_load", "label": "Page/component load"},
+    {"value": "scheduled", "label": "Scheduled/cron job"},
+    {"value": "webhook", "label": "External webhook/event"},
+    {"value": "realtime", "label": "Real-time/streaming updates"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+#### B. Technical Requirements (Research-Based Options)
+
+**Question 4: AI Provider** (options from research)
+```
+AskUserQuestion(
+  question="Which AI provider(s) should this endpoint support?",
+  options=[
+    // These options come from your Context7/WebSearch research!
+    {"value": "openai", "label": "OpenAI (gpt-4o, gpt-4-turbo)"},
+    {"value": "anthropic", "label": "Anthropic (claude-sonnet-4-20250514, claude-opus-4-20250514)"},
+    {"value": "google", "label": "Google (gemini-pro, gemini-flash)"},
+    {"value": "groq", "label": "Groq (llama-3.1-70b, mixtral)"},
+    {"value": "multiple", "label": "Multiple providers (configurable)"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 5: Response Format** (options from research)
+```
+AskUserQuestion(
+  question="What response format is needed?",
+  options=[
+    // Options based on what the SDK supports (from research)
+    {"value": "streaming", "label": "Streaming (real-time chunks)"},
+    {"value": "complete", "label": "Complete response (wait for full)"},
+    {"value": "structured", "label": "Structured/JSON mode"},
+    {"value": "tool_calls", "label": "Tool calling/function calls"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 6: Required Parameters**
+```
+AskUserQuestion(
+  question="Which parameters are REQUIRED (cannot work without)?",
+  options=[
+    // Based on researched SDK parameters
+    {"value": "prompt_only", "label": "Just the prompt/message"},
+    {"value": "prompt_model", "label": "Prompt + model selection"},
+    {"value": "prompt_model_config", "label": "Prompt + model + configuration"},
+    {"value": "full_config", "label": "Full configuration required"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 7: Optional Parameters**
+```
+AskUserQuestion(
+  question="Which optional parameters should be supported?",
+  options=[
+    // From research: discovered optional parameters
+    {"value": "temperature", "label": "temperature (creativity control)"},
+    {"value": "max_tokens", "label": "maxTokens (response length)"},
+    {"value": "system_prompt", "label": "system (system prompt)"},
+    {"value": "tools", "label": "tools (function calling)"},
+    {"value": "all_standard", "label": "All standard AI parameters"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+#### C. Dependencies & Integration
+
+**Question 8: External Services**
+```
+AskUserQuestion(
+  question="What external services does this endpoint need?",
+  options=[
+    {"value": "ai_only", "label": "AI provider only (OpenAI, Anthropic, etc.)"},
+    {"value": "ai_search", "label": "AI + Search (Brave, Perplexity)"},
+    {"value": "ai_scrape", "label": "AI + Web scraping (Firecrawl)"},
+    {"value": "ai_db", "label": "AI + Database (Supabase)"},
+    {"value": "multiple", "label": "Multiple external services"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+**Question 9: API Key Handling**
+```
+AskUserQuestion(
+  question="How should API keys be handled?",
+  options=[
+    {"value": "server_only", "label": "Server environment variables only"},
+    {"value": "server_header", "label": "Server env + custom header override"},
+    {"value": "client_next", "label": "NEXT_PUBLIC_ client-side keys"},
+    {"value": "all_methods", "label": "All methods (env, header, client)"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
+
+#### D. Error Handling & Edge Cases
+
+**Question 10: Error Response Format**
+```
+AskUserQuestion(
+  question="How should errors be returned?",
+  options=[
+    {"value": "simple", "label": "Simple: {error: string}"},
+    {"value": "detailed", "label": "Detailed: {error, code, details}"},
+    {"value": "ai_sdk", "label": "AI SDK standard format"},
+    {"value": "http_native", "label": "HTTP status codes + body"},
+    {"value": "custom", "label": "Type something else..."}
+  ]
+)
+```
 
 ### Phase 3: Analysis (Documentation)
 After interview, I will:
@@ -135,6 +238,7 @@ Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
 **Date:** [current-date]
 **Interviewed by:** Claude Code
 **Status:** Interview Complete
+**Research Sources:** [list of Context7/WebSearch sources]
 
 ## 1. Purpose & Context
 [Synthesized understanding of why this exists]
@@ -153,7 +257,14 @@ Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
 - API Keys Required: [list]
 - AI Models: [list]
 
-## 6. Real-World Scenarios
+## 6. Interview Responses
+| Question | User Selection | Notes |
+|----------|---------------|-------|
+| Purpose | [selected option] | |
+| Users | [selected option] | |
+| ... | ... | |
+
+## 7. Real-World Scenarios
 ### Scenario 1: [Common Use Case]
 **Request:**
 ```json
@@ -164,23 +275,23 @@ Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
 {example}
 ```
 
-## 7. Edge Cases & Error Handling
+## 8. Edge Cases & Error Handling
 [Identified edge cases and how to handle them]
 
-## 8. Validation Rules
+## 9. Validation Rules
 [What must be validated]
 
-## 9. Documentation Links
-- [Official docs]
-- [SDK docs]
-- [Related resources]
+## 10. Documentation Links
+- [Official docs from research]
+- [SDK docs from Context7]
+- [Related resources from WebSearch]
 
-## 10. Test Cases (To Implement)
+## 11. Test Cases (To Implement)
 - [ ] Test: [scenario from interview]
 - [ ] Test: [edge case from interview]
 - [ ] Test: [error handling from interview]
 
-## 11. Open Questions
+## 12. Open Questions
 [Any ambiguities to resolve]
 ```
 
@@ -190,17 +301,30 @@ Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
 /api-interview generate-css
 ```
 
-I will then ask all 20 questions, document responses, and create the endpoint documentation file ready for TDD implementation.
+I will:
+1. First complete research (Context7 + WebSearch)
+2. Build structured questions with options from research
+3. Ask all questions using AskUserQuestion with options
+4. Document responses and create the endpoint documentation
 
 <claude-commands-template>
-## Interview Guidelines
-
-1. **Ask ALL questions** - Don't skip steps even if obvious
-2. **Request examples** - Concrete examples > abstract descriptions
-3. **Clarify ambiguity** - If answer is unclear, ask follow-ups
-4. **Document links** - Capture ALL external documentation URLs
-5. **Real scenarios** - Focus on actual usage, not hypothetical
-6. **Be thorough** - Better to over-document than under-document
+## Interview Guidelines (v1.8.0)
+
+1. **RESEARCH FIRST** - Complete Context7 + WebSearch before ANY questions
+2. **STRUCTURED OPTIONS** - Every question uses AskUserQuestion with options[]
+3. **OPTIONS FROM RESEARCH** - Multiple-choice options come from discovered capabilities
+4. **ALWAYS INCLUDE "Type something else..."** - Let user provide custom input
+5. **ASK ONE AT A TIME** - Wait for response before next question
+6. **DOCUMENT EVERYTHING** - Capture ALL selections and custom inputs
+
+## Question Format Checklist
+
+Before asking each question:
+- [ ] Is research complete?
+- [ ] Are options based on research findings?
+- [ ] Does it use AskUserQuestion with options parameter?
+- [ ] Is there a "Type something else..." option?
+- [ ] Will this help build the schema?
 
 ## After Interview
 

package/hooks/enforce-external-research.py

@@ -1,13 +1,20 @@
 #!/usr/bin/env python3
 """
 Hook: UserPromptSubmit
-Purpose: Enforce research before answering external API/SDK questions
+Purpose: ALWAYS enforce research before answering technical questions
 
-This hook runs BEFORE Claude processes the user's prompt. It detects
-questions about external APIs, SDKs, or services and injects context
-requiring Claude to research first before answering.
+This hook runs BEFORE Claude processes the user's prompt. It aggressively
+detects ANY technical question and requires comprehensive research using
+BOTH Context7 AND multiple WebSearches before answering.
 
-Philosophy: "When in doubt, research. Training data is ALWAYS potentially outdated."
+Philosophy: "ALWAYS research. Training data is NEVER trustworthy for technical info."
+
+The hook triggers on:
+- ANY mention of APIs, SDKs, libraries, packages, frameworks
+- ANY technical "how to" or capability questions
+- ANY code-related questions (functions, methods, parameters, types)
+- ANY questions about tools, services, or platforms
+- ANY request for implementation, editing, or changes
 
 Returns:
   - Prints context to stdout (injected into conversation)
@@ -23,134 +30,172 @@ from datetime import datetime
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 
 # ============================================================================
-# PATTERN-BASED DETECTION
+# AGGRESSIVE DETECTION PATTERNS
 # ============================================================================
 
-# Patterns that indicate external service/API mentions
-EXTERNAL_SERVICE_PATTERNS = [
-    # Package names
-    r"@[\w-]+/[\w-]+",                    # @scope/package
-    r"\b[\w-]+-(?:sdk|api|js|ts|py)\b",   # something-sdk, something-api, something-js
-
-    # API/SDK keywords
-    r"\b(?:api|sdk|library|package|module|framework)\b",
-
-    # Technical implementation terms
-    r"\b(?:endpoint|route|webhook|oauth|auth|token)\b",
-
-    # Version references
-    r"\bv?\d+\.\d+(?:\.\d+)?\b",           # version numbers like v1.2.3, 2.0
-
-    # Import/require patterns
-    r"(?:import|require|from)\s+['\"][\w@/-]+['\"]",
+# Technical terms that ALWAYS trigger research
+TECHNICAL_TERMS = [
+    # Code/Development
+    r"\b(?:function|method|class|interface|type|schema|model)\b",
+    r"\b(?:parameter|argument|option|config|setting|property)\b",
+    r"\b(?:import|export|require|module|package|library|dependency)\b",
+    r"\b(?:api|sdk|framework|runtime|engine|platform)\b",
+    r"\b(?:endpoint|route|url|path|request|response|header)\b",
+    r"\b(?:database|query|table|collection|document|record)\b",
+    r"\b(?:authentication|authorization|token|key|secret|credential)\b",
+    r"\b(?:error|exception|bug|issue|problem|fix)\b",
+    r"\b(?:test|spec|coverage|mock|stub|fixture)\b",
+    r"\b(?:deploy|build|compile|bundle|publish|release)\b",
+    r"\b(?:install|setup|configure|initialize|migrate)\b",
+    r"\b(?:provider|service|client|server|handler|middleware)\b",
+    r"\b(?:stream|async|await|promise|callback|event)\b",
+    r"\b(?:component|widget|element|view|layout|template)\b",
+    r"\b(?:state|store|reducer|action|context|hook)\b",
+    r"\b(?:validate|parse|serialize|transform|convert)\b",
+
+    # Package patterns
+    r"@[\w-]+/[\w-]+",                      # @scope/package
+    r"\b[\w-]+-(?:sdk|api|js|ts|py|go|rs)\b",  # something-sdk, something-api
+
+    # Version patterns
+    r"\bv?\d+\.\d+(?:\.\d+)?(?:-[\w.]+)?\b",  # v1.2.3, 2.0.0-beta
+
+    # File patterns
+    r"\b[\w-]+\.(?:ts|js|tsx|jsx|py|go|rs|json|yaml|yml|toml|env)\b",
 ]
 
-# Patterns that indicate asking about features/capabilities
-CAPABILITY_QUESTION_PATTERNS = [
-    # "What does X support/have/do"
-    r"what\s+(?:does|can|are|is)\s+\w+",
-    r"what\s+\w+\s+(?:support|have|provide|offer)",
-
-    # "Does X support/have"
-    r"(?:does|can|will)\s+\w+\s+(?:support|have|handle|do|work)",
-
-    # "How to/do" questions
-    r"how\s+(?:to|do|does|can|should)\s+",
-
-    # Lists and availability
-    r"(?:list|show)\s+(?:of|all|available)",
-    r"which\s+\w+\s+(?:are|is)\s+(?:available|supported)",
-    r"all\s+(?:available|supported)\s+\w+",
-
-    # Examples and implementation
-    r"example\s+(?:of|for|using|with)",
-    r"how\s+to\s+(?:use|implement|integrate|connect|setup|configure)",
+# Question patterns that indicate asking about functionality
+QUESTION_PATTERNS = [
+    # Direct questions
+    r"\b(?:what|which|where|when|why|how)\b",
+    r"\b(?:can|could|would|should|will|does|do|is|are)\b.*\?",
+
+    # Requests
+    r"\b(?:show|tell|explain|describe|list|find|get|give)\b",
+    r"\b(?:help|need|want|looking for|trying to)\b",
+
+    # Actions
+    r"\b(?:create|make|build|add|implement|write|generate)\b",
+    r"\b(?:update|change|modify|edit|fix|refactor|improve)\b",
+    r"\b(?:delete|remove|drop|clear|reset)\b",
+    r"\b(?:connect|integrate|link|sync|merge)\b",
+    r"\b(?:debug|trace|log|monitor|track)\b",
+
+    # Comparisons
+    r"\b(?:difference|compare|versus|vs|between|or)\b",
+    r"\b(?:better|best|recommended|preferred|alternative)\b",
 ]
 
-# Common external service/company names (partial list - patterns catch the rest)
-KNOWN_SERVICES = [
-    # AI/ML
-    "openai", "anthropic", "google", "gemini", "gpt", "claude", "llama",
-    "groq", "perplexity", "mistral", "cohere", "huggingface", "replicate",
-
-    # Cloud/Infrastructure
-    "aws", "azure", "gcp", "vercel", "netlify", "cloudflare", "supabase",
-    "firebase", "mongodb", "postgres", "redis", "elasticsearch",
-
-    # APIs/Services
-    "stripe", "twilio", "sendgrid", "mailchimp", "slack", "discord",
-    "github", "gitlab", "bitbucket", "jira", "notion", "airtable",
-    "shopify", "salesforce", "hubspot", "zendesk",
-
-    # Data/Analytics
-    "segment", "mixpanel", "amplitude", "datadog", "sentry", "grafana",
-
-    # Media/Content
-    "cloudinary", "imgix", "mux", "brandfetch", "unsplash", "pexels",
-
-    # Auth
-    "auth0", "okta", "clerk", "nextauth", "passport",
+# Phrases that ALWAYS require research (no exceptions)
+ALWAYS_RESEARCH_PHRASES = [
+    r"how (?:to|do|does|can|should|would)",
+    r"what (?:is|are|does|can|should)",
+    r"(?:does|can|will|should) .+ (?:support|have|handle|work|do)",
+    r"(?:list|show|get|find) (?:all|available|supported)",
+    r"example (?:of|for|using|with|code)",
+    r"(?:implement|add|create|build|write|generate) .+",
+    r"(?:update|change|modify|edit|fix) .+",
+    r"(?:configure|setup|install|deploy) .+",
+    r"(?:error|issue|problem|bug|not working)",
+    r"(?:api|sdk|library|package|module|framework)",
+    r"(?:documentation|docs|reference|guide)",
+]
 
-    # Payments
-    "paypal", "square", "braintree", "adyen",
+# Exclusion patterns - things that DON'T need research
+EXCLUDE_PATTERNS = [
+    r"^(?:hi|hello|hey|thanks|thank you|ok|okay|yes|no|sure)[\s!?.]*$",
+    r"^(?:good morning|good afternoon|good evening|goodbye|bye)[\s!?.]*$",
+    r"^(?:please|sorry|excuse me)[\s!?.]*$",
+    r"^(?:\d+[\s+\-*/]\d+|calculate|math).*$",  # Simple math
 ]
 
 # ============================================================================
 # DETECTION LOGIC
 # ============================================================================
 
-def detect_external_api_question(prompt: str) -> dict:
+def is_excluded(prompt: str) -> bool:
+    """Check if prompt is a simple greeting or non-technical."""
+    prompt_clean = prompt.strip().lower()
+
+    # Very short prompts that are just greetings
+    if len(prompt_clean) < 20:
+        for pattern in EXCLUDE_PATTERNS:
+            if re.match(pattern, prompt_clean, re.IGNORECASE):
+                return True
+
+    return False
+
+
+def detect_technical_question(prompt: str) -> dict:
     """
-    Detect if the prompt is asking about external APIs/SDKs.
+    Aggressively detect if the prompt is technical and requires research.
 
     Returns:
         {
             "detected": bool,
             "terms": list of detected terms,
-            "patterns_matched": list of pattern types matched,
-            "confidence": "high" | "medium" | "low"
+            "patterns_matched": list of pattern types,
+            "confidence": "critical" | "high" | "medium" | "low" | "none"
         }
     """
+    if is_excluded(prompt):
+        return {
+            "detected": False,
+            "terms": [],
+            "patterns_matched": [],
+            "confidence": "none",
+        }
+
     prompt_lower = prompt.lower()
     detected_terms = []
     patterns_matched = []
 
-    # Check for known services
-    for service in KNOWN_SERVICES:
-        if service in prompt_lower:
-            detected_terms.append(service)
-            patterns_matched.append("known_service")
-
-    # Check external service patterns
-    for pattern in EXTERNAL_SERVICE_PATTERNS:
+    # Check for ALWAYS_RESEARCH_PHRASES first (highest priority)
+    for pattern in ALWAYS_RESEARCH_PHRASES:
+        if re.search(pattern, prompt_lower, re.IGNORECASE):
+            patterns_matched.append("always_research")
+            # Extract the matched phrase
+            match = re.search(pattern, prompt_lower, re.IGNORECASE)
+            if match:
+                detected_terms.append(match.group(0)[:50])
+
+    # Check technical terms
+    for pattern in TECHNICAL_TERMS:
         matches = re.findall(pattern, prompt_lower, re.IGNORECASE)
         if matches:
-            detected_terms.extend(matches)
-            patterns_matched.append("external_service_pattern")
+            detected_terms.extend(matches[:3])  # Limit per pattern
+            patterns_matched.append("technical_term")
 
-    # Check capability question patterns
-    for pattern in CAPABILITY_QUESTION_PATTERNS:
+    # Check question patterns
+    for pattern in QUESTION_PATTERNS:
         if re.search(pattern, prompt_lower, re.IGNORECASE):
-            patterns_matched.append("capability_question")
+            patterns_matched.append("question_pattern")
             break
 
     # Deduplicate
-    detected_terms = list(set(detected_terms))
+    detected_terms = list(dict.fromkeys(detected_terms))[:10]
     patterns_matched = list(set(patterns_matched))
 
-    # Determine confidence
-    if "known_service" in patterns_matched and "capability_question" in patterns_matched:
+    # Determine confidence - MUCH more aggressive
+    if "always_research" in patterns_matched:
+        confidence = "critical"
+    elif "technical_term" in patterns_matched and "question_pattern" in patterns_matched:
         confidence = "high"
-    elif "known_service" in patterns_matched or len(detected_terms) >= 2:
-        confidence = "medium"
-    elif patterns_matched:
-        confidence = "low"
+    elif "technical_term" in patterns_matched:
+        confidence = "high"  # Technical terms alone = high
+    elif "question_pattern" in patterns_matched and len(prompt) > 30:
+        confidence = "medium"  # Questions longer than 30 chars
+    elif len(prompt) > 50:
+        confidence = "low"  # Longer prompts default to low (still triggers)
     else:
         confidence = "none"
 
+    # AGGRESSIVE: Trigger on anything except "none"
+    detected = confidence != "none"
+
     return {
-        "detected": confidence in ["high", "medium"],
-        "terms": detected_terms[:10],  # Limit to 10 terms
+        "detected": detected,
+        "terms": detected_terms,
         "patterns_matched": patterns_matched,
         "confidence": confidence,
     }
@@ -165,11 +210,11 @@ def check_active_workflow() -> bool:
         state = json.loads(STATE_FILE.read_text())
         phases = state.get("phases", {})
 
-        # Check if any phase is in progress
         for phase_key, phase_data in phases.items():
             if isinstance(phase_data, dict):
                 status = phase_data.get("status", "")
-                if status in ["in_progress", "pending"]:
+                if status in ["in_progress", "pending", "complete"]:
+                    # If ANY phase has been touched, we're in a workflow
                     return True
 
         return False
@@ -177,50 +222,13 @@ def check_active_workflow() -> bool:
         return False
 
 
-def check_already_researched(terms: list) -> list:
-    """Check which terms have already been researched."""
-    if not STATE_FILE.exists():
-        return []
-
-    try:
-        state = json.loads(STATE_FILE.read_text())
-        research_queries = state.get("research_queries", [])
-
-        # Also check sources in phases
-        phases = state.get("phases", {})
-        all_sources = []
-        for phase_data in phases.values():
-            if isinstance(phase_data, dict):
-                sources = phase_data.get("sources", [])
-                all_sources.extend(sources)
-
-        # Combine all research text
-        all_research_text = " ".join(str(s) for s in all_sources)
-        all_research_text += " ".join(
-            str(q.get("query", "")) + " " + str(q.get("term", ""))
-            for q in research_queries
-            if isinstance(q, dict)
-        )
-        all_research_text = all_research_text.lower()
-
-        # Find which terms were already researched
-        already_researched = []
-        for term in terms:
-            if term.lower() in all_research_text:
-                already_researched.append(term)
-
-        return already_researched
-    except (json.JSONDecodeError, Exception):
-        return []
-
-
-def log_detection(prompt: str, detection: dict) -> None:
+def log_detection(prompt: str, detection: dict, injected: bool) -> None:
     """Log this detection for debugging/auditing."""
-    if not STATE_FILE.exists():
-        return
-
     try:
-        state = json.loads(STATE_FILE.read_text())
+        if STATE_FILE.exists():
+            state = json.loads(STATE_FILE.read_text())
+        else:
+            state = {"prompt_detections": []}
 
         if "prompt_detections" not in state:
             state["prompt_detections"] = []
@@ -229,11 +237,13 @@ def log_detection(prompt: str, detection: dict) -> None:
             "timestamp": datetime.now().isoformat(),
             "prompt_preview": prompt[:100] + "..." if len(prompt) > 100 else prompt,
             "detection": detection,
+            "injected": injected,
         })
 
-        # Keep only last 20 detections
-        state["prompt_detections"] = state["prompt_detections"][-20:]
+        # Keep only last 50 detections
+        state["prompt_detections"] = state["prompt_detections"][-50:]
 
+        STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
         STATE_FILE.write_text(json.dumps(state, indent=2))
     except Exception:
         pass  # Don't fail the hook on logging errors
@@ -248,69 +258,69 @@ def main():
     try:
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError:
-        # If we can't parse input, allow without injection
         sys.exit(0)
 
     prompt = input_data.get("prompt", "")
 
-    if not prompt:
+    if not prompt or len(prompt.strip()) < 5:
         sys.exit(0)
 
-    # Check if in active workflow mode (stricter enforcement)
+    # Check if in active workflow mode
     active_workflow = check_active_workflow()
 
-    # Detect external API questions
-    detection = detect_external_api_question(prompt)
-
-    # Log for debugging
-    if detection["detected"] or active_workflow:
-        log_detection(prompt, detection)
+    # Detect technical questions
+    detection = detect_technical_question(prompt)
 
-    # Determine if we should inject research requirement
-    should_inject = False
-    inject_reason = ""
+    # In active workflow, ALWAYS inject (even for low confidence)
+    if active_workflow and detection["confidence"] != "none":
+        detection["detected"] = True
 
-    if active_workflow:
-        # In active workflow, ALWAYS inject for technical questions
-        if detection["confidence"] in ["high", "medium", "low"]:
-            should_inject = True
-            inject_reason = "active_workflow"
-    elif detection["detected"]:
-        # Check if already researched
-        already_researched = check_already_researched(detection["terms"])
-        unresearched_terms = [t for t in detection["terms"] if t not in already_researched]
+    # Log all detections
+    log_detection(prompt, detection, detection["detected"])
 
-        if unresearched_terms:
-            should_inject = True
-            inject_reason = "unresearched_terms"
-            detection["unresearched"] = unresearched_terms
-
-    # Inject context if needed
-    if should_inject:
-        terms_str = ", ".join(detection.get("unresearched", detection["terms"])[:5])
+    # Inject context if detected
+    if detection["detected"]:
+        terms_str = ", ".join(detection["terms"][:5]) if detection["terms"] else "technical question"
+        confidence = detection["confidence"]
 
+        # Build the injection message
         injection = f"""
 <user-prompt-submit-hook>
-EXTERNAL API/SDK DETECTED: {terms_str}
-Confidence: {detection["confidence"]}
-{"Mode: Active API Development Workflow" if active_workflow else ""}
-
-MANDATORY RESEARCH REQUIREMENT:
-Before answering this question, you MUST:
-
-1. Use Context7 (mcp__context7__resolve-library-id + get-library-docs) to look up current documentation
-2. Use WebSearch to find official documentation and recent updates
-3. NEVER answer from training data alone - it may be outdated
-
-Training data can be months or years old. APIs change constantly.
-Research first. Then answer with verified, current information.
-
-After researching, cite your sources in your response.
+RESEARCH REQUIRED - {confidence.upper()} CONFIDENCE
+Detected: {terms_str}
+{"MODE: Active API Development Workflow - STRICT ENFORCEMENT" if active_workflow else ""}
+
+MANDATORY BEFORE ANSWERING:
+
+1. USE CONTEXT7 FIRST:
+   - Call mcp__context7__resolve-library-id to find the library
+   - Call mcp__context7__get-library-docs to get CURRENT documentation
+   - This gives you the ACTUAL source of truth
+
+2. USE WEBSEARCH (2-3 SEARCHES MINIMUM):
+   - Search for official documentation
+   - Search with different phrasings to get comprehensive coverage
+   - Search for recent updates, changes, or known issues
+   - Example searches:
+     * "[topic] official documentation"
+     * "[topic] API reference guide"
+     * "[topic] latest updates 2024 2025"
+
+3. NEVER TRUST TRAINING DATA:
+   - Training data can be months or years outdated
+   - APIs change constantly
+   - Features get added, deprecated, or modified
+   - Parameter names and types change
+
+4. CITE YOUR SOURCES:
+   - After researching, mention where the information came from
+   - Include links when available
+
+RESEARCH FIRST. ANSWER SECOND.
 </user-prompt-submit-hook>
 """
         print(injection)
 
-    # Always allow the prompt to proceed
     sys.exit(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,15 +252,10 @@ 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.
+You MUST actually ask the user questions using AskUserQuestion
+with structured options. Self-answering defeats the 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?
-
-Wait for their real answers before proceeding."""
+Reset the interview and ask with options based on research."""
             }))
             sys.exit(0)
 
@@ -179,5 +264,41 @@ Wait for their real answers before proceeding."""
     sys.exit(0)
 
 
+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,8 @@ def main():
         interview = phases.setdefault("interview", {
             "status": "not_started",
             "questions": [],
-            "user_question_count": 0
+            "user_question_count": 0,
+            "structured_question_count": 0
         })
 
         # Track the question
@@ -68,10 +69,22 @@ 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
+
         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 []
         }
         questions.append(question_entry)
 
@@ -82,6 +95,14 @@ 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),
+                "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.0",
+  "version": "1.8.0",
   "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
   "main": "bin/cli.js",
   "bin": {