@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/cmo/rules/playbooks.md

@@ -0,0 +1,327 @@
+# CMO Orchestration Playbooks
+
+Named end-to-end recipes. When the builder asks for something big, pick the right playbook, announce the plan, run the chain, hand back at the defined stop.
+
+**How to use:**
+- If the builder's request matches a named trigger phrase, start the playbook.
+- Announce the plan before step 1: *"Here's what I'll run: step 1 → step 2 → step 3. Ready?"*
+- Pause between phases when a **Gate** is marked — the user approves the artifact before the next step.
+- Every playbook ends with a **Stop** condition. Don't run past it.
+
+---
+
+## 1. Full Product Launch
+
+**Trigger:** *"launch my product"*, *"zero to launch"*, *"plan and run my launch"*, *"new startup, what do I do"*.
+
+**Use when:** fresh project, founder wants end-to-end. Allow 2-4 hours of compounding work.
+
+**Steps:**
+
+| # | Skill | Artifact produced | Gate? |
+|---|---|---|---|
+| 0 | `brainstorm` (skip if direction is clear) | direction summary | — |
+| 1 | `brand-voice` | `brand/voice-profile.md` | ✓ |
+| 2 | `audience-research` + `competitive-intel` (parallel via agents) | `brand/audience.md`, `brand/competitors.md` | ✓ |
+| 3 | `landscape-scan` | `brand/landscape.md` (with Claims Blacklist) | ✓ |
+| 4 | `positioning-angles` | `brand/positioning.md` | ✓ |
+| 5 | `visual-style` → `brand-kit-playground` | `brand/creative-kit.md` + HTML preview | ✓ (visual approval) |
+| 5b | (optional) `higgsfield-soul-id` if founder wants their face in launch creative | `brand/assets.md` reference_id | — |
+| 6 | `keyword-research` | `brand/keyword-plan.md` | — |
+| 7 | `seo-content` ×2-3 articles (cornerstone content) | `marketing/content/*.md` | ✓ (per article) |
+| 8 | `content-atomizer` on each article | `marketing/social/<slug>/*.md` | — |
+| 9 | `launch-strategy` | `marketing/launch/plan.md` | ✓ |
+| 10 | `startup-launcher` (brief + 56-platform tracker) | `marketing/launch/product-brief.md`, `launch-tracker.md` | ✓ |
+| 11 | Schedule social: `typefully` for X/threads, `postiz` for everything else | drafts in platform UIs | — |
+| 12 | Log the campaign: `mktg brand append-learning` | `brand/learnings.md` | — |
+
+**Stop:** launch day executed, drafts scheduled, learnings captured. Hand back with "next moves" list (monitor competitors, run conversion audits, plan next content batch).
+
+---
+
+## 2. Content Engine
+
+**Trigger:** *"I need a content system"*, *"publish weekly"*, *"keep the content flowing"*, *"content calendar setup"*.
+
+**Use when:** brand foundation exists; user wants repeatable weekly output.
+
+**Steps:**
+
+| # | Skill | Artifact | Notes |
+|---|---|---|---|
+| 1 | `keyword-research` | `brand/keyword-plan.md` (fresh) | Refresh if older than 90 days. |
+| 2 | `seo-content` (one cornerstone piece) | `marketing/content/<slug>.md` | User picks the topic from keyword-plan. |
+| 3 | `content-atomizer` | `marketing/social/<slug>/{linkedin,twitter,reddit,...}-posts.md` | Platform-native, per-channel. |
+| 4 | Distribution: `postiz` (LinkedIn/Reddit/Bluesky/Mastodon/Threads/IG/TikTok) + `typefully` (X) | drafts scheduled | Phase 5 of `social-campaign` picks the backend per post. |
+
+**Stop:** one week's worth of content scheduled. Recommend scheduling a recurring run (`/loop` or weekly reminder).
+
+---
+
+## 3. Founder Voice Rebrand
+
+**Trigger:** *"make this sound like me"*, *"extract my voice"*, *"my voice is all over the place"*, *"the brand voice doesn't match how I actually write"*.
+
+**Use when:** founder has a real writing voice (podcast, essays, tweets) that the current `voice-profile.md` doesn't capture.
+
+**Steps:**
+
+| # | Skill | Artifact | Notes |
+|---|---|---|---|
+| 1 | `voice-extraction` | structured voice pattern analysis | Spawns 10 parallel sub-agents, reverse-engineers patterns from real content. |
+| 2 | `brand-voice` (Extract mode) using extraction output | new `brand/voice-profile.md` | Overwrites the generic voice with the founder-calibrated one. |
+| 3 | **Mass regen trigger** — if there's existing copy in `marketing/`, flag for rewrite: run `direct-response-copy --mode edit` on each landing page, `seo-content --mode edit` on each article, `content-atomizer` re-runs on source content | updated files | Per plan:rules/brand-file-map.md, voice changes cascade to every downstream copy skill. |
+
+**Stop:** new `voice-profile.md` written + downstream rewrite plan surfaced. Don't auto-regenerate; the user decides which assets are worth rewriting.
+
+---
+
+## 4. Conversion Audit
+
+**Trigger:** *"audit my landing page"*, *"traffic isn't converting"*, *"why is my signup flow leaking"*, *"fix my CRO"*.
+
+**Steps:**
+
+| # | Skill | When |
+|---|---|---|
+| 1 | `page-cro` | Audits hero, CTA, social proof, objections on one URL. Produces a scored report + prioritized fix list. |
+| 2 | `conversion-flow-cro` | Only if problem spans a multi-step flow (signup → onboarding → paywall). |
+| 3 | If copy is the issue → `direct-response-copy --mode edit` | Surgical rewrite of the flagged copy. |
+| 4 | Capture what you learned → `mktg brand append-learning` | Feeds future routing. |
+
+**Stop:** ranked fix list delivered; rewrite executed if copy was the blocker.
+
+---
+
+## 5. Retention Recovery
+
+**Trigger:** *"people keep canceling"*, *"my churn is bad"*, *"reduce cancellations"*, *"win back lapsed users"*.
+
+**Steps:**
+
+| # | Skill | Artifact |
+|---|---|---|
+| 1 | `churn-prevention` | Cancel flow UX plan, dunning email sequence, win-back 90-day calendar. |
+| 2 | `email-sequences` (build the dunning + win-back flows from step 1's plan) | Full email sequences with subjects + timing. |
+| 3 | `send-email` (to wire the flow into Resend, if building inbound) | Transactional wiring. |
+
+**Stop:** dunning + win-back flows drafted, wire-up instructions given. User approves before any live sends.
+
+---
+
+## 6. Visual Identity
+
+**Trigger:** *"design my brand"*, *"I need a visual look"*, *"how should my brand look"*, *"set up image generation"*.
+
+**Steps:**
+
+| # | Skill | Artifact |
+|---|---|---|
+| 1 | `visual-style` | `brand/creative-kit.md` with palette, typography, image aesthetic. |
+| 2 | `brand-kit-playground` (immediately after) | Interactive HTML preview — tweakable palette/type/logo, social card + OG image. |
+| 3 | `creative` (when producing ad/social assets) | Multi-mode creative briefs per asset. |
+| 4 | Product imagery: `higgsfield-product-photoshoot` (10 modes: studio, lifestyle, Pinterest, hero banner, ad pack, virtual try-on, etc.) when Higgsfield is configured; otherwise `image-gen` (Gemini, free tier). | Brand-grade product visuals or Gemini-generated single images. |
+| 5 | One-off images without a product: `image-gen` | Gemini-generated image via creative-kit style anchors. |
+
+**Stop:** visual approval via `brand-kit-playground`. User copies refined tokens back, then unblocked for any future image work.
+
+---
+
+## 7. Video Content
+
+**Trigger:** *"make a video"*, *"TikTok content"*, *"product demo video"*, *"turn slides into video"*.
+
+**Steps (branching):**
+
+| Ask shape | Skill chain |
+|---|---|
+| "Product demo / walkthrough" | `marketing-demo` → `video-content` (ffmpeg or Remotion) |
+| "TikTok slideshow / social video" | `slideshow-script` → `paper-marketing` → `video-content` → (optional) `tiktok-slideshow` orchestrator bundles all three |
+| "AI video / branded ad / Marketing Studio / UGC ad with avatar" | `higgsfield-generate` (Seedance, Kling, Veo, or Marketing Studio mode for branded video with avatars + product) when Higgsfield is configured. No fallback for AI video. |
+| "Pitch deck / HTML slides" | `frontend-slides` (terminal path — not a video pipeline) |
+| "App Store screenshots" | `app-store-screenshots` (Next.js generator, NOT video) |
+
+**Distribution:** any resulting video → `postiz` for TikTok/IG/YouTube/Threads; `typefully` for X.
+
+**Stop:** video file exported + scheduled. Log to `brand/assets.md`.
+
+---
+
+## 8. Email Infrastructure
+
+**Trigger:** *"set up my email system"*, *"I need inbound email for an agent"*, *"wire up Resend"*.
+
+**Steps:**
+
+| # | Skill | Artifact |
+|---|---|---|
+| 1 | `agent-email-inbox` (if building agent-triggered email) | secure inbox config, webhook tunneling plan, prompt-injection defenses. |
+| 2 | `resend-inbound` (for receiving emails via Resend) | inbound domain setup + `email.received` webhook wiring. |
+| 3 | `email-sequences` (for automated flows: welcome, nurture, launch, win-back) | full sequences with timing and A/B plan. |
+| 4 | `send-email` (for one-off transactional sends) | Resend API calls for specific messages. |
+
+**Stop:** infrastructure validated (test send + receive round-trip). Log credentials env vars (via `brand/stack.md`).
+
+---
+
+## 9. SEO Authority Build
+
+Two paths. Pick by the user's horizon. If unclear, ask once with `AskUserQuestion`.
+
+**Path A triggers:** *"rank higher on Google"*, *"improve SEO"*, *"I want to show up in AI search"*, *"compete for [topic]"*, *"write me an SEO article"* — short-horizon, one-shot, no roadmap.
+
+**Path B triggers:** *"SEO machine"*, *"build organic traffic"*, *"programmatic SEO"*, *"alternatives pages"*, *"comparison pages"*, *"/for/ pages"*, *"we need traffic"*, *"build an SEO engine"* — multi-phase, ship dozens of pages, persistent roadmap.
+
+### Path A — Short-horizon authority push
+
+**Steps:**
+
+| # | Skill | Artifact |
+|---|---|---|
+| 1 | `keyword-research` | `brand/keyword-plan.md` with primary, secondary, long-tail terms + search intent notes. |
+| 2 | `seo-content` (ongoing) | `marketing/content/*.md` — rankable, anti-AI-slop articles with schema. |
+| 3 | `ai-seo` | Entity optimization, structured data, citation-worthy formatting for ChatGPT/Perplexity/Claude/Gemini/AI Overviews. |
+| 4 | `competitor-alternatives` | `marketing/alternatives/<competitor>-vs-us.md` — high-intent comparison pages. |
+| 5 | `seo-audit` (periodically) | Site architecture + schema markup audit. |
+
+**Stop:** one cornerstone + one AI-SEO piece + one alternatives page shipped. Schedule re-runs quarterly.
+
+### Path B — Programmatic SEO machine (long arc)
+
+When the user wants an *operating system* for organic growth — not one article. Ships dozens of programmatic pages across alternatives, comparisons, use-cases, and playbooks, with a persistent phase tracker (`docs/seo-machine.md`) the user resumes across sessions.
+
+**Steps:**
+
+| # | Skill / Agent | Artifact |
+|---|---|---|
+| 1 | Foundation prerequisites (if missing) | Spawn `mktg-competitive-scanner` + `mktg-audience-researcher` in parallel → `brand/competitors.md`, `brand/audience.md`. Run `keyword-research` → `brand/keyword-plan.md`. |
+| 2 | `seo-machine` (Initialize) | `docs/seo-machine.md` roadmap + `.seo/brand.md` + `.seo/link-inventory.md` + `.seo/config.json`. Stack auto-detected. |
+| 3 | `seo-machine` (Resume — per phase) | Generates the phase's pages (e.g. 12 `/alternatives/<competitor>` pages, or 8 `/for/<persona>` use-case pages) directly into the user's framework (Next.js / Astro / Rails+Inertia / markdown fallback). |
+| 4 | Per-phase quality gate — `mktg-content-reviewer` (voice) + `mktg-seo-analyst` (keyword adherence) | Scored, not rewritten. Spawn both in one message after each phase. |
+| 5 | Off-page checklist + technical audit | Chain into `off-page-seo` skill → spawns `mktg-backlink-prospector` agent to research competitor referring-domains → writes `.seo/backlink-targets.json`. Plus `scripts/link_audit.py` + `scripts/tech_audit.py` run locally; findings appended to `docs/seo-machine.md`. |
+| 6 | `seo-audit` (periodic, post-sprint) | Site-architecture review once pages are live. |
+
+**Resume protocol:** every subsequent /cmo session checks for `docs/seo-machine.md` — if it exists, seo-machine runs in Resume mode and picks the next pending phase. The user does not need to remember where they left off.
+
+**Stop (per phase):** all pages in the phase shipped, off-page checklist appended, quality gates passed. Then hand back: "Phase N complete — Y pages shipped. Phase N+1 is [pattern]. Run /cmo again when ready."
+
+**Picking the path:**
+
+| Signal | Path |
+|---|---|
+| "one article", "this week", "blog post" | A |
+| "machine", "system", "sprint", "dozens of pages", "programmatic", "operating system for SEO" | B |
+| User has 0 brand files | Run Path B Step 1 foundation first regardless |
+| User already has `docs/seo-machine.md` | Path B Resume — no question needed |
+
+**Cost asymmetry — sequence quick wins before long builds:**
+
+| Pattern | Build cost per page | Conversion intent | Sequence order |
+|---|---|---|---|
+| `/alternatives/[competitor]` | ~4 hours | Highest | First |
+| `/compare/[a]-vs-[b]` | ~3 hours | High | Second |
+| `/for/[use-case]` / `/for/[audience]` | ~4-5 hours | Medium-High | Third |
+| Long-form playbook (Pattern E) | ~2-3 days | Medium (AI-citation surface) | Late phases |
+
+When the user asks "what should I do this week?", default to ~4-hour alternatives pages over multi-day playbooks unless they explicitly want the AI-citation play. A user who ships 5 alternatives pages in a week beats one who ships half a playbook.
+
+### Path B sub-playbooks (cadence + situational)
+
+Beyond the linear sprint, /cmo runs these named sub-playbooks when the situation matches:
+
+| Sub-playbook | When | Chain |
+|---|---|---|
+| **B.1 Weekly SEO Maintenance Loop** | Recurring weekly cadence (use `/loop 7d` or schedule) | `seo-machine` striking-distance phase + `mktg compete scan` + reconcile new keyword opportunities into `brand/keyword-plan.md`. Output: weekly diff (pages to refresh, keywords to claim, competitor SERP movement). |
+| **B.2 Post-Launch SEO Ignition** | Immediately after `launch-strategy` completes | Day 1: `seo-machine` Initialize + Phase 0 (tech audit). Day 7: `seo-machine` Pattern A sprint (alternatives). Day 14: `seo-machine` Pattern D sprint (comparisons) + first striking-distance pass. Couples launch momentum to indexing momentum. |
+| **B.3 AI Overview Chase** | User wants Perplexity/ChatGPT/AI Overview citations | `ai-seo` for entity hardening + structured data → `seo-machine` Pattern E (playbook long-form, the AI-citation surface) → `competitor-alternatives` for honest "X vs Y" pages (AI engines preferentially cite honest comparisons over self-serving ones) → striking-distance refresh on already-cited weak rankers. |
+| **B.4 /for/ Persona Discovery Pipeline** | User has audience.md but no /for/ pages yet | `audience-research` (refresh if stale) → `keyword-research` for persona-keyed vocabulary → `seo-machine` Pattern B/C generation → `page-cro` review on the first 3 shipped. Ships persona-targeted landing pages from end to end. |
+| **B.5 Seasonal Sprint Replanner** | Triggered when `landscape.md` is refreshed (new competitors, market shift, category re-frame) | Re-rank pending phases in `docs/seo-machine.md` to chase the new landscape instead of continuing the stale plan. /cmo's learning-loop addition: stale roadmaps cost time, refreshing is cheap. |
+
+Each sub-playbook returns to the main Path B Resume loop afterward — they're situational overlays, not replacements.
+
+---
+
+## 10. Newsletter Launch
+
+**Trigger:** *"start a newsletter"*, *"set up weekly email"*, *"I want subscribers"*.
+
+**Steps:**
+
+| # | Skill | Artifact |
+|---|---|---|
+| 1 | `audience-research` (refresh if stale) | `brand/audience.md` — who reads this newsletter. |
+| 2 | `newsletter` | Newsletter strategy, template, cadence, growth playbook. |
+| 3 | `lead-magnet` | Free resource that captures emails (ebook, template, toolkit). |
+| 4 | `email-sequences` (welcome + nurture) | Automated onboarding for new subscribers. |
+| 5 | Distribution: landing page via `direct-response-copy`; sign-up capture via `send-email` + `resend-inbound` for double opt-in. | Full signup funnel. |
+
+**Stop:** newsletter #1 drafted, lead magnet live, welcome sequence scheduled. Hand back with growth tactics to run weekly.
+
+---
+
+## 11. Studio Launch
+
+**When:** The user wants to see their marketing operation on a dashboard rather than (or in addition to) in the terminal.
+
+**Goal:** `mktg init` → `mktg studio --open --intent cmo --session <id>` → tabs lit by live data within 60 seconds.
+
+| Phase | Skill / command | Why |
+|---|---|---|
+| 0 | `mktg studio --dry-run --json --intent cmo --session <id>` | Preview. Resolves sibling `mktg-studio/bin/mktg-studio.ts`, `MKTG_STUDIO_BIN`, or PATH, confirms ports + exact CMO dashboard URL, and never spawns. |
+| 1 | `mktg studio --open --intent cmo --session <id>` | Spawn server (port 3001) + dashboard (port 3000). Studio opens at `http://localhost:3000/dashboard?mode=cmo&session=<id>`. |
+| 2 | Foundation research (if first run) | Spawn `mktg-brand-researcher`, `mktg-audience-researcher`, `mktg-competitive-scanner` in parallel per the standard first-run protocol. Each agent writes a brand file. |
+| 3 | `POST /api/brand/refresh` after each agent | Tabs light up one by one as each brand file lands. User watches the dashboard populate in real time. |
+| 4 | `POST /api/navigate {tab: "pulse"}` | Bring the user to Pulse for the "do this next" card once foundation is complete. |
+| 5 | `POST /api/toast "Marketing brain ready"` | Confirmation. User now has a live dashboard + a populated brand. |
+
+**Stop:** Dashboard rendering the current primary surfaces (Pulse, Signals, Publish, Brand, Settings) with real data, Activity panel streaming /cmo events, Pulse has a prioritized next-action card. Hand back with: "Open `http://localhost:3000` — your marketing department is live. Want me to run the first recommended action?"
+
+See `rules/studio-integration.md` for the full POST contract.
+
+---
+
+## 12. Agent Team Coordination
+
+**When:** A multi-agent workflow needs to spawn several sub-agents in parallel and synthesize their outputs — most often on first run (3 research agents) or a content batch (content-reviewer + seo-analyst on the same draft).
+
+**Goal:** Parallelism without crossed wires, clean handoff from sub-agents back to /cmo, compounding written to `brand/learnings.md`.
+
+| Phase | Action | Why |
+|---|---|---|
+| 0 | Plan the split | Identify which sub-agents run in parallel vs sequentially. Research agents (3) are parallel; review agents (content-reviewer, seo-analyst) run after content lands. |
+| 1 | Spawn in ONE message | Use the Agent tool with N parallel `type: "tool_use"` blocks in a single message. Sequential spawns serialize — that defeats the purpose. |
+| 2 | Wait on all | Do not proceed until every spawned agent returns. Partial results produce incoherent positioning. |
+| 3 | Synthesize | /cmo reads each agent's output, resolves contradictions explicitly (not silently), writes the unified view. |
+| 4 | `POST /api/activity/log` per agent | The Activity panel shows N rows — one per sub-agent — so the user can see the parallel work. |
+| 5 | Record cross-agent learnings | If an agent surfaced an insight the others missed, append to `brand/learnings.md` with a `--learning` flag so future runs start ahead. |
+
+**Sub-agent roster (current):**
+- `mktg-brand-researcher` → `brand/voice-profile.md`
+- `mktg-audience-researcher` → `brand/audience.md`
+- `mktg-competitive-scanner` → `brand/competitors.md`
+- `mktg-content-reviewer` → scores content draft, writes nothing
+- `mktg-seo-analyst` → scores SEO content, writes nothing
+
+**Stop:** All spawned agents returned, /cmo has synthesized the output into a single coherent action or artifact, learnings appended. See `rules/sub-agents.md` for the per-agent spawn contract.
+
+---
+
+## Playbook selection — quick reference
+
+| Builder says… | Playbook |
+|---|---|
+| "launch", "zero to one", "ship my startup" | **Full Product Launch** |
+| "content system", "publish weekly", "keep content flowing" | **Content Engine** |
+| "my voice is off", "make it sound like me" | **Founder Voice Rebrand** |
+| "audit my page", "improve conversion", "fix my funnel" | **Conversion Audit** |
+| "reduce churn", "win back users" | **Retention Recovery** |
+| "brand visuals", "design my look" | **Visual Identity** |
+| "make a video", "TikTok" | **Video Content** |
+| "email system", "inbound email", "Resend setup" | **Email Infrastructure** |
+| "rank on Google", "AI search", "compete for [topic]", "one article" | **SEO Authority Build — Path A** |
+| "SEO machine", "build organic traffic", "programmatic SEO", "alternatives pages", "we need traffic" | **SEO Authority Build — Path B (seo-machine)** |
+| "start a newsletter", "subscribers" | **Newsletter Launch** |
+| "show me the dashboard", "launch the studio", "visual mode" | **Studio Launch** |
+| "spawn the research team", "parallel research", "do this across agents" | **Agent Team Coordination** |
+
+**Never run a playbook silently.** Announce the plan, confirm, run, surface the artifact at each Gate, stop at the Stop condition.

package/skills/cmo/rules/progressive-enhancement.md

@@ -0,0 +1,231 @@
+# Progressive Enhancement Ladder
+
+/cmo's capability depends on how populated `brand/` is. Brand memory enhances; it never gates. But be honest about what's possible at each rung — running SEO content at L0 produces generic slop; running it at L4 produces converting, grounded content.
+
+**Always check the ladder first.** Run `mktg status --json --fields brand.populated,brand.missing,brand.stale` to know where you stand. Announce the level to the builder: *"You're at L2 — I can route to X, Y, Z. A and B need another brand file first. Want me to run it now?"*
+
+---
+
+## L0 — Zero context (`mktg init` just ran; all `brand/*.md` templates)
+
+**What's populated:** nothing real. Templates only.
+
+**What /cmo can route to cleanly:**
+
+| Skill | Reason |
+|---|---|
+| `brainstorm` | No brand needed — it's the explorer. |
+| `brand-voice` | Foundation skill. Its job IS to populate voice-profile.md. |
+| `voice-extraction` | Standalone — reverse-engineers voice from external content. |
+| `audience-research` | Foundation. Populates audience.md. |
+| `competitive-intel` | Foundation. Populates competitors.md. |
+| `landscape-scan` | Foundation. Populates landscape.md. |
+| `positioning-angles` | Needs voice + audience; queue it once those land. |
+| `mktg-x` | Utility — reads external X content. |
+| `firecrawl` | Utility — scrapes external content. |
+| `summarize` | Utility — compresses pasted text. |
+| `create-skill` | Meta — adds new skills to the playbook. |
+
+**What /cmo cannot do well:**
+- Write converting copy (no voice, no audience, no positioning).
+- Route to any distribution (no content to distribute).
+- Run any playbook except **Full Product Launch** from scratch.
+
+**Response quality:** *"I can help, but first let me build the foundation. Here's the 4-agent parallel research I'll kick off: brand-voice, audience-research, competitive-intel, landscape-scan. This gives us voice + audience + competitive context + market grounding. It's a 10-minute investment that makes everything else 10× better."*
+
+**Playbooks unlocked:** **Full Product Launch** (starts here by design).
+
+---
+
+## L1 — Voice only (`brand/voice-profile.md` real)
+
+**What's populated:** voice-profile.md with real patterns.
+
+**What /cmo adds from L0:**
+
+| Skill | Reason |
+|---|---|
+| `direct-response-copy` | Can write copy in-voice now. Still generic targeting. |
+| `seo-content` | Same — voiced but audience/keyword-agnostic. |
+| `content-atomizer` | Can rewrite content in-voice across platforms. |
+| `creative` | Can generate copy variants in-voice. |
+| `newsletter` | Can draft in-voice. Topic selection is still guesswork. |
+| `lead-magnet` | Draft only — audience targeting is missing. |
+
+**What's still gated:**
+- `positioning-angles` (needs audience too)
+- `page-cro` / `conversion-flow-cro` (needs positioning for "why us" framing)
+- `launch-strategy` / `startup-launcher` (needs positioning)
+- `competitor-alternatives` (needs competitors.md)
+
+**Response quality:** *"Voice is locked in. Copy will sound like you. But I'm writing blind on who we're talking to — let me run /audience-research (5 min) so the next draft converts."*
+
+**Playbooks unlocked:** partial — Founder Voice Rebrand can finalize step 2; Content Engine can draft if user specifies topic manually.
+
+---
+
+## L2 — Voice + audience (`audience.md` real)
+
+**What /cmo adds:**
+
+| Skill | Reason |
+|---|---|
+| `positioning-angles` | Has both required inputs. Can run. |
+| `pricing-strategy` | Has audience context for willingness-to-pay. |
+| `email-sequences` | Audience-targeted flows now possible. |
+| `lead-magnet` (full) | Targeted resource. |
+| `social-campaign` (without landscape grounding) | Can plan calendar; still no market-claim enforcement. |
+| `keyword-research` | Better with audience context. |
+
+**What's still gated:**
+- Any skill that needs competitive context (`competitor-alternatives`, full `launch-strategy`).
+- Claims-grounded content (no `landscape.md` + Claims Blacklist yet).
+
+**Response quality:** *"Voice + audience are in. I can target now. But I don't know who you're competing against — let me run /competitive-intel (parallel to your next ask, 5 min) so I don't accidentally position us against ourselves."*
+
+**Playbooks unlocked:** Newsletter Launch, Conversion Audit (if the page exists), Visual Identity.
+
+---
+
+## L3 — Voice + audience + competitors + landscape + positioning
+
+**What's populated:** 5 of 10 brand files — the full research foundation.
+
+**What /cmo adds:**
+
+| Skill | Reason |
+|---|---|
+| `launch-strategy` | All required inputs. |
+| `startup-launcher` | Full brief auto-fills from brand/. |
+| `competitor-alternatives` | Has competitors + positioning. |
+| `free-tool-strategy` | Has audience + positioning for distribution plan. |
+| `seo-audit` | Has content context. |
+| `landscape-scan` refresh becomes meaningful | baseline exists to diff against. |
+
+**What's still gated (minor):**
+- Visual skills work but without `creative-kit.md` produce generic styling.
+- `keyword-plan.md` may or may not be run yet — SEO Authority Build needs it.
+
+**Response quality:** *"Foundation is complete. Claims Blacklist is active (from landscape.md) — I'll enforce it on every piece of copy. Ready to run any playbook."*
+
+**Playbooks unlocked:** all except those requiring visual identity (Visual Identity, Video Content) or SEO-specific (SEO Authority Build requires keyword-plan first).
+
+---
+
+## L4 — All 10 brand files current within freshness windows
+
+**What's populated:** `voice-profile.md`, `positioning.md`, `audience.md`, `competitors.md`, `landscape.md`, `keyword-plan.md`, `creative-kit.md`, `stack.md`, `assets.md` (append-only), `learnings.md` (append-only) — all real, none stale.
+
+**What /cmo adds from L3:**
+
+| Skill | Reason |
+|---|---|
+| `image-gen` | Has `creative-kit.md` style anchors. |
+| `visual-style` → `brand-kit-playground` | Full loop. |
+| `paper-marketing` | Has the design system to spawn designer agents. |
+| `slideshow-script` + `video-content` + `tiktok-slideshow` | Full video pipeline. |
+| `ai-seo` | Has keyword-plan + positioning for entity optimization. |
+| `frontend-slides` | Brand-consistent pitch decks. |
+| `app-store-screenshots` | Brand visuals in place. |
+| `email-sequences` with full stack awareness | Knows which ESP (`stack.md`) + audience segments. |
+| `typefully` + `postiz` routing | Full per-platform calibration. |
+| `mktg compete scan` | Landscape baseline to diff competitor changes against. |
+| `mktg plan next` | Has enough state to pick the single highest-priority task. |
+
+**Response quality:** *"You're at L4 — full CMO mode. I'll route with confidence. If it's a named playbook, I'll run it. If it's an ad-hoc ask, I'll pick the 1-2 best skills and execute."*
+
+**Playbooks unlocked:** all 10. Can compound work across multiple playbooks in one session.
+
+---
+
+## Level detection at activation
+
+Run at On Activation (see main SKILL.md):
+
+```bash
+mktg status --json --fields brand.populated,brand.missing,brand.stale
+```
+
+Map the result:
+
+| State | Level |
+|---|---|
+| `brand.populated.length === 0` OR all files are templates | L0 |
+| only `voice-profile.md` real | L1 |
+| `voice-profile.md` + `audience.md` real | L2 |
+| + `competitors.md` + `landscape.md` (fresh ≤ 14 days) + `positioning.md` | L3 |
+| All 10 files populated AND within freshness (30d profiles, 90d config, append-only never stale) | L4 |
+
+**When landscape.md is stale (>14 days):** downgrade to "L3 but not L4 for content routing" — warn the user before running any copy skill.
+
+**When any profile file (voice/positioning/audience/competitors/landscape) is stale (>30 days):** downgrade one level. Offer to refresh before routing.
+
+---
+
+## What "route with confidence" means
+
+At L3/L4, /cmo doesn't ask "what do you want to do" — it suggests. At L0-L2, /cmo explicitly names the missing input before running anything that needs it. The ladder is a contract: the builder knows what they'll get back at each level, and /cmo is honest about the quality ceiling.
+
+---
+
+## Ecosystem readiness — the orthogonal axis (E0–E4)
+
+Brand completeness (L0–L4 above) governs *content quality*. Ecosystem completeness (E0–E4 below) governs *what surfaces the builder can touch*. The two axes are independent — a project can be L4/E0 (brand-rich, CLI-only) or L1/E3 (brand-light, studio+native publish wired). /cmo routes across both.
+
+Detect ecosystem level at activation with a single `mktg doctor --json` — it returns studio reachability, integration status, and sibling presence.
+
+### E0 — CLI only
+
+**State:** `mktg` installed, `brand/` may or may not exist, no studio, no native providers, no postiz, no other integrations.
+
+**Surfaces /cmo can drive:** the mktg CLI itself + Claude Code terminal. Full read-and-write on `brand/`. All content skills work locally.
+
+**What /cmo cannot:** show a dashboard, post to social, trigger live signal collection.
+
+**Response:** *"You're CLI-only right now. I can write and save everything locally. Want me to help set up Studio or native publish providers when you're ready?"*
+
+### E1 — CLI + brand bootstrapped
+
+**State:** E0 + `brand/` has real files (L1 or higher on the brand axis).
+
+**What this unlocks:** every content skill now has at least voice grounding. Nothing new on the ecosystem axis — this rung exists to acknowledge that a CLI-only project CAN still produce meaningful output if the brand axis is funded.
+
+**Response:** *"Brand is in. I can write in-voice without any studio or postiz. Content goes to files in `brand/assets.md` or wherever you route it."*
+
+### E2 — Studio attached
+
+**State:** E1 + `mktg studio` running, `GET $STUDIO/api/health` returns 200 (`STUDIO` is the API base printed by the launcher, default `http://localhost:3001`).
+
+**What /cmo adds:** the five studio verbs from `rules/studio-integration.md` — activity, navigate, toast, brand-refresh, schema-fetch. Every skill run now mirrors to the Activity panel. Brand file writes trigger SWR invalidation. Tab switches are programmatic.
+
+**What's still gated:** external network posting requires Postiz, Typefully, or a browser profile. Native publish can still store the local queue/history.
+
+**Response:** *"Studio is live. You'll see every skill run land on the Activity panel. Open `http://localhost:3000` to watch — I'll surface toasts when something interesting ships."*
+
+### E3 — Studio + native publish connected
+
+**State:** E2 + at least one native provider exists from `mktg publish --adapter mktg-native --list-integrations --json`.
+
+**What /cmo adds:** local queue/history for the initial native rollout: X, TikTok, Instagram, Reddit, and LinkedIn. Campaign orchestration can now write platform-native posts into the workspace backend and show them in Studio.
+
+**What's still gated:** actual external network posting still requires Postiz, Typefully, or browser automation. Cross-sibling workflows require E4.
+
+**Response:** *"Native publish is wired — I can queue X, TikTok, Instagram, Reddit, and LinkedIn content into this workspace. If you want it pushed to the real networks, I'll route through Postiz, Typefully, or browser automation and tell you exactly which path is active."*
+
+### E4 — Full ecosystem
+
+**State:** E3 + a multi-repo marketing workspace. marketing-cli (the CLI), mktg-studio (the dashboard), and the marketing site each have their own `brand/` and their own git history.
+
+**What /cmo adds:** cross-sibling awareness per `rules/monorepo.md`. Can reason about mktg-site content strategy vs mktg-studio positioning vs marketing-cli docs, knowing each is a distinct brand but shares an overarching ecosystem identity. Can route audit work across siblings (F-chain tasks), can coordinate launch copy (C-chain) that references all four surfaces coherently.
+
+**What's still gated:** nothing on the ecosystem axis. At E4, /cmo operates the full marketing department.
+
+**Response:** *"Full ecosystem is live — CLI, studio, and site. If I need to cross-reference, I'll use `--cwd` explicitly and announce the sibling. Your launch copy can reference any of them; I'll keep voices distinct."*
+
+### Two-axis routing in practice
+
+A project at L4/E0 — full brand, no studio/postiz — gets polished copy shipped to files. Perfectly fine for a pre-launch stealth product.
+
+A project at L1/E3 — thin brand, full ecosystem — gets distribution-ready posts with voice-grounding but weak targeting. /cmo should recommend investing in the brand axis before scaling distribution, because E3 amplifies L1's weaknesses.
+
+The sweet spot for production use is L3+/E2+ — enough brand grounding for claims-aware copy, enough ecosystem for the builder to see and distribute what /cmo produces.

package/skills/cmo/rules/publish-index.md

@@ -0,0 +1,106 @@
+# Publish Index
+
+This is the /cmo routing index for distribution. Runtime schema wins:
+if this file conflicts with `mktg schema publish --json` or
+`mktg publish --list-adapters --json`, trust the live CLI output.
+
+## Current Adapters
+
+Refresh before a publishing session:
+
+```bash
+mktg publish --list-adapters --json
+mktg publish --adapter mktg-native --list-integrations --json
+mktg publish --adapter postiz --list-integrations --json
+mktg publish --adapter postiz --diagnose --json
+mktg catalog info postiz --json --fields configured,missing_envs,resolved_base
+```
+
+| Adapter | Role | Credentials | Reality |
+|---|---|---|---|
+| `mktg-native` | Local agent-first publish backend | None | Stores workspace account, providers, queue, history under `.mktg/native-publish/`. This is the current native Studio backend. |
+| `postiz` | External social provider catalog | `POSTIZ_API_KEY`, `POSTIZ_API_BASE` | Creates Postiz drafts through the REST API. Hosted or self-hosted; Docker roots like `http://localhost:4007` are retried through `/api`. |
+| `typefully` | X/threads specialist and fallback | `TYPEFULLY_API_KEY` | Creates Typefully drafts. Best for threads and X-specific workflows. |
+| `resend` | Email send path | `RESEND_API_KEY` | Transactional/email distribution. |
+| `file` | Always-on local export | None | Writes publish artifacts to disk for manual or later posting. |
+
+## Native Backend
+
+Initial native provider rollout is deliberately small:
+
+```text
+x, tiktok, instagram, reddit, linkedin
+```
+
+Native backend commands:
+
+```bash
+mktg publish --native-account --json
+mktg publish --native-upsert-provider --input '{"identifier":"linkedin","name":"Acme LinkedIn","profile":"acme"}' --json
+mktg publish --adapter mktg-native --list-integrations --json
+mktg publish --native-list-posts --json
+```
+
+Native publish manifest shape:
+
+```json
+{
+  "name": "campaign-name",
+  "items": [
+    {
+      "type": "social",
+      "adapter": "mktg-native",
+      "content": "Post copy",
+      "metadata": {
+        "providers": ["linkedin"],
+        "postType": "schedule",
+        "date": "2026-04-24T10:00:00.000Z"
+      }
+    }
+  ]
+}
+```
+
+Important: `mktg-native` is local-first. It records drafts, scheduled
+items, published-local state, and queue history. It does not magically own
+third-party OAuth yet; use Postiz or browser automation when real external
+network posting is required.
+
+## Platform Routing
+
+| Platform | Default route | Fallback route | Notes |
+|---|---|---|---|
+| X | `mktg-native` for local queue; `typefully` for real threads | Postiz if connected, then file | X thread UX remains Typefully-specialist. |
+| TikTok | `mktg-native` for local queue | Postiz if connected, then browser profile, then file | Browser path is account/session dependent. |
+| Instagram | `mktg-native` for local queue | Postiz if connected, then browser profile, then file | Browser path is account/session dependent. |
+| Reddit | `mktg-native` for local queue | Postiz if connected, then browser profile, then file | Respect subreddit rules and manual review. |
+| LinkedIn | `mktg-native` for local queue | Postiz or Typefully if connected, then file | Personal vs company page must be explicit. |
+
+## Safe Publish Sequence
+
+1. Generate platform-native copy first. Do not dump one generic post everywhere.
+2. Run `mktg publish --list-adapters --json`.
+3. If using native, ensure providers exist with `--adapter mktg-native --list-integrations`.
+4. If using Postiz, run `mktg publish --adapter postiz --diagnose --json` before live drafting.
+5. Run a dry-run publish first:
+
+```bash
+mktg publish --adapter mktg-native --dry-run --input '<manifest-json>' --json
+```
+
+6. Only after user approval, execute:
+
+```bash
+mktg publish --adapter mktg-native --confirm --input '<manifest-json>' --json
+```
+
+7. Mirror meaningful publishes to Studio with `/api/activity/log`,
+`/api/navigate {"tab":"publish"}`, and an honest toast.
+
+## Failure Policy
+
+- If native target resolution fails, add or correct the provider first.
+- If Postiz is unconfigured, surface `missing_envs` from `mktg catalog info postiz`.
+- If Postiz self-hosting fails, run `mktg publish --adapter postiz --diagnose --json` and check whether the base should be the Docker app root (`http://localhost:4007`) or backend path (`http://localhost:4007/api`).
+- If a live provider is down, do not pretend the content posted. Save to native or file and tell the user the external posting step is still pending.
+- If rate-limited, persist the remaining work and give a concrete resume path.