@caddis/cli 0.4.10 → 0.4.12

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.97",
+  "version": "1.3.101",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/scripts/caddis_spawn.py

@@ -546,14 +546,58 @@ def handshake_read(repo_root: Path, spawn_id: str) -> dict | None:
         return None
 
 
+MAX_REJECTS = 2
+
+
 def handshake_record(repo_root: Path, spawn_id: str, event: str,
-                     peer: str = "") -> tuple[dict | None, str]:
-    """Advance the handshake. Never rewinds: a verdict cannot un-answer the questions, and an
-    out-of-order event is a sign the operator has lost track of which round they are in — which
-    is exactly when a silent overwrite would hurt."""
+                     peer: str = "", verdict: str = "") -> tuple[dict | None, str]:
+    """Advance the handshake. One step forward, with exactly one named exception.
+
+    **REJECT sends it back to `awaiting-answers`, and that is the whole point of this function
+    having a rewind at all.** `spawn-session.md` defines REJECT as "an instruction to re-read named
+    sections and re-answer", and says "two REJECTs on one spawn means the HANDOVER is at fault —
+    regenerate it". Neither was possible until 2026-09-10: the states were strictly linear, so
+    after `verdict-sent` the only legal event was `ack`, and the handshake did not even record
+    WHICH verdict was sent. ACCEPT and REJECT were indistinguishable in the state file, so nothing
+    could count REJECTs and the two-strike rule was unenforceable prose.
+
+    Every other rewind is still refused. An out-of-order event is an operator who has lost track of
+    the round, which is exactly when a silent overwrite would hurt.
+    """
     state = handshake_read(repo_root, spawn_id)
     if state is None:
         return None, f"no handshake for {spawn_id} — run `handshake open --id {spawn_id}` first"
+
+    verdict = (verdict or "").strip().upper()
+    if event == "verdict" and verdict == "REJECT":
+        if state["state"] != "answered":
+            return state, (f"at `{state['state']}` — a REJECT only follows `answered`. "
+                           "There is nothing to reject yet.")
+        n = int(state.get("rejects", 0)) + 1
+        if n > MAX_REJECTS - 1:
+            state["rejects"] = n
+            # Recorded even though it is refused. The counter is the enforceable fact, but a
+            # history showing one REJECT beside a count of two is a state file that contradicts
+            # itself, and the next reader has to work out which half to believe.
+            state["history"].append({"event": "verdict", "verdict": "REJECT", "refused": True,
+                                     "at": int(time.time()),
+                                     **({"peer": peer} if peer else {})})
+            _handshake_path(repo_root, spawn_id).write_text(
+                json.dumps(state, indent=2) + chr(10), encoding="utf-8")
+            return state, (
+                f"REJECT #{n}. `spawn-session.md`: two REJECTs on one spawn means the HANDOVER is "
+                "at fault, not the successor. Regenerate it — do not coach the child through a "
+                "third round. Close this handshake and open a new one on a rewritten handover.")
+        state["rejects"] = n
+        state["state"] = "awaiting-answers"
+        state["history"].append({"event": "verdict", "verdict": "REJECT", "at": int(time.time()),
+                                 **({"peer": peer} if peer else {})})
+        if peer:
+            state["peer"] = peer
+        _handshake_path(repo_root, spawn_id).write_text(
+            json.dumps(state, indent=2) + chr(10), encoding="utf-8")
+        return state, ""
+
     target = _EVENT_STATE[event]
     here = HANDSHAKE_STATES.index(state["state"])
     there = HANDSHAKE_STATES.index(target)
@@ -571,6 +615,7 @@ def handshake_record(repo_root: Path, spawn_id: str, event: str,
     if peer:
         state["peer"] = peer
     state["history"].append({"event": event, "at": int(time.time()),
+                             **({"verdict": verdict} if event == "verdict" and verdict else {}),
                              **({"peer": peer} if peer else {})})
     state["state"] = target
     _handshake_path(repo_root, spawn_id).write_text(
@@ -659,6 +704,12 @@ def main(argv: list[str] | None = None) -> int:
     h.add_argument("--id", required=True)
     h.add_argument("--repo-root", default=".")
     h.add_argument("--event", choices=sorted(_EVENT_STATE))
+    h.add_argument("--verdict", default="",
+                   choices=["", "ACCEPT", "ACCEPT-WITH-CORRECTION", "REJECT"],
+                   help="with `--event verdict`. REJECT returns the handshake to "
+                        "`awaiting-answers` so the child re-reads and re-answers, and counts the "
+                        "strike; the second REJECT refuses and tells you to regenerate the "
+                        "handover instead of coaching the child through a third round")
     h.add_argument("--transport", choices=["auto", "message", "paste"], default="auto")
     h.add_argument("--peer", default="",
                    help="the child's name as ListAgents shows it — take it from the `from-name` "
@@ -763,11 +814,14 @@ def main(argv: list[str] | None = None) -> int:
             if not a.event:
                 sys.stderr.write("[spawn] --event is required for `record`" + chr(10))
                 return EXIT_REFUSED
-            st, err = handshake_record(root, a.id, a.event, a.peer)
+            st, err = handshake_record(root, a.id, a.event, a.peer, a.verdict)
             if err:
                 sys.stderr.write("[spawn] " + err + chr(10))
                 return EXIT_REFUSED
-            print(f"[spawn] {a.id}: {st['state']}")
+            rejects = int((st or {}).get("rejects", 0))
+            tail = f"  (REJECT #{rejects} — re-read and re-answer)" if \
+                (a.verdict.upper() == "REJECT" and rejects) else ""
+            print(f"[spawn] {a.id}: {st['state']}{tail}")
             return EXIT_OK
         if a.action == "close" and not (st.get("peer") or "").strip() \
                 and st["state"] != HANDSHAKE_STATES[0]:

package/bundles/antigravity-plugin/scripts/setup_project_ai.py

@@ -699,6 +699,16 @@ repo**: an access request, a decision from another team, a change only someone e
 table stops a sent message from going unchased. Comms are almost always sent to get an *action*, and
 an unanswered ask looks exactly like a forgotten one unless something is tracking it.
 
+**Read that rule the other way round: THIS TABLE IS WHERE YOU LOOK BEFORE YOU WRITE ONE.** Check it
+before drafting, not only after filing. A handover transfers a task, and for the whole overlap
+window two sessions can both believe an outbound note is theirs - on 2026-09-08 two of them wrote
+the same note five minutes apart, and both sat here marked ready to send. Two notes on one subject
+reaching one team reads as one team not talking to itself.
+
+**If you do find a duplicate, do not delete it.** Verify its unique contributions independently,
+fold them into the survivor, and archive the loser with a banner saying why. The second draft is a
+second reading - the one in that incident found a defect in the first.
+
 | Raised | Audience | Subject | Status | Blocks | File |
 |---|---|---|---|---|---|
 | _(none yet)_ | | | | | |

package/bundles/antigravity-plugin/skills/_registry.md

@@ -124,7 +124,6 @@
 | Best Practices | `best-practices/` | >- |
 | Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
 | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |
-| Golden Plan | `golden-plan/` | USE THIS SKILL whenever a user asks for a comprehensive implementation plan, a full-stack build plan, a UI+backend plan, or says 'create a plan for building X' where X spans multiple phases or systems. Also activate when the user says 'plan this project', 'I need a detailed plan', 'build plan', 'implementation plan', or attaches a mockup/wireframe and asks how to build it. Produces a zero-ambiguity, evidence-gated plan with self-contained per-phase prompts, exhaustive data binding tables, per-phase validation checklists, and a global quality gate. Evidence-gated: before writing phases, verify required artefacts (mockup, data sample, API contract, scaffold inventory); if any BLOCKER is missing, ask for it and wait before proceeding. Dual-mode: generic by default, junai-pipeline only when explicitly requested. Agent-agnostic - any agent with read/search/edit tools can use this skill. |
 | Preflight | `preflight/` | Plan-vs-codebase validation — verifies API contracts, type names, field accuracy, dependencies, and paths before implementation begins |
 | Setup Project Ai | `setup-project-ai/` | Install or refresh the agent-agnostic dev harness in this project (AGENTS.md-canonical rules hierarchy + CLAUDE.md @import shims, subagents, commands, settings) |
 | Skill Creator | `skill-creator/` | Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. |

package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md

@@ -44,8 +44,8 @@ Start by understanding the current project context, then ask questions one at a
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+- Use the `using-git-worktrees` skill (caddis, devops/) to create an isolated workspace
+- Use `/caddis:feature-plan` for a phased plan, or the `writing-plans` skill (caddis, docs/)
 
 ## Key Principles
 

package/bundles/antigravity-plugin/skills/explainer-doc/SKILL.md

@@ -13,7 +13,7 @@ either follows it blindly or argues with it. **The fix is not "add more detail"
 
 Proven in anger on a Genesys→ETL cutover spec handed to an external vendor team. The user's verdict:
 *"nailed it — the document was perfect, simple, this should be the standard for explainer documents."*
-Reference implementation to study: `serve-sight/docs/genesys-cutover/etl-implementation-spec.md` (full
+Reference implementation to study: `a fleet app/docs/genesys-cutover/etl-implementation-spec.md` (full
 spec) and `pega-cticallid-change-request.md` (the same pattern compressed to one page for a single ask).
 
 ## When this is NOT the right skill

package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md

@@ -69,7 +69,7 @@ over 400 changed lines. No judgement in any of those — deliberately, because j
 what failed.
 <!-- /shared:cross-review-trigger -->
 
-> **Why this is mechanical and not "consider a review here".** serve-sight shipped four
+> **Why this is mechanical and not "consider a review here".** a fleet app shipped four
 > production releases in one day — sixteen fixes across SQL, caches, refresh jobs and React — and
 > `/caddis:cross-review` ran **zero times**. Nothing was broken: the tool reported itself ready
 > with two providers keyed. Nothing decided *when* to call it. Measured there: 4 of 39 plan files

package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md

@@ -360,6 +360,21 @@ The vocabulary matches `/caddis:validate-phase` on purpose: same discipline, dif
 **Two REJECTs on one spawn means the HANDOVER is at fault, not the successor. Regenerate it** rather
 than coaching the child through it.
 
+**Record the verdict — the machine enforces both of those rules only if you tell it which one:**
+
+```
+python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spawn.py" handshake record --id <id> --event verdict --verdict REJECT
+```
+
+A REJECT returns the handshake to `awaiting-answers`, so `record --event answers` is legal again
+and the child re-answers. The **second** REJECT is refused: it tells you to regenerate the handover,
+and the only way forward is then ACCEPT or abandoning the handshake.
+
+Until 2026-09-10 `--verdict` did not exist. The states were strictly linear, so after `verdict-sent`
+the only legal event was `ack`, and nothing recorded WHICH verdict was sent — ACCEPT and REJECT were
+indistinguishable in the state file. So "re-read and re-answer" was impossible and "two REJECTs
+means regenerate" was unenforceable, because nothing counted them.
+
 ### When the fault is yours, fix the class
 
 If validation finds an error that came from your handover, **fix the source document in the same

package/bundles/antigravity-plugin/skills/ui-brief/SKILL.md

@@ -74,7 +74,12 @@ Every component must reflect the agreed colour story and font pairing — no fal
 
 **Motion discipline:**
 - Use animation as communication, not decoration
-- Always respect `prefers-reduced-motion` media query
+- Always respect `prefers-reduced-motion` media query — but treat it as a DEFAULT, not a verdict.
+  Windows Server ships with animations off with no user preference expressed, so a build that only
+  checks the media query once at load and never offers a way back can freeze a genuinely correct
+  animation for the whole session with no override (found in `.caddis/second-brain.html`: the OS
+  read is captured into a `var` at script start and never re-read). Read the OS default into a
+  visible toggle, and have the draw loop read the toggle's current state, not a captured constant.
 - One hero animation moment — not every element animating on load
 - 44px minimum touch targets on mobile
 

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.28",
+  "version": "1.3.29",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/_registry.md

@@ -99,30 +99,16 @@
 | Architecture Diagram | `architecture-diagram/` | Generate dark-themed technical architecture diagrams as self-contained HTML/SVG files. No external libraries or render tools needed — just a browser. Use for software system architecture, cloud infrastructure, microservice topologies, and deployment diagrams. |
 | Ascii Art | `ascii-art/` | Create text-based ASCII art using the right tool for the job — banners, borders, image conversion, pre-made art, and LLM-generated custom art. Decision-routing framework across pyfiglet, cowsay, TOIlet, boxes, and more. |
 | Excalidraw | `excalidraw/` | Brand-themed Excalidraw diagrams for project documentation |
-| Image Enhancer | `image-enhancer/` | Improves the quality of images, especially screenshots, by enhancing resolution, sharpness, and clarity. Perfect for preparing images for presentations, documentation, or social media posts. |
-| Notebooklm | `notebooklm/` | Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses. |
 | Plantuml | `plantuml/` | Brand-themed PlantUML diagrams for project documentation |
-| Slack Gif Creator | `slack-gif-creator/` | Toolkit for creating animated GIFs optimized for Slack, with validators for size constraints and composable animation primitives. This skill applies when users request animated GIFs or emoji animations for Slack from descriptions like "make me a GIF for Slack of X doing Y". |
 | Svg Create | `svg-create/` | Brand-themed SVG diagrams with consistent color palette and accessible design |
-| Video Downloader | `video-downloader/` | Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options. |
-| Youtube Transcript | `youtube-transcript/` | Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video. |
 
 ### Productivity
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Competitive Ads Extractor | `competitive-ads-extractor/` | Extracts and analyzes competitors' ads from ad libraries (Facebook, LinkedIn, etc.) to understand what messaging, problems, and creative approaches are working. Helps inspire and improve your own ad campaigns. |
-| Content Research Writer | `content-research-writer/` | Assists in writing high-quality content by conducting research, adding citations, improving hooks, iterating on outlines, and providing real-time feedback on each section. Transforms your writing process from solo effort to collaborative partnership. |
-| Domain Name Brainstormer | `domain-name-brainstormer/` | Generates creative domain name ideas for your project and checks availability across multiple TLDs (.com, .io, .dev, .ai, etc.). Saves hours of brainstorming and manual checking. |
 | Github Issues | `github-issues/` | Create well-structured GitHub issues with proper labels, descriptions, and acceptance criteria. Use when creating bug reports, feature requests, or tracking tasks. |
-| Humanizer | `humanizer/` | Identify and remove AI writing patterns from text to make it sound natural and human. Covers 29 documented LLM output patterns. Use when asked to humanize, de-AI, un-ChatGPT, or rewrite drafts (blogs, docs, emails, PRs, releases) to sound authentic. |
 | Internal Comms | `internal-comms/` | Write internal communications using company formats. Use when writing status reports, leadership updates, company newsletters, FAQs, incident reports, project updates, or any internal communications. |
-| Invoice Organizer | `invoice-organizer/` | Automatically organizes invoices and receipts for tax preparation by reading messy files, extracting key information, renaming them consistently, and sorting them into logical folders. Turns hours of manual bookkeeping into minutes of automated organization. |
 | Jira Issues | `jira-issues/` | Create, update, and manage Jira issues from natural language. Use when the user wants to log bugs, create tickets, update issue status, or manage their Jira backlog. |
-| Job Application | `job-application/` | Write tailored cover letters and job applications using a structured methodology. Analyzes job descriptions, maps experience, and generates personalized applications. |
-| Lead Research Assistant | `lead-research-assistant/` | Identifies high-quality leads for your product or service by analyzing your business, searching for target companies, and providing actionable contact strategies. Perfect for sales, business development, and marketing professionals. |
-| Meeting Insights Analyzer | `meeting-insights-analyzer/` | Analyzes meeting transcripts and recordings to uncover behavioral patterns, communication insights, and actionable feedback. Identifies when you avoid conflict, use filler words, dominate conversations, or miss opportunities to listen. Perfect for professionals seeking to improve their communication and leadership skills. |
-| Raffle Winner Picker | `raffle-winner-picker/` | Picks random winners from lists, spreadsheets, or Google Sheets for giveaways, raffles, and contests. Ensures fair, unbiased selection with transparency. |
 
 ### Testing
 
@@ -144,12 +130,8 @@
 | File Organizer | `file-organizer/` | Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort. |
 | Game Changing Features | `game-changing-features/` | Find 10x product opportunities and high-leverage improvements. Use when user wants strategic product thinking, mentions '10x', wants to find high-impact features, or says 'what would make this 10x better', 'product strategy', or 'what should we build next'. |
 | Golden Nuggets | `golden-nuggets/` | Extract durable tribal knowledge ('gold nuggets') from a codebase or a set of changed files and route each to its correct destination - instruction file, runbook, hub, or (in CI capture mode) a review inbox. This SKILL.md is the single source of truth for nugget categories, routing rules, write rules, inbox format, and verification gates. It is read by the knowledge-transfer agent (pipeline mode), by the /golden-nuggets prompt (independent mode), and referenced by the CI extraction script (capture mode). Use when capturing what was learned after a feature, fix, sprint, incident, or release. |
+| Golden Plan | `golden-plan/` | USE THIS SKILL whenever a user asks for a comprehensive implementation plan, a full-stack build plan, a UI+backend plan, or says 'create a plan for building X' where X spans multiple phases or systems. Also activate when the user says 'plan this project', 'I need a detailed plan', 'build plan', 'implementation plan', or attaches a mockup/wireframe and asks how to build it. Produces a zero-ambiguity, evidence-gated plan with self-contained per-phase prompts, exhaustive data binding tables, per-phase validation checklists, and a global quality gate. Evidence-gated: before writing phases, verify required artefacts (mockup, data sample, API contract, scaffold inventory); if any BLOCKER is missing, ask for it and wait before proceeding. Dual-mode: generic by default, junai-pipeline only when explicitly requested. Agent-agnostic - any agent with read/search/edit tools can use this skill. |
 | Intent Writer | `intent-writer/` | Structure freetext ideas, backlog items, or vague requirements into a formal Intent Document that preserves user intent across the entire agent pipeline chain. |
-| Onboard Project | `onboard-project/` | Bootstrap a new project's AI configuration by generating copilot-instructions.md and populating project-config.md. Idempotent — safe to re-run on existing projects. |
-| Pipeline State | `pipeline-state/` | Read and write `.github/pipeline-state.json` to track stage progress, artefacts, supervision gates, and handoff payloads in the agent pipeline. |
 | Receiving Code Review | `receiving-code-review/` | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation |
-| Relay | `relay/` | Create or update a root relay.md session-continuation document for any repository. Use this skill whenever the user asks to preserve project context, resume later, hand work to a future session, create a session relay, summarize current implementation state, or generate a reusable continuation prompt. The workflow is generic and must discover project structure at runtime. |
-| Requesting Code Review | `requesting-code-review/` | Use when completing tasks, implementing major features, or before merging to verify work meets requirements |
 | Setup Project Ai | `setup-project-ai/` | Install or refresh the agent-agnostic development harness in a project — an AGENTS.md-canonical rules hierarchy (root + per-folder) with a CLAUDE.md @import shim beside each, lean subagents, slash commands, settings.json, and the frontend/python test env. USE THIS SKILL when setting up AI resources on a new or existing project, bootstrapping the rules files (AGENTS.md/CLAUDE.md), adding subagents/commands, or when the user says 'set up the harness', 'setup-project-ai', 'generate CLAUDE.md', 'onboard this project to Claude Code / Codex / agy', or runs /setup-project-ai. Combines a deterministic generator (scripts/setup_project_ai.py) for the must-not-vary mechanics with an AI enrichment step that curates project-specific AGENTS.md content. |
-| State Tracking | `state-tracking/` | USE THIS SKILL when an agent needs to maintain a living record of task progress across multiple sessions or hand-offs. Covers append-only audit logs, CURRENT_STATE head-of-line pattern, relay hand-off protocol, and recovery from mid-session interruptions. Works in both generic and junai-pipeline modes. |
 | Verification Loop | `verification-loop/` | Systematic code change verification — lint, test, type-check, review |

package/bundles/codex/.codex/skills/docs/explainer-doc/SKILL.md

@@ -13,7 +13,7 @@ either follows it blindly or argues with it. **The fix is not "add more detail"
 
 Proven in anger on a Genesys→ETL cutover spec handed to an external vendor team. The user's verdict:
 *"nailed it — the document was perfect, simple, this should be the standard for explainer documents."*
-Reference implementation to study: `serve-sight/docs/genesys-cutover/etl-implementation-spec.md` (full
+Reference implementation to study: `a fleet app/docs/genesys-cutover/etl-implementation-spec.md` (full
 spec) and `pega-cticallid-change-request.md` (the same pattern compressed to one page for a single ask).
 
 ## When this is NOT the right skill

package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md

@@ -44,8 +44,8 @@ Start by understanding the current project context, then ask questions one at a
 
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+- Use the `using-git-worktrees` skill (caddis, devops/) to create an isolated workspace
+- Use `/caddis:feature-plan` for a phased plan, or the `writing-plans` skill (caddis, docs/)
 
 ## Key Principles
 

package/bundles/manifest.json

@@ -1,8 +1,8 @@
 {
-  "poolVersion": "1.3.97",
+  "poolVersion": "1.3.101",
   "bundles": {
-    "antigravity-plugin": "1.3.97",
-    "antigravity-plugin-extras": "1.3.28",
+    "antigravity-plugin": "1.3.101",
+    "antigravity-plugin-extras": "1.3.29",
     "codex": "unknown"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",

package/bundles/antigravity-plugin-extras/skills/competitive-ads-extractor/SKILL.md

@@ -1,294 +0,0 @@
----
-name: competitive-ads-extractor
-context: fork
-description: Extracts and analyzes competitors' ads from ad libraries (Facebook, LinkedIn, etc.) to understand what messaging, problems, and creative approaches are working. Helps inspire and improve your own ad campaigns.
----
-
-# Competitive Ads Extractor
-
-This skill extracts your competitors' ads from ad libraries and analyzes what's working—the problems they're highlighting, use cases they're targeting, and copy/creative that's resonating.
-
-## When to Use This Skill
-
-- Researching competitor ad strategies
-- Finding inspiration for your own ads
-- Understanding market positioning
-- Identifying successful ad patterns
-- Analyzing messaging that works
-- Discovering new use cases or pain points
-- Planning ad campaigns with proven concepts
-
-## What This Skill Does
-
-1. **Extracts Ads**: Scrapes ads from Facebook Ad Library, LinkedIn, etc.
-2. **Captures Screenshots**: Saves visual copies of all ads
-3. **Analyzes Messaging**: Identifies problems, use cases, and value props
-4. **Categorizes Ads**: Groups by theme, audience, or format
-5. **Identifies Patterns**: Finds common successful approaches
-6. **Provides Insights**: Explains why certain ads likely perform well
-
-## How to Use
-
-### Basic Extraction
-
-```
-Extract all current ads from [Competitor Name] on Facebook Ad Library
-```
-
-```
-Scrape ads from [Company] and analyze their messaging
-```
-
-### Specific Analysis
-
-```
-Get all ads from [Competitor] focusing on their messaging 
-about [specific problem]. What pain points are they highlighting?
-```
-
-### Competitive Set
-
-```
-Extract ads from these 5 competitors: [list]. 
-Compare their approaches and tell me what's working.
-```
-
-### Specific Platform
-
-```
-Get LinkedIn ads from [Competitor] and analyze their 
-B2B positioning strategy
-```
-
-## Example
-
-**User**: "Extract ads from Notion on Facebook Ad Library and tell me what messaging is working for them."
-
-**Process**:
-```
-Accessing Facebook Ad Library...
-Searching for: Notion
-Found: 23 active ads
-
-Extracting screenshots...
-[████████████████████] 100%
-
-Saved to: competitor-ads/notion/
-- ad-001-collaboration.png
-- ad-002-productivity.png
-- ad-003-templates.png
-...
-
-Analyzing messaging...
-```
-
-**Output**:
-```
-# Notion Ad Analysis
-
-## Overview
-- Total Ads: 23 active
-- Primary Themes: Productivity (35%), Collaboration (30%), 
-  Templates (20%), AI Features (15%)
-- Ad Formats: Static images (60%), Video (40%)
-- CTA Patterns: "Try for free", "Get started"
-
-## Key Problems They're Highlighting
-
-1. **Scattered Information** (8 ads)
-   Copy: "Stop switching between 10 different tools"
-   Why it works: Direct pain point many teams face
-
-2. **Meeting Overload** (5 ads)
-   Copy: "Replace unnecessary meetings with async updates"
-   Why it works: Post-COVID remote work pain point
-
-3. **Lost Documentation** (4 ads)
-   Copy: "Never ask 'where is that doc?' again"
-   Why it works: Universal workplace frustration
-
-## Successful Creative Patterns
-
-### Pattern 1: Before/After Split
-- Shows chaotic tool landscape → Clean Notion workspace
-- Used in 6 high-performing ads
-- Visual metaphor is immediately clear
-
-### Pattern 2: Feature Showcase
-- GIF of actual product usage
-- Shows specific feature in 5 seconds
-- Used for new features (AI, templates)
-
-### Pattern 3: Social Proof
-- "Join 20M users" messaging
-- Customer logos
-- Used in 4 ads targeting enterprise
-
-## Copy That's Working
-
-Best Headlines:
-1. "Your team's knowledge, finally in one place"
-   → Benefit-focused, addresses pain directly
-   
-2. "The all-in-one workspace"
-   → Clear positioning, broad appeal
-   
-3. "AI that actually helps you work"
-   → Addresses AI skepticism, practical angle
-
-Best Body Copy Patterns:
-- Short sentences (under 10 words)
-- Focus on outcomes not features
-- Include specific numbers ("Cut meetings by 50%")
-
-## Audience Targeting Insights
-
-Based on ad variations:
-- Startup founders: Solo productivity angle
-- Team leads: Collaboration and alignment
-- Enterprise: Security and compliance mentions
-- Students: Free plan, templates, organization
-
-## Recommendations for Your Ads
-
-1. **Test the "tool sprawl" pain point**
-   → Strong resonance based on their ad frequency
-
-2. **Use product screenshots over abstract visuals**
-   → All their top ads show actual UI
-
-3. **Lead with the problem, not the solution**
-   → "Tired of X?" performs better than "Introducing Y"
-
-4. **Keep copy under 100 characters**
-   → Their shortest ads seem most frequent
-
-5. **Test before/after visual formats**
-   → Proven pattern in their creative
-
-## Files Saved
-- All ads: ~/competitor-ads/notion/
-- Analysis: ~/competitor-ads/notion/analysis.md
-- Best performers: ~/competitor-ads/notion/top-10/
-```
-
-**Inspired by:** Sumant Subrahmanya's use case from Lenny's Newsletter
-
-## What You Can Learn
-
-### Messaging Analysis
-- What problems they emphasize
-- How they position against competition
-- Value propositions that resonate
-- Target audience segments
-
-### Creative Patterns
-- Visual styles that work
-- Video vs. static image performance
-- Color schemes and branding
-- Layout patterns
-
-### Copy Formulas
-- Headline structures
-- Call-to-action patterns
-- Length and tone
-- Emotional triggers
-
-### Campaign Strategy
-- Seasonal campaigns
-- Product launch approaches
-- Feature announcement tactics
-- Retargeting patterns
-
-## Best Practices
-
-### Legal & Ethical
-✓ Only use for research and inspiration
-✓ Don't copy ads directly
-✓ Respect intellectual property
-✓ Use insights to inform original creative
-✗ Don't plagiarize copy or steal designs
-
-### Analysis Tips
-1. **Look for patterns**: What themes repeat?
-2. **Track over time**: Save ads monthly to see evolution
-3. **Test hypotheses**: Adapt successful patterns for your brand
-4. **Segment by audience**: Different messages for different targets
-5. **Compare platforms**: LinkedIn vs Facebook messaging differs
-
-## Advanced Features
-
-### Trend Tracking
-```
-Compare [Competitor]'s ads from Q1 vs Q2. 
-What messaging has changed?
-```
-
-### Multi-Competitor Analysis
-```
-Extract ads from [Company A], [Company B], [Company C]. 
-What are the common patterns? Where do they differ?
-```
-
-### Industry Benchmarks
-```
-Show me ad patterns across the top 10 project management 
-tools. What problems do they all focus on?
-```
-
-### Format Analysis
-```
-Analyze video ads vs static image ads from [Competitor]. 
-Which gets more engagement? (if data available)
-```
-
-## Common Workflows
-
-### Ad Campaign Planning
-1. Extract competitor ads
-2. Identify successful patterns
-3. Note gaps in their messaging
-4. Brainstorm unique angles
-5. Draft test ad variations
-
-### Positioning Research
-1. Get ads from 5 competitors
-2. Map their positioning
-3. Find underserved angles
-4. Develop differentiated messaging
-5. Test against their approaches
-
-### Creative Inspiration
-1. Extract ads by theme
-2. Analyze visual patterns
-3. Note color and layout trends
-4. Adapt successful patterns
-5. Create original variations
-
-## Tips for Success
-
-1. **Regular Monitoring**: Check monthly for changes
-2. **Broad Research**: Look at adjacent competitors too
-3. **Save Everything**: Build a reference library
-4. **Test Insights**: Run your own experiments
-5. **Track Performance**: A/B test inspired concepts
-6. **Stay Original**: Use for inspiration, not copying
-7. **Multiple Platforms**: Compare Facebook, LinkedIn, TikTok, etc.
-
-## Output Formats
-
-- **Screenshots**: All ads saved as images
-- **Analysis Report**: Markdown summary of insights
-- **Spreadsheet**: CSV with ad copy, CTAs, themes
-- **Presentation**: Visual deck of top performers
-- **Pattern Library**: Categorized by approach
-
-## Related Use Cases
-
-- Writing better ad copy for your campaigns
-- Understanding market positioning
-- Finding content gaps in your messaging
-- Discovering new use cases for your product
-- Planning product marketing strategy
-- Inspiring social media content
-