Choose Narrator Voice
Adam
Deep, professional (~6 min)
Mark
Warm, conversational (~5.5 min)
Hope
Bright, energetic (~5 min)
Creature
Unique, character voice (~7.5 min)
Gaming
Dynamic, enthusiastic (~10.5 min)
0:00 0:00
HUSTLE API-DEV-TOOLS
@hustle-together/api-dev-tools
v2.0.8

"Hustle together. Share resources. Build stronger."

Enforced workflows for AI-assisted API development. Research first. Interview second. No shortcuts.

R Research
→
? Interview
→
T Test
→
C Code
→
D Docs
[ SCROLL TO BEGIN ]

## THE PROBLEM

### LLMs Make Their Own Decisions

Why This Matters

LLMs are powerful but ungrounded. Without structure, they default to training data, make assumptions, and forget context. These are the 3 critical gaps that compound:

- 🔍
  Gap 01
  AI Doesn't Use Your Exact Words
  You say one thing, but the AI searches for something different. Wrong library. Wrong documentation.
  You: "Use Brandfetch API"
  AI searches: "brand fetch library" (wrong!)
  Solution: Phase 0 disambiguation before research
- 🧠
  Gap 02
  Memory-Based Implementation
  After research, the AI forgets what it learned and implements from training data instead.
  AI researches Brandfetch v2 API, then implements v1 patterns from memory.
  Solution: Phase 9 verification re-reads docs after implementation
- 💨
  Gap 03
  Context Dilution
  After many turns, the AI forgets project structure, documentation locations, and your decisions.
  Turn 50: "What API key should I use?" (you already told it 40 turns ago)
  Solution: Re-grounding every 7 turns via hooks

## THE SOLUTION

### Programmatic Enforcement

How We Fix This

Instead of just asking the AI to follow a process (which it might ignore), we use Python hooks that intercept every action and enforce rules.

Think of it like guardrails on a highway. The AI can still drive, but it literally cannot skip important steps - the system blocks it.

📚
Research First
AI must search for live documentation before writing any code. No more outdated training data.
💬
Interview Required
AI must ask YOU questions and wait for answers. No more assumptions about what you want.
✅
Verification Built-In
System checks implementation matches interview. Warns about mismatches before completing.

## HOW IT WORKS

### The Hook System

What Are Hooks?

Hooks are small Python scripts that run automatically whenever the AI tries to do something. They check conditions and can either allow or block the action.

There are 3 types: PreToolUse (before an action), PostToolUse (after an action), and Stop (when trying to finish).

YOU: "Build me an AI chat API"
|
AI: Tries to write code
|

#### PreToolUse Hooks (Before Writing Code)

`enforce-research.py` Must research first
`enforce-interview.py` Must ask user questions
`verify-implementation.py` Check term matching

#### PostToolUse Hooks (After Actions)

`track-tool-use.py` Log all research activity

#### Stop Hook (When Finishing)

`api-workflow-check.py` Verify all phases done + git diff
|
[ ALLOWED ]
All checks pass
[ BLOCKED ]
Missing requirements

## THE WORKFLOW

### 12 Enforced Phases (v3.0)

The Complete Process

Every API goes through these 12 phases. The system tracks progress and won't let the AI skip ahead. Phase 0 (Disambiguation) and Phase 9 (Verify) are new in v3.0!

00
Disambiguate
Clarify ambiguous terms
→
01
Scope
Define what we're building
→
02
Research
Find live documentation
→
03
Interview
Questions FROM research
→
04
Deep Research
Adaptive, not shotgun
→
05
Schema
Define request/response
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
06
Environment
Check API keys exist
→
07
TDD Red
Write failing tests
→
08
TDD Green
Make tests pass
→
09
Verify
Re-research, find gaps
→
10
Refactor
Clean up the code
→
11
Documentation
Update all docs
→
12
Complete
Final verification

## LIVE SIMULATION

### 12-Phase Workflow (v3.0)

The Complete v3.0 Flow

Watch the full /api-create brandfetch command in action. The side panel explains each step as it happens. Notice the AI/User conversation format and how research findings drive the interview questions.

~/my-project
CLAUDE CODE

    ╭─────────────────────────────────────────────────────────────────────────────╮
    │                             │ Tips for getting started                   │
    │   Welcome back, Developer!  │ Run /init to create a CLAUDE.md file...    │
    │                             │ Try /api-create to start a new endpoint    │
    │         ▗ ▗   ▖ ▖           │ ────────────────────────────────────────    │
    │                             │ Recent activity                            │
    │           ▘▘ ▝▝             │   api/v2/search - completed                │
    │                             │   api/v2/analyze - 8 tests passing         │
    │   Opus 4.5 · Claude Max    │                                            │
    │      ~/my-project          │                                            │
    ╰─────────────────────────────────────────────────────────────────────────────╯

❯
👤 USER
`/api-create brandfetch`
🤖 CLAUDE
I understand you want to create an API endpoint for Brandfetch - a service for fetching brand assets (logos, colors, fonts) by domain.
Is this correct? ✓ Yes
🤖 CLAUDE
Starting research... I need to find the real documentation before asking questions.
mcp__context7__get-library-docs
"brandfetch" → Found SDK docs, /v2/brands endpoint, auth method
WebSearch
"Brandfetch API rate limits 2025" → 5 req/second
👤 USER
↩ LOOP BACK Can you also check what error responses look like?
🤖 CLAUDE
Good catch! Researching error handling...
WebSearch
"Brandfetch API error codes" → 401, 404, 429 with JSON error format
🤖 CLAUDE
Based on my research, I found these capabilities. Question 1/5: What's the primary purpose?
Brand lookup by domain
Logo extraction only
Full brand kit (logos, colors, fonts)
👤 USER
Selected: Full brand kit (logos, colors, fonts)
🤖 CLAUDE
Question 2/5: How should API keys be handled?
Server environment variables only
Custom header override (X-Brandfetch-Key)
Both methods
👤 USER
Selected: Server environment variables only
🤖 CLAUDE
Question 3/5: What caching strategy should we use?
No caching
Short cache (5 minutes)
Long cache (24 hours) - brands rarely change
👤 USER
Selected: Long cache (24 hours)
🤖 CLAUDE
Question 4/5: How should we handle errors?
Throw exceptions (let caller handle)
Return error objects with status codes
Fallback to empty brand object
👤 USER
Selected: Return error objects with status codes
🤖 CLAUDE
Question 5/5: Should we expose rate limit headers?
No - handle internally
Yes - X-RateLimit-Remaining, X-RateLimit-Reset
👤 USER
Selected: Yes - expose rate limit headers
🤖 CLAUDE
Based on your selections, I'll research more specifically:
WebSearch
"Brandfetch full brand response format" → JSON with logos[], colors[], fonts[]
WebSearch
"Brandfetch rate limit headers" → X-RateLimit-Limit, X-RateLimit-Remaining
🤖 CLAUDE
Creating Zod schema based on research + interview decisions...
Write
src/lib/schemas/brandfetch.ts → BrandRequestSchema, BrandResponseSchema, BrandErrorSchema
⚙️ HOOK
check-env.py: Checking required environment variables...
✓ BRANDFETCH_API_KEY found in .env.local
🤖 CLAUDE
Writing failing tests first (TDD Red)...
Write
src/lib/__tests__/brandfetch.test.ts (15 test cases)
Tests cover: full brand kit, caching, error objects, rate limit headers
🤖 CLAUDE
Implementing to pass tests...
Write
src/app/api/v2/brandfetch/route.ts
⚙️ HOOK
enforce-interview.py: REMEMBER USER DECISIONS:
• Purpose: full_brand_kit
• API Key Handling: server_only
• Caching: 24_hours
• Error Handling: return_error_objects
• Rate Limits: expose_headers
🤖 CLAUDE
✓ All 15 tests passing!
🤖 CLAUDE
Re-reading docs to verify implementation matches...
mcp__context7__get-library-docs
"brandfetch" → Comparing implementation to docs...
⚠️ GAP DETECTED
Missing `include_fonts` query parameter documented in v2 API
🔄 HOOK
↩ LOOP BACK TO PHASE 7 verify-implementation.py: Gap found! Returning to TDD Red phase to add missing test...
🤖 CLAUDE
Adding test for include_fonts parameter...
Edit
src/lib/__tests__/brandfetch.test.ts → Added test case #16
🤖 CLAUDE
Updating implementation for include_fonts...
Edit
src/app/api/v2/brandfetch/route.ts → Added include_fonts query param
✓ All 16 tests passing!
🤖 CLAUDE
Re-verifying implementation...
mcp__context7__get-library-docs
"brandfetch" → All documented features now implemented
✓ Verification complete - no gaps remaining
🤖 CLAUDE
Refactoring code (tests still pass)...
Edit
Extracted caching logic to utils, improved type safety
✓ 16/16 tests passing
🤖 CLAUDE
Updating documentation...
Write
api-tests-manifest.json → Added /api/v2/brandfetch entry
Edit
openapi.yaml → Added brandfetch endpoint schema
Write
.claude/research/brandfetch/ → Cached research for future sessions
✅ COMPLETE
All 12 phases complete! Brandfetch API ready.
📁 Files created: 5
✅ Tests passing: 16/16
🔄 Loop-backs: 2
📋 Interview decisions: 5
Phase Explanation
0
User Command
The user triggers the full 12-phase workflow with a single command.
This starts the entire interview-driven development process.
1
Scope Confirmation
Claude confirms understanding of what we're building before doing anything.
Prevents building the wrong thing. Loop back if unclear.
2
Initial Research
Claude researches REAL documentation using Context7 and WebSearch. No training data assumptions!
Questions will be generated FROM these findings - not generic templates.
3
Interview
Claude asks structured questions with options derived from research. User selects, answers tracked.
Every decision is recorded and injected during implementation.
4
Deep Research
Based on interview answers, Claude proposes targeted follow-up searches.
Adaptive research - not shotgun. Only what's relevant to YOUR choices.
5
Schema Design
Zod schemas created based on research + interview decisions.
Types before code. Schema drives tests and implementation.
6
Environment
Verify API keys exist and are configured correctly.
Catches config issues BEFORE writing code.
7
TDD Red
Write failing tests first. Define success BEFORE implementation.
No implementation until tests exist. Enforced by hooks.
8
TDD Green
Write minimal code to pass tests. Interview decisions injected by hook!
Hook reminds Claude of YOUR decisions on every write.
9
Verify
Re-read original docs, compare to implementation. Find gaps!
Catches memory-based errors. Loops back if gaps found.
10
Refactor
Clean up code while tests stay green.
Safe improvements - tests prove nothing broke.
11
Documentation
Update OpenAPI spec, test manifest, research cache.
No "complete" without docs. Stop hook enforces this.
12
Completion
All phases verified. API is ready for use!
api-workflow-check.py blocks completion if anything incomplete.

## TRACKING PROGRESS

### The State File

Why This Matters

All progress is saved to `.claude/api-dev-state.json`. This solves three critical problems:

🎯 Re-Grounding

Hooks inject your decisions into every file write, preventing the AI from "forgetting" what you asked for.

💾 Session Persistence

Come back tomorrow and pick up where you left off. The state file remembers research, interview answers, and progress.

🔄 Loop-Back Tracking

When verification finds gaps, we know exactly which phase to return to. No lost context.

{
"endpoint": "brandfetch",
"phases": {
"research_initial": {
"status": "complete",
"sources": ["context7", "websearch", "websearch"]
},
"interview": {
"status": "complete",
"user_question_count": 6,
"structured_question_count": 5, // Questions with options
"decisions": { // YOUR CHOICES - INJECTED ON WRITES
"purpose": {"value": "full_kit"},
"api_key_handling": {"value": "server_only"},
"response_format": {"value": "json"},
"error_handling": {"value": "detailed"}
},
"questions": [
{"tool_used": true, "has_options": true, "user_response": "full_kit"},
// ... more questions tracked
]
},
"tdd_red": { "status": "complete" },
"tdd_green": { "status": "complete" }
},
"files_created": [
"src/lib/schemas/brandfetch.ts",
"src/app/api/v2/brandfetch/route.ts",
"src/v2/docs/endpoints/brandfetch.md"
]
}

## GET STARTED

### One Command Installation

Easy Setup

Run a single command to install everything. The installer copies slash commands, Python hooks, and configures the system automatically. Works with any project.

`npx @hustle-together/api-dev-tools --scope=project`
📝
21 Slash Commands
/api-create, /api-interview, /red, /green, /refactor...
→
.claude/commands/
🐍
5 Python Hooks
enforce-research, enforce-interview, verify-implementation...
→
.claude/hooks/
⚙️
Settings Configuration
Hook registration, permissions, matchers
→
.claude/settings.json
🔌
MCP Servers
Context7 (live docs), GitHub (issues/PRs)
→
claude mcp add

## START BUILDING BETTER APIs

What You Get
Structured workflow - No more skipped steps or assumptions
Real enforcement - Hooks that actually block bad behavior
Audit trail - Every action logged to state file
Gap detection - Catches mismatches between requirements and code
TDD built-in - Tests written before implementation
VIEW ON GITHUB
INSTALL FROM NPM

Built on the shoulders of giants:

@wbern/claude-instructions C7 Context7

Made for developers who want AI assistants
that actually follow instructions.

v3.0.0 | MIT License
"Interview first, test first, document always"