@hustle-together/api-dev-tools 3.10.0 → 3.11.1

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

@@ -0,0 +1,159 @@
+{
+  "version": "3.0.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
+    }
+  ],
+  "phases": {
+    "disambiguation": {
+      "status": "not_started",
+      "clarified": null,
+      "search_variations": [],
+      "description": "Pre-research disambiguation to clarify ambiguous requests"
+    },
+    "scope": {
+      "status": "not_started",
+      "confirmed": false,
+      "description": "Initial scope understanding and confirmation"
+    },
+    "research_initial": {
+      "status": "not_started",
+      "sources": [],
+      "summary_approved": false,
+      "description": "Context7/WebSearch research for live documentation"
+    },
+    "interview": {
+      "status": "not_started",
+      "questions": [],
+      "user_question_count": 0,
+      "structured_question_count": 0,
+      "decisions": {},
+      "description": "Structured interview about requirements (generated FROM research)"
+    },
+    "research_deep": {
+      "status": "not_started",
+      "sources": [],
+      "proposed_searches": [],
+      "approved_searches": [],
+      "skipped_searches": [],
+      "description": "Deep dive based on interview answers (adaptive, not shotgun)"
+    },
+    "schema_creation": {
+      "status": "not_started",
+      "schema_file": null,
+      "schema_approved": false,
+      "description": "Zod schema creation from research"
+    },
+    "environment_check": {
+      "status": "not_started",
+      "keys_verified": [],
+      "keys_missing": [],
+      "confirmed": false,
+      "description": "API key and environment verification"
+    },
+    "tdd_red": {
+      "status": "not_started",
+      "test_file": null,
+      "test_count": 0,
+      "test_matrix_approved": false,
+      "description": "Write failing tests first"
+    },
+    "tdd_green": {
+      "status": "not_started",
+      "implementation_file": null,
+      "all_tests_passing": false,
+      "description": "Minimal implementation to pass tests"
+    },
+    "verify": {
+      "status": "not_started",
+      "gaps_found": 0,
+      "gaps_fixed": 0,
+      "intentional_omissions": [],
+      "re_research_done": false,
+      "description": "Re-research after Green to verify implementation matches docs"
+    },
+    "tdd_refactor": {
+      "status": "not_started",
+      "description": "Code cleanup while keeping tests green"
+    },
+    "documentation": {
+      "status": "not_started",
+      "files_updated": [],
+      "manifest_updated": false,
+      "openapi_updated": false,
+      "research_cached": false,
+      "description": "Update manifests, OpenAPI, cache research"
+    }
+  },
+  "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,185 @@
+# 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

package/.claude/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