@supa-media/claude 1.0.2

package/templates/commands/feature-validate.md

@@ -0,0 +1,189 @@
+# Feature Validation Agent
+
+A testing and validation agent that validates, completes, and polishes features based on handoff instructions from other agents or developers.
+
+## Usage
+
+```
+/feature-validate <handoff-instructions>
+```
+
+The handoff instructions should include:
+- Feature overview
+- Code locations (files, worktree, branch)
+- Pre-test setup steps
+- Test workflow
+- Expected behavior
+
+## Agent Instructions
+
+You are a Feature Validation agent. Your job is to validate a feature implementation, complete any unfinished work, and polish it for production.
+
+### Phase 1: Setup Environment
+
+1. **Parse the handoff instructions** to understand:
+   - Which git worktree/branch to work in
+   - What dependencies need to be installed
+   - What migrations or setup steps need to run
+   - What servers need to be started
+
+2. **Set up isolated testing environment:**
+   ```bash
+   # If working in a different worktree, cd to it
+   cd <worktree-path>
+
+   # Install dependencies
+   pnpm install
+
+   # Run any required database migrations or setup
+   # (details from handoff instructions)
+
+   # Start servers on custom ports if needed (to avoid conflicts)
+   pnpm dev
+   ```
+
+3. **Verify environment is ready:**
+   - Check that servers are responding
+   - Verify all required services are connected
+   - Ensure test credentials/data are set up
+
+### Phase 2: Code Review
+
+1. **Review implementation for completeness:**
+   ```bash
+   # Check git status
+   git status
+
+   # Review recent commits
+   git log --oneline -10
+
+   # Look for TODO comments
+   grep -r "TODO" --include="*.ts" --include="*.tsx" <relevant-paths>
+   ```
+
+2. **Verify key files exist and are complete:**
+   - Check all files mentioned in handoff
+   - Verify exports and registrations
+   - Check for missing imports
+
+3. **Identify potential issues:**
+   - ID mismatches (frontend vs backend)
+   - Timezone or date handling issues
+   - Error handling
+   - Edge cases
+   - Missing validation
+
+### Phase 3: Fix Issues Found
+
+For each issue identified:
+
+1. **Document the issue** - What's wrong and why
+2. **Create a fix** - Make minimal, focused changes
+3. **Commit immediately** - Atomic commits for each fix
+   ```bash
+   git add <files>
+   git commit -m "fix: <description>
+
+   <detailed explanation>
+
+   Co-Authored-By: Claude <noreply@anthropic.com>"
+   ```
+
+### Phase 4: Visual/Integration Testing
+
+1. **Test via Playwright** (for web apps):
+   - Use `mcp__playwright__browser_navigate` to open the app
+   - Use `mcp__playwright__browser_snapshot` to see accessibility tree
+   - Click through the feature workflow
+   - Use `mcp__playwright__browser_take_screenshot` to capture evidence
+
+2. **Test via iOS Simulator** (for mobile apps):
+   - Use `mcp__ios-simulator__ui_view` to see current screen
+   - Navigate through the feature workflow
+   - Use `mcp__ios-simulator__ui_tap` and `mcp__ios-simulator__ui_type` to interact
+
+3. **Test API directly** (if backend):
+   ```bash
+   # Use Convex CLI to test functions
+   npx convex run functions/<function-name>
+   ```
+
+### Phase 5: Verification Checklist
+
+Before marking complete, verify:
+
+- [ ] All files mentioned in handoff exist and are complete
+- [ ] No TODO comments left in the code
+- [ ] No debug console.logs left behind
+- [ ] Error handling is in place
+- [ ] Edge cases are handled
+- [ ] UI renders correctly
+- [ ] API endpoints work correctly
+- [ ] Data persists after save
+- [ ] Feature works end-to-end
+
+### Phase 6: Final Report
+
+Provide a summary:
+
+```markdown
+## Feature Validation Report
+
+**Feature:** <feature name>
+**Branch:** <branch name>
+**Status:** Validated / Needs Work
+
+### Code Review Results
+- Files reviewed: X
+- Issues found: Y
+- Issues fixed: Z
+
+### Testing Results
+- API: Passed/Failed
+- UI: Passed/Failed
+- Integration: Passed/Failed
+
+### Changes Made
+- <commit hash> - <description>
+- <commit hash> - <description>
+
+### Outstanding Issues
+- <issue 1> (if any)
+- <issue 2> (if any)
+
+### Manual Testing Required
+- <test 1> (if couldn't be automated)
+- <test 2> (if couldn't be automated)
+```
+
+## Test Credentials
+
+The handoff instructions should include test credentials or point to a seed/fixture file. Use the appropriate test data for the feature you're validating.
+
+## Troubleshooting
+
+### Watchman Issues
+
+If you encounter "FSEventStreamStart failed" errors:
+```bash
+# Watchman may be corrupted - reset it
+brew reinstall watchman
+
+# Clear Watchman state
+rm -rf ~/.local/state/watchman
+```
+
+### Port Conflicts
+If ports are in use:
+```bash
+# Kill process on specific port
+lsof -ti :<port> | xargs kill -9
+```
+
+## Safety Rules
+
+1. **Work in the specified worktree/branch** - Don't pollute main
+2. **Use separate ports** - Avoid disrupting other dev servers
+3. **Commit frequently** - Small, atomic commits
+4. **Don't push unless asked** - Let the user decide when to merge
+5. **Document blockers** - If something can't be tested, explain why

package/templates/commands/fix-ci.md

@@ -0,0 +1,304 @@
+# CI Fix Agent
+
+Investigates CI/CD pipeline failures, fixes the root cause, and adds regression tests to prevent future occurrences.
+
+## Usage
+
+```
+/fix-ci <github-actions-url>
+```
+
+Example:
+```
+/fix-ci https://github.com/OWNER/REPO/actions/runs/20758445422/job/59606854681
+```
+
+You can also provide just the run ID:
+```
+/fix-ci 20758445422
+```
+
+## Agent Instructions
+
+You are a CI Fix agent. Your job is to investigate CI/CD failures, understand the root cause, fix the issue, and add tests to prevent the same failure from happening again.
+
+### Phase 1: Investigate the Failure
+
+1. **Fetch the failed job logs:**
+   ```bash
+   # If given a full URL, extract the run ID
+   gh run view <run-id> --log-failed 2>&1 | head -500
+   ```
+
+2. **Get run details:**
+   ```bash
+   gh run view <run-id> --json conclusion,status,name,headBranch,event
+   ```
+
+3. **Identify the failure:**
+   - Look for error messages (lines with `error`, `Error`, `ERROR`, `failed`, `FAILED`)
+   - Look for TypeScript errors (`error TS`)
+   - Look for test failures (`FAIL`, `AssertionError`)
+   - Look for build failures (`Build failed`, `exit code 1`)
+   - Look for Docker build failures (`#XX ERROR`, `failed to build`)
+
+4. **Document the failure:**
+   ```markdown
+   ## CI Failure Analysis
+
+   **Run ID:** <run-id>
+   **Branch:** <branch>
+   **Job:** <job-name>
+   **Error Type:** Build / Test / Deploy / Type Check
+   **Error Message:** <exact error>
+   **File(s) Affected:** <file paths>
+   ```
+
+### Phase 2: Root Cause Analysis
+
+1. **Read the affected files:**
+   - Use the file paths from error messages
+   - Understand the code context around the failure
+
+2. **Trace the dependency chain:**
+   - If it's a module not found error, check package.json dependencies
+   - If it's a type error, trace the type definitions
+   - If it's a build error, check build configuration (Dockerfile, tsconfig, turbo.json, etc.)
+
+3. **Identify when the issue was introduced:**
+   ```bash
+   # Check recent commits on the branch
+   gh run view <run-id> --json headSha --jq '.headSha'
+   git log --oneline -10 <sha>
+   ```
+
+4. **Determine preventability:**
+   Ask yourself:
+   - Could a unit test have caught this?
+   - Could a build/type-check test have caught this?
+   - Could a configuration validation test have caught this?
+   - Was this a missing dependency that could be validated?
+
+### Phase 3: Fix the Issue
+
+1. **Create a fix branch:**
+   ```bash
+   git fetch origin main
+   git checkout main
+   git pull origin main
+   git checkout -b fix/ci-<descriptive-name>
+   ```
+
+2. **Implement the fix:**
+   - Make the minimal change needed to fix the issue
+   - Follow existing code patterns
+   - Don't introduce unrelated changes
+
+3. **Verify the fix locally:**
+   ```bash
+   # Run the same checks that failed in CI
+   # Use package filters if applicable (e.g., pnpm --filter=<package> for monorepos)
+   pnpm build
+   pnpm typecheck
+   pnpm test
+   ```
+
+### Phase 4: Add Regression Tests
+
+**This is critical.** For every CI fix, determine what test could have prevented it:
+
+#### For Missing Dependencies (Docker/Workspace Issues)
+
+If the failure was a missing dependency in Docker or workspace configuration:
+
+```typescript
+// Example: dockerfile.test.ts or workspace.test.ts
+describe('Workspace Configuration', () => {
+  it('should include all required package dependencies', () => {
+    // Read package.json and Dockerfile/config
+    // Verify all workspace:* dependencies are properly included
+  });
+});
+```
+
+#### For Type Errors
+
+The TypeScript compiler should catch these, but ensure:
+- `typecheck` script exists and runs in CI
+- `strict` mode is enabled in tsconfig
+
+#### For Build Configuration Errors
+
+Create a test that validates the configuration:
+
+```typescript
+// Example: tsconfig.test.ts
+describe('tsconfig.json', () => {
+  it('should have correct module settings', () => {
+    // Read and validate tsconfig
+  });
+});
+```
+
+#### For Runtime Errors
+
+Create a unit test that exercises the failing code path:
+
+```typescript
+// Example: feature.test.ts
+describe('Feature', () => {
+  it('should handle edge case that caused CI failure', () => {
+    // Test the specific scenario
+  });
+});
+```
+
+#### Test Location Guidelines
+
+| Error Type | Test Location |
+|------------|---------------|
+| Docker/workspace dependency issues | `apps/<app>/src/__tests__/dockerfile.test.ts` or `__tests__/workspace.test.ts` |
+| tsconfig issues | `apps/<app>/src/__tests__/tsconfig.test.ts` |
+| Package.json issues | `apps/<app>/src/__tests__/package.test.ts` |
+| Build script issues | `apps/<app>/src/__tests__/build.test.ts` |
+| Runtime errors | Near the affected code in `__tests__/` folder |
+
+### Phase 5: Create PR and Review Cycle
+
+1. **Run all tests to verify:**
+   ```bash
+   pnpm test
+   ```
+
+2. **Commit the changes:**
+   ```bash
+   git add .
+   git commit -m "fix: <description of CI fix>
+
+   Root cause: <brief explanation>
+   Prevention: Added <test-name> test to catch this in the future.
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+   Co-Authored-By: Claude <noreply@anthropic.com>"
+   ```
+
+3. **Push and create PR:**
+   ```bash
+   git push -u origin fix/ci-<descriptive-name>
+
+   gh pr create --title "fix: <CI fix description>" --body "$(cat <<'EOF'
+   ## Summary
+   Fixes CI/CD pipeline failure from run #<run-id>.
+
+   ## Root Cause
+   <explanation of what caused the failure>
+
+   ## Fix
+   <description of the fix>
+
+   ## Prevention
+   Added regression test(s) to prevent this from happening again:
+   - `<test-file>`: <what it validates>
+
+   ## Test plan
+   - [x] Local build passes
+   - [x] Local tests pass
+   - [x] New regression test passes
+   - [ ] CI pipeline passes
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   EOF
+   )" --base main
+   ```
+
+4. **Launch review cycle:**
+   ```
+   /review-cycle <pr-number>
+   ```
+
+### Phase 6: Final Summary
+
+Provide a complete summary:
+
+```markdown
+## CI Fix Complete
+
+**Original Failure:** Run #<run-id>
+**PR:** #<pr-number>
+**Status:** Ready for review / Review cycle complete
+
+### Root Cause
+<detailed explanation>
+
+### Fix Applied
+- <file>: <change description>
+
+### Tests Added
+- `<test-file>`: <what it prevents>
+
+### Verification
+- Local build: PASS
+- Local tests: PASS
+- New regression test: PASS
+```
+
+## Common CI Failure Patterns
+
+### Pattern 1: Missing Workspace Dependency in Docker
+
+**Symptoms:**
+```
+error TS2307: Cannot find module '@workspace/xxx'
+or in Dockerfile build step:
+failed to copy file/directory or build context
+```
+
+**Fix:**
+1. Check Dockerfile and ensure all workspace packages are copied
+2. Check package.json workspace dependencies are included
+3. Add regression test in `dockerfile.test.ts` or `workspace.test.ts`
+
+### Pattern 2: TypeScript Configuration Mismatch
+
+**Symptoms:**
+```
+error TS1259: Module can only be default-imported using...
+```
+
+**Fix:**
+1. Check tsconfig.json settings
+2. Ensure `esModuleInterop` and `moduleResolution` are correct
+3. Add regression test in `tsconfig.test.ts`
+
+### Pattern 3: Missing Environment Variable
+
+**Symptoms:**
+```
+Error: Missing required environment variable: XXX
+```
+
+**Fix:**
+1. Add to CI workflow secrets
+2. Add validation in code with helpful error message
+3. Document in README or .env.example
+
+### Pattern 4: Dependency Version Mismatch
+
+**Symptoms:**
+```
+peer dep missing: xxx@^2.0.0, found xxx@1.0.0
+```
+
+**Fix:**
+1. Update package.json dependency version
+2. Run `pnpm install` to update lockfile
+3. Test locally before pushing
+
+## Safety Rules
+
+1. **Always reproduce locally first** - Don't push fixes without verifying they work
+2. **Minimal changes only** - Fix the CI issue, nothing else
+3. **Always add a test** - Every CI fix should have a corresponding regression test
+4. **Document the root cause** - Future developers need to understand why
+5. **Don't skip the review cycle** - Even urgent fixes need bot review

package/templates/commands/ios-build.md

@@ -0,0 +1,188 @@
+# iOS Build and App Store Deployment
+
+Guide for building iOS apps and submitting to App Store Connect.
+
+## Version Management
+
+This project uses a **bare workflow** with a native `ios/` folder. Version numbers must be updated in multiple places:
+
+### Files to Update
+
+1. **`apps/mobile/ios/<AppName>/Info.plist`** (Primary for native builds)
+   - `CFBundleShortVersionString` - Marketing version shown in App Store (e.g., "1.0.13")
+   - `CFBundleVersion` - Build number, auto-incremented by EAS
+
+2. **`apps/mobile/app.config.js`** (Expo configuration)
+   - `version` - Should match Info.plist CFBundleShortVersionString
+   - `runtimeVersion` - Used for OTA updates compatibility
+
+### How to Change Version
+
+```bash
+# In Info.plist, update:
+<key>CFBundleShortVersionString</key>
+<string>1.0.14</string>  # Change this
+
+# In app.config.js, update:
+version: "1.0.14",        # Match Info.plist
+runtimeVersion: "1.0.14", # Match for OTA compatibility
+```
+
+**Important**: In bare workflow, EAS uses Info.plist for the actual build version, not app.config.js. Keep them in sync to avoid confusion.
+
+---
+
+## Local Builds (Free)
+
+Local builds run on your Mac using EAS credentials but don't consume cloud build credits.
+
+### Prerequisites
+- Xcode installed with iOS SDK
+- Valid Apple Developer account linked to EAS
+- CocoaPods installed (`gem install cocoapods`)
+
+### Build Command
+
+```bash
+cd apps/mobile
+eas build --platform ios --profile production --local --non-interactive
+```
+
+### What Happens
+1. EAS downloads your provisioning profiles and certificates
+2. Build runs locally using Xcode on your machine
+3. Outputs an `.ipa` file in `apps/mobile/`
+4. Build number auto-increments per EAS profile settings
+
+### Submit Local Build to App Store
+
+```bash
+# Find your IPA file
+ls apps/mobile/build-*.ipa
+
+# Submit to App Store Connect
+eas submit --platform ios --path ./build-TIMESTAMP.ipa
+```
+
+---
+
+## Cloud Builds ($2/build)
+
+Cloud builds run on EAS servers. Useful when you don't have a Mac or need CI/CD.
+
+### Build Only
+
+```bash
+cd apps/mobile
+eas build --platform ios --profile production --non-interactive
+```
+
+### Build and Auto-Submit
+
+```bash
+cd apps/mobile
+eas build --platform ios --profile production --auto-submit --non-interactive
+```
+
+This builds on EAS servers and automatically submits to App Store Connect when complete.
+
+### Check Build Status
+
+```bash
+# List recent builds
+eas build:list --platform ios --limit 5
+
+# View specific build logs
+eas build:view
+```
+
+---
+
+## Adding Native Permissions
+
+When adding Expo libraries that require native permissions (location, camera, contacts, etc.), update `Info.plist`:
+
+### Common Permissions
+
+```xml
+<!-- Location -->
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your location to show nearby events</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your location</string>
+
+<!-- Motion/Sensors -->
+<key>NSMotionUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to detect device motion for interactive features</string>
+
+<!-- Calendar -->
+<key>NSCalendarsUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to add events to your calendar</string>
+<key>NSCalendarsFullAccessUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your calendars</string>
+
+<!-- Contacts -->
+<key>NSContactsUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your contacts to invite friends</string>
+
+<!-- Camera -->
+<key>NSCameraUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your camera</string>
+
+<!-- Microphone -->
+<key>NSMicrophoneUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your microphone</string>
+
+<!-- Photos -->
+<key>NSPhotoLibraryUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to access your photos</string>
+<key>NSPhotoLibraryAddUsageDescription</key>
+<string>Allow $(PRODUCT_NAME) to save photos</string>
+```
+
+### After Adding Permissions
+
+1. Rebuild the native app (OTA updates cannot add new permissions)
+2. Test on device to verify permission prompts appear correctly
+
+---
+
+## OTA Updates vs Native Builds
+
+### OTA Updates (No App Store Review)
+- JavaScript/TypeScript code changes
+- Asset changes (images, fonts)
+- Does NOT require new build
+
+```bash
+cd apps/mobile
+pnpm update:ota
+```
+
+### Native Builds Required
+- New Expo libraries with native code
+- New iOS permissions
+- Changes to Info.plist, Podfile, or native Swift/Objective-C code
+- Expo SDK upgrades
+
+---
+
+## Build Profiles
+
+Defined in `apps/mobile/eas.json`:
+
+- **preview**: Development/testing builds
+- **production**: App Store distribution builds (auto-increment enabled)
+
+---
+
+## Troubleshooting
+
+### "Provisioning profile doesn't support Push Notifications"
+Use `eas build --local` instead of direct Xcode builds. EAS manages the correct distribution profiles.
+
+### Build number conflicts
+EAS auto-increments build numbers. If you get conflicts, check `eas build:list` for the latest build number.
+
+### Version not updating
+In bare workflow, update `Info.plist` directly. The `app.config.js` version is not used for native builds.