# Newsletter — Starter Pack This directory contains the complete newsletter production system scaffolded by `create-claudify`. It ships as a **working starter pack** with all the structure pre-built. The foundation files need your brand before your first issue. --- ## What's inside ### Foundation files (`foundations/`) Read by every newsletter agent at startup. The 6 files codify the voice, audience, format, and known-failure rules of your newsletter. | File | Purpose | Adapt? | |---|---|---| | `PERSONA.md` | Audience floor / middle / ceiling reader segmentation | **YES** — define your readers first | | `VOICE.md` | Voice bible: hard bans, preferred patterns, calibration paragraphs | **YES** — voice is brand-specific | | `GLOSSARY.md` | 4-bucket glossary decision tree for technical terms | **PARTIAL** — Bucket 4 (banned acronyms) is universal; Buckets 1-3 are brand-specific | | `BUDGETS.md` | Numerical limits (word count, sentence length, link count, visual blocks) | **PARTIAL** — limits are calibrated against email-rendering reality, not arbitrary | | `PIPELINE-PERSONALITIES.md` | Email client quirks (Beehiiv mojibake, Outlook flexbox break, Gmail clip threshold) | **NO** — universal rendering pipeline facts | | `MISTAKES-LOG.md` | Every documented failure pattern with the auditor check that prevents recurrence | **NO** — universal mistakes; ADD your own as you ship | ### Schema + rubric | File | Purpose | |---|---| | `ISSUE-SCHEMA.md` | Required fields per issue, format rules | | `GOD-PROMPT-RUBRIC.md` | 6-criterion rubric for evaluating god-tier prompts (the prompt-architect agent enforces this) | | `COMPONENTS.html` | Reusable HTML email building blocks — copy these into `TIP_BODY` | | `email-template.html` | Master HTML template with `{{PLACEHOLDERS}}` filled by `build.py` | ### Build pipeline | File | Purpose | |---|---| | `build.py` | Renders an issue source markdown to HTML by filling the email-template placeholders | | `send.js` | Sends preview email to your inbox via Resend; creates Beehiiv broadcast drafts | | `render-test.sh` | Playwright-based render test at 4 viewports (320, 414, 768, 1024) | | `test-god-prompt.py` | 3-codebase test harness for the prompt-architect agent | ### Issue / brief / draft folders | Folder | Purpose | |---|---| | `issues/` | Issue source files (`NNN.md`) + rendered HTML output (`NNN-rendered.html`) | | `briefs/` | Strategist's briefs that the drafter consumes | | `drafts/` | Prompt-architect's god-tier prompt drafts during validation cycles | --- ## Setup checklist **Before your first issue:** 1. **Edit `foundations/PERSONA.md`** — define your floor / middle / ceiling reader 2. **Edit `foundations/VOICE.md`** — add your calibration paragraph pairs, banned phrases, signature phrases 3. **Adapt `foundations/GLOSSARY.md`** — Buckets 1-3 for your audience's vocabulary 4. **Edit `email-template.html`** — replace `YOUR BRAND`, `Your Name`, `yourdomain.com` with your actual brand 5. **Create `newsletter/.env`** (gitignored) — add your API keys: ``` RESEND_API_KEY=re_... BEEHIIV_API_KEY=... BEEHIIV_PUB_ID=pub_... RESEND_FROM=Your Newsletter PREVIEW_TO=you@yourdomain.com ``` 6. **Edit `BACKLOG.md`** — add your topic ideas and rotation plan --- ## Running the pipeline ```bash # Start the full newsletter pipeline (all 9 phases) /newsletter strategy 001 # Or run phases individually: /newsletter draft 001 # Write the issue /newsletter architect 001 # Design the god-tier prompt /newsletter build 001 # python3 newsletter/build.py 001 /newsletter render-test 001 # bash newsletter/render-test.sh 001 /newsletter preview 001 # node newsletter/send.js 001 --preview /newsletter send 001 # node newsletter/send.js 001 ``` --- ## How the agents use this directory The `newsletter-orchestrator` agent runs the 9-phase pipeline and reads from this directory: ``` strategy → draft → architect → build → audit → render-test → preview → send → analyse | | | | | | | | | strategist drafter prompt-arch build.py auditor stylist send.js manual analyst + render-test.sh ``` Each phase's sub-agent runs in fresh context to avoid drafter blind-spots. --- ## Customisation guide **What to customise (in priority order):** 1. `foundations/PERSONA.md` — your audience, not the template author's 2. `foundations/VOICE.md` — your voice anchors (calibration paragraph pairs do the work abstract style guides don't) 3. `foundations/GLOSSARY.md` — your term decisions 4. `email-template.html` — your brand name, author name, domain 5. `BACKLOG.md` — your topics **What NOT to customise:** - `foundations/PIPELINE-PERSONALITIES.md` — these are empirical email-client facts - `foundations/MISTAKES-LOG.md` — keep all pre-seeded entries; add yours on top - `foundations/BUDGETS.md` — word counts are calibrated against rendering reality; only adjust after 3+ shipped issues show the budget is wrong - The HTML structure in `email-template.html` — the table-based layout and inline styles exist for Outlook and Gmail compatibility - `COMPONENTS.html` — the pre-styled blocks ensure visual consistency --- ## What the pre-seeded mistakes prevent `foundations/MISTAKES-LOG.md` ships with 15 universal failure patterns that have been documented from real production cycles. Every one has an auditor check that prevents recurrence: - Em dash in copy (AI-detector tell) - Subject line over 50 characters (Gmail mobile truncation) - Placeholder text in code blocks (breaks "copy-paste ready" promise) - Banned filler phrases ("simply", "obviously") - Low-contrast text (WCAG failure) - Flexbox in HTML (Outlook breaks) - Raw non-ASCII in HTML (Beehiiv mojibake) - `