@hustle-together/api-dev-tools 1.0.0

package/commands/add-command.md

@@ -0,0 +1,209 @@
+---
+description: Guide for creating new slash commands
+argument-hint: <command-name> <description>
+---
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+# Slash Command Creator Guide
+
+## How This Command Works
+
+The `/add-command` command shows this guide for creating new slash commands. It includes:
+
+- Command structure and syntax
+- Common patterns and examples
+- Security restrictions and limitations
+- Frontmatter options
+
+**Note for AI**: When creating commands, you CAN use bash tools like `Bash(mkdir:*)`, `Bash(ls:*)`, `Bash(git status:*)` in the `allowed-tools` frontmatter of NEW commands - but ONLY for operations within the current project directory. This command itself doesn't need bash tools since it's just documentation.
+
+## Command Locations
+
+- **Personal**: `~/.claude/commands/` (available across all projects)
+- **Project**: `.claude/commands/` (shared with team, shows "(project)")
+
+## Basic Structure
+
+```markdown
+---
+allowed-tools: Read, Glob, Grep, Bash(git status:*), Task
+description: Brief description of what this command does
+argument-hint: [required-arg] [optional-arg]
+---
+
+# Command Title
+
+Your command instructions here.
+
+Arguments: $ARGUMENTS
+
+File reference: @path/to/file.js
+
+Bash command output: (exclamation)git status(backticks)
+```
+
+## ⚠️ Security Restrictions
+
+**Bash Commands (exclamation prefix)**: Limited to current working directory only.
+
+- ✅ Works: `! + backtick + git status + backtick` (in project dir)
+- ❌ Blocked: `! + backtick + ls /outside/project + backtick` (outside project)  
+- ❌ Blocked: `! + backtick + pwd + backtick` (if referencing dirs outside project)
+
+**File References (`@` prefix)**: No directory restrictions.
+
+- ✅ Works: `@/path/to/system/file.md`
+- ✅ Works: `@../other-project/file.js`
+
+## Common Patterns
+
+### Simple Command
+
+```bash
+echo "Review this code for bugs and suggest fixes" > ~/.claude/commands/review.md
+```
+
+### Command with Arguments
+
+**Note for AI**: The example below uses a fullwidth dollar sign (＄, U+FF04) to prevent interpolation in this documentation. When creating actual commands, use the regular `$` character.
+
+```markdown
+Fix issue ＄ARGUMENTS following our coding standards
+```
+
+### Command with File References
+
+```markdown
+Compare @src/old.js with @src/new.js and explain differences
+```
+
+### Command with Bash Output (Project Directory Only)
+
+```markdown
+---
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*)
+---
+Current status: (!)git status(`)
+Current branch: (!)git branch --show-current(`)
+Recent commits: (!)git log --oneline -5(`)
+
+Create commit for these changes.
+```
+
+**Note**: Only works with commands in the current project directory.
+
+### Namespaced Command
+
+**Note for AI**: The example below uses a fullwidth dollar sign (＄, U+FF04) to prevent interpolation in this documentation. When creating actual commands, use the regular `$` character.
+
+```bash
+mkdir -p ~/.claude/commands/ai
+echo "Ask GPT-5 about: ＄ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
+# Creates: /ai:gpt5
+```
+
+## Frontmatter Options
+
+- `allowed-tools`: Tools this command can use
+  - **Important**: Intrusive tools like `Write`, `Edit`, `NotebookEdit` should NEVER be allowed in commands unless the user explicitly requests them. These tools modify files and should only be used when the command's purpose is to make changes.
+  - ✅ Safe for most commands: `Read`, `Glob`, `Grep`, `Bash(git status:*)`, `Task`, `AskUserQuestion`
+- `description`: Brief description (shows in /help)
+- `argument-hint`: Help text for arguments
+- `model`: Specific model to use
+
+## Best Practices
+
+### Safe Commands (No Security Issues)
+
+```markdown
+# System prompt editor (file reference only)  
+(@)path/to/system/prompt.md
+
+Edit your system prompt above.
+```
+
+### Project-Specific Commands (Bash OK)
+
+```markdown
+---
+allowed-tools: Bash(git status:*), Bash(npm list:*)
+---
+Current git status: (!)git status(`)
+Package info: (!)npm list --depth=0(`)
+
+Review project state and suggest next steps.
+```
+
+### Cross-Directory File Access (Use @ not !)
+
+```markdown
+# Compare config files
+Compare (@)path/to/system.md with (@)project/config.md
+
+Show differences and suggest improvements.
+```
+
+## Usage
+
+After creating: `/<command-name> [arguments]`
+
+Example: `/review` or `/ai:gpt5 "explain this code"`
+
+
+## 🛡 Project Rules (Injected into every command)
+
+1. **NO BROKEN BUILDS:**
+   - Run `pnpm test` before every `/commit`
+   - Ensure all tests pass
+   - Fix any type errors immediately
+
+2. **API DEVELOPMENT:**
+   - All new APIs MUST have Zod request/response schemas
+   - All APIs MUST be documented in both:
+     - OpenAPI spec ([src/lib/openapi/](src/lib/openapi/))
+     - API test manifest ([src/app/api-test/api-tests-manifest.json](src/app/api-test/api-tests-manifest.json))
+   - Test ALL parameters and edge cases
+   - Include code examples and real-world outputs
+
+3. **TDD WORKFLOW:**
+   - ALWAYS use /red → /green → /refactor cycle
+   - NEVER write implementation without failing test first
+   - Use /cycle for feature development
+   - Use characterization tests for refactoring
+
+4. **API KEY MANAGEMENT:**
+   - Support three loading methods:
+     - Server environment variables
+     - NEXT_PUBLIC_ variables (client-side)
+     - Custom headers (X-OpenAI-Key, X-Anthropic-Key, etc.)
+   - Never hardcode API keys
+   - Always validate key availability before use
+
+5. **COMPREHENSIVE TESTING:**
+   - When researching APIs, read actual implementation code
+   - Discover ALL possible parameters (not just documented ones)
+   - Test with various parameter combinations
+   - Document custom headers, query params, request/response schemas
+   - Include validation rules and testing notes
+
+6. **NO UI BLOAT:**
+   - This is an API project with minimal frontend
+   - Only keep necessary test/documentation interfaces
+   - Delete unused components immediately
+   - No unnecessary UI libraries or features
+
+7. **DOCUMENTATION:**
+   - If you change an API, you MUST update:
+     - OpenAPI spec
+     - api-tests-manifest.json
+     - Code examples
+     - Testing notes
+   - Document expected behavior and edge cases
+   - Include real-world output examples

package/commands/api-create.md

@@ -0,0 +1,166 @@
+# API Create - Comprehensive API Development Workflow
+
+**Usage:** `/api-create [endpoint-name]`
+
+**Purpose:** Orchestrates the complete API development workflow using interview-driven, test-first methodology.
+
+## Workflow Steps
+
+This command executes the following phases automatically:
+
+### Phase 1: Planning & Research
+1. **Documentation Discovery**
+   - Search for official API documentation
+   - Track all documentation links
+   - Identify available SDKs and libraries
+   - Document version requirements
+
+2. **User Interview** (Anthropic Interviewer methodology)
+   - What is this API endpoint for? (Purpose)
+   - Who will use it? (Users)
+   - When/where will it be used? (Context)
+   - What are common use cases? (Real-world scenarios)
+   - What are edge cases to handle? (Boundaries)
+   - What are dependencies? (External services, API keys)
+
+### Phase 2: Documentation & Schema
+3. **Schema Documentation**
+   - Document ALL request parameters (required + optional)
+   - Document ALL response fields
+   - Create Zod request schema
+   - Create Zod response schema
+   - Document validation rules
+   - Document error cases
+
+4. **Environment Setup**
+   - Identify required API keys
+   - Check .env.example for keys
+   - Verify environment variables
+   - Document custom header support
+   - Create setup instructions
+
+### Phase 3: TDD Implementation
+5. **Red Phase** - Write failing tests
+   - Test basic success case
+   - Test all parameter combinations
+   - Test validation failures
+   - Test error handling
+   - Test edge cases from interview
+   - Run tests (should fail)
+
+6. **Green Phase** - Minimal implementation
+   - Create route handler
+   - Implement Zod validation
+   - Add AI SDK integration
+   - Pass all tests
+   - Run tests (should pass)
+
+7. **Refactor Phase** - Clean up
+   - Extract reusable patterns
+   - Improve error messages
+   - Add JSDoc comments
+   - Optimize performance
+   - Run tests (should still pass)
+
+### Phase 4: Documentation & Integration
+8. **Update Documentation**
+   - Add to `/src/app/api-test/api-tests-manifest.json`
+   - Update `/src/v2/docs/v2-api-implementation-status.md`
+   - Add OpenAPI spec to `/src/lib/openapi/`
+   - Include code examples
+   - Document real-world outputs
+   - Add testing notes
+
+9. **Final Validation**
+   - Run full test suite
+   - Check test coverage (must be 100%)
+   - Verify TypeScript compilation
+   - Test in API test interface
+   - Create commit with `/commit`
+
+## Template for Interview
+
+When executing this command, conduct the following interview:
+
+```
+## API Endpoint: [endpoint-name]
+
+### 1. Purpose & Context
+- **What problem does this solve?**
+- **Who are the primary users?**
+- **What triggers usage of this API?**
+
+### 2. Real-World Usage
+- **Describe a typical request scenario:**
+- **What are the most common parameters?**
+- **What does a successful response look like?**
+
+### 3. Parameters & Configuration
+- **What parameters are REQUIRED?**
+- **What parameters are OPTIONAL?**
+- **What are valid value ranges/formats?**
+- **Are there parameter dependencies?**
+
+### 4. Dependencies & Integration
+- **What external services does this use?**
+- **What API keys are required?**
+- **What AI models/providers are involved?**
+- **Are there rate limits or quotas?**
+
+### 5. Edge Cases & Errors
+- **What can go wrong?**
+- **How should errors be handled?**
+- **What are boundary conditions?**
+- **What should be validated?**
+
+### 6. Documentation Sources
+- **Official documentation links:**
+- **SDK/library documentation:**
+- **Related endpoints or examples:**
+```
+
+## Output Artifacts
+
+This command creates:
+
+1. **Interview Document**: `/src/v2/docs/endpoints/[endpoint-name].md`
+2. **Route Handler**: `/src/app/api/v2/[endpoint-name]/route.ts`
+3. **Test Suite**: `/src/app/api/v2/[endpoint-name]/__tests__/[endpoint-name].api.test.ts`
+4. **OpenAPI Spec**: `/src/lib/openapi/endpoints/[endpoint-name].ts`
+5. **Updated Manifests**:
+   - `/src/app/api-test/api-tests-manifest.json`
+   - `/src/v2/docs/v2-api-implementation-status.md`
+
+## Execution
+
+Execute this command and I will:
+1. ✅ Start the interview to understand the endpoint
+2. ✅ Research and document all available options
+3. ✅ Create comprehensive Zod schemas
+4. ✅ Verify environment/API key requirements
+5. ✅ Write failing tests first (TDD Red)
+6. ✅ Implement minimal passing code (TDD Green)
+7. ✅ Refactor for quality (TDD Refactor)
+8. ✅ Update all documentation and manifests
+9. ✅ Verify 100% test coverage
+10. ✅ Create semantic commit
+
+<claude-commands-template>
+## Project-Specific Rules
+
+1. **API Location**: All V2 APIs go in `/src/app/api/v2/[endpoint-name]/`
+2. **Testing**: Use Vitest, require 100% coverage
+3. **Validation**: All requests/responses use Zod schemas
+4. **AI SDK**: Use Vercel AI SDK 5.0.11 patterns from `/src/v2/docs/ai-sdk-catalog.json`
+5. **Package Manager**: Use `pnpm` for all operations
+6. **Documentation**: Follow patterns in `/src/v2/docs/Main Doc – V2 Development Patterns.md`
+7. **API Keys**: Support three methods (env, NEXT_PUBLIC_, custom headers)
+8. **Test Command**: `pnpm test:run` before commits
+
+## Never Skip
+- Interview phase (understand before coding)
+- Documentation research (find ALL parameters)
+- Failing tests first (TDD Red is mandatory)
+- Manifest updates (keep docs in sync)
+- Coverage verification (100% required)
+</claude-commands-template>

package/commands/api-env.md

@@ -0,0 +1,50 @@
+# API Environment - Check API Keys & Configuration
+
+**Usage:** `/api-env [endpoint-name]`
+
+**Purpose:** Quick check for required API keys and environment setup before implementation.
+
+## What This Checks
+
+1. **Reads endpoint documentation** to identify required services
+2. **Checks .env.local** for API keys
+3. **Verifies .env.example** has templates
+4. **Reports missing keys** with setup instructions
+
+## Output
+
+```
+🔑 Environment Check: [endpoint-name]
+
+Required API Keys:
+✅ OPENAI_API_KEY (found)
+❌ FIRECRAWL_API_KEY (missing)
+
+Action Required:
+1. Get key from https://firecrawl.dev
+2. Add to .env.local: FIRECRAWL_API_KEY=fc-...
+3. Add to .env.example template
+
+Status: BLOCKED - Cannot proceed without FIRECRAWL_API_KEY
+```
+
+## Usage in Workflow
+
+```bash
+# Before starting implementation
+/api-interview generate-css
+/api-research firecrawl
+/api-env generate-css  ← Check keys
+/red                   ← Start TDD if ready
+```
+
+<claude-commands-template>
+## API Key Support
+
+The project supports three methods:
+1. Server env: `OPENAI_API_KEY=sk-...`
+2. Client env: `NEXT_PUBLIC_OPENAI_API_KEY=sk-...`
+3. Custom headers: `X-OpenAI-Key: sk-...`
+
+Check src/lib/api-keys.ts for implementation.
+</claude-commands-template>

package/commands/api-interview.md

@@ -0,0 +1,211 @@
+# API Interview - Structured API Discovery
+
+**Usage:** `/api-interview [endpoint-name]`
+
+**Purpose:** Conduct structured interview to understand API endpoint purpose, usage, and requirements before any implementation.
+
+## Interview Methodology
+
+Based on Anthropic Interviewer approach with three phases:
+
+### Phase 1: Planning (Internal)
+- Review endpoint name and context
+- Identify key areas to explore
+- Prepare follow-up questions
+
+### Phase 2: Interviewing (User Interaction)
+Ask structured questions to understand:
+
+#### 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?
+
+### Phase 3: Analysis (Documentation)
+After interview, I will:
+- Synthesize answers into structured document
+- Identify gaps or ambiguities
+- Create preliminary schema based on answers
+- Document all external links and resources
+- Outline test cases from real-world scenarios
+
+## Output
+
+Creates: `/src/v2/docs/endpoints/[endpoint-name].md`
+
+**Document Structure:**
+```markdown
+# API Endpoint: [endpoint-name]
+
+**Date:** [current-date]
+**Interviewed by:** Claude Code
+**Status:** Interview Complete
+
+## 1. Purpose & Context
+[Synthesized understanding of why this exists]
+
+## 2. Users & Usage Patterns
+[Who uses it and how]
+
+## 3. Request Schema (Preliminary)
+[Zod-style schema based on interview]
+
+## 4. Response Schema (Preliminary)
+[Expected response structure]
+
+## 5. Dependencies
+- External Services: [list]
+- API Keys Required: [list]
+- AI Models: [list]
+
+## 6. Real-World Scenarios
+### Scenario 1: [Common Use Case]
+**Request:**
+```json
+{example}
+```
+**Response:**
+```json
+{example}
+```
+
+## 7. Edge Cases & Error Handling
+[Identified edge cases and how to handle them]
+
+## 8. Validation Rules
+[What must be validated]
+
+## 9. Documentation Links
+- [Official docs]
+- [SDK docs]
+- [Related resources]
+
+## 10. Test Cases (To Implement)
+- [ ] Test: [scenario from interview]
+- [ ] Test: [edge case from interview]
+- [ ] Test: [error handling from interview]
+
+## 11. Open Questions
+[Any ambiguities to resolve]
+```
+
+## Usage Example
+
+```bash
+/api-interview generate-css
+```
+
+I will then ask all 20 questions, document responses, and create the endpoint documentation file ready for TDD implementation.
+
+<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
+
+## After Interview
+
+- Read interview document before implementing
+- Refer to it during TDD cycles
+- Update it if requirements change
+- Use it for code review context
+</claude-commands-template>