@hustle-together/api-dev-tools 3.10.1 → 3.12.1

package/.claude/agents/test-writer.md

@@ -0,0 +1,104 @@
+---
+name: test-writer
+description: Test case generator from schemas and interview decisions. Use during Phase 8 (TDD Red) to create comprehensive failing tests before implementation.
+tools: Read, Write, Grep, Glob
+model: sonnet
+---
+
+# Test Writer Agent
+
+You are a TDD specialist that writes comprehensive, failing tests based on schemas and interview decisions.
+
+## Your Role
+
+1. **Analyze schemas** - Understand request/response structure
+2. **Apply interview decisions** - Test user-specified behaviors
+3. **Write failing tests** - Tests that define expected behavior
+4. **Cover edge cases** - Error handling, validation, edge cases
+
+## Input Format
+
+You will receive:
+
+- Zod schemas for request/response
+- Interview decisions (error handling, formats, etc.)
+- Target test file path
+- Endpoint path and method
+
+## Output Format
+
+Generate comprehensive test file:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest } from "next/server";
+import { POST } from "../route";
+
+describe("[Endpoint] API", () => {
+  describe("POST /api/v2/[endpoint]", () => {
+    // Happy path tests
+    it("should return data with valid request", async () => {
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({
+          /* valid data */
+        }),
+      });
+
+      const response = await POST(request);
+      const data = await response.json();
+
+      expect(response.status).toBe(200);
+      expect(data).toHaveProperty("result");
+    });
+
+    // Validation tests
+    it("should return 400 for missing required fields", async () => {
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({}),
+      });
+
+      const response = await POST(request);
+      expect(response.status).toBe(400);
+    });
+
+    // Error handling tests (from interview)
+    it("should handle API errors gracefully", async () => {
+      // Mock external API failure
+      vi.spyOn(global, "fetch").mockRejectedValueOnce(new Error("API down"));
+
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({
+          /* valid data */
+        }),
+      });
+
+      const response = await POST(request);
+      expect(response.status).toBe(500);
+    });
+
+    // Format tests (from interview)
+    it("should return requested format", async () => {
+      // Test based on interview format decisions
+    });
+  });
+});
+```
+
+## Test Categories
+
+1. **Happy Path** - Valid requests return expected data
+2. **Validation** - Invalid input returns 400 with helpful message
+3. **Error Handling** - API failures handled per interview decisions
+4. **Authentication** - API key handling
+5. **Edge Cases** - Empty data, nulls, large payloads
+
+## Guidelines
+
+1. **Tests MUST fail initially** - Implementation doesn't exist yet
+2. **One assertion per test** - Clear failure messages
+3. **Use interview decisions** - Error strategy, formats, etc.
+4. **Mock external APIs** - Don't make real API calls in tests
+5. **Cover 100%** - Every schema field should be tested

package/.claude/api-dev-state.json

@@ -0,0 +1,331 @@
+{
+  "version": "3.12.0",
+  "created_at": null,
+  "endpoint": null,
+  "library": null,
+  "session_id": null,
+  "turn_count": 0,
+  "last_turn_timestamp": null,
+  "research_queries": [],
+  "prompt_detections": [
+    {
+      "timestamp": "2025-12-27T15:58:25.936482",
+      "prompt_preview": "can you push 3.2.0 to npm please",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "3.2.0"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T16:07:06.370872",
+      "prompt_preview": "3.11.1",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "3.11.1"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T17:51:34.506745",
+      "prompt_preview": "npm notice 10.7kB templates/ui-showcase/_components/PreviewCard.tsx\nnpm notice 23.3kB templates/ui-s...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "install from a",
+          "error",
+          "api",
+          "package",
+          "url",
+          "token",
+          "install",
+          "@hustle-together/api-dev-tools",
+          "hustle-together-api",
+          "3.11.1"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:31:26.336088",
+      "prompt_preview": "1. CREATE PR\n   - Go to GitHub: https://github.com/hustle-together/api-dev-tools\n   - Create PR from...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "create pr",
+          "update version (i can do this for you now)",
+          "api",
+          "package",
+          "test",
+          "publish",
+          "@hustle-together/api-dev-tools",
+          "1.0.0",
+          "3.12.0",
+          "package.json"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "question_pattern",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:32:03.480897",
+      "prompt_preview": "File    Purpose\nworkflow-demo.html (247KB)    Main interactive workflow demo\nexecution-trace-COMPREH...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "write integration demo",
+          "api",
+          "interview-driven-api"
+        ],
+        "patterns_matched": [
+          "question_pattern",
+          "always_research",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:35:36.217406",
+      "prompt_preview": "> File    Purpose\nworkflow-demo.html (247KB)    Main interactive workflow demo\nexecution-trace-COMPR...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "write integration demo",
+          "api",
+          "view",
+          "interview-driven-api"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "question_pattern",
+          "always_research"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:36:41.163781",
+      "prompt_preview": "how do i merge it i am on the comment page ",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "how do"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:40:21.674198",
+      "prompt_preview": "ok i did it check the main now please",
+      "detection": {
+        "detected": false,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "none"
+      },
+      "injected": false
+    },
+    {
+      "timestamp": "2025-12-27T22:43:21.172124",
+      "prompt_preview": "wait was the github master updated witht he most current push?",
+      "detection": {
+        "detected": true,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "low"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:45:59.739199",
+      "prompt_preview": "ok now update the npm package, make a skill for this as well based on my api-dev-tools and mcp if th...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "update the npm package, make a skill for this as w",
+          "package",
+          "api"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:49:36.519292",
+      "prompt_preview": "/Users/alfonso/Documents/GitHub/api-dev-tools/demo/hustle-together/workflow-demo-backup-20251212-134...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "api",
+          "0.0.1"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:52:43.366799",
+      "prompt_preview": "help me use that publish skill how do i get that code?",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "how do",
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "always_research",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:53:54.327491",
+      "prompt_preview": "id rather use the terminal command to open the pafge",
+      "detection": {
+        "detected": true,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "low"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:58:35.375132",
+      "prompt_preview": "No no, I use a secret key, so you just open my page for me, and I just gave it access by using my se...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "secret",
+          "key"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:59:14.000695",
+      "prompt_preview": "No, that's dumb. Normally you just give me some commands that I run in terminal and they just work.N...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:59:56.192298",
+      "prompt_preview": "  npm login run that and i will tap the security code access then you can run the publish command",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    }
+  ],
+  "phases": {
+    "disambiguation": {
+      "status": "not_started"
+    },
+    "scope": {
+      "status": "not_started"
+    },
+    "research_initial": {
+      "status": "not_started"
+    },
+    "interview": {
+      "status": "not_started"
+    },
+    "research_deep": {
+      "status": "not_started"
+    },
+    "schema_creation": {
+      "status": "not_started"
+    },
+    "environment_check": {
+      "status": "not_started"
+    },
+    "tdd_red": {
+      "status": "not_started"
+    },
+    "tdd_green": {
+      "status": "not_started"
+    },
+    "verify": {
+      "status": "not_started"
+    },
+    "tdd_refactor": {
+      "status": "not_started"
+    },
+    "documentation": {
+      "status": "not_started"
+    }
+  },
+  "verification": {
+    "all_sources_fetched": false,
+    "schema_matches_docs": false,
+    "tests_cover_params": false,
+    "all_tests_passing": false,
+    "coverage_percent": null,
+    "post_green_verification": false
+  },
+  "research_index": {},
+  "reground_history": []
+}

package/.claude/commands/README.md

@@ -0,0 +1,196 @@
+# API Development Slash Commands v3.0
+
+**Interview-driven, research-first API development workflow with continuous verification loops**
+
+## What's New in v3.0
+
+- **Phase 1: Disambiguation** - Search variations before research
+- **Phase 10: Verify** - Re-research after tests pass to catch memory errors
+- **Adaptive Research** - Propose searches based on context, not shotgun
+- **Questions FROM Research** - Interview generates questions from discovered params
+- **7-Turn Re-grounding** - Periodic context injection prevents dilution
+- **Research Freshness** - 7-day cache with staleness warnings
+
+## Hook Architecture (9 Hooks)
+
+| Hook                           | Event            | Purpose                            |
+| ------------------------------ | ---------------- | ---------------------------------- |
+| `session-startup.py`           | SessionStart     | Inject state at session start      |
+| `enforce-external-research.py` | UserPromptSubmit | Detect API terms, require research |
+| `enforce-research.py`          | PreToolUse       | Block writes until research done   |
+| `enforce-interview.py`         | PreToolUse       | Inject interview decisions         |
+| `verify-implementation.py`     | PreToolUse       | Require test file before route     |
+| `track-tool-use.py`            | PostToolUse      | Log research, count turns          |
+| `periodic-reground.py`         | PostToolUse      | Re-ground every 7 turns            |
+| `verify-after-green.py`        | PostToolUse      | Trigger Phase 10 after test pass   |
+| `api-workflow-check.py`        | Stop             | Block if phases incomplete         |
+
+## Available Commands
+
+### Complete Workflow
+
+**`/api-create [endpoint-name]`**
+
+- Runs all 13 phases automatically
+- Loop-back architecture at every checkpoint
+- See [api-create.md](api-create.md) for full flow
+
+### Individual Phases
+
+**`/api-interview [endpoint-name]`**
+
+- Questions GENERATED from research findings
+- Different question types: enum, continuous, boolean
+- See [api-interview.md](api-interview.md)
+
+**`/api-research [library-or-service]`**
+
+- Adaptive propose-approve flow (not shotgun)
+- Research cached with 7-day freshness
+- See [api-research.md](api-research.md)
+
+**`/api-verify [endpoint-name]`** (NEW)
+
+- Manual Phase 10 verification
+- Re-read docs, compare to implementation
+- Report gaps, loop back or document omissions
+- See [api-verify.md](api-verify.md)
+
+**`/api-env [endpoint-name]`**
+
+- Check API keys and environment
+- See [api-env.md](api-env.md)
+
+**`/api-status [endpoint-name]`**
+
+- Track progress through 13 phases
+- See [api-status.md](api-status.md)
+
+### TDD Commands
+
+From [@wbern/claude-instructions](https://github.com/wbern/claude-instructions):
+
+- `/red` - Write ONE failing test
+- `/green` - Minimal implementation to pass
+- `/refactor` - Clean up while tests pass
+- `/cycle [description]` - Full Red → Green → Refactor
+
+## 13-Phase Flow
+
+```
+Phase 1:  DISAMBIGUATION     - Clarify ambiguous terms
+Phase 2:  SCOPE              - Confirm understanding
+Phase 3:  INITIAL RESEARCH   - 2-3 targeted searches
+Phase 4:  INTERVIEW          - Questions FROM research
+Phase 5:  DEEP RESEARCH      - Adaptive propose-approve
+Phase 6:  SCHEMA             - Zod from research + interview
+Phase 7:  ENVIRONMENT        - Verify API keys
+Phase 8:  TDD RED            - Write failing tests
+Phase 9:  TDD GREEN          - Minimal implementation
+Phase 10: VERIFY             - Re-research, find gaps
+Phase 11: TDD REFACTOR       - Clean up code
+Phase 12: DOCUMENTATION      - Update manifests
+Phase 13: COMPLETION         - Final verification
+```
+
+## State File
+
+All progress tracked in `.claude/api-dev-state.json`:
+
+```json
+{
+  "version": "3.0.0",
+  "endpoint": "brandfetch",
+  "turn_count": 23,
+  "phases": {
+    "disambiguation": { "status": "complete" },
+    "scope": { "status": "complete" },
+    "research_initial": { "status": "complete" },
+    "interview": { "status": "complete", "decisions": {...} },
+    "research_deep": {
+      "proposed_searches": [...],
+      "approved_searches": [...],
+      "skipped_searches": [...]
+    },
+    "verify": {
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": [...]
+    }
+  },
+  "reground_history": [...]
+}
+```
+
+## Research Cache
+
+Research cached in `.claude/research/`:
+
+```
+.claude/research/
+├── brandfetch/
+│   ├── 2025-12-08_initial.md
+│   ├── 2025-12-08_deep.md
+│   └── CURRENT.md
+└── index.json  ← Freshness tracking (7-day validity)
+```
+
+## Quick Start
+
+### Automated
+
+```bash
+/api-create my-endpoint
+```
+
+### Manual Step-by-Step
+
+```bash
+/api-research [library]      # Initial research
+/api-interview [endpoint]    # Questions from research
+/api-env [endpoint]          # Verify environment
+/red                         # Failing tests
+/green                       # Make tests pass
+/api-verify [endpoint]       # Compare to docs
+/refactor                    # Clean up
+/commit                      # Semantic commit
+```
+
+## Installation
+
+```bash
+npx @hustle-together/api-dev-tools --scope=project
+```
+
+Installs:
+
+- Commands in `.claude/commands/`
+- Hooks in `.claude/hooks/`
+- Settings in `.claude/settings.json`
+- State template in `.claude/api-dev-state.json`
+- Research index in `.claude/research/index.json`
+
+### Team-Wide
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx @hustle-together/api-dev-tools --scope=project"
+  }
+}
+```
+
+## Key Principles
+
+1. **Loop Until Green** - Every verification loops back if not successful
+2. **Continuous Interviews** - Checkpoints at EVERY phase transition
+3. **Adaptive Research** - Propose based on context, not shotgun
+4. **Self-Documenting** - State file captures everything
+5. **Verify After Green** - Re-research to catch memory errors
+
+---
+
+**Version:** 3.0.0
+**Last Updated:** 2025-12-08