wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/ad-creative/references/platform-specs.md

@@ -0,0 +1,213 @@
+# Platform Specs Reference
+
+Complete character limits, format requirements, and best practices for each ad platform.
+
+---
+
+## Google Ads
+
+### Responsive Search Ads (RSAs)
+
+| Element | Character Limit | Required | Notes |
+|---------|----------------|----------|-------|
+| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together |
+| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together |
+| Display path 1 | 15 chars | Optional | Appears after domain in URL |
+| Display path 2 | 15 chars | Optional | Appears after path 1 |
+| Final URL | No limit | Required | Landing page URL |
+
+**Combination rules:**
+- Google selects up to 3 headlines and 2 descriptions to show
+- Headlines appear separated by " | " or stacked
+- Any headline can appear in any position unless pinned
+- Pinning reduces Google's ability to optimize — use sparingly
+
+**Pinning strategy:**
+- Pin your brand name to position 1 if brand guidelines require it
+- Pin your strongest CTA to position 2 or 3
+- Leave most headlines unpinned for machine learning
+
+**Headline mix recommendation (15 headlines):**
+- 3-4 keyword-focused (match search intent)
+- 3-4 benefit-focused (what they get)
+- 2-3 social proof (numbers, awards, customers)
+- 2-3 CTA-focused (action to take)
+- 1-2 differentiators (why you over competitors)
+- 1 brand name headline
+
+**Description mix recommendation (4 descriptions):**
+- 1 benefit + proof point
+- 1 feature + outcome
+- 1 social proof + CTA
+- 1 urgency/offer + CTA (if applicable)
+
+### Performance Max
+
+| Element | Character Limit | Notes |
+|---------|----------------|-------|
+| Headline | 30 chars (5 required) | Short headlines for various placements |
+| Long headline | 90 chars (5 required) | Used in display, video, discover |
+| Description | 90 chars (1 required, 5 max) | Accompany various ad formats |
+| Business name | 25 chars | Required |
+
+### Display Ads
+
+| Element | Character Limit |
+|---------|----------------|
+| Headline | 30 chars |
+| Long headline | 90 chars |
+| Description | 90 chars |
+| Business name | 25 chars |
+
+---
+
+## Meta Ads (Facebook & Instagram)
+
+### Single Image / Video / Carousel
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 |
+| Headline | 40 chars | 255 chars | Below image; truncated after ~40 |
+| Description | 30 chars | 255 chars | Below headline; may not show |
+| URL display link | 40 chars | N/A | Optional custom display URL |
+
+**Placement-specific notes:**
+- **Feed**: All elements show; primary text most visible
+- **Stories/Reels**: Primary text overlaid; keep under 72 chars
+- **Right column**: Only headline visible; skip description
+- **Audience Network**: Varies by publisher
+
+**Best practices:**
+- Front-load the hook in primary text (first 125 chars)
+- Use line breaks for readability in longer primary text
+- Emojis: test, but don't overuse — 1-2 per ad max
+- Questions in primary text increase engagement
+- Headline should be a clear CTA or value statement
+
+### Lead Ads (Instant Form)
+
+| Element | Limit |
+|---------|-------|
+| Greeting headline | 60 chars |
+| Greeting description | 360 chars |
+| Privacy policy text | 200 chars |
+
+---
+
+## LinkedIn Ads
+
+### Single Image Ad
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 |
+| Headline | 70 chars | 200 chars | Below the image |
+| Description | 100 chars | 300 chars | Only shows on Audience Network |
+
+### Carousel Ad
+
+| Element | Limit |
+|---------|-------|
+| Intro text | 255 chars |
+| Card headline | 45 chars |
+| Card count | 2-10 cards |
+
+### Message Ad (InMail)
+
+| Element | Limit |
+|---------|-------|
+| Subject line | 60 chars |
+| Message body | 1,500 chars |
+| CTA button | 20 chars |
+
+### Text Ad
+
+| Element | Limit |
+|---------|-------|
+| Headline | 25 chars |
+| Description | 75 chars |
+
+**LinkedIn-specific guidelines:**
+- Professional tone, but not boring
+- Use job-specific language the audience recognizes
+- Statistics and data points perform well
+- Avoid consumer-style hype ("Amazing!" "Incredible!")
+- First-person testimonials from peers resonate
+
+---
+
+## TikTok Ads
+
+### In-Feed Ads
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Ad text | 80 chars | 100 chars | Above the video |
+| Display name | N/A | 40 chars | Brand name |
+| CTA button | Platform options | Predefined | Select from TikTok's options |
+
+### Spark Ads (Boosted Organic)
+
+| Element | Notes |
+|---------|-------|
+| Caption | Uses original post caption |
+| CTA button | Added by advertiser |
+| Display name | Original creator's handle |
+
+**TikTok-specific guidelines:**
+- Native content outperforms polished ads
+- First 2 seconds determine if they watch
+- Use trending sounds and formats
+- Text overlay is essential (most watch with sound off)
+- Vertical video only (9:16)
+
+---
+
+## Twitter/X Ads
+
+### Promoted Tweets
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Tweet text | 280 chars | Full tweet with image/video |
+| Card headline | 70 chars | Website card |
+| Card description | 200 chars | Website card |
+
+### Website Cards
+
+| Element | Limit |
+|---------|-------|
+| Headline | 70 chars |
+| Description | 200 chars |
+
+**Twitter/X-specific guidelines:**
+- Conversational, casual tone
+- Short sentences work best
+- One clear message per tweet
+- Hashtags: 1-2 max (0 is often better for ads)
+- Threads can work for consideration-stage content
+
+---
+
+## Character Counting Tips
+
+- **Spaces count** as characters on all platforms
+- **Emojis** count as 1-2 characters depending on platform
+- **Special characters** (|, &, etc.) count as 1 character
+- **URLs** in body text count against limits
+- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults
+- Always verify in the platform's ad preview before launching
+
+---
+
+## Multi-Platform Creative Adaptation
+
+When creating for multiple platforms simultaneously, start with the most restrictive format:
+
+1. **Google Search headlines** (30 chars) — forces the tightest messaging
+2. **Expand to Meta headlines** (40 chars) — add a word or two
+3. **Expand to LinkedIn intro text** (150 chars) — add context and proof
+4. **Expand to Meta primary text** (125+ chars) — full hook and value prop
+
+This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space.

package/src/skills-lib/adversarial-reviewer/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: adversarial-reviewer
+description: Adversarial code review that assumes bugs exist and hunts for them. Use when asked to review code, find bugs, audit for correctness, stress-test a PR, or when someone says "tear this apart" or "what's wrong with this". Give no benefit of the doubt — every line is guilty until proven innocent.
+---
+
+# Adversarial Code Reviewer
+
+You are a hostile reviewer. Your job is to find bugs, not to be helpful. Assume the code is broken and prove yourself right.
+
+## Mindset
+
+- **Guilty until proven innocent.** Every line of code is a suspect.
+- **No compliments.** Don't say what's good. Say what's wrong.
+- **No "potential issue" hedging.** If something looks wrong, say it's wrong. Be direct.
+- **Prove it.** Construct concrete inputs, sequences, or race conditions that trigger the bug. Don't hand-wave.
+- **Silence means approval.** If you don't mention something, that IS your approval. Don't waste tokens on "this looks fine".
+
+## Review Checklist
+
+Work through these categories in order. Skip a category only when it genuinely doesn't apply.
+
+### 1. Logic Errors
+
+- Off-by-one in loops, slices, ranges, pagination
+- Inverted or missing conditions (especially negation — `!` is easy to miss)
+- Fallthrough in switch/match without break
+- Short-circuit evaluation hiding side effects
+- Wrong operator (`=` vs `==`, `&&` vs `||`, `&` vs `&&`)
+- Integer overflow, floating point comparison, implicit coercion
+
+### 2. Edge Cases & Boundaries
+
+- Empty inputs: empty string, empty array, null, undefined, 0, NaN
+- Single-element collections
+- Maximum values, minimum values, negative numbers
+- Unicode, multi-byte characters, RTL text
+- Concurrent calls with identical arguments
+- What happens when it's called twice? What about zero times?
+
+### 3. Error Handling
+
+- Catch blocks that swallow errors silently
+- Missing error handling on async operations
+- Error handling that catches too broadly (bare `catch` / `catch(e)`)
+- Cleanup/finally blocks missing or incomplete
+- Error messages that leak internals to users
+- Thrown errors that aren't Error instances
+
+### 4. State & Concurrency
+
+- Shared mutable state without synchronization
+- TOCTOU (time-of-check-to-time-of-use) races
+- Stale closures capturing variables that mutate
+- Event handler registration without cleanup
+- Assumptions about execution order of async operations
+
+### 5. Security
+
+- Unsanitized user input reaching SQL, HTML, shell, or file paths
+- Missing or incorrect authorization checks
+- Information leakage in error responses
+- CSRF, open redirect, path traversal
+- Secrets in code, logs, or error messages
+- Timing attacks on comparison operations
+
+### 6. Data Integrity
+
+- Missing validation at system boundaries
+- Type coercion hiding bad data
+- Partial writes without transactions
+- Missing uniqueness constraints
+- Cascading deletes that orphan or destroy data
+- Schema mismatches between code and database
+
+### 7. Resource Management
+
+- Missing cleanup: file handles, connections, timers, listeners
+- Unbounded growth: caches without eviction, arrays without limits
+- Memory leaks from retained references
+- Missing timeouts on network operations
+- Retry loops without backoff or limits
+
+## Output Format
+
+For each bug found:
+
+```
+**BUG: [short title]**
+File: path/to/file.ts:42
+Category: [from checklist above]
+Severity: CRITICAL | HIGH | MEDIUM | LOW
+
+[What's wrong — one or two sentences, no filler]
+
+Trigger: [concrete scenario that hits this bug]
+
+Fix: [minimal code change or approach — don't rewrite the function]
+```
+
+Order findings by severity (CRITICAL first).
+
+## Severity Guide
+
+- **CRITICAL**: Data loss, security vulnerability, crash in production
+- **HIGH**: Wrong behavior users will hit in normal usage
+- **MEDIUM**: Wrong behavior in edge cases, resource leaks under load
+- **LOW**: Cosmetic logic issues, unnecessary work, misleading names that could cause future bugs
+
+## What This Review Is NOT
+
+- Not a style review. Don't comment on formatting, naming conventions, or "I'd do it differently".
+- Not a feature review. Don't suggest additions, improvements, or refactors.
+- Not a test review. Don't say "this needs more tests" — say what's broken.
+- Not a compliment sandwich. There is no sandwich. There is only bugs.
+
+## Process
+
+1. Read ALL the code under review before writing anything. Form a mental model of the data flow.
+2. Trace the unhappy paths. What happens when things go wrong?
+3. Look for implicit assumptions. What does this code believe about its inputs that isn't enforced?
+4. Check the boundaries between components. Where does trust transfer happen?
+5. Write up findings. If you found nothing, say "No bugs found" and stop. Don't manufacture issues to seem thorough.

package/src/skills-lib/agent-browser/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: agent-browser
+description: Browser automation for testing and verification. Use when you need to interact with web UIs, verify visual changes, fill forms, or capture screenshots.
+---
+
+# Agent Browser Skill
+
+Fast browser automation CLI for AI agents. Use this to verify web UI changes, test interactions, and capture screenshots.
+
+## When to Use
+
+- Verify visual changes after modifying frontend code
+- Test form interactions and user flows
+- Capture screenshots for documentation or debugging
+- Inspect rendered HTML/accessibility tree
+- Debug why something isn't working in the browser
+
+## Core Workflow
+
+### 1. Open a URL
+
+```bash
+agent-browser open http://localhost:4321/
+```
+
+### 2. Take a Snapshot
+
+The snapshot command returns an accessibility tree with refs (`@e1`, `@e2`, etc.) that you can use for interactions:
+
+```bash
+agent-browser snapshot -i    # -i = interactive elements only (recommended)
+agent-browser snapshot -c    # -c = compact (removes empty structural elements)
+agent-browser snapshot -i -c # Both flags work together
+```
+
+### 3. Interact Using Refs
+
+Use the `@ref` values from the snapshot to interact with elements:
+
+```bash
+agent-browser click @e5           # Click element
+agent-browser fill @e3 "hello"    # Clear and type
+agent-browser type @e3 "world"    # Type without clearing
+agent-browser select @e7 "option" # Select dropdown
+agent-browser check @e9           # Check checkbox
+```
+
+### 4. Screenshot
+
+```bash
+agent-browser screenshot              # Viewport only
+agent-browser screenshot --full       # Full page
+agent-browser screenshot output.png   # Save to file
+```
+
+ALWAYS check the image size before attempting to load. If it is larger than 2MB, process it using a tool such as sips or ImageMagick to reduce the size. Large files cannot be loaded by your tools.
+
+## Common Patterns
+
+### Form Verification
+
+```bash
+agent-browser open http://localhost:4321/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin/content/posts/new
+agent-browser snapshot -i   # Check what fields are visible
+agent-browser fill @e3 "Test Title"
+agent-browser fill @e5 "Test content here"
+agent-browser click @e7     # Save button
+```
+
+### Get Element Info
+
+```bash
+agent-browser get text @e1      # Get text content
+agent-browser get html @e1      # Get inner HTML
+agent-browser get value @e2     # Get input value
+agent-browser get url           # Current URL
+agent-browser get title         # Page title
+agent-browser get count "button" # Count matching elements
+```
+
+### Check Element State
+
+```bash
+agent-browser is visible @e1
+agent-browser is enabled @e2
+agent-browser is checked @e3
+```
+
+### Find by Role/Label
+
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find label "Email" fill "test@example.com"
+agent-browser find placeholder "Search..." type "query"
+```
+
+## Sessions
+
+Sessions keep browser state (cookies, storage) between commands:
+
+```bash
+# Use named session (persists until closed)
+agent-browser --session mytest open http://localhost:4321
+agent-browser --session mytest snapshot -i
+
+# Or set via environment
+export AGENT_BROWSER_SESSION=mytest
+agent-browser open http://localhost:3000
+```
+
+## Useful Options
+
+| Option             | Description                         |
+| ------------------ | ----------------------------------- |
+| `--session <name>` | Isolated browser session            |
+| `--headed`         | Show browser window (not headless)  |
+| `--json`           | JSON output for programmatic use    |
+| `--full`           | Full page screenshot                |
+| `-i`               | Snapshot: interactive elements only |
+| `-c`               | Snapshot: compact output            |
+| `-d <n>`           | Snapshot: limit tree depth          |
+
+## Debugging
+
+```bash
+agent-browser --headed open http://localhost:3000  # See what's happening
+agent-browser console                               # View console logs
+agent-browser errors                                # View page errors
+agent-browser highlight @e5                         # Highlight element
+agent-browser eval "document.title"                 # Run JS
+```
+
+## Tips
+
+1. **Always snapshot first** - Get refs before interacting
+2. **Use `-i` flag** - Interactive-only snapshots are much cleaner
+3. **Wait when needed** - Use `wait <ms>` or `wait <selector>` after actions that trigger loading
+4. **Sessions for auth** - Use named sessions to persist login state
+5. **Headed for debugging** - Use `--headed` when things aren't working as expected