@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: brainstorm
+description: "Structured marketing brainstorming when direction is unclear. Use when the agent doesn't know which skill to run, the user is vague about what..."
+allowed-tools: []
+---
+
+# /brainstorm — Marketing Brainstorm
+
+Structured exploration when marketing direction is unclear. You produce a brief that tells /cmo where to route next.
+
+For brand memory protocol, see /cmo [rules/brand-memory.md](../cmo/rules/brand-memory.md).
+
+## On Activation
+
+1. Read `brand/` files if they exist (voice-profile.md, audience.md, positioning.md, learnings.md). They enhance but never gate.
+2. Assess the user's request clarity level.
+
+## Phase 0: Assess Clarity
+
+Gate check. If the request is already specific, skip brainstorming:
+
+| Signal | Action |
+|--------|--------|
+| "Write a landing page for X" | Skip. Route to `direct-response-copy`. |
+| "Do SEO for my blog" | Skip. Route to `keyword-research`. |
+| "I want to market my app" | Proceed. Multiple valid paths. |
+| "What should I do next?" | Proceed. No clear direction. |
+| "Help me think through our launch" | Proceed. Needs exploration. |
+
+If skipping: "Your request is specific enough to execute directly. Routing to `/<skill>` instead of brainstorming."
+
+## Phase 1: Understand the Challenge
+
+Ask ONE question at a time. Prefer multiple choice when natural options exist. Skip questions already answered by brand/ context.
+
+**Questions to cover (in order, stop when clear):**
+
+1. **Goal** — What are you trying to achieve? (awareness / leads / revenue / retention / launch)
+2. **Product** — What are you marketing? (Brief description if not obvious from project context)
+3. **Audience** — Who buys this? (Skip if `brand/audience.md` exists and is current — confirm briefly instead: "Your audience profile says X. Still accurate?")
+4. **Channels** — Where does your audience hang out? (search / social / email / communities / paid)
+5. **Constraints** — Budget, timeline, team size, tools available?
+6. **Competition** — Who else does this? What makes you different? (Skip if `brand/competitors.md` exists — reference it instead)
+
+Stop as soon as you have enough to propose approaches. 3-4 questions is usually enough.
+
+## Phase 2: Explore Approaches
+
+Present 2-3 concrete strategic directions. For each:
+
+```
+### Approach [N]: [Name]
+
+**Core angle:** [One sentence positioning]
+**Channels:** [Primary → Secondary]
+**Audience fit:** [Why this resonates with the target]
+**Timeline:** [Quick win vs. long play]
+**Pros:** [2-3 bullet points]
+**Cons:** [1-2 bullet points]
+**Best when:** [Conditions that make this the right choice]
+```
+
+Ask the user to pick one, combine elements, or explore further.
+
+**Handling responses:**
+
+| User says | Action |
+|-----------|--------|
+| Picks an approach | Move to Phase 3 with that approach |
+| Wants to combine | Merge the relevant elements into a hybrid approach, confirm the blend, then move to Phase 3 |
+| Rejects all approaches | Ask what felt wrong. Probe for the constraint or preference you missed. Generate 1-2 new approaches informed by their feedback |
+| "I want to do all of them" | Recommend a sequence: "Start with [approach] because [reason]. If that works, layer in [approach 2] in week 3." Prioritize, don't parallelize |
+| Wants to explore further | Ask one targeted follow-up question, then generate 1-2 additional approaches |
+
+## Phase 3: Capture Marketing Brief
+
+Write a structured brief to `marketing/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`:
+
+```markdown
+---
+type: marketing-brainstorm
+date: YYYY-MM-DD
+topic: [kebab-case topic]
+goal: [awareness|leads|revenue|retention|launch]
+chosen-approach: [N]
+---
+
+# Marketing Brief: [Topic]
+
+## Context
+[What we're marketing and why now]
+
+## Chosen Approach
+[Selected direction with rationale]
+
+## Target Audience
+[Who we're reaching]
+
+## Channels
+[Primary and secondary channels]
+
+## Key Messages
+[3-5 core messages]
+
+## Constraints
+[Budget, timeline, tools]
+
+## Success Metrics
+[How we'll measure impact]
+
+## Structured Handoff
+next-skill: [skill-name]
+confidence: [high|medium|low]
+context-summary: "[One line summary for /cmo routing]"
+```
+
+The `next-skill` field is critical — it tells /cmo where to route after brainstorming.
+
+## Phase 4: Route Back to /cmo
+
+After writing the brief:
+
+"The brainstorm is complete. Brief saved to `marketing/brainstorms/[filename]`. Run `/cmo` to execute the next step (`/[next-skill]`), or invoke `/<next-skill>` directly."
+
+Do not list all 50 skills. Recommend the ONE next skill based on the brief.
+
+## Worked Example
+
+**User request:** 'I just built a verified meal delivery app, what should I do for marketing?'
+
+**Approach 1: Community-Led Growth**
+Build presence in health-focused community spaces (neighborhood Slack groups, campus food subreddits, verified-source food Instagram). Create shareable content that spreads through existing trust networks.
+→ next-skill: audience-research
+
+**Approach 2: SEO + Content**
+Capture 'verified meal delivery' search traffic with city-specific landing pages. Write comparison content ('Is DoorDash organic?') to redirect competitor traffic.
+→ next-skill: keyword-research
+
+**Recommended:** Approach 1 — community trust is the moat for verification-driven products. SEO is Phase 2 after you have testimonials to feature.
+
+---
+
+## Output Format
+
+Follow the output formatting rules from /cmo [rules/output-format.md](../cmo/rules/output-format.md). Key requirements:
+- Header with "MARKETING BRAINSTORM" and date
+- Each approach as a clearly separated section
+- FILES SAVED section showing the brief path
+- WHAT'S NEXT section with the recommended next-skill
+
+## Anti-Patterns
+
+| Anti-pattern | Instead | Why |
+|-------------|---------|-----|
+| Asking 5+ questions at once | One question at a time, multiple choice | Builders get overwhelmed by question walls. Each answer should shape the next question. |
+| Jumping straight to tactics | Explore the strategic direction first | Tactics without strategy leads to scattered effort. "Post on TikTok" isn't a plan. |
+| Proposing 5+ approaches | 2-3 focused options, not a menu | More options = more decision paralysis. The builder came here because they were stuck — don't make it worse. |
+| Generic advice ("build an audience") | Specific to their product and context | Anyone can say "build an audience." The value is knowing WHICH audience, WHERE, with WHAT message. |
+| Brainstorming when direction is clear | Skip to the execution skill | Brainstorming is exploration, not procrastination. If they know what they want, execute. |
+| Leaving the user without a next step | Always include `next-skill` in the brief | A brainstorm that doesn't lead to action is just a meeting. The handoff is the whole point. |
+
+## YAGNI Principles
+
+- Resist adding channels you can't actually execute on
+- One campaign well-executed beats three half-started
+- If the user has no audience data, start with `audience-research`, not guessing
+- Don't brainstorm pricing, launches, or SEO strategy — those have dedicated skills
+- The brief is a compass, not a bible. It should fit on one page.

package/skills/brand-kit-playground/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: brand-kit-playground
+description: >
+  Generate an interactive HTML brand playground that shows your brand rendered
+  live — palette, typography, logo, voice — with a social card and OG image
+  preview that updates as you tweak tokens. Opens in browser. The visual
+  approval step for the /cmo flow: /visual-style writes the brand, this skill
+  shows it. Use when the user says "show me my brand", "brand playground",
+  "preview my brand", "what does our brand look like", "visual preview",
+  "brand kit", "see my colors", "how does my brand look", or after /visual-style
+  completes and the user needs to approve the visual identity before moving to
+  content generation. Also use when someone says "I want to see it" during any
+  brand-building conversation.
+reads:
+  - brand/creative-kit.md
+  - brand/voice-profile.md
+  - brand/positioning.md
+  - brand/audience.md
+writes:
+  - brand/creative-kit.md
+  - brand/assets.md
+depends-on:
+  - visual-style
+triggers:
+  - brand playground
+  - show me my brand
+  - preview my brand
+  - what does our brand look like
+  - visual preview
+  - brand kit
+  - see my colors
+  - how does my brand look
+  - brand kit playground
+  - render my brand
+allowed-tools:
+  - Bash(open *)
+---
+
+# /brand-kit-playground — Visual Brand Workbench
+
+Your brand lives in markdown files. This skill renders it as a living, interactive HTML page the user opens in their browser — palette swatches, type specimens, logo lockups, and a real social card preview that updates as they tweak tokens. When they're happy, they copy the structured JSON and you write it back to `brand/creative-kit.md`.
+
+This is the visual approval step in the /cmo flow. `/visual-style` writes the brand identity. This skill shows it.
+
+---
+
+## On Activation
+
+1. Read `brand/creative-kit.md` — extract the Colors, Typography, and Visual Brand Style sections.
+   - If the file is template/empty: **warn** the user. "Your creative kit is empty — the playground will use placeholder values. Run `/visual-style` first for a real preview, or continue and I'll use defaults you can tweak."
+   - If it has real content: proceed. Parse colors (hex values), fonts (family names), border radius, shadows, gradients.
+2. Read `brand/voice-profile.md` — extract tone adjectives, vocabulary preferences, headline style.
+3. Read `brand/positioning.md` — extract the primary positioning angle for the social card headline.
+4. Read `brand/audience.md` if it exists — extract audience description for the voice snapshot panel.
+5. If no brand files exist at all: proceed with sensible defaults. The playground works at L0. Show placeholder brand with a note: "These are defaults. Fill in your brand files and re-run for a real preview."
+
+---
+
+## What You Build
+
+A **single self-contained HTML file** with inline CSS and JS. Zero external dependencies except Google Fonts (loaded via `<link>`). No framework. No build step. No server.
+
+The file is written to the project root as `brand-playground.html` and opened in the user's default browser via `open brand-playground.html`.
+
+### Layout
+
+```
++-- BRAND BAR ------------------------------------------------+
+|  [Logo] Project Name Brand Playground    [Light/Dark toggle] |
++--------------------------------------------------------------+
+|                    |                                          |
+|  CONTROLS          |  TAB: [Brand System] [Social Card] [OG] |
+|  --------          |  ----------------------------------------|
+|                    |                                          |
+|  > Colors          |  (Brand System tab)                     |
+|    Primary [pick]  |  COLOR PALETTE                          |
+|    Secondary       |  ## ## ## ## ## (live swatches)          |
+|    Accent          |                                         |
+|                    |  TYPOGRAPHY                             |
+|  > Typography      |  Display: Aa Space Grotesk              |
+|    Display font    |  Body: Aa Inter Regular                 |
+|    Body font       |  Mono: Aa JetBrains Mono               |
+|    Scale ratio     |                                         |
+|                    |  VOICE SNAPSHOT                         |
+|  > Visual Style    |  Tone: confident, warm, technical       |
+|    Border radius   |  Audience: indie developers             |
+|    Shadow depth    |  Style: short-punchy headlines          |
+|    Texture         |                                         |
+|                    |  (Social Card tab)                      |
+|  > Social Card     |  +---------------------------+          |
+|    Headline        |  |                           |          |
+|    Subhead         |  |  We just shipped          |          |
+|    Badge text      |  |  dark mode                |          |
+|    Layout [v]      |  |                           |          |
+|    Background [v]  |  |  [logo]          [NEW]    |          |
+|                    |  |                           |          |
+|  > Presets         |  +---------------------------+          |
+|    Launch          |  1200x675 - Twitter/X                   |
+|    Blog Post       |                                         |
+|    Feature         |  MULTI-PREVIEW:                         |
+|                    |  [Tw] [Li] [IG] [St]                    |
++--------------------+-----------------------------------------+
+|  TOKEN OUTPUT (structured JSON)              [Copy Tokens]   |
++--------------------------------------------------------------+
+```
+
+### Three Tabs
+
+**Tab 1: Brand System** — The identity overview. Color palette rendered as large swatches with hex values and contrast ratios. Typography specimens at the brand's modular scale. Logo lockups (primary, mark, on-dark) if logo paths exist in creative-kit.md. Voice snapshot showing tone, vocabulary, headline style from voice-profile.md.
+
+**Tab 2: Social Card** — A live social card preview rendered with the brand tokens. The user types a headline, picks a layout variant (centered, split, overlay, minimal), chooses a background style (gradient, solid, dark, light). The card re-renders instantly. Below: a multi-preview strip showing the same card at Twitter (1200x675), LinkedIn (1200x627), Instagram (1080x1080), and Story (1080x1920) aspect ratios.
+
+**Tab 3: OG Image** — Same pattern as social card but for OG images. Inputs: title, description, author, category tag. Layouts: editorial, minimal, bold. Target: 1200x630.
+
+### Controls Panel (Left Side)
+
+Controls are grouped by concern. Each group is collapsible. Controls update the preview instantly — no "Apply" button.
+
+| Token | Control | Range |
+|-------|---------|-------|
+| Colors (primary, secondary, accent, background, foreground) | Color picker (native `<input type="color">`) | Any hex |
+| Display font | Dropdown | 10 curated options + current brand font |
+| Body font | Dropdown | 10 curated options + current brand font |
+| Scale ratio | Slider | 1.125 (Major Second) to 1.5 (Perfect Fifth) |
+| Border radius | Slider | 0px to 24px |
+| Shadow depth | Slider | none / sm / md / lg / xl |
+| Social card headline | Text input | Max 60 chars |
+| Social card layout | Segmented buttons | Centered / Split / Overlay / Minimal |
+| Social card background | Dropdown | Gradient / Solid / Dark / Light |
+
+### Token Output (Bottom)
+
+A `<pre>` block showing the current token state as structured JSON:
+
+```json
+{
+  "colors": {
+    "primary": "#6366F1",
+    "primaryForeground": "#FFFFFF",
+    "secondary": "#7C3AED",
+    "accent": "#F59E0B",
+    "background": "#FFFFFF",
+    "foreground": "#0F172A"
+  },
+  "typography": {
+    "display": { "family": "Space Grotesk", "weights": [700, 800] },
+    "body": { "family": "Inter", "weights": [400, 500, 600] },
+    "scale": { "base": 16, "ratio": 1.25 }
+  },
+  "visual": {
+    "borderRadius": "8px",
+    "shadowDepth": "md",
+    "texture": "none"
+  }
+}
+```
+
+A "Copy Tokens" button copies this JSON to the clipboard. The user pastes it back into the conversation. The agent reads the JSON and updates `brand/creative-kit.md` accordingly.
+
+### Presets
+
+Include 3-5 presets that snap all controls to a cohesive combination:
+
+| Preset | Vibe | Colors | Type | Visual |
+|--------|------|--------|------|--------|
+| **Tech Startup** | Clean, modern, confident | Indigo + violet + amber | Space Grotesk + Inter | 8px radius, md shadow |
+| **Indie Maker** | Warm, approachable, fun | Coral + teal + gold | Instrument Serif + DM Sans | 12px radius, lg shadow |
+| **Enterprise** | Precise, authoritative, refined | Navy + slate + emerald | General Sans + IBM Plex | 4px radius, sm shadow |
+| **Creative Studio** | Bold, expressive, artistic | Hot pink + lime + black | Space Grotesk + Syne | 0px radius, none shadow |
+| **From Brand** | Current creative-kit.md values | (extracted) | (extracted) | (extracted) |
+
+The "From Brand" preset is always first and always selected on load. It represents the current brand state. Other presets are for exploration.
+
+---
+
+## How You Generate It
+
+### Step 1: Extract Tokens
+
+Parse `brand/creative-kit.md` into structured data. Look for:
+
+- **Colors section**: hex values for primary, secondary, accent. If not found, derive from the first hex codes mentioned anywhere in the file.
+- **Typography section**: font family names, weights. If Google Fonts, construct the `<link>` URL.
+- **Visual Brand Style section**: aesthetic direction, lighting, composition notes. Use these to inform the playground's own aesthetic (dark mode vs light, gradient direction, texture).
+- **Logo paths**: if mentioned, include as `<img>` tags in the brand system tab.
+
+If parsing is ambiguous, use reasonable defaults and note what you assumed.
+
+### Step 2: Write the HTML
+
+Use the template structure from [references/html-architecture.md](references/html-architecture.md). The file should be 800-1500 lines depending on brand complexity. Key implementation details:
+
+- All CSS as `<style>` in `<head>`. Brand tokens as CSS custom properties on `:root`.
+- All JS as `<script>` before `</body>`. Single `state` object, single `updateAll()` function.
+- Google Fonts loaded via `<link rel="stylesheet">` — this is the ONE external dependency.
+- Dark/light toggle switches `:root` variables. Both themes use the brand palette.
+- Social card renderer uses absolute positioning within a fixed-aspect-ratio container.
+- Multi-preview strip uses CSS `transform: scale()` to show all sizes simultaneously.
+- Color pickers use native `<input type="color">` — no library needed.
+- Token output updates on every state change via `JSON.stringify(state.tokens, null, 2)`.
+- Copy button uses `navigator.clipboard.writeText()`.
+
+### Step 3: Open It
+
+```bash
+open brand-playground.html
+```
+
+Tell the user: "Your brand playground is open in the browser. Play with the controls — every change updates the preview instantly. When you're happy with how it looks, click 'Copy Tokens' and paste the JSON here. I'll update your brand files."
+
+### Step 4: Process Feedback
+
+When the user pastes the token JSON back:
+
+1. Parse it.
+2. Diff against current `brand/creative-kit.md` values.
+3. Show the diff: "You changed primary from #6366F1 to #4F46E5 and increased border radius to 12px. Want me to update creative-kit.md?"
+4. On confirmation, write the changes to the appropriate sections of `creative-kit.md`.
+5. Log the update to `brand/assets.md`: "Brand playground session — updated colors and visual style."
+
+---
+
+## Integration with /cmo Flow
+
+This skill slots into the /cmo foundation-building workflow:
+
+```
+/cmo activation
+  -> mktg init (if needed)
+  -> 3 research agents in parallel (brand, audience, competitors)
+  -> /visual-style (writes creative-kit.md)
+  -> /brand-kit-playground (renders creative-kit.md as interactive HTML)
+     -> User tweaks in browser
+     -> User copies tokens
+     -> Agent updates creative-kit.md
+  -> Continue to /image-gen, /creative, etc.
+```
+
+The playground is the **approval gate** between brand definition and brand execution. Before this skill existed, the user approved their visual identity by reading markdown. Now they see it rendered.
+
+---
+
+## Progressive Enhancement Levels
+
+| Level | Context | Behavior |
+|-------|---------|----------|
+| **L0** | No brand files | Placeholder brand with defaults. Full functionality. Note: "These are defaults." |
+| **L1** | creative-kit.md only | Tokens extracted. No voice or positioning in the snapshot panels. |
+| **L2** | creative-kit + voice | Tokens + voice snapshot. Social card headlines informed by voice style. |
+| **L3** | creative-kit + voice + positioning | Full context. Social card headline defaults to positioning angle. |
+| **L4** | All 4 files | Complete playground with audience info in voice panel. Best experience. |
+
+---
+
+## Anti-Patterns
+
+| Anti-pattern | Instead | Why |
+|-------------|---------|-----|
+| Generating a Next.js app with npm install | Single HTML file, zero dependencies | The playground must be instant. `npm install` is a 30-second wall that kills the flow. `/app-store-screenshots` scaffolds Next.js because it needs html-to-image for PNG export. This skill only needs browser rendering. |
+| Using a framework (React, Vue, etc.) | Vanilla JS with a state object | Frameworks add bundle size, build complexity, and failure modes. The /playground plugin proves vanilla JS works for interactive previews. |
+| Making the HTML generic/template-looking | The playground LOOKS like the brand | If the brand is dark and moody, the playground chrome should be dark. If the brand is warm and organic, the playground should feel warm. The playground's own aesthetic is derived from the brand tokens — it's not neutral gray chrome. |
+| Hardcoding Google Fonts URLs | Construct URLs from the font names in creative-kit.md | The user's brand may use any font. Read the font name, build the URL. If the font isn't on Google Fonts, fall back to the closest system font. |
+| Skipping the multi-preview strip | Always show at least 3 aspect ratios | The whole point of the social card tab is to see how the brand renders at real platform dimensions. One size isn't enough — the user needs to see Twitter vs Instagram vs Story to catch layout problems. |
+| Outputting raw CSS instead of JSON tokens | Structured JSON with semantic names | The agent needs to parse the output and write it to creative-kit.md. CSS variables are for the browser. JSON tokens are for the agent loop. |
+| Asking the user to manually edit creative-kit.md after the playground | Read the pasted JSON and write the changes yourself | The playground exists to make brand editing visual. Making the user edit markdown afterward defeats the purpose. |
+
+---
+
+## Governance Checks (Built Into the HTML)
+
+The playground includes a governance strip below the preview:
+
+```
+[checkmark] Contrast: AA   [checkmark] Heading readable   [warning] Accent on bg: 2.8:1 (needs 3:1)
+```
+
+Implementation: after each state change, run WCAG contrast ratio checks on all text-background combinations. Use the relative luminance formula inline — no library needed. Flag failures as warnings with the specific ratio.
+
+---
+
+## Font Curation
+
+For the font dropdowns, offer these curated options plus whatever the brand currently uses:
+
+**Display fonts:** Space Grotesk, General Sans, Instrument Serif, Syne, Clash Display, Satoshi, Plus Jakarta Sans, Outfit, Bricolage Grotesque, Manrope
+
+**Body fonts:** Inter, DM Sans, IBM Plex Sans, Source Sans 3, Nunito Sans, Geist, Work Sans, Rubik, Lato, Open Sans
+
+These are all on Google Fonts. The dropdown should show the font name rendered in that font (via per-option `font-family`).
+
+---
+
+## File Output
+
+| File | Path | Description |
+|------|------|-------------|
+| Playground HTML | `brand-playground.html` (project root) | The interactive playground |
+| Asset log entry | `brand/assets.md` | "Brand playground generated — [date]" |
+
+The HTML file is gitignored by convention (it's a generated artifact). The user can regenerate it anytime by re-running the skill.
+
+---
+
+## Error Recovery
+
+| Problem | Fix |
+|---------|-----|
+| creative-kit.md has no parseable colors | Use defaults. Note which values were assumed in the token output. |
+| Font not found on Google Fonts | Use the closest system font. Show a warning: "Couldn't load [font]. Using [fallback]." |
+| User doesn't paste tokens back | That's fine. The playground served its purpose as a visual check. No brand files need updating. |
+| Logo path in creative-kit.md doesn't resolve | Skip logo rendering. Show placeholder text: "[Logo]". |
+| User wants to re-run after brand changes | Just re-run the skill. It reads current brand files and generates a fresh HTML. |