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

package/README.md

@@ -30,9 +30,9 @@ Six Python hooks that provide **real programmatic guarantees**:
 
 - **`enforce-external-research.py`** - (v1.7.0) Detects external API questions and requires research before answering
 - **`enforce-research.py`** - Blocks API code writing until research is complete
-- **`enforce-interview.py`** - Verifies user questions were actually asked (prevents self-answering)
+- **`enforce-interview.py`** - (v1.8.0+) Verifies structured questions with options were asked; (v1.9.0+) Injects decision reminders on writes
 - **`verify-implementation.py`** - Checks implementation matches interview requirements
-- **`track-tool-use.py`** - Logs all research activity (Context7, WebSearch, WebFetch, AskUserQuestion)
+- **`track-tool-use.py`** - (v1.9.0+) Captures user decisions from AskUserQuestion; logs all research activity
 - **`api-workflow-check.py`** - Prevents stopping until required phases are complete + git diff verification
 
 ### State Tracking
@@ -470,6 +470,34 @@ INJECTS: "RESEARCH REQUIRED: Use Context7/WebSearch before answering"
 CLAUDE: Researches first → Gives accurate answer
 ```
 
+### Gap 7: Interview Decisions Not Used During Implementation (v1.9.0+)
+**Problem:** AI asks good interview questions but then ignores the answers when writing code.
+
+**Example:**
+- Interview: User selected "server environment variables only" for API key handling
+- Implementation: AI writes code with custom header overrides (not what user wanted!)
+
+**Fix:** Two-part solution in `track-tool-use.py` and `enforce-interview.py`:
+
+1. **track-tool-use.py** now captures:
+   - The user's actual response from AskUserQuestion
+   - Matches responses to option values
+   - Stores decisions in categorized `decisions` dict (purpose, api_key_handling, etc.)
+
+2. **enforce-interview.py** now injects a decision summary on EVERY write:
+```
+✅ Interview complete. REMEMBER THE USER'S DECISIONS:
+
+• Primary Purpose: full_brand_kit
+• API Key Handling: server_only
+• Response Format: JSON with asset URLs
+• Error Handling: detailed (error, code, details)
+
+Your implementation MUST align with these choices.
+```
+
+This ensures the AI is constantly reminded of what the user actually wanted throughout the entire implementation phase.
+
 ## 🔧 Requirements
 
 - **Node.js** 14.0.0 or higher

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