@hustle-together/api-dev-tools 1.2.1 → 1.6.0

package/README.md

@@ -26,16 +26,18 @@ Five powerful slash commands for Claude Code:
 - **`/api-status [endpoint]`** - Track implementation progress and phase completion
 
 ### Enforcement Hooks
-Three Python hooks that provide **real programmatic guarantees**:
+Five Python hooks that provide **real programmatic guarantees**:
 
 - **`enforce-research.py`** - Blocks API code writing until research is complete
-- **`track-tool-use.py`** - Logs all research activity (Context7, WebSearch, WebFetch)
-- **`api-workflow-check.py`** - Prevents stopping until required phases are complete
+- **`enforce-interview.py`** - Verifies user questions were actually asked (prevents self-answering)
+- **`verify-implementation.py`** - Checks implementation matches interview requirements
+- **`track-tool-use.py`** - Logs all research activity (Context7, WebSearch, WebFetch, AskUserQuestion)
+- **`api-workflow-check.py`** - Prevents stopping until required phases are complete + git diff verification
 
 ### State Tracking
 - **`.claude/api-dev-state.json`** - Persistent state file tracking all workflow progress
 
-### MCP Servers (Auto-configured in `.mcp.json`)
+### MCP Servers (Auto-installed via `claude mcp add`)
 - **Context7** - Fetches LIVE documentation from library source code (not training data)
 - **GitHub** - Read/create issues, pull requests, and access repository data (requires `GITHUB_PERSONAL_ACCESS_TOKEN`)
 
@@ -402,6 +404,47 @@ The `.claude/api-dev-state.json` file tracks:
 - All research activity is **logged** - auditable trail
 - Workflow completion is **verified** - can't stop early
 
+## 🔍 Gap Detection & Verification (v1.6.0+)
+
+The workflow now includes automatic detection of common implementation gaps:
+
+### Gap 1: Exact Term Matching
+**Problem:** AI paraphrases user terminology instead of using exact terms for research.
+
+**Example:**
+- User says: "Use Vercel AI Gateway"
+- AI searches for: "Vercel AI SDK" (wrong!)
+
+**Fix:** `verify-implementation.py` extracts key terms from interview answers and warns if those exact terms weren't used in research queries.
+
+### Gap 2: File Change Tracking
+**Problem:** AI claims "all files updated" but doesn't verify which files actually changed.
+
+**Fix:** `api-workflow-check.py` runs `git diff --name-only` and compares against tracked `files_created`/`files_modified` in state. Warns about untracked changes.
+
+### Gap 3: Skipped Test Investigation
+**Problem:** AI accepts "9 tests skipped" without investigating why.
+
+**Fix:** `verification_warnings` in state file tracks issues that need review. Stop hook shows unaddressed warnings.
+
+### Gap 4: Implementation Verification
+**Problem:** AI marks task complete without verifying implementation matches interview.
+
+**Fix:** Stop hook checks that:
+- Route files exist if endpoints mentioned
+- Test files are tracked
+- Key terms from interview appear in implementation
+
+### Gap 5: Test/Production Alignment
+**Problem:** Test files check different environment variables than production code.
+
+**Example:**
+- Interview: "single gateway key"
+- Production: uses `AI_GATEWAY_API_KEY`
+- Test: still checks `OPENAI_API_KEY` (wrong!)
+
+**Fix:** `verify-implementation.py` warns when test files check env vars that don't match interview requirements.
+
 ## 🔧 Requirements
 
 - **Node.js** 14.0.0 or higher
@@ -432,7 +475,7 @@ Required for `/pr` and `/issue` commands to work with GitHub MCP tools.
 export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
 ```
 
-The MCP configuration is written to `.mcp.json` in your project root and will be picked up by Claude Code on restart. First use will prompt for security approval.
+The installer runs `claude mcp add` commands directly, which registers the servers in your Claude Code config (`~/.claude.json`). Restart Claude Code after installation for MCP tools to be available.
 
 ## 📖 Documentation
 

package/bin/cli.js

@@ -234,40 +234,40 @@ function main() {
   }
 
   // ========================================
-  // 5. Install/Merge MCP Servers (Context7, GitHub)
+  // 5. Install MCP Servers via CLI (Context7, GitHub)
   // ========================================
-  // NOTE: Claude Code uses .mcp.json in project root, NOT .claude/mcp-servers.json
-  const mcpSource = path.join(sourceTemplatesDir, 'mcp-servers.json');
-  const mcpDest = path.join(targetDir, '.mcp.json');
+  // NOTE: We use `claude mcp add` directly because .mcp.json requires manual approval
+  // and doesn't auto-load. Using the CLI ensures servers are immediately available.
+  log('\n🔌 Configuring MCP servers:', 'cyan');
 
-  if (fs.existsSync(mcpSource)) {
-    log('\n🔌 Configuring MCP servers:', 'cyan');
+  const { execSync } = require('child_process');
 
+  const mcpServers = [
+    { name: 'context7', command: 'npx -y @upstash/context7-mcp', description: 'Live documentation from library source code' },
+    { name: 'github', command: 'npx -y @modelcontextprotocol/server-github', description: 'GitHub issues, PRs, and repository access' }
+  ];
+
+  for (const server of mcpServers) {
     try {
-      const newMcp = JSON.parse(fs.readFileSync(mcpSource, 'utf8'));
-
-      if (fs.existsSync(mcpDest)) {
-        // Merge with existing MCP config
-        const existingMcp = JSON.parse(fs.readFileSync(mcpDest, 'utf8'));
-        const mergedMcp = mergeMcpServers(existingMcp, newMcp);
-        fs.writeFileSync(mcpDest, JSON.stringify(mergedMcp, null, 2));
-        log('   ✅ Merged into existing .mcp.json', 'green');
-      } else {
-        // Create new MCP config file
-        fs.writeFileSync(mcpDest, JSON.stringify(newMcp, null, 2));
-        log('   ✅ Created .mcp.json in project root', 'green');
+      // Check if server already exists
+      const checkResult = execSync(`claude mcp get ${server.name} 2>&1`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+      if (checkResult.includes('Connected') || checkResult.includes('Scope:')) {
+        log(`   ✓ ${server.name} - already configured`, 'blue');
+      }
+    } catch (checkError) {
+      // Server doesn't exist, add it
+      try {
+        execSync(`claude mcp add ${server.name} -- ${server.command}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+        log(`   ✅ ${server.name} - ${server.description}`, 'green');
+      } catch (addError) {
+        log(`   ⚠️  ${server.name} - Could not add (run manually: claude mcp add ${server.name} -- ${server.command})`, 'yellow');
       }
-
-      log('\n   MCP servers configured:', 'blue');
-      log('   • context7 - Live documentation from library source code', 'blue');
-      log('   • github   - GitHub issues, PRs, and repository access', 'blue');
-      log('\n   ⚠️  GitHub MCP requires GITHUB_PERSONAL_ACCESS_TOKEN in env', 'yellow');
-      log('   ⚠️  First use will prompt for security approval', 'yellow');
-    } catch (error) {
-      log(`   ❌ Failed to configure MCP servers: ${error.message}`, 'red');
     }
   }
 
+  log('\n   ⚠️  GitHub MCP requires GITHUB_PERSONAL_ACCESS_TOKEN in env', 'yellow');
+  log('   💡 Restart Claude Code for MCP tools to be available', 'yellow');
+
   // ========================================
   // Success Summary
   // ========================================
@@ -280,7 +280,7 @@ function main() {
   log('   Hooks:     .claude/hooks/*.py', 'blue');
   log('   Settings:  .claude/settings.json', 'blue');
   log('   State:     .claude/api-dev-state.json', 'blue');
-  log('   MCP:       .mcp.json (Context7, GitHub)', 'blue');
+  log('   MCP:       context7, github (via claude mcp add)', 'blue');
 
   log('\n🔒 Enforcement Features:', 'bright');
   log('   • Research MUST happen before code writing', 'cyan');