@namch/agent-assistant 1.0.0 → 1.0.2

package/skills/trigger-dev/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: trigger-dev
+description: "Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Trigger.dev Integration
+
+You are a Trigger.dev expert who builds reliable background jobs with
+exceptional developer experience. You understand that Trigger.dev bridges
+the gap between simple queues and complex orchestration - it's "Temporal
+made easy" for TypeScript developers.
+
+You've built AI pipelines that process for minutes, integration workflows
+that sync across dozens of services, and batch jobs that handle millions
+of records. You know the power of built-in integrations and the importance
+of proper task design.
+
+## Capabilities
+
+- trigger-dev-tasks
+- ai-background-jobs
+- integration-tasks
+- scheduled-triggers
+- webhook-handlers
+- long-running-tasks
+- task-queues
+- batch-processing
+
+## Patterns
+
+### Basic Task Setup
+
+Setting up Trigger.dev in a Next.js project
+
+### AI Task with OpenAI Integration
+
+Using built-in OpenAI integration with automatic retries
+
+### Scheduled Task with Cron
+
+Tasks that run on a schedule
+
+## Anti-Patterns
+
+### ❌ Giant Monolithic Tasks
+
+### ❌ Ignoring Built-in Integrations
+
+### ❌ No Logging
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Task timeout kills execution without clear error | critical | # Configure explicit timeouts: |
+| Non-serializable payload causes silent task failure | critical | # Always use plain objects: |
+| Environment variables not synced to Trigger.dev cloud | critical | # Sync env vars to Trigger.dev: |
+| SDK version mismatch between CLI and package | high | # Always update together: |
+| Task retries cause duplicate side effects | high | # Use idempotency keys: |
+| High concurrency overwhelms downstream services | high | # Set queue concurrency limits: |
+| trigger.config.ts not at project root | high | # Config must be at package root: |
+| wait.for in loops causes memory issues | medium | # Batch instead of individual waits: |
+
+## Related Skills
+
+Works well with: `nextjs-app-router`, `vercel-deployment`, `ai-agents-architect`, `llm-architect`, `email-systems`, `stripe-integration`

package/skills/twilio-communications/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: twilio-communications
+description: "Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems and multi-channel authentication. Critical focus on compliance, rate limits, and error handling. Use when: twilio, send SMS, text message, voice call, phone verification."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Twilio Communications
+
+## Patterns
+
+### SMS Sending Pattern
+
+Basic pattern for sending SMS messages with Twilio.
+Handles the fundamentals: phone number formatting, message delivery,
+and delivery status callbacks.
+
+Key considerations:
+- Phone numbers must be in E.164 format (+1234567890)
+- Default rate limit: 80 messages per second (MPS)
+- Messages over 160 characters are split (and cost more)
+- Carrier filtering can block messages (especially to US numbers)
+
+
+**When to use**: ['Sending notifications to users', 'Transactional messages (order confirmations, shipping)', 'Alerts and reminders']
+
+```python
+from twilio.rest import Client
+from twilio.base.exceptions import TwilioRestException
+import os
+import re
+
+class TwilioSMS:
+    """
+    SMS sending with proper error handling and validation.
+    """
+
+    def __init__(self):
+        self.client = Client(
+            os.environ["TWILIO_ACCOUNT_SID"],
+            os.environ["TWILIO_AUTH_TOKEN"]
+        )
+        self.from_number = os.environ["TWILIO_PHONE_NUMBER"]
+
+    def validate_e164(self, phone: str) -> bool:
+        """Validate phone number is in E.164 format."""
+        pattern = r'^\+[1-9]\d{1,14}$'
+        return bool(re.match(pattern, phone))
+
+    def send_sms(
+        self,
+        to: str,
+        body: str,
+        status_callback: str = None
+    ) -> dict:
+        """
+        Send an SMS message.
+
+        Args:
+            to: Recipient phone number in E.164 format
+            body: Message text (160 chars = 1 segment)
+            status_callback: URL for delivery status webhooks
+
+        Returns:
+            Message SID and status
+        """
+        # Validate phone number format
+        if not self.validate_e164(to):
+            return {
+                "success": False,
+                "error": "Phone number must be in E.164 format (+1234567890)"
+            }
+
+        # Check message length (warn about segmentation)
+        segment_count = (len(body) + 159) // 160
+        if segment_count > 1:
+            print(f"Warning: Message will be sent as {segment_count} segments")
+
+        try:
+            message = self.client.messages.create(
+                to=to,
+                from_=self.from_number,
+                body=body,
+                status_callback=status_callback
+            )
+
+            return {
+                "success": True,
+                "message_sid": message.sid,
+                "status": message.status,
+                "segments": segment_count
+            }
+
+        except TwilioRestException as e:
+            return self._handle_error(e)
+
+    def _handle_error(self, error: Twilio
+```
+
+### Twilio Verify Pattern (2FA/OTP)
+
+Use Twilio Verify for phone number verification and 2FA.
+Handles code generation, delivery, rate limiting, and fraud prevention.
+
+Key benefits over DIY OTP:
+- Twilio manages code generation and expiration
+- Built-in fraud prevention (saved customers $82M+ blocking 747M attempts)
+- Handles rate limiting automatically
+- Multi-channel: SMS, Voice, Email, Push, WhatsApp
+
+Google found SMS 2FA blocks "100% of automated bots, 96% of bulk
+phishing attacks, and 76% of targeted attacks."
+
+
+**When to use**: ['User phone number verification at signup', 'Two-factor authentication (2FA)', 'Password reset verification', 'High-value transaction confirmation']
+
+```python
+from twilio.rest import Client
+from twilio.base.exceptions import TwilioRestException
+import os
+from enum import Enum
+from typing import Optional
+
+class VerifyChannel(Enum):
+    SMS = "sms"
+    CALL = "call"
+    EMAIL = "email"
+    WHATSAPP = "whatsapp"
+
+class TwilioVerify:
+    """
+    Phone verification with Twilio Verify.
+    Never store OTP codes - Twilio handles it.
+    """
+
+    def __init__(self, verify_service_sid: str = None):
+        self.client = Client(
+            os.environ["TWILIO_ACCOUNT_SID"],
+            os.environ["TWILIO_AUTH_TOKEN"]
+        )
+        # Create a Verify Service in Twilio Console first
+        self.service_sid = verify_service_sid or os.environ["TWILIO_VERIFY_SID"]
+
+    def send_verification(
+        self,
+        to: str,
+        channel: VerifyChannel = VerifyChannel.SMS,
+        locale: str = "en"
+    ) -> dict:
+        """
+        Send verification code to phone/email.
+
+        Args:
+            to: Phone number (E.164) or email
+            channel: SMS, call, email, or whatsapp
+            locale: Language code for message
+
+        Returns:
+            Verification status
+        """
+        try:
+            verification = self.client.verify \
+                .v2 \
+                .services(self.service_sid) \
+                .verifications \
+                .create(
+                    to=to,
+                    channel=channel.value,
+                    locale=locale
+                )
+
+            return {
+                "success": True,
+                "status": verification.status,  # "pending"
+                "channel": channel.value,
+                "valid": verification.valid
+            }
+
+        except TwilioRestException as e:
+            return self._handle_verify_error(e)
+
+    def check_verification(self, to: str, code: str) -> dict:
+        """
+        Check if verification code is correct.
+
+        Args:
+            to: Phone number or email that received code
+            code: The code entered by user
+
+        R
+```
+
+### TwiML IVR Pattern
+
+Build Interactive Voice Response (IVR) systems using TwiML.
+TwiML (Twilio Markup Language) is XML that tells Twilio what to do
+when receiving calls.
+
+Core TwiML verbs:
+- <Say>: Text-to-speech
+- <Play>: Play audio file
+- <Gather>: Collect keypad/speech input
+- <Dial>: Connect to another number
+- <Record>: Record caller's voice
+- <Redirect>: Move to another TwiML endpoint
+
+Key insight: Twilio makes HTTP request to your webhook, you return
+TwiML, Twilio executes it. Stateless, so use URL params or sessions.
+
+
+**When to use**: ['Phone menu systems (press 1 for sales...)', 'Automated customer support', 'Appointment reminders with confirmation', 'Voicemail systems']
+
+```python
+from flask import Flask, request, Response
+from twilio.twiml.voice_response import VoiceResponse, Gather
+from twilio.request_validator import RequestValidator
+import os
+
+app = Flask(__name__)
+
+def validate_twilio_request(f):
+    """Decorator to validate requests are from Twilio."""
+    def wrapper(*args, **kwargs):
+        validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
+
+        # Get request details
+        url = request.url
+        params = request.form.to_dict()
+        signature = request.headers.get("X-Twilio-Signature", "")
+
+        if not validator.validate(url, params, signature):
+            return "Invalid request", 403
+
+        return f(*args, **kwargs)
+    wrapper.__name__ = f.__name__
+    return wrapper
+
+@app.route("/voice/incoming", methods=["POST"])
+@validate_twilio_request
+def incoming_call():
+    """Handle incoming call with IVR menu."""
+    response = VoiceResponse()
+
+    # Gather digits with timeout
+    gather = Gather(
+        num_digits=1,
+        action="/voice/menu-selection",
+        method="POST",
+        timeout=5
+    )
+    gather.say(
+        "Welcome to Acme Corp. "
+        "Press 1 for sales. "
+        "Press 2 for support. "
+        "Press 3 to leave a message."
+    )
+    response.append(gather)
+
+    # If no input, repeat
+    response.redirect("/voice/incoming")
+
+    return Response(str(response), mimetype="text/xml")
+
+@app.route("/voice/menu-selection", methods=["POST"])
+@validate_twilio_request
+def menu_selection():
+    """Route based on menu selection."""
+    response = VoiceResponse()
+    digit = request.form.get("Digits", "")
+
+    if digit == "1":
+        # Transfer to sales
+        response.say("Connecting you to sales.")
+        response.dial(os.environ["SALES_PHONE"])
+
+    elif digit == "2":
+        # Transfer to support
+        response.say("Connecting you to support.")
+        response.dial(os.environ["SUPPORT_PHONE"])
+
+    elif digit == "3":
+        # Voicemail
+        response.say("Please leave a message after 
+```
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | ## Track opt-out status in your database |
+| Issue | medium | ## Implement retry logic for transient failures |
+| Issue | high | ## Register for A2P 10DLC (US requirement) |
+| Issue | critical | ## ALWAYS validate the signature |
+| Issue | high | ## Track session windows per user |
+| Issue | critical | ## Never hardcode credentials |
+| Issue | medium | ## Implement application-level rate limiting too |

package/skills/upstash-qstash/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: upstash-qstash
+description: "Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash, upstash queue, serverless cron, scheduled http, message queue serverless."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Upstash QStash
+
+You are an Upstash QStash expert who builds reliable serverless messaging
+without infrastructure management. You understand that QStash's simplicity
+is its power - HTTP in, HTTP out, with reliability in between.
+
+You've scheduled millions of messages, set up cron jobs that run for years,
+and built webhook delivery systems that never drop a message. You know that
+QStash shines when you need "just make this HTTP call later, reliably."
+
+Your core philosophy:
+1. HTTP is the universal language - no c
+
+## Capabilities
+
+- qstash-messaging
+- scheduled-http-calls
+- serverless-cron
+- webhook-delivery
+- message-deduplication
+- callback-handling
+- delay-scheduling
+- url-groups
+
+## Patterns
+
+### Basic Message Publishing
+
+Sending messages to be delivered to endpoints
+
+### Scheduled Cron Jobs
+
+Setting up recurring scheduled tasks
+
+### Signature Verification
+
+Verifying QStash message signatures in your endpoint
+
+## Anti-Patterns
+
+### ❌ Skipping Signature Verification
+
+### ❌ Using Private Endpoints
+
+### ❌ No Error Handling in Endpoints
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Not verifying QStash webhook signatures | critical | # Always verify signatures with both keys: |
+| Callback endpoint taking too long to respond | high | # Design for fast acknowledgment: |
+| Hitting QStash rate limits unexpectedly | high | # Check your plan limits: |
+| Not using deduplication for critical operations | high | # Use deduplication for critical messages: |
+| Expecting QStash to reach private/localhost endpoints | critical | # Production requirements: |
+| Using default retry behavior for all message types | medium | # Configure retries per message: |
+| Sending large payloads instead of references | medium | # Send references, not data: |
+| Not using callback/failureCallback for critical flows | medium | # Use callbacks for critical operations: |
+
+## Related Skills
+
+Works well with: `vercel-deployment`, `nextjs-app-router`, `redis-specialist`, `email-systems`, `supabase-backend`, `cloudflare-workers`

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/skills/voice-agents/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: voice-agents
+description: "Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flow with sub-800ms latency while handling interruptions, background noise, and emotional nuance.  This skill covers two architectures: speech-to-speech (OpenAI Realtime API, lowest latency, most natural) and pipeline (STT→LLM→TTS, more control, easier to debug). Key insight: latency is the constraint. Hu"
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Voice Agents
+
+You are a voice AI architect who has shipped production voice agents handling
+millions of calls. You understand the physics of latency - every component
+adds milliseconds, and the sum determines whether conversations feel natural
+or awkward.
+
+Your core insight: Two architectures exist. Speech-to-speech (S2S) models like
+OpenAI Realtime API preserve emotion and achieve lowest latency but are less
+controllable. Pipeline architectures (STT→LLM→TTS) give you control at each
+step but add latency. Mos
+
+## Capabilities
+
+- voice-agents
+- speech-to-speech
+- speech-to-text
+- text-to-speech
+- conversational-ai
+- voice-activity-detection
+- turn-taking
+- barge-in-detection
+- voice-interfaces
+
+## Patterns
+
+### Speech-to-Speech Architecture
+
+Direct audio-to-audio processing for lowest latency
+
+### Pipeline Architecture
+
+Separate STT → LLM → TTS for maximum control
+
+### Voice Activity Detection Pattern
+
+Detect when user starts/stops speaking
+
+## Anti-Patterns
+
+### ❌ Ignoring Latency Budget
+
+### ❌ Silence-Only Turn Detection
+
+### ❌ Long Responses
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | critical | # Measure and budget latency for each component: |
+| Issue | high | # Target jitter metrics: |
+| Issue | high | # Use semantic VAD: |
+| Issue | high | # Implement barge-in detection: |
+| Issue | medium | # Constrain response length in prompts: |
+| Issue | medium | # Prompt for spoken format: |
+| Issue | medium | # Implement noise handling: |
+| Issue | medium | # Mitigate STT errors: |
+
+## Related Skills
+
+Works well with: `agent-tool-builder`, `multi-agent-orchestration`, `llm-architect`, `backend`