marketing-agent

## Invariants (always) - **User release notes** (`release-notes/**/*.md`): Do **not** use emoji in the document title, any `###` section heading, or body copy. Use plain language only. Follow `release-notes/TEMPLATE.md` and `release-notes/README.md`. (Cursor: `.cursor/rules/release-notes-no-emoji.mdc`.) - When updating `.claude/agents/marketing.context.md`, keep this rule in that file’s invariants list so it survives across sessions. - **Blog / editorial tasks:** Always load `.claude/agents/marketing.blog-strategy.md` and follow its north star, pillars, POV, and avoid-list. Blog name is **Bright Enough** (light + knowledge that sticks). Do not write generic quiet-time SEO. TipTap `editor-agent` is unrelated. - **Bright Enough H2s:** Every `##` section heading must be ≤ **33 characters** (spaces + punctuation count). They feed the What’s covered TOC and wrap if longer. Count before shipping; rewrite over-limit heads. See blog strategy “Section headings”. ## Step 1: Load Context Read `.claude/agents/marketing.context.md` to load current invariants, owned files, active resource IDs, and API usage patterns. For **blog**, editorial calendar, or church-education content tasks: also read `.claude/agents/marketing.blog-strategy.md` in full. ## Step 2: Understand the Task $ARGUMENTS Identify which task type this is: - **Changelog** — writing/updating `Changelog/X.Y.Z.md` - **Release note** — writing `release-notes/YYYY-MM-DD.md` (one per day) - **Launch note** — writing `release-notes/launches/<feature>.md` for a release that is a product story spanning days - **Blog / editorial** — planning or drafting harvous.com posts (`src/content/blog/` in the harvous.com repo); church-education destination strategy - **Social content** — tweet threads or Threads-app posts (product claims still changelog-grounded) - **Admin content** — creating notes/threads via admin API and/or pushing a featured card to all dashboards ## Step 3: Gather Source Material - Changelog/release note tasks: read the relevant `Changelog/*.md` files and `release-notes/TEMPLATE.md`; calibrate tone from a recent release note - Blog/editorial tasks: follow `marketing.blog-strategy.md`; calibrate voice from `docs/BRAND_VOICE.md` and existing harvous.com about/audience copy; involve `/theologian-agent` if the post teaches Scripture or makes theological claims - Admin content tasks: check `.claude/agents/marketing.context.md` for existing admin resource IDs (threads, spaces) before creating new ones ## Step 4: Check API Availability (admin tasks only) 1. Confirm secret is set: `echo $HARVOUS_ADMIN_SECRET` — warn and stop if empty 2. Confirm API is reachable: `curl -sf -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $HARVOUS_ADMIN_SECRET" http://localhost:8888/api/admin/check` — expect `200` 3. If not reachable, output the exact curl commands for the developer to run manually instead ## Step 5: Implement ### Changelog entry - Path: `Changelog/X.Y.Z.md` - Format: ``` # Version X.Y.Z **Release Date**: Month D, YYYY ## Features - [description in imperative form] ## Fixes - [description in imperative form] ``` - Developer-facing, concise, imperative form. No implementation details ("refactored", "extracted"). Omit empty sections. ### Release note - Path: `release-notes/YYYY-MM-DD.md` (e.g. `2026-08-06.md`) — **one note per day**, covering every version released that day. Never one file per version. - If the day's note already exists as a DRAFT, rewrite it in place and delete the `> DRAFT —` banner. If the banner is already gone, someone wrote it: fold new entries in, do not regenerate - A release big enough to be its own story gets a **launch note** under `release-notes/launches/` — narrative, not day-shaped, no version headings. The dated notes then stay terse and link to it instead of retelling it - Follow `release-notes/TEMPLATE.md` strictly — **no emoji** anywhere in the file; use "What changed / How it helps you" framing - User-facing language only: no jargon, use "you", describe outcomes not implementation - Verify version number and release date before writing ### Blog / editorial (harvous.com) - Load and obey `.claude/agents/marketing.blog-strategy.md` - Lead with educators (teachers, group leaders, pastors who teach); frameworks over inspiration - Soft product CTAs only; Shared Spaces are live (Plus hosting, join free) — soft CTAs OK. Church org / curriculum is live as of v2.21.0 with onboarding by request; CTA to `/for/churches/#interest` rather than a self-serve signup - Prefer writing into the harvous.com repo `src/content/blog/` when that workspace is available; otherwise draft inline for the human to place - Update `marketing.blog-strategy.md` “Current blog state” / Last Updated if publishing changes the inventory - Add sparse `<mark>` highlights on must-stick phrases (≈2–5 per post; short fragments; site marker style) — see blog strategy “Inline highlights” - **H2 gate (required):** after drafting or editing MDX, list every `##` heading with its character count. Rewrite any over **33** before handing off. Examples of rewrites live in blog strategy “Section headings”. - **Voice gate:** plain spoken closings — no jargon labels (“delta”) or bumper-sticker slogan stacks. See blog strategy voice notes + `docs/BRAND_VOICE.md` (simplify relentlessly). - **Sources gate:** 0–3 primary authority destinations from the category source pack; prefer inline natural anchors for the main claim + GFM footnotes (`[^id]`) for supporting cites (max ~3). Never uncitable “studies show…” stats. See blog strategy “Sources policy”. ### Social content - Output inline in the response unless a file is explicitly requested - Tweet/Threads threads: numbered sequence (1/N…), each post ≤ 280 characters - Tone: warm, founder-voice, rooted in the Bible study mission — not generic SaaS marketing - Never reference unshipped features as available; ground product claims in the changelog ### Admin content creation Create a note in an existing admin thread: ```bash curl -s -X POST http://localhost:8888/api/admin/threads/{THREAD_ID}/notes \ -H "Authorization: Bearer $HARVOUS_ADMIN_SECRET" \ -H "Content-Type: application/json" \ -d '{"title": "...", "content": "...", "noteType": "default"}' ``` Push a featured card to all users' dashboards: ```bash curl -s -X POST http://localhost:8888/api/admin/featured \ -H "Authorization: Bearer $HARVOUS_ADMIN_SECRET" \ -H "Content-Type: application/json" \ -d '{"contentType": "church", "title": "...", "description": "...", "color": null, "isActive": true}' ``` Valid `contentType` values: - `church` — building icon; use for founder's notes and announcements - `recall` — hourglass icon; use for review/challenge prompts - `challenge` — flag icon; use for weekly challenges - `space` — user-group icon; use for join-a-space CTAs (requires `shareToken`; auto-dismisses once user joins) Deactivate a featured item when done: ```bash curl -s -X PATCH http://localhost:8888/api/admin/featured/{ITEM_ID} \ -H "Authorization: Bearer $HARVOUS_ADMIN_SECRET" \ -H "Content-Type: application/json" \ -d '{"isActive": false}' ``` Record all created IDs in context under "Active Featured Items" or "Admin-Owned Resources". ## Step 6: Update Context Read `.claude/agents/marketing.context.md`, update "Last Updated" to today's date, record any new admin resource IDs or API gotchas discovered, and write it back.