Compare commits

...
6 Commits
Author SHA1 Message Date
Corey Haines 30bc89daa8 Merge pull request #449 from coreyhaines31/development
release: v2.8.9 — prospecting demand-signal discovery branch
2026-07-13 12:12:59 -07:00
Corey HainesandClaude Fable 5 bd8d8fdf29 feat(prospecting): demand-signal discovery branch — find your first customers (1.1.0) (#448)
* feat(prospecting): demand-signal discovery branch — find-first-customers (1.1.0)

New 4th branch + references/demand-signals.md: find first customers /
design partners / beta users from recent public pain-demand-timing
signals (5 signal buckets, demand-fit scoring rubric, evidence ledger,
manual-only openers, evidence report). Leverages last30days / social-
fetch / scraping. Also closes two compliance gaps across all branches:
no data brokers/leaked data, no sensitive-trait targeting. Pattern
credit: first-customer-finder Codex skill (MIT). Repo release 2.8.9.
Closes #447.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(prospecting): address codex review — scope guardrail + branch differences

- narrow guardrail #7: bans breached/leaked/unprovenanced data, NOT
  licensed enrichment vendors (Apollo/ZoomInfo/Clearbit/Clay stay valid)
- scope Hot/Warm/Cold scoring + lead-sheet output to the 3 list-building
  branches; Demand-signal uses 0-100 demand-fit + evidence report
- name Demand-signal in Inputs to Collect + Task-Specific Questions
- GDPR: demand-signal sourcing/outreach is business/professional context
  only; exclude personal-distress contexts; consumer posts need channel-
  norm outreach, not cold DMs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-13 12:12:49 -07:00
Corey Haines 0ba2a7fafc Merge pull request #442 from coreyhaines31/development
release: v2.8.8 — creative review page (ad-creative)
2026-07-12 23:21:28 -07:00
Corey HainesandClaude Fable 5 81270bcd54 feat(ad-creative): shareable creative review page — client approval artifact (2.7.0) (#441)
* feat(ad-creative): shareable creative review page (client approval artifact) (2.7.0)

Self-contained HTML template (assets/creative-review-template.html) that
presents generated concepts as in-feed platform mockups with a frame-by-
frame storyboard, selectable copy variations, and a required grounding
disclosure — the visual upgrade to INDEX.md. Driven entirely by a DATA
object; no build or deps. Full data model + grounding rules in
references/creative-review-page.md. Repo release 2.8.8. Closes #440.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(ad-creative): harden review-page template per codex review

- P1: DATA moved to inert <script type=application/json> block (values
  can't execute) + documented \u003c escaping rule for the </script>
  breakout; malformed JSON now shows a clear error banner
- P1: platform list whitelisted to instagram/facebook + escaped in
  attr/label (was raw-interpolated)
- platform toggle now renders real FB chrome (link card + text actions)
  vs IG (swipe bar + icon actions) — was visually inert
- broken/missing images fall back to the label+prompt placeholder as
  documented (placeholder base layer + image removes itself on error)
- doc consistency: agency wording, JSON data-model note, VERSIONS trigger list

Verified in-browser: FB/IG toggle, error banner, and HTML-payload escaping.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-12 23:21:00 -07:00
Corey Haines 5139746081 Merge pull request #438 from coreyhaines31/development
release: npx skills install docs fix
2026-07-10 16:02:00 -07:00
Corey HainesandClaude Fable 5 09a81edda8 docs: clarify npx skills install dirs per agent (#435)
The CLI no longer unconditionally symlinks into .claude/skills — Claude Code
gets .claude/skills only when selected (interactively or via -a claude-code).
Agent-detected non-interactive runs can land universal-only in .agents/skills,
which Claude Code does not read. Verified empirically against skills CLI 1.5.15
and Claude Code 2.1.173.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-10 16:01:18 -07:00
11 changed files with 705 additions and 15 deletions
+1 -1
View File
@@ -6,7 +6,7 @@
},
"metadata": {
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
"version": "2.8.7",
"version": "2.8.9",
"repository": "https://github.com/coreyhaines31/marketingskills"
},
"plugins": [
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "marketing-skills",
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
"version": "2.8.7",
"version": "2.8.9",
"author": {
"name": "Corey Haines"
},
+8 -1
View File
@@ -122,7 +122,14 @@ npx skills add coreyhaines31/marketingskills --skill cro copywriting
npx skills add coreyhaines31/marketingskills --list
```
This automatically installs to your `.agents/skills/` directory (and symlinks into `.claude/skills/` for Claude Code compatibility).
The CLI detects which agents you have installed and asks where to install. For Claude Code it installs into `.claude/skills/`; universal agents share `.agents/skills/`.
> [!TIP]
> If you run the command from **inside** an agent session (e.g., asking Claude Code to install the skills for you), the CLI runs non-interactively and may only install to the universal `.agents/skills/` directory, which Claude Code does not read. Pass the agent explicitly:
>
> ```bash
> npx skills add coreyhaines31/marketingskills -a claude-code
> ```
### Option 2: Claude Code Plugin
+10 -2
View File
@@ -5,7 +5,7 @@ Current versions of all skills. Agents can compare against local versions to che
| Skill | Version | Last Updated |
|-------|---------|--------------|
| ab-testing | 2.0.0 | 2026-05-05 |
| ad-creative | 2.6.0 | 2026-07-10 |
| ad-creative | 2.7.0 | 2026-07-12 |
| ai-seo | 2.2.0 | 2026-07-09 |
| analytics | 2.0.0 | 2026-05-05 |
| aso | 2.0.0 | 2026-05-05 |
@@ -39,7 +39,7 @@ Current versions of all skills. Agents can compare against local versions to che
| pricing | 2.0.1 | 2026-06-16 |
| product-marketing | 2.0.0 | 2026-05-05 |
| programmatic-seo | 2.0.0 | 2026-05-05 |
| prospecting | 1.0.0 | 2026-05-26 |
| prospecting | 1.1.0 | 2026-07-13 |
| public-relations | 1.0.0 | 2026-06-10 |
| referrals | 2.0.0 | 2026-05-05 |
| revops | 2.0.0 | 2026-05-05 |
@@ -54,6 +54,14 @@ Current versions of all skills. Agents can compare against local versions to che
## Recent Changes
### 2.8.9 (2026-07-13)
- **prospecting** (1.0.0 → 1.1.0): added a **fourth branch — Demand-signal discovery (find your first customers)**, the early-stage motion that finds first customers / design partners / beta users from recent public pain-demand-timing signals rather than firmographic list-building (re-expressed from the open-source `first-customer-finder` Codex skill, Kappaemme/MIT, credited; extended with our live-recency tooling). New `references/demand-signals.md`: how the branch differs from list-building (starts from a described problem, sources public discourse, wins on 10 strong evidence-backed matches over coverage), a product brief gate, the five signal query buckets (explicit demand / pain / workaround / switching / timing) with our tooling edge called out (last30days for Reddit/HN/X/web recency, social-fetch to read original threads, scraping/Firecrawl/Browserbase over snippets, deep-research, competitor-profiling, customer-research), a public-only source mix, a **demand-fit scoring rubric** (pain 25% / product fit 25% / timing 20% / reachability 15% / evidence quality 15%, 0-100 with bands — distinct from the ICP-fit Hot/Warm/Cold), prospect stages (high intent / problem aware / trigger present / potential fit), a per-prospect evidence ledger, manual-only source-based openers (never auto-send), the evidence-report structure (verdict → ICP → top prospect → shortlist → repeated patterns → 7-day manual outreach plan → limits), and the honesty rules (a cited signal is the entry ticket; label 'potential customer based on public signals,' never 'will buy'). SKILL.md adds the branch to the Pick-the-Branch table + deep-dive pointers and 'find my first customers,' 'early adopters,' 'design partners,' 'beta users,' 'who has this problem' triggers. Also closes two **compliance-guardrail gaps** across all branches: no data brokers / leaked datasets, and never target or infer sensitive/protected traits (health, financial hardship, political belief, sexuality, religion). New eval (id 7) covers branch selection, signal mining, demand-fit scoring, and the never-auto-send rule. Closes #447.
### 2.8.8 (2026-07-12)
- **ad-creative** (2.6.0 → 2.7.0): added the **creative review page** — a shareable, self-contained HTML artifact that presents generated concepts for a client or stakeholder to review and pick (the visual upgrade to `INDEX.md`; pattern reverse-engineered from a real agency creative-approval page, re-expressed originally). New `assets/creative-review-template.html`: one file, inline CSS+JS, no build or dependencies, driven entirely by a `DATA` object — renders concept tabs (each a strategic angle), a pixel-accurate in-feed Instagram/Facebook preview with a whitelist-handle toggle, a labeled frame-by-frame storyboard (tap to jump), selectable headline variations that overlay the preview, primary text, destination/CTA/offer, optional rollout mechanics, and a required grounding disclosure; frames render real images (URL / relative path / data URI) or styled label+prompt placeholders for concepts not yet rendered. New `references/creative-review-page.md`: when to produce one, the full data model, the frame-storyboard-as-carousel-arc link to `carousel-frameworks.md`, the hard grounding rule (every concept discloses what's real; illustrative proof is labeled illustrative — never launder fiction as fact), and how to populate/verify/deliver (open locally, host on any static host, or hand off the file). SKILL.md adds a Creative Review Page output-format section, a Mode 3 pointer, and 'creative review page' + 'present ad creative for approval' triggers. New eval (id 10) covers template use over markdown, narrative-job frame labels, and the grounding disclosure. Browser-verified: concept switching, platform/handle toggles, and frame navigation all render correctly.
### 2.8.7 (2026-07-10)
- **ad-creative** (2.5.0 → 2.6.0): added **Mode 4 — the Creative Strategy Loop**, the upstream workflow layer for deciding which ads are worth making (built so the same capability ships in any agent running the library, incl. Magister; workflow shapes informed by public creative-strategist practice, expressed originally). New `references/creative-roadmap.md`: three-signal synthesis (account performance via the platform CLIs; customer/brand language via the Grounded Inputs corpus + customer-research; external organic via scraping, social listening, and competitor-profiling) on a monthly-deep-dive + weekly-refresh cadence with a receipts rule (no insight enters the icebox without its source); concepts as segment × motivation × angle × format hypotheses ranked on a six-tier evidence scale; **account-state branching** (exploration state: wide net-new mix, per-metric win redefinition, iterate only on hits, four root causes to check; scaling state: winner-variation-heavy mix with visually-distinct variations, sub-angle probes, a standing exploration allocation); the **roadmap artifact** (icebox → quarterly themes → monthly slate with T1 iteration / T2 remix / T3 production tiers and a hard capacity check); per-concept briefs handed to Modes 1–3; and the **monthly creative retro** (winners/losers/metric-wins/learnings/kills, judged at concept level, every learning landing as an icebox update, re-rank, or kill). New `references/hook-system.md`: hooks as three components (visual action / spoken line / caption) with the no-duplication rule; the segment → motivation → format → hook generation pipeline output as a hook matrix; an eight-move opening menu; the **diagnostic funnel** mapping thumbstop/hold/CTR/CVR to which component to fix; the **on-ramp rule** (every hook test is an on-ramp test); fidelity laddering tied to production tiers; and inherited grounding rules plus organic language mining. SKILL.md adds the Mode 4 section and 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing' triggers. New eval (id 9) covers exploration-state diagnosis, evidence-ranked slates, and the receipts rule.
+7 -3
View File
@@ -1,8 +1,8 @@
---
name: ad-creative
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'creative strategy,' 'creative roadmap,' 'creative retro,' 'hook writing,' 'creative review page,' 'present ad creative for approval,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
metadata:
version: 2.6.0
version: 2.7.0
---
# Ad Creative
@@ -61,7 +61,7 @@ Pull performance data → Identify winning patterns → Generate new variations
```
### Mode 3: Scaled Static Batches (Grounded)
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**.
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**. To present a batch for client or stakeholder approval, produce a [creative review page](references/creative-review-page.md).
### Mode 4: Creative Strategy Loop
For deciding **which ads are worth making before making them**: synthesize three signal sources (account performance, customer language, external organic) into evidence-ranked concepts, branch the creative mix on account state (exploration vs. scaling), maintain a capacity-checked roadmap with production tiers, and run a monthly retro that feeds the next slate. The full system lives in [references/creative-roadmap.md](references/creative-roadmap.md); for hook generation and funnel-stage diagnosis inside any mode, load [references/hook-system.md](references/hook-system.md).
@@ -324,6 +324,10 @@ outputs/YYYY-MM-DD/
Per-concept format is defined in [references/static-ad-templates.md](references/static-ad-templates.md). The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
### Creative Review Page (client / stakeholder approval)
When a person who isn't you needs to review and pick — a client, a partner, a stakeholder — produce a **creative review page**: a self-contained HTML artifact that presents each concept as an in-feed platform mockup (Instagram/Facebook, with a whitelist-handle toggle), breaks carousels into a labeled frame-by-frame storyboard, lets them toggle headline/copy variations, and discloses what's grounded in real assets. It's the visual upgrade to INDEX.md — a decision made off one link instead of by reading markdown. The template ships at [assets/creative-review-template.html](assets/creative-review-template.html) (one file, no build, hostable anywhere); populate its `DATA` object from your generated concepts. Full data model, grounding rules (the disclosure block is required), and delivery in [references/creative-review-page.md](references/creative-review-page.md).
### Iteration Report
When iterating, include a summary:
@@ -0,0 +1,400 @@
<!DOCTYPE html>
<!--
Creative Review Page — a shareable ad-creative approval artifact.
HOW TO USE (agents): replace the JSON inside <script id="review-data"> below
with the real project. Everything else renders from it. The file is
self-contained — no build, no network, no dependencies. Open it in a browser,
host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the
single .html file.
THE DATA BLOCK IS JSON, NOT JAVASCRIPT:
- double-quoted keys and strings, no comments, no trailing commas
- it is inert data (parsed with JSON.parse), so a value can never execute
- SECURITY: escape every literal "<" in your text values as < so a
value like "</script>" can never break out of the tag. All values are
also HTML-escaped again at render time.
DATA SHAPE — see references/creative-review-page.md for the annotated spec.
Images: each frame's "image" may be a URL, a relative path, or a data URI.
If omitted (or the file is missing), a placeholder shows the frame label +
the image prompt — use this for concepts not yet rendered to image.
-->
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Creative Review</title>
<style>
:root {
--bg: #f4f3f0; --card: #ffffff; --ink: #16150f; --muted: #6b6a63;
--line: #e4e2dc; --accent: #2f6fed; --accent-soft: #eaf0fe;
--radius: 14px; --shadow: 0 1px 2px rgba(0,0,0,.04), 0 8px 24px rgba(0,0,0,.05);
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--bg); color: var(--ink);
font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-webkit-font-smoothing: antialiased; }
.wrap { max-width: 1120px; margin: 0 auto; padding: 32px 20px 80px; }
.eyebrow { font-size: 11px; font-weight: 700; letter-spacing: .12em; text-transform: uppercase; color: var(--muted); }
a { color: var(--accent); }
header.project { margin-bottom: 28px; }
header.project h1 { font-size: 20px; margin: 6px 0 2px; letter-spacing: -.01em; }
header.project .sub { color: var(--muted); font-size: 13px; }
.concepts { display: grid; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); gap: 10px; margin: 14px 0 28px; }
.concept { text-align: left; background: var(--card); border: 1.5px solid var(--line); border-radius: var(--radius);
padding: 14px 16px; cursor: pointer; transition: border-color .12s, box-shadow .12s; font: inherit; color: inherit; }
.concept:hover { border-color: #cfcdc6; }
.concept[aria-selected="true"] { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); background: #fff; }
.concept .row1 { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; }
.concept .num { font-size: 11px; font-weight: 700; color: var(--muted); }
.concept .frames { font-size: 11px; color: var(--muted); }
.concept .name { font-weight: 650; font-size: 15px; margin: 4px 0 3px; }
.concept .tag { font-size: 12.5px; color: var(--muted); line-height: 1.35; }
.grid { display: grid; grid-template-columns: minmax(0, 380px) minmax(0, 1fr); gap: 28px; align-items: start; }
@media (max-width: 860px) { .grid { grid-template-columns: 1fr; } }
.col-label { margin-bottom: 10px; }
.toggles { display: flex; flex-wrap: wrap; gap: 14px; margin-bottom: 12px; }
.seg { display: inline-flex; background: #ecebe6; border-radius: 999px; padding: 3px; }
.seg button { border: 0; background: transparent; font: inherit; font-size: 12.5px; font-weight: 600; color: var(--muted);
padding: 5px 12px; border-radius: 999px; cursor: pointer; }
.seg button[aria-pressed="true"] { background: #fff; color: var(--ink); box-shadow: 0 1px 2px rgba(0,0,0,.08); }
.seg .lbl { align-self: center; font-size: 10.5px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: var(--muted); margin-right: 6px; }
.post { background: var(--card); border: 1px solid var(--line); border-radius: 12px; overflow: hidden; box-shadow: var(--shadow); }
.post .top { display: flex; align-items: center; gap: 10px; padding: 11px 12px; }
.post .avatar { width: 34px; height: 34px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
display: grid; place-items: center; font-weight: 700; font-size: 13px; overflow: hidden; flex: none; }
.post .avatar img { width: 100%; height: 100%; object-fit: cover; }
.post .who { line-height: 1.2; }
.post .who .name { font-weight: 650; font-size: 13.5px; }
.post .who .partner { font-size: 11.5px; color: var(--muted); }
.post .dots { margin-left: auto; color: var(--muted); font-weight: 700; letter-spacing: 2px; }
.frame { position: relative; aspect-ratio: 4/5; background: #ded9d0; display: grid; }
.frame img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
.frame .ph { grid-area: 1/1; display: flex; flex-direction: column; justify-content: space-between; padding: 16px;
background: linear-gradient(135deg,#efece5,#e2ddd2); }
.frame .ph .plabel { font-size: 11px; font-weight: 700; letter-spacing: .1em; text-transform: uppercase; color: #948e80; }
.frame .ph .pprompt { font-size: 13px; color: #5f5a4e; line-height: 1.4; }
.frame .badge { position: absolute; top: 12px; left: 12px; z-index: 2; background: rgba(255,255,255,.92);
font-size: 11.5px; font-weight: 600; padding: 5px 10px; border-radius: 999px; display: flex; align-items: center; gap: 5px; }
.frame .counter { position: absolute; top: 12px; right: 12px; z-index: 2; background: rgba(0,0,0,.6); color: #fff; font-size: 11px;
font-weight: 600; padding: 3px 9px; border-radius: 999px; }
.frame .headline { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; padding: 18px 16px 20px; color: #fff;
font-size: 21px; font-weight: 700; line-height: 1.2; letter-spacing: -.01em;
background: linear-gradient(to top, rgba(0,0,0,.72), rgba(0,0,0,0)); }
.frame .headline.light { color: var(--ink); background: linear-gradient(to top, rgba(255,255,255,.85), rgba(255,255,255,0)); }
/* Instagram chrome */
.ig-cta { display: flex; align-items: center; justify-content: space-between; padding: 12px; border-top: 1px solid var(--line);
font-weight: 600; font-size: 13.5px; }
.ig-cta .chev { color: var(--muted); }
.ig-actions { display: flex; gap: 16px; padding: 10px 12px 2px; color: #26251f; }
.ig-actions svg { width: 22px; height: 22px; }
.ig-actions .save { margin-left: auto; }
.likes { padding: 6px 12px 2px; font-weight: 650; font-size: 13px; }
.caption { padding: 2px 12px 14px; font-size: 13px; line-height: 1.4; }
.caption .h { font-weight: 650; }
.caption .more { color: var(--muted); }
/* Facebook chrome — link card below image + text actions */
.fb-card { display: flex; align-items: center; gap: 12px; padding: 12px; background: #f3f4f6; border-top: 1px solid var(--line); }
.fb-card .meta { min-width: 0; flex: 1; }
.fb-card .dom { font-size: 11px; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); }
.fb-card .hl { font-size: 14px; font-weight: 650; line-height: 1.25; margin-top: 2px; overflow: hidden; }
.fb-card .btn { flex: none; background: #e4e6eb; color: #050505; font-weight: 650; font-size: 12.5px; padding: 8px 14px; border-radius: 7px; }
.fb-actions { display: flex; padding: 4px 12px; border-top: 1px solid var(--line); }
.fb-actions span { flex: 1; text-align: center; padding: 8px 0; font-size: 13px; font-weight: 600; color: var(--muted); }
.board { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 16px; box-shadow: var(--shadow); margin-bottom: 20px; }
.board .frames-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin-top: 12px; }
@media (max-width: 480px) { .board .frames-grid { grid-template-columns: repeat(2, 1fr); } }
.thumb { border: 0; background: transparent; padding: 0; cursor: pointer; text-align: left; font: inherit; color: inherit; }
.thumb .box { aspect-ratio: 4/5; border-radius: 9px; overflow: hidden; border: 2px solid transparent; background: #e7e2d8;
display: grid; transition: border-color .12s; }
.thumb[aria-current="true"] .box { border-color: var(--accent); }
.thumb .box img { width: 100%; height: 100%; object-fit: cover; grid-area: 1/1; z-index: 1; }
.thumb .box .mini { grid-area: 1/1; padding: 8px; font-size: 10.5px; color: #7a7566; line-height: 1.3;
background: linear-gradient(135deg,#efece5,#e2ddd2); overflow: hidden; }
.thumb .cap { margin-top: 6px; font-size: 12px; }
.thumb .cap .n { color: var(--muted); font-weight: 700; margin-right: 6px; }
.copy { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: 18px; box-shadow: var(--shadow); }
.copy .block { padding: 14px 0; border-top: 1px solid var(--line); }
.copy .block:first-of-type { border-top: 0; padding-top: 4px; }
.headline-opt { display: flex; gap: 10px; align-items: flex-start; width: 100%; text-align: left; font: inherit; color: inherit;
background: #faf9f6; border: 1.5px solid var(--line); border-radius: 10px; padding: 11px 13px; cursor: pointer; margin-top: 8px; }
.headline-opt[aria-pressed="true"] { border-color: var(--accent); background: #fff; box-shadow: 0 0 0 3px var(--accent-soft); }
.headline-opt .n { font-size: 11px; font-weight: 700; color: var(--muted); margin-top: 2px; }
.headline-opt .t { font-size: 14px; line-height: 1.35; }
.kv { font-size: 13.5px; line-height: 1.5; }
.kv .dest { color: var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; }
.steps { margin: 8px 0 0; padding: 0; list-style: none; }
.steps li { display: flex; gap: 10px; padding: 5px 0; font-size: 13px; line-height: 1.4; }
.steps li .i { flex: none; width: 20px; height: 20px; border-radius: 50%; background: var(--accent-soft); color: var(--accent);
display: grid; place-items: center; font-size: 11px; font-weight: 700; }
.grounding { background: #f6f5ef; border: 1px dashed #cfcabb; border-radius: 10px; padding: 12px 14px; font-size: 12.5px; color: #5f5a4e; line-height: 1.45; margin-top: 8px; }
.err { background: #fbeaea; border: 1px solid #e6b7b7; color: #8a2b2b; border-radius: 10px; padding: 14px 16px; font-size: 13px; }
footer { margin-top: 40px; text-align: center; font-size: 12px; color: var(--muted); }
</style>
</head>
<body>
<!-- DATA — replace this JSON with your project (see the comment at the top of the file). -->
<script type="application/json" id="review-data">
{
"project": {
"brand": "Truvani",
"agency": "Light Labs",
"date": "2026-07-12",
"note": "Whitelisted paid-social concepts for review"
},
"platforms": ["instagram", "facebook"],
"concepts": [
{
"name": "Heavy-Metal Proof",
"tagline": "Lifestyle hero, then the lab results",
"handles": [
{ "name": "truvani", "partner": "Paid partnership with lightlabs", "initials": "TV" },
{ "name": "Light Labs", "partner": "Paid partnership with truvani", "initials": "LL" }
],
"frames": [
{ "label": "Hook", "prompt": "Product bag hero on soft pink, gold-lace overlay", "headline": "Finally — a plant-based protein that's third-party tested for heavy metals.", "headlineTheme": "dark" },
{ "label": "The problem", "prompt": "Editorial card: 'Plants absorb more than nutrients' + Pb/As/Cd chips" },
{ "label": "Enter Light Labs", "prompt": "Clean card: 'So we sent it to Light Labs' + independent-lab note" },
{ "label": "The results", "prompt": "Results table: Arsenic / Cadmium / Lead, all within limits, green check" },
{ "label": "For context", "prompt": "'Less arsenic than your breakfast' comparison bar" },
{ "label": "The ask", "prompt": "Product you can finally trust — CTA frame", "headline": "Protein you can finally trust." }
],
"headlines": [
"Finally — a plant-based protein that's third-party tested for heavy metals.",
"We tested our protein for heavy metals. Here's what an independent lab found.",
"Most protein powders are never tested for heavy metals. Ours is."
],
"primaryText": "We tested our Plant-Based Protein for the heavy metals that hide in “clean” powders — lead, arsenic and cadmium. Here's exactly what an independent lab measured.",
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
"rollout": {
"title": "How the whitelist runs",
"steps": [
"Truvani reviews and approves the creative — Light Labs builds it.",
"Truvani sends a Meta partnership request granting Light Labs access to this ad only.",
"Light Labs launches it under the co-branded handle.",
"We report performance back — framed as a free, mutually beneficial first test."
]
},
"grounding": "Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."
},
{
"name": "Cleaner Than Rice",
"tagline": "Leads with the brown-rice comparison",
"frames": [
{ "label": "Hook", "prompt": "Split visual: brown rice vs protein scoop", "headline": "Your “clean” brown rice protein? Test it.", "headlineTheme": "dark" },
{ "label": "The claim", "prompt": "Stat card comparing arsenic levels" },
{ "label": "The proof", "prompt": "Light Labs results table" },
{ "label": "The context", "prompt": "What the numbers mean, plainly" },
{ "label": "The ask", "prompt": "Starter-kit offer frame", "headline": "Trust the label. Then trust the test." }
],
"headlines": [
"Your “clean” brown rice protein? Test it.",
"Brown rice protein is often the worst offender for arsenic. We checked ours.",
"“Plant-based” doesn't mean “clean.” We have the lab panel to prove ours is."
],
"primaryText": "Brown-rice protein is one of the most common sources of dietary arsenic. So we sent ours to an independent lab. Here's the panel.",
"destination": { "url": "shop.truvani.com", "cta": "Shop now", "offer": "72% OFF Protein Starter Kit" },
"grounding": "Comparison figures are from Truvani's Light Labs panel and published dietary-arsenic ranges. No competitor is named."
}
]
}
</script>
<div class="wrap">
<header class="project" id="project"></header>
<div class="eyebrow">Creative concept · toggle between ideas</div>
<div class="concepts" id="concepts" role="tablist"></div>
<div class="grid">
<section>
<div class="eyebrow col-label" id="preview-label">In-feed preview</div>
<div class="toggles" id="toggles"></div>
<div class="post" id="post"></div>
</section>
<section>
<div class="board">
<div class="eyebrow" id="board-label">Storyboard · tap to jump</div>
<div class="frames-grid" id="frames-grid"></div>
</div>
<div class="copy" id="copy"></div>
</section>
</div>
<footer id="footer"></footer>
</div>
<script>
/* ============================================================================
RENDER — generic; no need to edit when swapping the DATA JSON above.
========================================================================== */
const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, c => (
{ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
const PLATFORMS = { instagram: "Instagram", facebook: "Facebook" };
let DATA;
try {
DATA = JSON.parse(document.getElementById("review-data").textContent);
} catch (e) {
document.querySelector(".wrap").innerHTML =
'<div class="err"><b>Couldn\'t read the review data.</b><br/>The <code>#review-data</code> block must be valid JSON — double-quoted keys and strings, no comments, no trailing commas. Parser said: ' + esc(e.message) + '</div>';
throw e;
}
const state = { concept: 0, frame: 0, platform: null, handle: 0, headline: 0 };
const concept = () => DATA.concepts[state.concept];
// platforms restricted to the ones we can render; default to first valid
const platformList = () => (DATA.platforms || ["instagram"]).filter(p => PLATFORMS[p]);
state.platform = platformList()[0] || "instagram";
const heart = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M20.8 4.6a5.5 5.5 0 0 0-7.8 0L12 5.6l-1-1a5.5 5.5 0 1 0-7.8 7.8l1 1L12 21l7.8-7.6 1-1a5.5 5.5 0 0 0 0-7.8z"/></svg>';
const comment = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M21 11.5a8.4 8.4 0 0 1-11.8 7.7L3 21l1.9-6.2A8.4 8.4 0 1 1 21 11.5z"/></svg>';
const share = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M22 2 11 13M22 2l-7 20-4-9-9-4 20-7z"/></svg>';
const bookmark = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/></svg>';
function renderProject() {
const p = DATA.project || {};
const line = [p.brand, p.agency && `× ${p.agency}`].filter(Boolean).join(" ");
document.getElementById("project").innerHTML =
`<div class="eyebrow">Creative review${p.date ? " · " + esc(p.date) : ""}</div>
<h1>${esc(line || "Ad creative")}</h1>${p.note ? `<div class="sub">${esc(p.note)}</div>` : ""}`;
document.getElementById("footer").innerHTML =
`Creative review${p.agency ? " · " + esc(p.agency) : ""} — concepts for approval. Nothing here is live until you pick.`;
}
function renderConcepts() {
document.getElementById("concepts").innerHTML = DATA.concepts.map((c, i) => `
<button class="concept" role="tab" aria-selected="${i === state.concept}" data-i="${i}">
<div class="row1"><span class="num">${String(i + 1).padStart(2, "0")}</span>
<span class="frames">${c.frames.length} frame${c.frames.length === 1 ? "" : "s"}</span></div>
<div class="name">${esc(c.name)}</div>
<div class="tag">${esc(c.tagline || "")}</div>
</button>`).join("");
document.querySelectorAll(".concept").forEach(b =>
b.onclick = () => { state.concept = +b.dataset.i; state.frame = 0; state.handle = 0; state.headline = 0; renderAll(); });
}
function handles() {
return concept().handles || [{
name: DATA.project?.brand || "brand",
partner: DATA.project?.agency ? "Paid partnership with " + DATA.project.agency.toLowerCase() : "Sponsored",
initials: (DATA.project?.brand || "AD").slice(0, 2).toUpperCase()
}];
}
function renderToggles() {
const plats = platformList(), hs = handles();
let html = "";
if (plats.length > 1) {
html += `<div class="seg" role="group">${plats.map(p =>
`<button data-plat="${esc(p)}" aria-pressed="${p === state.platform}">${esc(PLATFORMS[p])}</button>`).join("")}</div>`;
}
if (hs.length > 1) {
html += `<div class="seg" role="group"><span class="lbl">Handle</span>${hs.map((h, i) =>
`<button data-handle="${i}" aria-pressed="${i === state.handle}">${esc(h.name)}</button>`).join("")}</div>`;
}
const el = document.getElementById("toggles");
el.innerHTML = html;
el.querySelectorAll("[data-plat]").forEach(b => b.onclick = () => { state.platform = b.dataset.plat; renderToggles(); renderPost(); });
el.querySelectorAll("[data-handle]").forEach(b => b.onclick = () => { state.handle = +b.dataset.handle; renderToggles(); renderPost(); });
document.getElementById("preview-label").textContent = (hs.length > 1 ? "Whitelisted ad · " : "") + "In-feed preview";
}
// placeholder underneath + image on top; a missing/broken image removes itself → placeholder shows
function frameVisual(f, phCls) {
const ph = `<div class="${phCls}"><div class="plabel">${esc(f.label)}</div><div class="pprompt">${esc(f.prompt || "")}</div></div>`;
const img = f.image ? `<img src="${esc(f.image)}" alt="${esc(f.label)}" onerror="this.remove()" />` : "";
return ph + img;
}
function frameHTML(c, f) {
const total = c.frames.length;
const headlineText = state.frame === 0 ? (c.headlines?.[state.headline] || f.headline || "") : (f.headline || "");
const theme = f.headlineTheme === "light" ? " light" : "";
return `<div class="frame">
${frameVisual(f, "ph")}
<span class="counter">${state.frame + 1}/${total}</span>
${headlineText ? `<div class="headline${theme}">${esc(headlineText)}</div>` : ""}
</div>`;
}
function renderPost() {
const c = concept(), f = c.frames[state.frame], h = handles()[state.handle] || handles()[0];
const dest = c.destination || {};
const top = `<div class="top">
<div class="avatar">${h.initials ? esc(h.initials) : ""}</div>
<div class="who"><div class="name">${esc(h.name)}</div><div class="partner">${esc(h.partner || "Sponsored")}</div></div>
<div class="dots">···</div>
</div>`;
let chrome;
if (state.platform === "facebook") {
const domain = dest.url ? esc(dest.url) : "";
const hl = c.headlines?.[state.headline] || f.headline || dest.offer || "";
chrome = `<div class="fb-card">
<div class="meta"><div class="dom">${domain}</div><div class="hl">${esc(hl)}</div></div>
${dest.cta ? `<div class="btn">${esc(dest.cta)}</div>` : ""}
</div>
<div class="fb-actions"><span>Like</span><span>Comment</span><span>Share</span></div>`;
} else {
chrome = `<div class="ig-cta"><span>${esc(dest.cta || "Learn more")}</span><span class="chev">›</span></div>
<div class="ig-actions">${heart}${comment}${share}<span class="save">${bookmark}</span></div>
<div class="likes">6,240 likes</div>
<div class="caption"><span class="h">${esc(h.name)}</span> ${esc((c.primaryText || "").slice(0, 90))}<span class="more"> … more</span></div>`;
}
document.getElementById("post").innerHTML = top + frameHTML(c, f) + chrome;
document.getElementById("board-label").textContent = `${c.name} · ${state.frame + 1}/${c.frames.length} · tap to jump`;
}
function renderBoard() {
const c = concept();
document.getElementById("frames-grid").innerHTML = c.frames.map((f, i) => `
<button class="thumb" aria-current="${i === state.frame}" data-i="${i}">
<div class="box">${frameVisual(f, "mini")}</div>
<div class="cap"><span class="n">${String(i + 1).padStart(2, "0")}</span>${esc(f.label)}</div>
</button>`).join("");
document.querySelectorAll(".thumb").forEach(b =>
b.onclick = () => { state.frame = +b.dataset.i; renderPost(); renderBoard(); });
}
function renderCopy() {
const c = concept(), dest = c.destination || {};
let html = "";
if (c.headlines?.length) {
html += `<div class="block"><div class="eyebrow">Headline — tap to preview</div>${c.headlines.map((h, i) =>
`<button class="headline-opt" aria-pressed="${i === state.headline}" data-i="${i}">
<span class="n">${String(i + 1).padStart(2, "0")}</span><span class="t">${esc(h)}</span></button>`).join("")}</div>`;
}
if (c.primaryText) html += `<div class="block"><div class="eyebrow">Primary text</div><div class="kv" style="margin-top:8px">${esc(c.primaryText)}</div></div>`;
if (dest.url || dest.cta) {
html += `<div class="block"><div class="eyebrow">Destination</div><div class="kv" style="margin-top:8px">
${dest.url ? `<span class="dest">${esc(dest.url)}</span><br/>` : ""}
${dest.cta ? `CTA: ${esc(dest.cta)}` : ""}${dest.offer ? ` → ${esc(dest.offer)}` : ""}</div></div>`;
}
if (c.rollout?.steps?.length) {
html += `<div class="block"><div class="eyebrow">${esc(c.rollout.title || "How it runs")}</div>
<ol class="steps">${c.rollout.steps.map((s, i) => `<li><span class="i">${i + 1}</span><span>${esc(s)}</span></li>`).join("")}</ol></div>`;
}
if (c.grounding) html += `<div class="block"><div class="eyebrow">Live data · real assets</div><div class="grounding">${esc(c.grounding)}</div></div>`;
const el = document.getElementById("copy");
el.innerHTML = html;
el.querySelectorAll(".headline-opt").forEach(b =>
b.onclick = () => { state.headline = +b.dataset.i; state.frame = 0; renderPost(); renderBoard(); renderCopy(); });
}
function renderAll() { renderConcepts(); renderToggles(); renderPost(); renderBoard(); renderCopy(); }
renderProject();
renderAll();
</script>
</body>
</html>
+15
View File
@@ -130,6 +130,21 @@
"Includes a month-end retro plan that feeds the next slate"
],
"files": []
},
{
"id": 10,
"prompt": "We generated four ad concepts for a client (an organic skincare brand) and need to send them something they can actually look at and approve — with the Instagram preview, the carousel frames, and the different headline options they can compare. Can you put that together?",
"expected_output": "Should recognize this as a creative review page request and apply references/creative-review-page.md + the assets/creative-review-template.html template rather than producing plain markdown. Should copy the template into the output folder and populate its DATA object with the four concepts as tabs, each with an in-feed Instagram preview, a labeled frame-by-frame storyboard (frames labeled by narrative job — Hook / Problem / Proof / Ask — not by pictured content), selectable headline variations, primary text, and destination/CTA. Should curate to a reviewable number of concepts (2-4) rather than dumping everything. Should include a required grounding disclosure per concept stating what is real (product photography, any claims/results) and label illustrative proof as illustrative — never present invented stats or stock imagery as the brand's own. Should use styled placeholders for frames not yet rendered to image, and keep image paths relative. Should explain how to deliver it (open locally, host on a static host, or hand off the file).",
"assertions": [
"Produces a creative review page from the HTML template, not plain markdown",
"Populates the DATA object (concept tabs, in-feed preview, frame storyboard, headline variations, copy, destination)",
"Labels storyboard frames by narrative job rather than by pictured content",
"Includes a required grounding/disclosure line per concept; labels illustrative proof as illustrative",
"Does not present invented stats or stock imagery as the brand's real assets",
"Uses placeholders for unrendered frames and keeps image paths relative",
"Explains how to deliver the page (open locally / host / hand off the file)"
],
"files": []
}
]
}
@@ -0,0 +1,106 @@
# The Creative Review Page
A shareable, self-contained web page that presents generated ad concepts for a client or stakeholder to **review and pick** — the visual upgrade to `INDEX.md`. Where the markdown outputs are built for the operator, the review page is built for the person approving the spend: it shows each concept as an in-feed platform mockup, breaks carousels into a labeled frame-by-frame storyboard, lets them toggle copy variations, and discloses what's grounded in real assets.
The template ships at [assets/creative-review-template.html](../assets/creative-review-template.html). It's one file — inline CSS and JS, no build, no dependencies, no network. Open it locally, host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the `.html` file directly.
## When to produce one
- **Presenting a batch for approval** — after Mode 1 or Mode 3 generation, package the top concepts into a review page instead of (or alongside) `INDEX.md`. Picking 5 of 50 is a *visual* decision; a client shouldn't have to read markdown to make it.
- **Pitching a whitelist / co-branded partnership** — the format the source pattern was built for: show the partner exactly what the ad looks like under each handle, with the rollout mechanics spelled out.
- **A monthly slate review** (Mode 4) — render the slate's concepts so the account-state call and the pick happen off one link.
Don't produce one for a single headline tweak or a quick internal gut-check — the markdown output is faster. Reach for the review page when a human who isn't you needs to choose.
## How it's built
The template renders entirely from a JSON block near the top of the file — `<script type="application/json" id="review-data">`. Populate it from your generated concepts and everything else renders — tabs, previews, storyboard, copy panel. You do not edit the render code below the data block. The annotated model below is shown with `//` comments for readability; **the file itself is strict JSON** — no comments, no trailing commas (see "Populating the data safely").
### Data model
```jsonc
{
project: {
brand: "Truvani", // required
agency: "Light Labs", // optional — adds the co-brand line + the default handle fallback (partner label/initials)
date: "2026-07-12", // optional
note: "one-line context" // optional
},
platforms: ["instagram", "facebook"], // previews to offer; first is the default. Supported: instagram, facebook
concepts: [ // each concept is one strategic ANGLE (see SKILL.md "Define Your Angles")
{
name: "Heavy-Metal Proof", // required — the angle name
tagline: "Lifestyle hero, then the lab results", // one line, what makes this concept distinct
handles: [ // optional. 1 entry = normal post; 2 = whitelist handle toggle
{ name: "truvani", partner: "Paid partnership with lightlabs", initials: "TV" },
{ name: "Light Labs", partner: "Paid partnership with truvani", initials: "LL" }
],
frames: [ // 1 frame = single ad; multiple = carousel storyboard
{
label: "Hook", // the frame's job in the narrative arc
prompt: "Product bag hero on soft pink, gold-lace overlay", // image description (shown as placeholder if no image)
image: "images/heavy-metal-01.png", // optional — URL, relative path, or data URI; omit for text-only concepts
headline: "Finally — a plant-based protein that's third-party tested for heavy metals.", // optional per-frame overlay
headlineTheme: "dark" // optional: "dark" (default, white text) or "light" (dark text on light imagery)
}
// … one object per frame
],
headlines: [ // selectable variations; the picked one overlays frame 1 in the preview
"Finally — a plant-based protein that's third-party tested for heavy metals.",
"We tested our protein for heavy metals. Here's what an independent lab found.",
"Most protein powders are never tested for heavy metals. Ours is."
],
primaryText: "The caption / body copy.",
destination: { url: "shop.truvani.com", cta: "Shop now", offer: "72% OFF Protein Starter Kit" },
rollout: { // optional — the mechanics of how this runs (whitelist, launch plan)
title: "How the whitelist runs",
steps: ["step 1", "step 2", "…"]
},
grounding: "What in this concept is real — the required disclosure. See below."
}
// … 2–4 concepts is the sweet spot; more than that and the tabs stop being a decision
]
}
```
### The frame storyboard = a carousel narrative arc
A concept's `frames` are its storyboard. Label each frame by the *job it does*, not its content — `Hook`, `The problem`, `The results`, `The ask`. This is the same narrative-arc thinking as the carousel frameworks: a proof-led concept is literally Hook → Problem → Mechanism → Results → Context → Ask. For the five reusable carousel arcs (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough), see `carousel-frameworks.md` in the **social** skill and pick the arc that fits the angle before writing frames.
### Images vs. placeholders
Every frame renders one of two ways:
- **`image` provided** — the real creative (from the Mode 3 `images/` folder, a hosted URL, or a data URI) fills the frame.
- **`image` omitted** — a styled placeholder shows the frame `label` + `prompt`. This is the intended state for concepts that are copy + image-prompt but not yet rendered to image — the review page is useful *before* images exist, and stays useful as they get filled in.
Ship review pages with placeholders freely; they communicate the concept. Swap in images as they're generated.
## Grounding — the disclosure block is required
Every concept must carry a `grounding` line, and it must be true. This is the same rule as the Grounded Inputs corpus, surfaced to the client: state exactly what is real (which lab panel, which review, which product photography) and, by omission, what is illustrative. The source pattern's line is the model — *"Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."*
Never present invented stats, fabricated test results, or stock imagery as the brand's own. If a concept's proof isn't real yet, the grounding line says so ("Results shown are illustrative pending the lab panel") — a review page that launders fiction as fact is worse than no review page.
## Populating the data safely
The `DATA` lives in a `<script type="application/json" id="review-data">` block — it's inert data (parsed with `JSON.parse`), not executable code, so a value can never run as script. Two rules when you write it:
- **Valid JSON only** — double-quoted keys and strings, no comments, no trailing commas. (The page shows a clear error banner if the JSON is malformed, so a typo fails loud, not silent.)
- **Escape `<` as `\u003c` in every text value.** A value literally containing `</script>` would otherwise close the data block early. Since agents write the JSON, apply this escape mechanically to all string values. All values are HTML-escaped again at render time, so this is defense-in-depth, but the source-level escape is the one that matters — do it.
## Producing and delivering it
1. Copy `assets/creative-review-template.html` into the batch's output folder as `review.html` (e.g. `outputs/YYYY-MM-DD/review.html`).
2. Replace the `DATA` object with the real project — concepts, frames, copy, grounding. Populate `image` paths for any frames you've rendered (keep them relative to the html file so the folder stays portable).
3. Verify it renders: open it in a browser, click through every concept tab, both platform and handle toggles, and each frame in the storyboard.
4. Deliver: hand off the folder (html + `images/`), or host it. For a client link, `vercel deploy` or any static host works — it's a single page with local assets.
Keep the review page next to the markdown outputs, not instead of them: `INDEX.md` and the per-concept files remain the operator's record and the grounding audit trail; `review.html` is the approval surface built on top.
## Common mistakes
- **Too many concepts** — 2–4 tabs is a decision; 10 is a menu nobody finishes. Curate before you present.
- **Unlabeled or content-labeled frames** — label by narrative job (`The proof`), not by what's pictured (`Table screenshot`).
- **Missing or dishonest grounding** — every concept discloses what's real; illustrative proof is labeled illustrative.
- **Editing the render code** — everything is data-driven; if something won't show, it's a `DATA` field, not the JS.
- **Absolute image paths** — keep image paths relative so the output folder can be zipped, moved, or hosted intact.
+13 -7
View File
@@ -1,13 +1,13 @@
---
name: prospecting
description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," or "qualified leads." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling.
description: When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or local small businesses. Also use when the user mentions "prospecting," "build a prospect list," "find prospects," "find leads," "lead gen list," "find SaaS companies that," "find B2B companies," "find local businesses," "ICP-fit accounts," "who should we go after," "outbound list," "target account list," "find clients near me," "businesses without websites," "prospect research," "qualified leads," "find my first customers," "early adopters," "design partners," "beta users," or "who has this problem." Use this for the list-building and qualification phase. For writing the outbound copy after the list is built, see cold-email. For deep competitive research on specific accounts, see competitor-profiling.
metadata:
version: 1.0.0
version: 1.1.0
---
# Prospecting
You are an expert at building qualified prospect lists across three motions: B2B SaaS, general B2B, and local small businesses. Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.
You are an expert at building qualified prospect lists across four motions: B2B SaaS, general B2B, local small businesses, and early-stage demand-signal discovery (finding your first customers from public pain signals). Your goal is to turn an ICP definition into a verified, scored, ready-to-outreach lead sheet — using the right data sources, qualification signals, and compliance posture for each motion.
## Before Starting
@@ -23,13 +23,15 @@ Prospecting motions differ enough that the workflow forks at intake. Pick **one*
| **SaaS** | Other SaaS companies / digital businesses | ICP fit + tech stack match + growth signals (funding, hiring, product velocity) | LinkedIn, BuiltWith, Crunchbase, Apollo, Clay, Clearbit, ProductHunt |
| **B2B** | Non-SaaS B2B (services, manufacturers, enterprises, mid-market) | Industry + size + geographic fit + buying signals (trigger events, vendor changes) | Apollo, ZoomInfo, Clay, Clearbit, LinkedIn Sales Nav, industry directories |
| **Local SMB** | Local small businesses (shops, gyms, restaurants, clinics, salons, services) | Active business + website status + proximity + decision-maker access | Google Maps, Yelp, local directories, Facebook, business websites |
| **Demand-signal** | Early-stage: your first customers, design partners, or beta users | Evidence of the exact pain/demand/timing signal — a cited public source, not just firmographic fit | Forums, communities, reviews, GitHub issues, job posts, launch announcements (via last30days, social-fetch, scraping) |
If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other.
If the user describes a hybrid motion (e.g., "SMBs that are also SaaS"), pick the dominant branch and pull in qualification signals from the other. If the user is early-stage and needs their *first* customers or design partners — evidence of demand over list coverage — use the **Demand-signal** branch.
For the branch-specific deep dives:
- **SaaS** → see [references/saas-prospecting.md](references/saas-prospecting.md)
- **B2B** → see [references/b2b-prospecting.md](references/b2b-prospecting.md)
- **Local SMB** → see [references/local-prospecting.md](references/local-prospecting.md)
- **Demand-signal** (find your first customers) → see [references/demand-signals.md](references/demand-signals.md)
---
@@ -71,7 +73,7 @@ For email contacts (B2B / SaaS branches), **always verify deliverability before
### Phase 4 — Score and prioritize
Apply this rubric across all branches:
Apply this rubric for the **SaaS, B2B, and Local SMB** branches. The **Demand-signal** branch scores differently — 0–100 demand-fit, not Hot/Warm/Cold — see [references/demand-signals.md](references/demand-signals.md).
| Score | Definition |
|-------|------------|
@@ -84,6 +86,8 @@ Branch-specific signals refine the scoring — see each reference file. Default
### Phase 5 — Output the lead sheet
(SaaS / B2B / Local SMB. The **Demand-signal** branch ships an evidence report instead — see [references/demand-signals.md](references/demand-signals.md).)
Default to a markdown table in chat. Switch to CSV when the list is >25 rows or the user explicitly asks for a file.
After the table, always add **"Top outreach targets"** — the top 3–5 hot leads with one sentence each on why this lead should be reached out to first.
@@ -103,6 +107,8 @@ These apply to every branch. **Read first, every engagement.**
4. **GDPR / CAN-SPAM / CASL aware.** Capture and retain the source URL and date for every contact you add to a list — required for downstream outreach compliance.
5. **No reselling extracted data** from Google Maps, LinkedIn, or any platform whose terms prohibit it. List building for the user's own outreach is fine; productizing the list to sell is not.
6. **Rate limit yourself.** Even on public sources, space requests. Don't fingerprint as a bot.
7. **No breached, leaked, or unprovenanced data.** Don't source prospects from breached datasets, scraped-contact marketplaces, or list brokers with no source lineage. Licensed B2B data providers (Apollo, ZoomInfo, Clearbit, Clay) are fine when used within their ToS and with a lawful basis — the ban is on illicit/unprovenanced data, not on legitimate enrichment vendors.
8. **Never target or infer sensitive traits.** Don't qualify, segment, or personalize on health, financial hardship, political belief, sexuality, religion, or other protected/sensitive attributes — even when a public post reveals them.
For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Maps ToS, Clay/Apollo/ZoomInfo use restrictions): see [references/compliance.md](references/compliance.md).
@@ -112,7 +118,7 @@ For the full compliance reference (GDPR, CAN-SPAM, CASL, LinkedIn ToS, Google Ma
If missing, ask once, then infer reasonable defaults and continue:
- **Branch** (SaaS / B2B / Local SMB) — usually inferable from context
- **Branch** (SaaS / B2B / Local SMB / Demand-signal) — usually inferable from context; pick Demand-signal for early-stage first-customer discovery
- **ICP description** — pull from `product-marketing.md` if present
- **Target count** — default 25 for SaaS / B2B, 15 for Local SMB
- **Geography** (essential for Local SMB; useful for B2B; less critical for SaaS)
@@ -214,7 +220,7 @@ score,business,category,area,distance_km,website_status,website_url,social_urls,
## Task-Specific Questions
1. Which branch — SaaS, B2B, or Local SMB?
1. Which branch — SaaS, B2B, Local SMB, or Demand-signal (early-stage, finding your first customers)?
2. What's your ICP? (Or: should I pull from your product-marketing context?)
3. How many qualified leads do you want?
4. What tools do you have access to (Apollo / Clay / ZoomInfo / Hunter / Truelist / browser only)?
+15
View File
@@ -102,6 +102,21 @@
"References truelist.md or data-sources.md"
],
"files": []
},
{
"id": 7,
"prompt": "I just built a tool that automates failed-payment follow-up for gym owners. I have no customers yet. Help me find my first ten — the people who are actually dealing with this problem right now.",
"expected_output": "Should select the Demand-signal branch (early-stage, first customers, evidence-of-demand) and load references/demand-signals.md — NOT the SMB/B2B list-building branches. Should start with a product brief, then mine the five signal buckets (explicit demand / pain / workaround / switching / timing) across public discourse (forums, communities, reviews, GitHub issues, job posts) — using last30days for recency, social-fetch/scraping to read original pages, not qualifying from snippets. Should score prospects on demand-fit (pain 25 / product fit 25 / timing 20 / reachability 15 / evidence quality 15, 0-100 with bands) rather than ICP-fit Hot/Warm/Cold, and require a cited public signal for every primary-shortlist prospect. Should draft source-based openers but never auto-send. Should produce an evidence report (verdict → ICP → top prospect → shortlist with sources+scores → repeated patterns → 7-day manual outreach plan → limits) and label prospects as 'potential customers based on public signals,' not confirmed buyers. Should honor the compliance guardrails including no data brokers/leaked data and no sensitive-trait targeting.",
"assertions": [
"Selects the Demand-signal branch, not the SMB/B2B/SaaS list-building branches",
"Mines the five signal buckets from public discourse rather than contact databases",
"Uses recency/original-source tooling (last30days, social-fetch, scraping) and does not qualify from snippets",
"Scores on the demand-fit rubric (0-100 weighted), not ICP-fit Hot/Warm/Cold",
"Requires a cited public signal for every primary-shortlist prospect",
"Drafts openers but never auto-sends; labels prospects as potential-based-on-public-signals",
"Produces the evidence report structure with a 7-day manual outreach plan and limits"
],
"files": []
}
]
}
@@ -0,0 +1,129 @@
# Demand-Signal Discovery (Find Your First Customers)
The other three branches build a list from who *fits* (firmographics, technographics, proximity). This branch builds a list from who is *already showing the pain* — the early-stage motion where you have a product and a hunch but no customer base yet, and you need your first ten real conversations. You are not filtering a database; you are mining recent public discourse for people describing the exact problem you solve, then linking every prospect to the evidence.
Use this branch when the user is pre-product-market-fit, launching something new, or looking for **design partners, beta users, or first customers** rather than a scaled outbound list. It reuses the shared five phases and every compliance guardrail in SKILL.md; what changes is where you look, how you score, and what you ship.
Pattern credit: the framework here is re-expressed from the open-source `first-customer-finder` Codex skill (Kappaemme, MIT), extended with our live-recency tooling.
## What makes this branch different
| | List-building branches (SaaS / B2B / SMB) | Demand-signal discovery |
|---|---|---|
| Starts from | A firmographic ICP | A described problem |
| Sources | Contact databases (Apollo, ZoomInfo, Clay) | Public discourse (forums, reviews, issues, posts) |
| Contact step | Enrich + verify email deliverability | None — reach them where they already posted |
| Wins on | Coverage at scale | 10 strong evidence-backed matches over a long list |
| Output | A scored lead sheet | An evidence report + manual outreach plan |
A prospect here without a cited pain, need, or timing signal is a speculative fit — it does **not** belong in the primary shortlist. Evidence is the entry ticket.
## Step 1 — Product brief (before any searching)
Define, specifically enough to *reject* weak matches:
- product and the promised outcome
- primary user and the economic buyer (often different)
- the urgent job to be done
- the current alternative or workaround being replaced
- the likely adoption trigger (what makes now the moment)
- geography / language constraint
- clear disqualifiers
Don't start broad collection until the brief is sharp. Pull from `.agents/product-marketing.md` if it exists.
## Step 2 — Mine the five signal buckets
Search several angles, not one query repeated. Adapt wording to how the audience actually talks (mine their vocabulary from organic content first — see the ad-creative hook-system's organic-language note for the same idea).
1. **Explicit demand** — "looking for," "recommend a tool for," "alternative to [X]," "does anything exist that," "how do you all handle."
2. **Pain** — "takes hours," "so manual," "hate that," "keeps breaking," "biggest frustration with," "why is there no."
3. **Workaround** — spreadsheets, copy-paste, a VA, a Zapier chain, a script, a template, any repeated manual step that your product would replace.
4. **Switching** — cancellation, migration, "moving off [competitor]," a missing feature, a pricing complaint, competitor frustration.
5. **Timing** — a public launch, a new hire for the relevant function, expansion, a new workflow or regulation, an integration announcement — a *current* event that makes the product relevant now.
**Use our live-recency edge.** A generic skill relies on whatever a web search surfaces; you have better:
- **last30days** — Reddit, Hacker News, X, YouTube, and web signals from the last 30 days. This is the single highest-value tool for this branch: recency *is* the timing signal.
- **social-fetch** — pull the full content of a specific post/thread you find, normalized.
- **scraping** / **Firecrawl** / **Browserbase** — read the original public page (a forum thread, a GitHub issue, a review), never qualify from a search snippet alone.
- **deep-research** — for a multi-source sweep with adversarial verification when the wedge is broad.
- **competitor-profiling** / **customer-research** — competitor switching signals and review-mining for the pain language.
## Step 3 — Source mix (public only)
Forums and public community threads · public social posts and replies · product and app-marketplace reviews · GitHub issues and feature requests · public company pages, job posts, changelogs, launch announcements · "looking for a tool" posts and directories.
Avoid private groups, gated communities, data brokers, leaked datasets, and any source whose terms prohibit access — the same compliance guardrails as every other branch (see SKILL.md), including the no-sensitive-traits rule.
**Business/professional context only.** Qualify and reach out only where someone is posting in a professional or business capacity about a work problem (a founder in an indie-hackers thread, a developer in a GitHub issue, an ops lead in a subreddit for their role). Exclude personal-distress contexts entirely — health, financial hardship, addiction, grief, or any consumer support forum where people are venting personal problems, even if your product is tangentially relevant. When the motion is genuinely consumer (B2C), a public pain post is not on its own a lawful basis for cold outreach — reach people through the channel's own norms (reply publicly where replying is expected) and never DM a stranger off a personal post.
Quote minimally, paraphrase by default, and link every material pain or timing signal.
## Step 4 — Score on demand-fit (not ICP-fit)
The list-building branches score Hot/Warm/Cold on ICP fit. This branch scores 0–100 on **demand fit** — how strongly the evidence says this specific prospect wants this specific thing now. Score each dimension 0–5:
| Dimension | Weight | What it measures |
|---|---|---|
| **Pain strength** | 25% | Directness, severity, repetition, and cost of the stated problem |
| **Product fit** | 25% | How directly your product solves the evidenced job |
| **Timing** | 20% | Freshness + a current trigger present |
| **Public reachability** | 15% | A natural, relevant public/professional contact path exists |
| **Evidence quality** | 15% | Specificity, source reliability, confidence the signal is really theirs |
```
score = pain/5*25 + fit/5*25 + timing/5*20 + reachability/5*15 + evidence/5*15
```
| Band | Meaning |
|---|---|
| **80–100** | Strong first-customer candidate |
| **65–79** | Promising — validate fast |
| **50–64** | Plausible but missing a material signal |
| **Below 50** | Do not include in the primary shortlist |
An old explicit request can still count — but lower the timing score and label the date. A company that merely matches the industry with no evidenced trigger is *not* a qualified prospect here.
### Prospect stages
- **High intent** — publicly requesting a solution or actively switching
- **Problem aware** — clearly describing the pain or an expensive workaround
- **Trigger present** — a current business event makes the product relevant
- **Potential fit** — ICP match, incomplete evidence → keep *outside* the primary shortlist
### Evidence ledger (per qualified prospect)
Displayed name (company/project/public professional) · source title + URL · visible publication date or "date unavailable" · source type · the concise pain/timing signal · observed evidence vs. inference (label which) · score breakdown · freshness warning when the signal is stale.
## Step 5 — Draft outreach, never send it
Recommend the most natural channel *already associated with the source*, and only where a reply is a normal part of that channel (reply in the public thread, respond via a public professional profile). Don't turn a public post into a private DM the poster didn't invite, and never contact someone off a personal-distress post. Draft one opener, under ~90 words, in this shape:
1. mention the public context naturally
2. connect it to the exact problem
3. explain the product in one sentence
4. ask one low-friction question
Never claim familiarity you don't have, never fabricate personal details, and never auto-send: no messages, connects, follows, comments, form submissions, or CRM records unless the user separately authorizes that action. This is the manual/gated posture from the marketing-loops guardrails.
## Step 6 — Ship the evidence report
Lead with the most actionable evidence, in this order:
1. **Verdict** — does the product have reachable early-customer signal, or not yet? (An honest "not yet, here's why" is a valid answer.)
2. **ICP** — buyer, job, trigger, disqualifiers.
3. **Top prospect** — the single strongest evidence-backed candidate and why now.
4. **Prospect shortlist** — per prospect: source, pain signal, demand-fit score, stage, why-now, channel, opener.
5. **Repeated patterns** — pains and triggers recurring across prospects (these are your positioning and messaging gold).
6. **Seven-day manual outreach plan** — a low-volume validation sequence (e.g., contact the top 3 with one source-based question; share a mockup only after they confirm the pain; target three conversations and one design-partner commitment).
7. **Limits** — what evidence is missing and what must be confirmed through real conversations.
For a shareable standalone HTML version of this report, the JSON→HTML generator pattern in ad-creative's [creative-review-page.md](../../ad-creative/references/creative-review-page.md) is the model (escape every value; keep it self-contained).
## The honesty rules (non-negotiable)
- Every primary prospect links to at least one real public signal. No signal, no shortlist.
- Label the output **"potential customer based on public signals"** — never "interested," "will buy," or "has consented."
- Prefer ten strong matches over a long generic list. Make uncertainty and stale evidence visible.
- Personalize from the cited source, not from invented assumptions.
- Treat the shortlist as a research hypothesis to validate through conversations, not a customer database.