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

package/.skills/api-verify/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: api-verify
+description: Manual Phase 10 verification - re-research documentation after tests pass to catch memory-based implementation errors. Compares implementation to docs, reports gaps. Use after TDD Green phase. Keywords: verification, testing, documentation, gaps, quality
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "testing"
+  tags: ['verification', 'testing', 'documentation', 'quality']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+# API Verify - Implementation Verification (Phase 10) v3.0
+
+**Usage:** `/api-verify [endpoint-name]`
+
+**Purpose:** Manually trigger Phase 10 verification - re-research documentation and compare to implementation to catch memory-based errors.
+
+## When to Use
+
+- After tests pass (TDD Green complete)
+- Before proceeding to Refactor phase
+- When unsure if implementation matches documentation
+- After significant time has passed since initial research
+
+## Verification Process
+
+### Step 1: Re-Read Original Documentation
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ RE-RESEARCHING DOCUMENTATION                               │
+│                                                            │
+│ Fetching current documentation for: [endpoint-name]        │
+│                                                            │
+│ Sources:                                                   │
+│ - Context7: [library-name]                                 │
+│ - Official docs: [URL]                                     │
+│ - Cached research: .claude/research/[api]/CURRENT.md       │
+│                                                            │
+│ Freshness: [X days old]                                    │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 2: Feature-by-Feature Comparison
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ IMPLEMENTATION VERIFICATION                                │
+│                                                            │
+│ Comparing documentation to implementation:                 │
+│                                                            │
+│ │ Feature         │ In Docs │ Implemented │ Status        │
+│ ├─────────────────┼─────────┼─────────────┼───────────────│
+│ │ domain param    │ ✓       │ ✓           │ ✅ Match      │
+│ │ format param    │ 4 opts  │ 3 opts      │ ⚠️ Missing    │
+│ │ quality range   │ 1-100   │ 1-100       │ ✅ Match      │
+│ │ size param      │ ✓       │ ✗           │ ⚠️ Missing    │
+│ │ webhook support │ ✓       │ ✗           │ ℹ️ Intentional │
+│ │ batch mode      │ ✓       │ ✗           │ ℹ️ Intentional │
+│                                                            │
+│ MATCHES: 2                                                 │
+│ MISSING: 2                                                 │
+│ INTENTIONAL OMISSIONS: 2                                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Gap Analysis
+
+For each discrepancy:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ GAP #1: format parameter                                   │
+│                                                            │
+│ Documentation says: ["json", "svg", "png", "raw"]          │
+│ Implementation has:  ["json", "svg", "png"]                │
+│                                                            │
+│ Missing: "raw" format                                      │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add "raw" format support                         │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────┐
+│ GAP #2: size parameter                                     │
+│                                                            │
+│ Documentation says: size parameter exists (16-4096)        │
+│ Implementation has:  not implemented                       │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add size parameter                               │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 4: Loop Back or Proceed
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ VERIFICATION SUMMARY                                       │
+│                                                            │
+│ Gaps to fix: 2                                             │
+│ Intentional omissions: 2                                   │
+│                                                            │
+│ DECISION:                                                  │
+│                                                            │
+│ [x] Fix gaps → Return to TDD Red (write tests for gaps)    │
+│ [ ] Skip all → Document as omissions, proceed to Refactor  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## State File Updates
+
+```json
+{
+  "phases": {
+    "verify": {
+      "status": "complete",
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": [
+        {
+          "feature": "webhook support",
+          "reason": "User declined in interview",
+          "documented_at": "..."
+        },
+        {
+          "feature": "batch mode",
+          "reason": "Out of scope for v1",
+          "documented_at": "..."
+        }
+      ],
+      "re_research_done": true,
+      "completed_at": "..."
+    }
+  }
+}
+```
+
+## Verification Report
+
+Creates: `.claude/research/[api-name]/verification.md`
+
+```markdown
+# Verification Report: [API Name]
+
+**Date:** [current-date]
+**Implementation File:** src/app/api/v2/[endpoint]/route.ts
+**Test File:** src/app/api/v2/[endpoint]/**tests**/[endpoint].api.test.ts
+
+## Documentation Sources Re-Checked
+
+| Source          | URL                               | Checked |
+| --------------- | --------------------------------- | ------- |
+| Official docs   | [URL]                             | ✓       |
+| Context7        | [library]                         | ✓       |
+| Cached research | .claude/research/[api]/CURRENT.md | ✓       |
+
+## Feature Comparison
+
+| Feature      | In Docs   | Implemented | Status         |
+| ------------ | --------- | ----------- | -------------- |
+| domain param | ✓         | ✓           | ✅ Match       |
+| format param | 4 options | 3 options   | ⚠️ Fixed       |
+| size param   | ✓         | ✓           | ⚠️ Fixed       |
+| webhook      | ✓         | ✗           | ℹ️ Intentional |
+
+## Gaps Fixed
+
+1. **format parameter** - Added "raw" format support
+   - Test added: test/format-raw.test.ts:15
+   - Implementation: route.ts:45
+
+2. **size parameter** - Added size validation
+   - Test added: test/size-param.test.ts:10
+   - Implementation: route.ts:52
+
+## Intentional Omissions
+
+1. **webhook support**
+   - Reason: User declined in interview (Phase 4)
+   - Decision recorded: api-dev-state.json
+   - May add in v2
+
+2. **batch mode**
+   - Reason: Out of scope for initial release
+   - Documented for future consideration
+
+## Verification Result
+
+- **Status:** PASSED
+- **All documented features accounted for**
+- **Ready for Refactor phase**
+```
+
+## Hook Integration
+
+This command is normally triggered automatically by `verify-after-green.py` hook after tests pass.
+
+Manual invocation is useful when:
+
+- Hook was skipped or didn't trigger
+- Want to re-verify after changes
+- Research is stale and needs refresh
+
+## Workflow Position
+
+```
+Phase 8: TDD Red (write tests)
+    │
+    ▼
+Phase 9: TDD Green (implementation)
+    │
+    ▼
+Phase 10: VERIFY ← /api-verify triggers this
+    │
+    ├─► Gaps found? → Loop back to Phase 8
+    │
+    └─► All verified → Proceed to Phase 11 (Refactor)
+```
+
+<claude-commands-template>
+## Verification Guidelines
+
+1. **Re-read, don't remember** - Fresh fetch of docs every time
+2. **Feature-by-feature** - Systematic comparison
+3. **Document omissions** - Intentional != forgotten
+4. **Loop back for gaps** - Return to TDD Red if fixes needed
+5. **Update state file** - Track everything
+6. **Create verification report** - Audit trail
+
+## Common Gaps to Check
+
+- Parameter counts match?
+- Enum options complete?
+- Range boundaries correct?
+- Error codes handled?
+- Optional features accounted for?
+- Default values match docs?
+  </claude-commands-template>

package/.skills/beepboop/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: beepboop
+description: Communicate AI-generated content with transparent attribution. Adds markers indicating AI authorship. Use when sharing AI-generated code or content. Keywords: attribution, transparency, ai-generated, ethics, communication
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "workflow"
+  tags: ['attribution', 'transparency', 'ai-generated', 'ethics']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+---
+
+description: Communicate AI-generated content with transparent attribution
+argument-hint: <task-description>
+
+---
+
+# AI-Attributed Communication Command
+
+Execute the user's requested task (e.g., posting PR comments, GitHub issue comments, or other communications through various MCPs), but frame the output with clear AI attribution.
+
+## 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
+
+## Instructions
+
+Arguments: $ARGUMENTS
+
+**IMPORTANT Communication Format:**
+
+1. **Opening**: Begin with "_Beep boop, I am Claude Code 🤖, my user has reviewed and approved the following written by me:_"
+   - Use italics for this line
+   - Clearly establishes AI authorship
+
+2. **Middle**: Perform the requested task (post comment, create review, etc.)
+   - Execute whatever communication task the user requested
+   - Write the actual content that accomplishes the user's goal
+
+3. **Closing**: End with "_Beep boop, Claude Code 🤖 out!_"
+   - Use italics for this line
+   - Provides clear closure
+
+## Purpose
+
+This command ensures transparency about AI usage while maintaining that the user has reviewed and approved the content. It prevents offloading review responsibility to other users while being open about AI assistance.
+
+## Examples
+
+- Posting a GitHub PR review comment
+- Adding a comment to a GitHub issue
+- Responding to feedback with AI-generated explanations
+- Any communication where AI attribution is valuable
+
+## 🛡 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/.skills/busycommit/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: busycommit
+description: Create multiple atomic git commits, one logical change at a time. Analyzes changes and separates into meaningful commits. Use for complex changesets. Keywords: git, commit, atomic, granular, organization
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "git"
+  tags: ['git', 'commit', 'atomic', 'granular']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+---
+
+description: Create multiple atomic git commits, one logical change at a time
+argument-hint: [optional-commit-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
+
+Create multiple atomic git commits, committing the smallest possible logical unit at a time
+
+Include any of the following info if specified: $ARGUMENTS
+
+## Process
+
+1. Run `git status` and `git diff` to review changes
+2. Run `git log --oneline -5` to see recent commit style
+3. Stage relevant files with `git add`
+4. Create commit with descriptive message
+5. Verify with `git status`
+
+## Example
+
+```bash
+git add <files>
+git commit -m "feat(#123): add validation to user input form"
+```
+
+## Atomic Commit Approach
+
+Each commit should represent ONE logical change. Do NOT bundle multiple unrelated changes into one commit.
+
+- Identify the smallest atomic units of change
+- For EACH atomic unit: stage only those files/hunks, commit, verify
+- Use `git add -p` to stage partial file changes when a file contains multiple logical changes
+- Repeat until all changes are committed
+- It is OK to create multiple commits without stopping - keep going until `git status` shows clean
+
+## Multi-Commit Example
+
+If a single file contains multiple unrelated changes, use `git add -p` to stage hunks interactively:
+
+```bash
+# Stage only the validation-related hunks from the file
+git add -p src/user-service.ts
+# Select 'y' for validation hunks, 'n' for others
+git commit -m "feat(#123): add email format validation"
+
+# Stage the error handling hunks
+git add -p src/user-service.ts
+git commit -m "fix(#124): handle null user gracefully"
+
+# Stage remaining changes
+git add src/user-service.ts
+git commit -m "refactor: extract user lookup to helper"
+```
+
+## 🛡 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/.skills/commit/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: commit
+description: Create semantic git commit following project standards with co-author attribution. Analyzes staged changes, suggests commit message. Use after completing features. Keywords: git, commit, semantic, versioning, attribution
+license: MIT
+compatibility: Requires Claude Code with MCP servers (Context7, GitHub), Python 3.9+ for hooks, pnpm 10.11.0+
+metadata:
+  version: "3.0.0"
+  category: "git"
+  tags: ['git', 'commit', 'semantic', 'versioning']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+---
+
+description: Create a git commit following project standards
+argument-hint: [optional-commit-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
+
+Create a git commit following project standards
+
+Include any of the following info if specified: $ARGUMENTS
+
+## Process
+
+1. Run `git status` and `git diff` to review changes
+2. Run `git log --oneline -5` to see recent commit style
+3. Stage relevant files with `git add`
+4. Create commit with descriptive message
+5. Verify with `git status`
+
+## Example
+
+```bash
+git add <files>
+git commit -m "feat(#123): add validation to user input form"
+```
+
+## 🛡 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