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

package/.skills/update-todos/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: update-todos
+description: Update TodoWrite progress tracker for multi-phase workflows. Internal helper skill that visualizes workflow progress with checkboxes. Automatically determines status based on current phase. Keywords: todowrite, progress, tracking, workflow, visualization, helper
+license: MIT
+compatibility: Requires Claude Code with TodoWrite tool support
+metadata:
+  version: "1.0.0"
+  category: "workflow"
+  tags: ["todowrite", "progress", "tracking", "visualization", "helper"]
+  author: "Hustle Together"
+allowed-tools: TodoWrite Read
+---
+
+# Update Todos - TodoWrite Progress Helper
+
+**Usage:** `/update-todos [workflow] [current-phase]`
+
+**Purpose:** Updates the TodoWrite visual progress tracker for multi-phase workflows. Internal helper skill called by workflow commands.
+
+## Parameters
+
+- **workflow**: Which workflow to update
+  - `api-create` - 13-phase API development
+  - `ui-create-component` - 13-phase component development
+  - `ui-create-page` - 13-phase page development
+  - `combine` - 12-phase API orchestration
+
+- **current-phase**: Phase number just completed (0 = initialization, 1-13 = phases)
+
+## Workflow Phase Definitions
+
+### API Create (13 phases)
+
+```
+Phase 1:  Disambiguation - Clarify ambiguous API terms
+Phase 2:  Scope - Confirm endpoint understanding
+Phase 3:  Initial Research - Targeted doc searches (Context7, Web)
+Phase 4:  Interview - Questions FROM research findings
+Phase 5:  Deep Research - Adaptive propose-approve searches
+Phase 6:  Schema - Zod schema from research + interview
+Phase 7:  Environment - Verify API keys exist
+Phase 8:  TDD Red - Write failing tests
+Phase 9:  TDD Green - Minimal implementation
+Phase 10: Verify - Re-research docs vs implementation
+Phase 11: Refactor - Clean up code
+Phase 12: Documentation - Update manifests, cache research
+Phase 13: Completion - Final verification, commit
+```
+
+### UI Create Component (13 phases)
+
+```
+Phase 1:  Component Scope - Define type (Atom/Molecule/Organism)
+Phase 2:  Brand Guide - Check existing design system
+Phase 3:  Research - ShadCN, Radix, Tailwind patterns
+Phase 4:  Props Interview - Component API questions
+Phase 5:  ShadCN Detection - Check if base exists
+Phase 6:  Component Schema - Props, variants, defaults
+Phase 7:  TDD Red - Write component tests
+Phase 8:  TDD Green - Implement component
+Phase 9:  Storybook Stories - Create interactive docs
+Phase 10: Responsive Check - Test breakpoints
+Phase 11: Accessibility - WCAG AA/AAA audit
+Phase 12: Brand Validation - Verify design system compliance
+Phase 13: Showcase Update - Add to UI showcase page
+```
+
+### UI Create Page (13 phases)
+
+```
+Phase 1:  Page Type - Landing/Dashboard/Form/List/Detail/Auth
+Phase 2:  Route Planning - Define URL structure
+Phase 3:  API Route Check - Verify backend exists
+Phase 4:  Data Schema - Define page data requirements
+Phase 5:  Component Research - Find needed UI components
+Phase 6:  Layout Design - Structure with App Router patterns
+Phase 7:  TDD Red - Write Playwright E2E tests
+Phase 8:  TDD Green - Implement page
+Phase 9:  Data Integration - Connect to API routes
+Phase 10: SEO Metadata - Add meta tags, OG, Twitter cards
+Phase 11: Accessibility - Keyboard nav, ARIA, focus management
+Phase 12: E2E Validation - Run Playwright tests
+Phase 13: Registry Update - Add to route registry
+```
+
+### Combine APIs (12 phases)
+
+```
+Phase 1:  API Selection - Choose 2+ existing APIs from registry
+Phase 2:  Registry Verification - Confirm APIs are complete
+Phase 3:  Flow Type - Sequential/Parallel/Conditional
+Phase 4:  Data Mapping - Define transformations between APIs
+Phase 5:  Error Strategy - Fail-fast/Fallback/Retry
+Phase 6:  Schema Design - Combined Zod schema
+Phase 7:  TDD Red - Write orchestration tests
+Phase 8:  TDD Green - Implement orchestration
+Phase 9:  Curl Examples - Generate test commands
+Phase 10: Performance Test - Verify latency acceptable
+Phase 11: Documentation - Update manifests with examples
+Phase 12: Showcase Update - Add to API showcase
+```
+
+## Implementation
+
+You are a TodoWrite progress updater. Your job is to:
+
+1. **Read the workflow parameter** to determine which phase structure to use
+2. **Build the todos array** with proper status for each phase
+3. **Call TodoWrite** with the complete array
+4. **Return silently** without output to the user
+
+### Status Logic
+
+For a given `current_phase` number:
+
+- Phases < current_phase: `"completed"`
+- Phase == current_phase: `"in_progress"`
+- Phases > current_phase: `"pending"`
+
+### Example Call
+
+User calls: `/update-todos api-create 3`
+
+You build:
+
+```json
+[
+  {"content": "Phase 1: Disambiguation", "status": "completed", "activeForm": "Clarified API terms"},
+  {"content": "Phase 2: Scope", "status": "completed", "activeForm": "Confirmed endpoint understanding"},
+  {"content": "Phase 3: Initial Research", "status": "in_progress", "activeForm": "Researching documentation"},
+  {"content": "Phase 4: Interview", "status": "pending", "activeForm": "Interviewing user for requirements"},
+  ...
+]
+```
+
+Then call TodoWrite with this array.
+
+## Special Cases
+
+### Initialization (phase 0)
+
+When `current_phase = 0`, all phases are `"pending"` with one `"in_progress"`:
+
+- Phase 1: `"in_progress"` (starting workflow)
+- Phases 2-13: `"pending"`
+
+### Completion (phase 13 for 13-phase workflows)
+
+When `current_phase = 13`:
+
+- All phases: `"completed"`
+- Display completion message
+
+### Loop-Back Scenarios
+
+If a verification phase fails (e.g., Phase 10 requires going back to Phase 8):
+
+- The calling workflow will call `/update-todos` with the looped-back phase number
+- Example: After Phase 10 fails verification → `/update-todos api-create 8`
+- Phase 8 becomes `"in_progress"` again
+- Phases 9-13 revert to `"pending"`
+
+## Error Handling
+
+If invalid parameters:
+
+- Invalid workflow name → Use `api-create` as default, warn user
+- Invalid phase number → Clamp to valid range (0-13 or 0-12)
+- Missing parameters → Ask user to provide them
+
+## Silent Operation
+
+**CRITICAL:** This is a helper skill. After calling TodoWrite, you MUST:
+
+- **NOT output any text to the user**
+- **NOT explain what you did**
+- **NOT ask follow-up questions**
+- Simply update the todos and return control to the calling workflow
+
+The calling workflow (e.g., `/api-create`) will handle all user communication.
+
+## Usage Examples
+
+### From api-create workflow
+
+```markdown
+# Start of workflow
+
+/update-todos api-create 0
+
+# After Phase 1 completes
+
+/update-todos api-create 1
+
+# After Phase 10 verification fails (loop back to Phase 8)
+
+/update-todos api-create 8
+```
+
+### From ui-create-component workflow
+
+```markdown
+# Start of workflow
+
+/update-todos ui-create-component 0
+
+# After completing Brand Guide check
+
+/update-todos ui-create-component 2
+```
+
+### From combine workflow
+
+```markdown
+# Start of workflow (note: only 12 phases)
+
+/update-todos combine 0
+
+# After Flow Type selection
+
+/update-todos combine 3
+```
+
+## Integration Points
+
+This skill is called by:
+
+- `.skills/api-create/SKILL.md` (or `/hustle-api-create`)
+- `.skills/hustle-ui-create/SKILL.md` (component mode)
+- `.skills/hustle-ui-create-page/SKILL.md` (page mode)
+- `.skills/hustle-combine/SKILL.md` (orchestration)
+
+## Testing
+
+To test this helper independently:
+
+```bash
+/update-todos api-create 5
+# Should show phases 1-4 completed, phase 5 in_progress, 6-13 pending
+
+/update-todos combine 12
+# Should show all 12 phases completed
+
+/update-todos ui-create-component 0
+# Should show phase 1 in_progress, rest pending
+```
+
+---
+
+**Now execute the TodoWrite update based on the provided parameters.**

package/.skills/worktree-add/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: worktree-add
+description: Add new git worktree from branch name or GitHub issue URL. Copies settings, installs deps, opens in IDE. Use for parallel feature development. Keywords: git, worktree, parallel, workflow, branches
+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', 'worktree', 'parallel', 'workflow']
+  author: "Hustle Together"
+allowed-tools: WebSearch WebFetch mcp__context7 mcp__github AskUserQuestion Read Write Edit Bash TodoWrite
+---
+
+---
+
+description: Add a new git worktree from branch name or GitHub issue URL, copy settings, install deps, and open in current IDE
+argument-hint: <branch-name-or-github-issue-url> [optional-base-branch]
+
+---
+
+# Git Worktree Setup
+
+## 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 new git worktree for branch: $ARGUMENTS
+
+<current_state>
+Current branch: !git branch --show-current`
+Current worktrees: !git worktree list`
+Remote branches: !git branch -r`
+Uncommitted changes: !git status --short`
+</current_state>
+
+<execution_steps>
+<step_0>
+<description>Validate MCP dependencies</description>
+<check_github_mcp>
+<requirement>GitHub MCP server must be configured</requirement>
+<fallback>If unavailable, use `gh` CLI commands</fallback>
+<validation> - Try listing available MCP resources - If GitHub MCP not found, switch to CLI fallback - Inform user about MCP configuration if needed
+</validation>
+</check_github_mcp>
+<error_handling>
+If MCP validation fails: - Show clear error message - Provide setup instructions - Fallback to CLI if possible
+</error_handling>
+<purpose>Ensure required MCP dependencies are available before proceeding</purpose>
+</step_0>
+
+<step_1>
+<description>Detect current IDE environment</description>
+<detection_methods>
+<method_1>
+<tool>mcp**ide**getDiagnostics</tool>
+<vs_code_insiders>Check for paths containing "Code - Insiders"</vs_code_insiders>
+<vs_code>Check for paths containing "Code/" or "Code.app"</vs_code>
+<cursor>Check for paths containing "Cursor"</cursor>
+<zed>Check for paths containing "Zed"</zed>
+</method_1>
+<method_2>
+<fallback_detection>Use which command to find available IDEs</fallback_detection>
+<commands>which code-insiders code zed cursor</commands>
+<priority_order>code-insiders > cursor > zed > code</priority_order>
+</method_2>
+</detection_methods>
+<set_variables>
+<ide_command>Detected command (code-insiders|code|zed|cursor)</ide_command>
+<ide_name>Human-readable name</ide_name>
+<supports_tasks>true for VS Code variants, false for others</supports_tasks>
+</set_variables>
+<purpose>Automatically detect which IDE to use for opening the new worktree</purpose>
+</step_1>
+
+<step_2>
+<description>Parse the arguments</description>
+<input>The user-provided arguments</input>
+<expected_format>branch-name-or-github-url [optional-base-branch]</expected_format>
+<example>fix/issue-123-main-content-area-visually-clipped main</example>
+<example_github_url><https://github.com/owner/project/issues/123> main</example_github_url>
+<default_base_branch>main (if not specified)</default_base_branch>
+</step_1>
+
+<step_2_5>
+<description>Handle GitHub issue URLs</description>
+<condition>If first argument matches GitHub issue URL pattern</condition>
+<url_detection>Check if argument contains "github.com" and "/issues/"</url_detection>
+<url_parsing>
+<pattern>https://github.com/{owner}/{repo}/issues/{issue_number}</pattern>
+<extract>owner, repo, issue_number from URL</extract>
+</url_parsing>
+<fetch_issue_details>
+<tool>mcp**github**issue_read</tool>
+<method>get</method>
+<parameters>owner, repo, issue_number</parameters>
+</fetch_issue_details>
+<generate_branch_name>
+<determine_type>Analyze issue title/labels to determine type (feat/fix/refactor/chore)</determine_type>
+<format>{type}/{repo}-{issue_number}-{kebab-case-title}</format>
+<kebab_case>Convert title to lowercase, replace spaces/special chars with hyphens</kebab_case>
+<sanitization>
+<rule>Always use lowercase for branch names</rule>
+<rule>Replace # with - (hash symbol not allowed in git branch names)</rule>
+<rule>Remove or replace other special characters: @, $, %, ^, &, \*, (, ), [, ], {, }, \, |, ;, :, ", ', <, >, ?, /, ~, `</rule>
+<rule>Replace multiple consecutive hyphens with single hyphen</rule>
+<rule>Trim leading/trailing hyphens</rule>
+</sanitization>
+<truncate>Limit total branch name to reasonable length (~60 chars)</truncate>
+</generate_branch_name>
+<user_confirmation>
+<display>Show generated branch name and ask for confirmation</display>
+<options>"Yes, proceed" or "No, exit" or "Edit branch name"</options>
+<if_no>Exit command gracefully</if_no>
+<if_edit>Allow user to modify the branch name</if_edit>
+<if_yes>Continue with generated/modified branch name</if_yes>
+</user_confirmation>
+<examples>
+<input>https://github.com/owner/project/issues/456</input>
+
+<title>"Fix duplicate items in list view"</title>
+<generated>fix/issue-456-duplicate-items-in-list-view</generated>
+</examples>
+</step_1_5>
+
+<step_3>
+<description>Add all files and stash uncommitted changes if any exist</description>
+<condition>If output is not empty (has uncommitted changes)</condition>
+<command>git add -A && git stash push -m "Worktree switch: Moving changes to ${branch_name}"</chained_command>
+<purpose>Preserve work in progress before switching worktrees</purpose>
+<note>Remember stash was created for later restoration</note>
+</step_3>
+
+<step_4>
+<description>Determine worktree parent directory</description>
+<check_if_in_worktree>git rev-parse --is-inside-work-tree && git worktree list --porcelain | grep "$(git rev-parse --show-toplevel)"</check_if_in_worktree>
+<set_parent_path>
+<if_main_worktree>Set parent_path=".."</if_main_worktree>
+<if_secondary_worktree>Set parent_path="../.." (need to go up two levels)</if_secondary_worktree>
+</set_parent_path>
+<purpose>Correctly determine where to create new worktree regardless of current location</purpose>
+<note>This handles both main worktree and secondary worktree scenarios</note>
+</step_4>
+
+<step_5>
+<description>Fetch latest changes from remote</description>
+<command>git fetch origin</command>
+<purpose>Ensure we have the latest remote branches and main branch state</purpose>
+<note>This ensures new worktrees are created from the most recent main branch</note>
+</step_6>
+
+<step_7>
+<description>Check if branch exists on remote</description>
+<command>git branch -r | grep "origin/${branch_name}"</command>
+<decision>
+<if_exists>Branch exists on remote - will checkout existing branch</if_exists>
+<if_not_exists>Branch does not exist - will create new branch from base</if_not_exists>
+</decision>
+</step_5>
+
+<step_6>
+<description>Create the worktree</description>
+<option_a_new_branch>
+<condition>Remote branch does NOT exist</condition>
+<command>git worktree add ${parent_path}/${branch_name} -b ${branch_name} ${base_branch}</command>
+      <example>git worktree add ../fix/issue-123-main-content-area-visually-clipped -b fix/issue-123-main-content-area-visually-clipped main</example>
+    </option_a_new_branch>
+    <option_b_existing_branch>
+      <condition>Remote branch EXISTS</condition>
+      <command>git worktree add ${parent_path}/${branch_name} ${branch_name}</command>
+<example>git worktree add ../fix/issue-123-main-content-area-visually-clipped fix/issue-123-main-content-area-visually-clipped</example>
+</option_b_existing_branch>
+</step_7>
+
+<step_8>
+<description>Copy Claude settings to new worktree</description>
+
+<source>.claude/settings.local.json</source>
+<destination>${parent_path}/${branch_name}/.claude/settings.local.json</destination>
+<command>cp -r .claude/settings.local.json ${parent_path}/${branch_name}/.claude/settings.local.json</command>
+<purpose>Preserve all permission settings and configurations</purpose>
+</step_8>
+
+<step*9>
+<description>Copy .env.local files to new worktree</description>
+<search_command>find . -name ".env.local" -type f</search_command>
+<copy_logic>For each .env.local file found, copy to corresponding location in new worktree</copy_logic>
+<common_locations> - app/.env.local - packages/\*/.env.local - (any other .env.local files found)
+</common_locations>
+<copy_command>find . -name ".env.local" -type f -exec sh -c 'mkdir -p "$(dirname "${parent_path}/${branch_name}/$1")" && cp "$1" "${parent_path}/${branch_name}/$1"' *{} \;</copy_command>
+<purpose>Preserve local environment configurations for development</purpose>
+<note>Only copies files that exist; ignores missing ones</note>
+</step_9>
+
+<step_10>
+<description>Create IDE-specific configuration (conditional)</description>
+<condition>Only if supports_tasks is true (VS Code variants)</condition>
+<vs_code_tasks>
+<create_directory>mkdir -p ${parent_path}/${branch_name}/.vscode</create_directory>
+<create_file_command>cat > ${parent_path}/${branch_name}/.vscode/tasks.json << 'EOF'
+{
+"version": "2.0.0",
+"tasks": [
+{
+"label": "Auto start Claude",
+"type": "shell",
+"command": "claude",
+"runOptions": {
+"runOn": "folderOpen"
+},
+"presentation": {
+"echo": false,
+"reveal": "always",
+"focus": true,
+"panel": "new"
+}
+}
+]
+}
+EOF</create_file_command>
+</vs_code_tasks>
+<purpose>Create auto-start Claude task for VS Code variants on folder open</purpose>
+<note>Only creates for VS Code variants (code, code-insiders, cursor)</note>
+<skip_message>Skipping IDE-specific config for non-VS Code IDEs</skip_message>
+</step_10>
+
+<step_11>
+<description>Install dependencies in new worktree</description>
+<working_directory>${parent_path}/${branch_name}</working_directory>
+<command>cd ${parent_path}/${branch_name} && pnpm install</command>
+<purpose>Ensure all node_modules are installed for the new worktree</purpose>
+</step_11>
+
+<step_12>
+<description>Apply stashed changes to new worktree (if stash was created)</description>
+<condition>Only if stash was created in step_3</condition>
+<working_directory>${parent_path}/${branch_name}</working_directory>
+<command>cd ${parent_path}/${branch_name} && git stash pop</command>
+<purpose>Restore uncommitted work-in-progress to the new worktree branch</purpose>
+<note>This moves your uncommitted changes to the new branch where you'll continue working</note>
+</step_12>
+
+<step_13>
+<description>Open detected IDE in new worktree</description>
+<command>${ide_command} ${parent_path}/${branch_name}</command>
+<ide_specific_behavior>
+<vs_code_variants>Opens folder in VS Code/Insiders/Cursor with tasks.json auto-starting Claude</vs_code_variants>
+<zed>Opens folder in Zed editor</zed>
+<other>Uses detected IDE command to open folder</other>
+</ide_specific_behavior>
+<purpose>Launch development environment for the new worktree using detected IDE</purpose>
+<confirmation_message>Opening worktree in ${ide_name}</confirmation_message>
+</step_11>
+</execution_steps>
+
+<important_notes>
+
+- Automatically detects and uses your current IDE (VS Code, VS Code Insiders, Cursor, Zed, etc.)
+- Creates VS Code-specific tasks.json only for VS Code variants (auto-starts Claude on folder open)
+- Branch names with slashes (feat/, fix/, etc.) are fully supported
+- The worktree directory path will match the full branch name including slashes
+- Settings are copied to maintain the same permissions across worktrees
+- Environment files (.env.local) are copied to preserve local configurations
+- Each worktree has its own node_modules installation
+- Uncommitted changes are automatically stashed and moved to the new worktree
+- Your work-in-progress seamlessly transfers to the new branch
+- IDE detection fallback: checks available editors and uses priority order
+  </important_notes>
+
+## 🛡 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