Single plugin, namespaced
All Vakari work routes through /vakari:<skill>. No fragmented plugin maze, no name collisions, no "which version of /research is this." One pull, one install, one source of truth.
A consolidated Claude Code plugin that encodes the full Vakari workflow — research, strategy, creative, production guidance, diagnostics, reporting, case studies, sell — as skills that hand off clean packets to each other. It includes a make-time craft loop and a Meta-ID-keyed ad-lifecycle data spine tying production route to live outcome, plus a video skill family — b-roll, captions, and HyperFrames overlays — each gated preview-first, none of them silently spending or rendering.
Each one is load-bearing. Together they explain why this is one plugin instead of eighteen separate skills — and why outputs feel coherent across skills you've never explicitly trained together.
All Vakari work routes through /vakari:<skill>. No fragmented plugin maze, no name collisions, no "which version of /research is this." One pull, one install, one source of truth.
Skills produce Markdown packets with named sections — not rigid JSON. Enough structure to make the next skill's job reliable; loose enough that judgment isn't squeezed out.
Eleven shared reference files hold the operating doctrine — confidence levels, packet shapes, artifact system, diagnostic rules, craft schema, output routing. The per-medium video doctrine (b-roll / captions / HyperFrames) lives inside each skill's own folder — single-consumer files stay local. Skills consult references section-scoped, so a compliant run loads under 900 lines. Updating one reference makes every consuming skill smarter without per-skill rewrites.
Every generating skill produces both — a text-heavy Markdown packet (the carrier) and a fit-for-purpose HTML artifact (the action surface, designed for what someone actually wants to do with it).
A make-time craft loop records which route/tool/model fit each job and what worked or fell short — gated on judgment at production time, not on conversion. Read-back is asymmetric: misses redirect the next build immediately; wins stay advisory until proven. Lessons live in files the skills read, never hard-coded into prompts — so the system gets less bad without getting less creative.
The video skills generate assets and can cost money, so they obey a preview-then-approve gate: emit the packet + a cheap preview by default, surface an estimated cost, and never run a paid generation or final render without explicit per-run approval. And /vakari:hyperframes wraps the HeyGen HyperFrames runtime — it directs the native skills and gates the render, but never reimplements the framework or edits its workspace.
The canonical chain runs through research → strategy → creative strategy (launch frame + concepts) → production — including the video family (b-roll, captions, HyperFrames overlays). Three loops sit around it: feedback (winners + craft), data (campaigns DB + reconciliation), artifact + sell (proof and growth). Click any skill node to jump to its detail.
vakari:researchvakari:meta-strategyvakari:creative-strategyvakari:scriptsvakari:brollvakari:hyperframesvakari:captionsvakari:static-adsvakari:transcribevakari:craftvakari:winnersvakari:ingestvakari:reconcile-adsvakari:diagnosevakari:reportvakari:case-studyvakari:growth-diagnosticvakari:sell
Each handoff is a packet — a Markdown doc with named sections defined in references/packet-contracts.md. Skills can skip levels (case-study consumes research + the campaign README + winners + transcripts directly), but the chain is the default reliable route. The data loop accepts two input shapes: a Meta CSV (loaded into the campaigns DB) or a performance-packet bundling Meta-side metrics with downstream CRM funnel data (Meta rows written to the DB; full-funnel context preserved as queryable Markdown — along with exact Meta lead submissions and lead → GHL contact → opportunity attribution). /vakari:ingest stamps each ad's Meta ad_id into the DB and queues it for /vakari:reconcile-ads, which links the ad to its workspace creative and stamps its production route — so the _craft bank's route lessons join live period_metrics and route-vs-outcome becomes answerable. A video slot from /vakari:scripts flows through the video family — /vakari:broll plans supporting footage (reference-image → Seedance, gated), /vakari:hyperframes directs overlays/motion-graphics on the HeyGen runtime, and /vakari:captions adds the caption-last track (timing from the cut, words from what was actually said — a three-way reconcile of approved script × as-delivered × audio). Each emits a packet + preview and gates the render.
Each skill stays lean by deferring shared concepts to references. Click + details on any skill to see inputs, outputs, agents, and references. Click any slash command to copy it.
Client research orchestrator. Campaign-add mode (the common path) researches only a new campaign's delta with a scoped subset of the 5 specialist agents; foundation mode runs the full 5-agent audit for a cold client. Produces research-packet + Markdown carrier brief; HTML dashboard on request or when prospect-facing; updates brand.json as a byproduct.
Meta account architecture + operational strategy. Translates research — or, for known clients, campaigns.db history + brand kit + wiki client page via the fast path — into how the account is structured and operated. ABO equal-spend default per methodology.
Launch framing + concept generation. Owns the launch frame (falsifiable campaign goal, success/kill criteria, 3–6 slot band, budget allocation, timeline — written into the campaign README, not a separate artifact) AND fills each slot with a concept (angle + hook + visual + format + production route + what it tests). Consults the winners library, the _craft bank, and creative intelligence by default. Replaces the retired /vakari:campaign.
Video ad script writer. Each script follows the Vakari 5-beat path (hook → pain → outcome → offer → CTA) in the client's voice. Reads winners + brand.json + audience language. Ships a print-ready teleprompter export; Meta launch copy is NOT here — /vakari:static-ads writes it at launch time from the as-delivered VO.
Static (and carousel) ad planning, copy, AND design. On-image text, primary text, description, CTA, format, dimensions, carousel order — then the design phase: layout, typography, color, asset list, production-route recommendation (Figma / AI gen / HTML render / hybrid, per-job, not pipeline-locked), with a campaign design-system lock created on the first static run and reused after. Also writes Meta launch copy for finished video spots at launch time from the as-delivered VO. Replaces the retired /vakari:design.
B-roll planner, router, and prompter. Produces one broll.md — the pre-spend plan first, then the generation record appended after approved generation — per-clip objective, shot type, route, prompts, provenance. NOT a blind text-to-video generator: the default AI route is reference-image-first (Carter photo OR a generated still → operator approves the still → Seedance via Higgsfield). Planning + dry-run by default; paid generation is gated behind explicit per-run approval with a surfaced cost estimate.
Overlay / motion-graphics director. Plans the overlay-packet (lower-thirds, stat callouts, proof tags, CTA bugs, kinetic type, end cards), ports proven prior-campaign overlay comps before authoring fresh, then wraps the HeyGen HyperFrames runtime — delegating composition mechanics to its native skills and driving the native preview for creative approval. The render itself is local + free, no spend gate. Does NOT reimplement HyperFrames; does NOT edit the framework workspace.
data-* composition to the native /hyperframes, /hyperframes-cli, /hyperframes-media skills. If those are absent, it surfaces the install step and stops — never reimplements./hyperframes-cli.<spot>/transcript.json (beat timing) · brand.json (ingredient, not prison)Caption-last finishing pass. Takes a picture-locked WIP MP4 + script-as-delivered.md + the approved script and produces timed, brand-styled captions. The load-bearing rule: timing comes from the cut, words come from what was actually said — resolved by a three-way reconcile (approved script × as-delivered × audio). Whisper is authoritative for timing only. Emits a caption-packet + preview by default; the final burn-in/alpha render follows operator approval.
<spot>/transcript.json, else a local Whisper pass on the WIP) supplies timing only. Words resolve by the three-way reconcile — approved script × as-delivered × audio; where sources disagree, what was actually said wins and the timing snaps to it.script-as-delivered.md · approved script (<spot>/_docs/script.md) · transcript.json if present · brand.json (caption style).srt/.vtt on approvalLocal video transcription via mlx_whisper. Primary path — a local final render in a Vakari spot → script-as-delivered.md + transcript.json (word timings) + an as-delivered-vs-scripted diff. Other modes on request: URL download via yt-dlp (Instagram / Meta Ad Library), business-name Ad Library search, batch. Preserves transcripts; cleans up downloaded media.
<spot>/_docs/script-as-delivered.md + <spot>/transcript.json~/wikis/vakari/raw/notes/7-category winner capture. Stores proven creative — video scripts, static ads, prompts, offers, visual hooks, campaign structures, downstream-quality observations — with templatized versions for cross-client reuse. Reconciles headline evidence against campaigns.db lifetime data at capture and cite time; accepts pre-filled data-triggered handoffs from /vakari:ingest and /vakari:diagnose.
_winners/<vertical>/<category>/<slug>.md[COMPANY], [CITY], [SPEC], etc.) so future skills can fill the template for new clients in the same vertical.creative-intelligence.md via wiki ingest.Make-time craft capture. Run after producing a creative element (static or video) to record what worked or fell short per production stage — descriptive route/tool/model naming + tagged conditions. Gated on judgment at production time, not conversion. Feeds semantic read-back in static-ads + creative-strategy. Writes _craft/ files only (no DB). "Less bad, not less creative."
working-doctrine or promoted. Multi-entry per run — one ad fans across several decisions.Two modes — Meta Ads-Manager CSV → campaigns DB (Mode A), or C2 performance-packet (Meta + CRM full-funnel together) → campaigns DB (Meta rows) + preserved as queryable Markdown, plus exact Meta lead submissions and lead-path attribution (Mode B). Auto-detects mode. Idempotent. Auto-populates optimization_log from status/budget diffs between ingests — no interactive prompt. Stamps each ad's Meta ad_id onto the lifecycle spine and queues new ads for /vakari:reconcile-ads — never blocks on identity. Doesn't make recommendations — emits an ingest log + recommended-next-skill pointer.
period_metrics at the ads_manager_sliced grain (demographic age/gender slices) · prefers an external ingest script, falls back to inline SQL.packet_lifetime_all_up grain) where entity IDs + dates fit · preserves the GHL/full-funnel packet at the canonical drop location as queryable Markdown · loads exact lead submissions (meta_lead_submissions) + lead-path attribution (lead_paths) + per-asset-element sidecars. Accepts C2's title-cased all-time CSV and the …_asset-insights sidecar filenames.ad_id onto the DB lifecycle spine; new or changed ads are queued pending for /vakari:reconcile-ads. Ingest never blocks on identity — reconciliation is a separate, interactive step.optimization_log is auto-populated from status/budget diffs between ingests — the closed loop no longer depends on remembering to confirm.period_metrics holds both ads_manager_sliced demographic rows and packet_lifetime_all_up packet-lifetime rows. Reads pick between them via queries.select_grain so a stale demographic export never shadows a fresher all-up packet; a documented retire_sliced_for_client path drops stale slices once all-up is authoritative.exact_id_match · exact_contact_match (same phone OR email + a compatible name, high-confidence) · strong_inferred · weak_inferred · unmatched. A value_tier guard never promotes pipeline/opportunity value to booked/won/revenue without explicit evidence.The identity bridge. Resolves the pending reconciliations /vakari:ingest queued — links each live Meta ad to its workspace creative (canonical_creative_id) and stamps its production route onto the campaigns-DB lifecycle spine. Batch-confirms confident matches; handles ambiguous ones one-by-one; never auto-merges.
meta_ad_id is the stable key. Closing the bridge is what lets the _craft route lessons join live period_metrics — route-vs-outcome.ad_aliases hit (auto-suggested, batch-confirmed). Ambiguous = fuzzy / multiple candidates → resolved one-by-one or marked ignored._craft bank for the matched creative and pre-fills route (route_source: craft vs manual). Conflicting craft routes are never auto-filled — it asks._craft only where route_source='craft' — never overwrites a manual route.Live-campaign triage. Reads the performance-packet (Meta + CRM together) where available, plus the campaigns DB. Applies kill rules / troubleshooting patterns / fatigue thresholds / scaling triggers. Separates cheap leads from leads that actually progress, weighted by attribution confidence. Reads optimization_log (auto-populated at ingest) for the recently-optimized rule. Produces priority-tagged actions (Immediate / This Week / Monitor). Internal tier — direct, no client softening; Markdown carrier by default, HTML on request.
exact matches reliable, strong-inferred usable with caveats, weak-inferred shouldn't drive kill/scale decisions alone.diagnostic-rules.mdoptimization_log — auto-populated at ingest, not written interactively here.Recurring client-facing performance report. Reads the performance-packet (Meta + CRM together) where available for full-funnel framing — lead quality and pipeline movement alongside the headline metrics, not just CPL. Client-facing tier — polished, narrative, no internal jargon.
Prospect Blueprint diagnostic. 6 weighted pillars (acquisition, conversion, lead handoff, sales process, measurement integrity, unit economics). Scorecard + funnel leak map + top findings + quick wins + 30-day roadmap. Engine for the paid Blueprint deliverable.
Durable proof / narrative artifact from a closed campaign — or, in backfill mode, rebuilt retroactively from campaigns.db + results + captured winners when artifacts predate the packet discipline. Three tiers — internal (sources cited), client-facing (polished), prospect-facing (one-paragraph + KPI bar, reconciled campaigns.db figures; familial engagements disclose the relationship). ONE headline metric discipline; named transferable pattern; publishes shareable tiers to the vault on request.
Founder-led sales — a lazy-loading router across 8 modes spanning the sales cycle: outreach, Blueprint framing, pre-call prep, discovery, qualification, objection handling, proposal drafting, follow-up. Detects the mode and loads ONLY that mode's doctrine (~400 lines a run, down from 1,799). Written outputs save to the workspace _sell/ pipeline (per-prospect files + pipeline.md board). Composes with public sales frameworks for depth on hard prospects.
references/modes/ and loads only when that mode fires. Proof, objection patterns, offer construction, qualification signals, proposal scaffold + voice context stay skill-local. Plugin-level methodology + artifact-system apply.Skills stay lean by deferring shared concepts here — and references are section-scoped, so a compliant run loads only what it cites (under 900 lines, down from 1,700–2,200). Updating one reference makes every consuming skill smarter without per-skill rewrites — the engine for ongoing improvement. The 14 single-consumer video-family references (system / vocabulary / taste-rubric / failure-taxonomy / output-contract per medium) moved into their skills' own folders — b-roll, captions, and HyperFrames doctrine now travels with its skill.
| Reference | What it owns | Consumed by |
|---|---|---|
| methodology.md | Operating doctrine: account-structure defaults (ABO equal-spend) · four-level confidence scale · brand-as-reference framing · lead-conversion moat | every skill |
| artifact-system.md | MD-as-carrier / HTML-as-deliverable doctrine · use-first design · 3 tiers (internal/client/prospect) · rejection of default shapes | every generating skill |
| artifact-components.md | Component vocabulary: KPI cards · scorecards · funnel leak maps · campaign architecture maps · script cards · hook tables · creative test matrices · persona cards · competitor blocks · prompt blocks · source drawers · action cards · tier markers · video-family components (storyboard/timeline · caption-preview · contact sheet · render-review) · the preview-then-approve gate lives in artifact-system.md | every HTML-rendering skill |
| packet-contracts.md | 17 packet shapes: research · meta-strategy · creative-strategy · script · static-ad · performance (Meta + CRM full-funnel with attribution confidence, exact lead submissions, lead-path attribution) · winner · diagnosis · report · prospect-blueprint · case-study · ingest · transcript · video packet shapes: broll-plan · broll-packet · caption-packet · overlay-packet — campaign + design packets absorbed into creative-strategy + static-ad | every skill |
| winners-schema.md | 7-category winner taxonomy · per-type required content · file location convention · templatization rules · promotion path | winners · scripts · static-ads · creative-strategy · case-study · sell · growth-diagnostic |
| creative-intelligence.md | Crystallized patterns from validated winners — hook patterns · offer patterns · visual patterns · campaign-structure patterns · downstream-quality patterns · format patterns · script structure patterns · vertical notes | scripts · static-ads · creative-strategy · sell · growth-diagnostic · meta-strategy · diagnose |
| craft-schema.md | Make-time craft capture → _craft/ bank · locked frontmatter (type · verdict · confidence) · descriptive route + open tool/model naming (semantic read-back — matched on meaning, not a locked enum) · condition-tag vocabulary · canonical_creative_id format (shared with the DB spine, so files join the DB) · asymmetric read-back algorithm |
craft · static-ads · creative-strategy · case-study |
| case-study-schema.md | Three tier shapes · ONE-headline-metric discipline · pattern naming · sources discipline · file naming | case-study · sell |
| data-paths.md | Canonical paths to the campaigns DB + scripts · the tables clients · campaigns · ad_sets · ads (the Meta-ID-keyed ad lifecycle spine: meta_ad_id · canonical_creative_id · route · reconcile_status · launched/retired) · period_metrics at two grains (ads_manager_sliced demographic slices + packet_lifetime_all_up packet-lifetime rows, chosen freshness-aware via queries.select_grain; retire_sliced_for_client maintenance path) · asset_metrics · adset_settings_snapshot · meta_lead_submissions (exact Meta Page-token submissions) · lead_paths (lead → GHL contact → opportunity attribution, typed match confidence + value_tier guard) · optimization_log · ad_aliases · performance-packet drop + preservation · idiomatic queries |
ingest · reconcile-ads · diagnose · report |
| output-paths.md | Canonical output routing — every skill writes to _docs/<skill>/<YYYY-MM-DD>/<carrier>.md · the _craft/ bank location · uniform client + campaign naming |
every generating skill |
| diagnostic-rules.md | Kill rules (hard + soft) · troubleshooting pattern matching · frequency / fatigue thresholds · scaling rules · don't-recommend-changes rules · common-mistakes watchlist | diagnose · report |
These are the canonical compositions. Skip-level invocations are fine (case-study can consume research + winners directly), but these are the reliable default chains.
When: a new client signs up. Goal: get from intake brief to a launched campaign with a documented creative foundation.
When: a video slot needs producing end-to-end. Goal: a finished cut with supporting footage, overlays, and captions — each step gated, nothing spent or rendered silently.
When: a campaign is running. Goal: surface what to do this week + capture what's working.
ad_id); the packet (when supplied) is preserved as the queryable artifact for downstream context.optimization_log from the status/budget diffs — closed-loop tracking with no manual confirmation step.When: a campaign closes with proof worth carrying forward. Goal: durable proof artifact + named transferable pattern.
creative-intelligence.md in the next wiki ingest.When: a prospect signs up for the paid Blueprint diagnostic (or a new client needs a baseline assessment).
When: any sales interaction — outreach, pre-call prep, discovery, qualification, objection handling, proposal, follow-up.
<!-- ADD: --> slot. The skill gets sharper with each completed conversation.The architecture isn't just for organization — it's for compounding. Six mechanics make every campaign improve every future campaign — and as of 3.0 the loops run on a clock, not on memory.
Proven creative gets captured via /vakari:winners with structured evidence — and capture is now data-triggered: ingest and diagnose hand off pre-filled candidates instead of waiting on memory, and headline numbers are refreshed against campaigns.db lifetime data at capture and cite time. When 3+ winners share an underlying mechanism, the pattern crystallizes in creative-intelligence.md through wiki ingest. All consuming skills (scripts, static-ads, creative-strategy) immediately reference the new pattern on next invocation.
Every skill consumes and produces packets with named sections. The contract forces skills to surface what they need rather than guess; it forces upstream skills to deliver substantive output rather than narrate. Brittle conversations become reliable handoffs that survive across sessions and across machines.
When the diagnostic rules need a new kill threshold, edit diagnostic-rules.md once. /vakari:diagnose and /vakari:report both pick it up immediately. When a new artifact component earns its place, add to artifact-components.md — every HTML-producing skill has the new vocabulary. No per-skill rewrites.
Every creative push can leave a make-time craft trail via /vakari:craft — which route/tool/model fit, what worked, what to redirect. Naming is descriptive, and read-back is semantic — consuming skills match on meaning, not a locked enum. static-ads and creative-strategy read it back before generating, so each build starts closer to one-shot. Read-back is asymmetric and lives in files — the system gets less bad without converging on one look.
The campaigns DB became a Meta-ID-keyed lifecycle spine — every ad tracked conception → death. /vakari:ingest stamps the ad_id and auto-populates optimization_log from status/budget diffs; /vakari:reconcile-ads links the ad to its workspace creative and stamps its route. A weekly launchd Meta pull plus a Tuesday freshness checkpoint (alerts past 9 days stale) keep the spine current without anyone remembering to. Because _craft and the DB share the canonical_creative_id, a route hypothesis ("Figma overlay beat AI-gen for this offer") can finally be checked against live period_metrics.
The video family can spend money and render assets — so it's built to be safe where money moves. /vakari:broll gates paid generation behind explicit per-run approval with a surfaced cost estimate; /vakari:captions gates the final burn-in behind the caption-preview. /vakari:hyperframes wraps the HeyGen runtime rather than reimplementing it, and its local render is free and ungated — approval there is creative, not financial. The preview-gate doctrine lives in one shared reference, so a fourth video skill would inherit it for free.