@hustle-together/api-dev-tools 1.0.0

package/commands/issue.md

@@ -0,0 +1,192 @@
+---
+description: Analyze GitHub issue and create TDD implementation plan
+argument-hint: [optional-issue-number]
+---
+
+Analyze GitHub issue and create TDD implementation plan.
+
+## 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
+
+Process:
+
+1. Get Issue Number
+
+- Either from branch name use that issue number
+  - Patterns: issue-123, 123-feature, feature/123, fix/123
+- Or from this bullet point with custom info: $ARGUMENTS
+- If not found: ask user
+
+1. Fetch Issue
+
+Try to fetch the issue using GitHub MCP (mcp__github__issue_read tool).
+
+If GitHub MCP is not configured, show:
+
+```
+GitHub MCP not configured!
+See: https://github.com/modelcontextprotocol/servers/tree/main/src/github
+Trying GitHub CLI fallback...
+```
+
+Then try using `gh issue view [ISSUE_NUMBER] --json` as fallback.
+
+1. Analyze and Plan
+
+Summarize the issue and requirements, then:
+
+## Discovery Phase
+
+Understand the requirement by asking (use AskUserQuestion if needed):
+
+**Problem Statement**
+
+- What problem does this solve?
+- Who experiences this problem?
+- What's the current pain point?
+
+**Desired Outcome**
+
+- What should happen after this is built?
+- How will users interact with it?
+- What does success look like?
+
+**Scope & Constraints**
+
+- What's in scope vs. out of scope?
+- Any technical constraints?
+- Dependencies on other systems/features?
+
+**Context Check**
+
+- Search codebase for related features/modules
+- Check for existing test files that might be relevant
+
+## TDD Fundamentals
+
+### The TDD Cycle
+
+The foundation of TDD is the Red-Green-Refactor cycle:
+
+1. **Red Phase**: Write ONE failing test that describes desired behavior
+
+   - The test must fail for the RIGHT reason (not syntax/import errors)
+   - Only one test at a time - this is critical for TDD discipline
+     - Exception: For browser-level tests or expensive setup (e.g., Storybook `*.stories.tsx`), group multiple assertions within a single test block to avoid redundant setup - but only when adding assertions to an existing interaction flow. If new user interactions are required, still create a new test. Split files by category if they exceed ~1000 lines.
+   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
+   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
+   - For DOM-based tests, use `data-testid` attributes to select elements rather than CSS classes, tag names, or text content
+   - Avoid hard-coded timeouts both in form of sleep() or timeout: 5000 etc; use proper async patterns (`waitFor`, `findBy*`, event-based sync) instead and rely on global test configs for timeout settings
+
+2. **Green Phase**: Write MINIMAL code to make the test pass
+
+   - Implement only what's needed for the current failing test
+   - No anticipatory coding or extra features
+   - Address the specific failure message
+
+3. **Refactor Phase**: Improve code structure while keeping tests green
+   - Only allowed when relevant tests are passing
+   - Requires proof that tests have been run and are green
+   - Applies to BOTH implementation and test code
+   - No refactoring with failing tests - fix them first
+
+### Core Violations
+
+1. **Multiple Test Addition**
+
+   - Adding more than one new test at once
+   - Exception: Initial test file setup or extracting shared test utilities
+
+2. **Over-Implementation**
+
+   - Code that exceeds what's needed to pass the current failing test
+   - Adding untested features, methods, or error handling
+   - Implementing multiple methods when test only requires one
+
+3. **Premature Implementation**
+   - Adding implementation before a test exists and fails properly
+   - Adding implementation without running the test first
+   - Refactoring when tests haven't been run or are failing
+
+### Critical Principle: Incremental Development
+
+Each step in TDD should address ONE specific issue:
+
+- Test fails "not defined" → Create empty stub/class only
+- Test fails "not a function" → Add method stub only
+- Test fails with assertion → Implement minimal logic only
+
+### Optional Pre-Phase: Spike Phase
+
+In rare cases where the problem space, interface, or expected behavior is unclear, a **Spike Phase** may be used **before the Red Phase**.
+This phase is **not part of the regular TDD workflow** and must only be applied under exceptional circumstances.
+
+- The goal of a Spike is **exploration and learning**, not implementation.
+- The code written during a Spike is **disposable** and **must not** be merged or reused directly.
+- Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**.
+- A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior.
+
+### General Information
+
+- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
+- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
+- In the refactor phase, it is perfectly fine to refactor both test and implementation code. That said, completely new functionality is not allowed. Types, clean up, abstractions, and helpers are allowed as long as they do not introduce new behavior.
+- Adding types, interfaces, or a constant in order to replace magic values is perfectly fine during refactoring.
+- Provide the agent with helpful directions so that they do not get stuck when blocking them.
+
+
+## 🛡 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/plan.md

@@ -0,0 +1,168 @@
+---
+description: Create implementation plan from feature/requirement with PRD-style discovery and TDD acceptance criteria
+argument-hint: <feature/requirement description or GitHub issue URL/number>
+---
+
+# Plan: PRD-Informed Task Planning for TDD
+
+Create structured implementation plan that bridges product thinking (PRD) with test-driven development.
+
+## 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
+
+## Input
+
+$ARGUMENTS
+
+(If no input provided, check conversation context)
+
+## Input Processing
+
+The input can be one of:
+
+1. **GitHub Issue URL** (e.g., `https://github.com/owner/repo/issues/123`)
+2. **GitHub Issue Number** (e.g., `#123` or `123`)
+3. **Feature Description** (e.g., "Add user authentication")
+4. **Empty** - use conversation context
+
+### GitHub Issue Integration
+
+If input looks like a GitHub issue:
+
+**Step 1: Extract Issue Number**
+
+- From URL: extract owner/repo/number
+- From number: try to infer repo from git remote
+- From branch name: check patterns like `issue-123`, `123-feature`, `feature/123`
+
+**Step 2: Fetch Issue**
+Try GitHub MCP first:
+
+- If available: use `mcp__github__issue_read` to fetch issue details
+- If not available: show message and try `gh issue view <number>`
+
+```
+GitHub MCP not configured!
+See: https://github.com/modelcontextprotocol/servers/tree/main/src/github
+Trying GitHub CLI fallback...
+```
+
+**Step 3: Use Issue as Discovery Input**
+
+- Title → Feature name
+- Description → Problem statement and context
+- Labels → Type/priority hints
+- Comments → Additional requirements and discussion
+- Linked issues → Dependencies
+
+Extract from GitHub issue:
+
+- Problem statement and context
+- Acceptance criteria (if present)
+- Technical notes (if present)
+- Related issues/dependencies
+
+## Process
+
+## Discovery Phase
+
+Understand the requirement by asking (use AskUserQuestion if needed):
+
+**Problem Statement**
+
+- What problem does this solve?
+- Who experiences this problem?
+- What's the current pain point?
+
+**Desired Outcome**
+
+- What should happen after this is built?
+- How will users interact with it?
+- What does success look like?
+
+**Scope & Constraints**
+
+- What's in scope vs. out of scope?
+- Any technical constraints?
+- Dependencies on other systems/features?
+
+**Context Check**
+
+- Search codebase for related features/modules
+- Check for existing test files that might be relevant
+
+## Key Principles
+
+**From PRD World:**
+
+- Start with user problems, not solutions
+- Define success criteria upfront
+- Understand constraints and scope
+
+**From TDD World:**
+
+- Make acceptance criteria test-ready
+- Break work into small, testable pieces
+- Each task should map to test(s)
+
+## Integration with Other Commands
+
+- **Before /plan**: Use `/spike` if you need technical exploration first
+- **After /plan**: Use `/red` to start TDD on first task
+
+
+## 🛡 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/pr.md

@@ -0,0 +1,122 @@
+---
+description: Creates a pull request using GitHub MCP
+argument-hint: [optional-pr-title-and-description]
+---
+
+# Create Pull Request
+
+## 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 pull request for the current branch using GitHub MCP tools.
+
+## Workflow
+
+Current branch status:
+!`git status`
+
+Recent commits:
+!`git log --oneline -5`
+
+Arguments: $ARGUMENTS
+
+**Process:**
+
+1. **Ensure Branch is Ready**:
+   !`git status`
+   - Commit all changes
+   - Push to remote: `git push origin [branch-name]`
+
+2. **Create PR**: Create a well-formatted pull request
+
+   Title: conventional commits format, like `feat(#123): add user authentication`
+
+   Description template:
+
+   ```markdown
+   <!--
+     Are there any relevant issues / PRs / mailing lists discussions?
+     Please reference them here.
+   -->
+
+   ## References
+
+   - [links to github issues referenced in commit messages]
+
+   ## Summary
+
+   [Brief description of changes]
+
+   ## Test Plan
+
+   - [ ] Tests pass
+   - [ ] Manual testing completed
+   ```
+
+3. **Set Base Branch**: Default to main unless specified otherwise
+
+4. **Link Issues**: Reference related issues found in commit messages
+
+## Use GitHub MCP Tools
+
+1. Check current branch and ensure it's pushed
+2. Create a well-formatted pull request with proper title and description
+3. Set the base branch (default: main)
+4. Include relevant issue references if found in commit messages
+
+
+## 🛡 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/red.md

@@ -0,0 +1,142 @@
+---
+description: Execute TDD Red Phase - write ONE failing test
+argument-hint: [optional additional info]
+---
+
+RED PHASE! Apply the below to the info given by user input here:
+
+$ARGUMENTS
+
+## 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
+
+(If there was no info above, fallback to the context of the conversation)
+
+## TDD Fundamentals
+
+### The TDD Cycle
+
+The foundation of TDD is the Red-Green-Refactor cycle:
+
+1. **Red Phase**: Write ONE failing test that describes desired behavior
+
+   - The test must fail for the RIGHT reason (not syntax/import errors)
+   - Only one test at a time - this is critical for TDD discipline
+     - Exception: For browser-level tests or expensive setup (e.g., Storybook `*.stories.tsx`), group multiple assertions within a single test block to avoid redundant setup - but only when adding assertions to an existing interaction flow. If new user interactions are required, still create a new test. Split files by category if they exceed ~1000 lines.
+   - **Adding a single test to a test file is ALWAYS allowed** - no prior test output needed
+   - Starting TDD for a new feature is always valid, even if test output shows unrelated work
+   - For DOM-based tests, use `data-testid` attributes to select elements rather than CSS classes, tag names, or text content
+   - Avoid hard-coded timeouts both in form of sleep() or timeout: 5000 etc; use proper async patterns (`waitFor`, `findBy*`, event-based sync) instead and rely on global test configs for timeout settings
+
+2. **Green Phase**: Write MINIMAL code to make the test pass
+
+   - Implement only what's needed for the current failing test
+   - No anticipatory coding or extra features
+   - Address the specific failure message
+
+3. **Refactor Phase**: Improve code structure while keeping tests green
+   - Only allowed when relevant tests are passing
+   - Requires proof that tests have been run and are green
+   - Applies to BOTH implementation and test code
+   - No refactoring with failing tests - fix them first
+
+### Core Violations
+
+1. **Multiple Test Addition**
+
+   - Adding more than one new test at once
+   - Exception: Initial test file setup or extracting shared test utilities
+
+2. **Over-Implementation**
+
+   - Code that exceeds what's needed to pass the current failing test
+   - Adding untested features, methods, or error handling
+   - Implementing multiple methods when test only requires one
+
+3. **Premature Implementation**
+   - Adding implementation before a test exists and fails properly
+   - Adding implementation without running the test first
+   - Refactoring when tests haven't been run or are failing
+
+### Critical Principle: Incremental Development
+
+Each step in TDD should address ONE specific issue:
+
+- Test fails "not defined" → Create empty stub/class only
+- Test fails "not a function" → Add method stub only
+- Test fails with assertion → Implement minimal logic only
+
+### Optional Pre-Phase: Spike Phase
+
+In rare cases where the problem space, interface, or expected behavior is unclear, a **Spike Phase** may be used **before the Red Phase**.
+This phase is **not part of the regular TDD workflow** and must only be applied under exceptional circumstances.
+
+- The goal of a Spike is **exploration and learning**, not implementation.
+- The code written during a Spike is **disposable** and **must not** be merged or reused directly.
+- Once sufficient understanding is achieved, all spike code is discarded, and normal TDD resumes starting from the **Red Phase**.
+- A Spike is justified only when it is impossible to define a meaningful failing test due to technical uncertainty or unknown system behavior.
+
+### General Information
+
+- Sometimes the test output shows as no tests have been run when a new test is failing due to a missing import or constructor. In such cases, allow the agent to create simple stubs. Ask them if they forgot to create a stub if they are stuck.
+- It is never allowed to introduce new logic without evidence of relevant failing tests. However, stubs and simple implementation to make imports and test infrastructure work is fine.
+- In the refactor phase, it is perfectly fine to refactor both test and implementation code. That said, completely new functionality is not allowed. Types, clean up, abstractions, and helpers are allowed as long as they do not introduce new behavior.
+- Adding types, interfaces, or a constant in order to replace magic values is perfectly fine during refactoring.
+- Provide the agent with helpful directions so that they do not get stuck when blocking them.
+
+
+## 🛡 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