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

package/.claude/commands/worktree-add.md

@@ -0,0 +1,315 @@
+---
+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

package/.claude/commands/worktree-cleanup.md

@@ -0,0 +1,281 @@
+---
+description: Clean up merged worktrees by verifying PR/issue status, consolidating settings, and removing stale worktrees
+argument-hint: (no arguments)
+---
+
+# Worktree Cleanup
+
+## 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
+
+Clean up merged worktrees by finding the oldest merged branch, consolidating settings, and removing stale worktrees.
+
+Additional info: $ARGUMENTS
+
+<current_state>
+Current branch: !git branch --show-current`
+Current worktrees: !git worktree list`
+</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>Verify we're in main branch</description>
+    <check_command>git branch --show-current</check_command>
+    <required_branch>main</required_branch>
+    <error_if_not_main>Exit with error message: "This command must be run from the main branch"</error_if_not_main>
+    <purpose>Ensure we're consolidating to the main worktree</purpose>
+  </step_1>
+
+  <step_2>
+    <description>Get list of all worktrees</description>
+    <command>git worktree list --porcelain</command>
+    <parse_output>Extract worktree paths and branch names</parse_output>
+    <exclude_main>Filter out the main worktree from cleanup candidates</exclude_main>
+    <purpose>Identify all worktrees that could potentially be cleaned up</purpose>
+  </step_2>
+
+  <step_3>
+    <description>Find oldest worktree by directory age</description>
+    <get_worktree_ages>
+      <command_macos>git worktree list | grep -v "main" | awk '{print $1}' | while read path; do /usr/bin/stat -f "%Sm|%N" -t "%Y-%m-%d %H:%M:%S" "$path" 2>/dev/null; done | sort</command_macos>
+      <command_linux>git worktree list | grep -v "main" | awk '{print $1}' | xargs stat -c "%y|%n" | sort</command_linux>
+      <purpose>List all worktrees sorted by directory modification time (oldest first)</purpose>
+      <note>Use full path /usr/bin/stat on macOS, regular stat on Linux.</note>
+    </get_worktree_ages>
+    <filter_recent>
+      <exclude_new>For worktrees created within the last 24 hours, let user know that this worktree might not be worth cleaning</exclude_new>
+      <get_current_time>date +"%Y-%m-%d %H:%M"</get_current_time>
+    </filter_recent>
+    <select_oldest>
+      <extract_branch_name>Parse branch name from oldest worktree path</extract_branch_name>
+      <important_note>DO NOT use "git branch --merged" to check merge status - it's unreliable</important_note>
+      <proceed_to_pr_check>Move directly to step 4 to verify PR merge status instead</proceed_to_pr_check>
+    </select_oldest>
+    <purpose>Identify oldest worktree candidate - actual merge verification happens via GitHub PR in next step</purpose>
+  </step_3>
+
+  <step_4>
+    <description>Verify GitHub PR merge status (primary merge verification)</description>
+    <determine_repo>
+      <check_remote>git remote get-url origin</check_remote>
+      <parse_repo>Extract owner/repo from GitHub URL</parse_repo>
+      <fallback>Use project repository from git remote (owner/repo format)</fallback>
+    </determine_repo>
+    <search_pr>
+      <tool>mcp__github__search_pull_requests</tool>
+      <query>repo:owner/repo head:{branch_name} base:main</query>
+      <purpose>Find PR for this branch targeting main</purpose>
+      <important>This is the PRIMARY way to verify if a branch was merged - NOT git commands</important>
+    </search_pr>
+    <verify_pr_merged>
+      <if_pr_found>
+        <get_pr_details>Use mcp__github__pull_request_read to get full PR info</get_pr_details>
+        <confirm_merged>Verify PR state is "closed" AND merged_at is not null AND base is "main"</confirm_merged>
+        <extract_issue_number>Look for issue references in PR title/body (e.g., #14533, owner/repo#14533)</extract_issue_number>
+        <if_merged>Proceed with cleanup - this branch was definitively merged to main</if_merged>
+        <if_not_merged>
+          <skip_worktree>This worktree is NOT merged - continue to next oldest worktree</skip_worktree>
+          <repeat_from_step_3>Go back and find the next oldest worktree to check</repeat_from_step_3>
+        </if_not_merged>
+      </if_pr_found>
+      <if_no_pr>
+        <skip_worktree>No PR found - this branch was likely never submitted for review</skip_worktree>
+        <continue_to_next>Continue checking next oldest worktree</continue_to_next>
+      </if_no_pr>
+    </verify_pr_merged>
+    <purpose>Use GitHub PR status as the authoritative source for merge verification instead of unreliable git commands</purpose>
+  </step_4>
+
+  <step_4_5>
+    <description>Check and close related GitHub issue</description>
+    <if_issue_found>
+      <get_issue_details>
+        <tool>mcp__github__issue_read</tool>
+        <method>get</method>
+        <extract_repo>From issue reference (main-repo vs cross-repo)</extract_repo>
+      </get_issue_details>
+      <check_issue_state>
+        <if_open>
+          <ask_close>Ask user: "Related issue #{number} is still open. Should I close it? (y/N)"</ask_close>
+          <if_yes_close>
+            <add_closing_comment>
+              <tool>mcp__github__add_issue_comment</tool>
+              <body_template>Closing this issue as branch {branch_name} was merged to main on {merge_date} via PR #{pr_number}.</body_template>
+              <get_merge_date>Extract merge date from PR details</get_merge_date>
+              <get_pr_number>Use PR number from search results</get_pr_number>
+            </add_closing_comment>
+            <close_issue>
+              <tool>mcp__github__issue_write</tool>
+              <method>update</method>
+              <state>closed</state>
+              <state_reason>completed</state_reason>
+            </close_issue>
+          </if_yes_close>
+        </if_open>
+        <if_closed>Inform user issue is already closed</if_closed>
+      </check_issue_state>
+    </if_issue_found>
+    <if_no_issue>Continue without issue management</if_no_issue>
+    <purpose>Ensure proper issue lifecycle management</purpose>
+  </step_4_5>
+
+  <step_5>
+    <description>Check if worktree is locked</description>
+    <check_command>git worktree list --porcelain | grep -A5 "worktree {path}" | grep "locked"</check_command>
+    <if_locked>
+      <unlock_command>git worktree unlock {path}</unlock_command>
+      <notify_user>Inform user that worktree was unlocked</notify_user>
+    </if_locked>
+    <purpose>Unlock worktree if it was locked for tracking purposes</purpose>
+  </step_5>
+
+  <step_6>
+    <description>Analyze Claude settings differences</description>
+    <read_main_settings>.claude/settings.local.json</read_main_settings>
+    <read_worktree_settings>{worktree_path}/.claude/settings.local.json</read_worktree_settings>
+    <compare_allow_lists>
+      <extract_main_allows>Extract "allow" array from main settings</extract_main_allows>
+      <extract_worktree_allows>Extract "allow" array from worktree settings</extract_worktree_allows>
+      <find_differences>Identify entries in worktree that are not in main</find_differences>
+    </compare_allow_lists>
+    <filter_suggestions>
+      <include_filesystem>Read permissions for filesystem paths</include_filesystem>
+      <exclude_intrusive>Exclude bash commands, write permissions, etc.</exclude_intrusive>
+      <focus_user_specific>Include only user-specific, non-disruptive entries</focus_user_specific>
+    </filter_suggestions>
+    <purpose>Identify useful settings to consolidate before cleanup</purpose>
+  </step_6>
+
+  <step_7>
+    <description>Suggest settings consolidation</description>
+    <if_differences_found>
+      <display_suggestions>Show filtered differences to user</display_suggestions>
+      <ask_confirmation>Ask user which entries to add to main settings</ask_confirmation>
+      <apply_changes>Update main .claude/settings.local.json with selected entries</apply_changes>
+    </if_differences_found>
+    <if_no_differences>Inform user no settings need consolidation</if_no_differences>
+    <purpose>Preserve useful development settings before removing worktree</purpose>
+  </step_7>
+
+  <step_8>
+    <description>Final cleanup confirmation</description>
+    <summary>
+      <display_worktree>Show worktree path and branch name</display_worktree>
+      <show_pr_status>Show merged PR details if found</show_pr_status>
+      <show_issue_status>Show related issue status if found</show_issue_status>
+      <show_last_activity>Display directory creation/modification date</show_last_activity>
+    </summary>
+    <safety_checks>
+      <check_uncommitted>git status --porcelain in worktree directory</check_uncommitted>
+      <warn_if_dirty>Alert user if uncommitted changes exist</warn_if_dirty>
+    </safety_checks>
+    <ask_deletion>Ask user confirmation: "Delete this worktree? (y/N)"</ask_deletion>
+    <purpose>Final safety check before irreversible deletion</purpose>
+  </step_8>
+
+  <step_9>
+    <description>Delete worktree</description>
+    <if_confirmed>
+      <remove_worktree>git worktree remove {path} --force</remove_worktree>
+      <cleanup_branch>git branch -d {branch_name}</cleanup_branch>
+      <success_message>Inform user worktree was successfully removed</success_message>
+      <next_steps>Suggest running command again to find next candidate</next_steps>
+    </if_confirmed>
+    <if_declined>Exit gracefully with no changes</if_declined>
+    <purpose>Perform the actual cleanup and guide user for next iteration</purpose>
+  </step_9>
+</execution_steps>
+
+<important_notes>
+
+- Uses GitHub PR merge status as the ONLY reliable way to verify if a branch was merged
+- DOES NOT use "git branch --merged" command as it's unreliable for merge verification
+- Only processes branches with PRs that were definitively merged to main
+- Skips worktrees without merged PRs and continues to next oldest candidate
+- Checks and optionally closes related GitHub issues
+- Prioritizes oldest worktrees by directory age first for systematic cleanup
+- Warns about very recent worktrees (created within 24 hours) to avoid cleaning active work
+- Preserves useful development settings before deletion
+- Requires explicit confirmation before any destructive actions
+- Handles locked worktrees automatically
+- Processes one worktree at a time to maintain control
+- Must be run from main branch for safety
+- Works with standard GitHub repository URLs (owner/repo format)
+</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