git:20260808.5ce8d82 to git:20260824.d18190a

---

name: kelly-campaigns

description: Outbound email-marketing desk (Busabase App-in-Skill) for building segments, drafting campaigns, newsletters, and sequences, running pre-send deliverability and subject-line QA, and approving every send before it is scheduled. Structured around the SEND discipline — Setup, Engage, Nurture, Deliver — with an email-quality-auditor gate (EQS score + SHIP/FIX/BLOCK verdict). Use when the user invokes $kelly-campaigns or /kelly-campaigns, or mentions email marketing, campaigns, newsletters, drip/welcome/win-back sequences, broadcasts, segments, subject-line A/B tests, deliverability (SPF/DKIM/DMARC/spam score/inbox placement), or wants to review and approve marketing email before it is sent. This is OUTBOUND marketing to a subscriber list, distinct from kelly-email inbox triage (incoming mail). 出站邮件营销：策划分群、起草营销活动 / 新闻邮件 / 邮件序列，发送前做可送达性与主题行质检，人工审批后再排期发送。

metadata:

category: marketing

tags:

- risk:gated-write

- surface:busabase

---

# Kelly Campaigns

## Overview

Kelly Campaigns is a Busabase Cloud App-in-Skill. Its canonical product

surface is the AirApp in Busabase, not a separate local-data product. The

same Hono source supports an explicitly requested local preview with OAuth

connection bootstrap. Use this skill as Kelly's outbound email-marketing

operator: it keeps a dashboard over audience segments, drafted **sends**

(campaign broadcasts, newsletter issues, and sequence steps), pre-send

deliverability and subject-line QA, and post-send performance. The skill

builds segments, drafts email copy, runs deliverability and quality checks,

and prepares sends; the human reviews, edits, and approves each send in the

app **before anything is scheduled or sent**.

This is **outbound marketing to a subscriber list**. It is distinct from

`kelly-email`, which triages an incoming inbox. Keep them separate:

`kelly-email` is about mail you received; `kelly-campaigns` is about mail you

send to many people.

Default behavior is AirApp-first. Unless the user explicitly asks only for

explanation, update Busabase directly and give the user the clickable AirApp

URL. Start localhost only when local preview/debugging is explicitly

requested; it uses the same Busabase resources and never offers another data

provider. Use chat-only mode only when the user says "纯聊天", "chat only", "不要打开 UI", or similar; in that mode present numbered sends (`Send #1`) and take verdicts in the conversation.

This skill is an implementation of the **App-in-Skill** pattern — a Codex/agent skill paired with a small companion UI for review and approval. See the spec paper: <https://mr-kelly.github.io/research/app-in-skill-specification-for-pairing-agent-skills-with-a-local-companion-ui.pdf>.

## Mandatory Dependencies

1. Read and follow `$kelly-app-skill-creator` for product behavior, visual

2. Read and follow `$busabase` for connection, target Space, node discovery,

ChangeRequests, review, and merge behavior.

3. Read and follow `$busabase-app-creator` for resource modeling, AirApp

runtime limits, security, validation, and deployment.

If a dependency is unavailable, preserve this skill's local artifact and

product contracts, stop before the unavailable Busabase operation, and report

the exact missing dependency. Do not invent a second data backend.

## The SEND Discipline

Work is organized around four phases. Every send is tagged with the phase it belongs to, and the app groups by phase.

- **Setup** — the sending foundation: authentication and deliverability, audience segments, list growth, list hygiene.

- **Engage** — the creative: email copy, subject lines, HTML render / dark-mode, dynamic personalization.

- **Nurture** — the lifecycle: sequences (welcome, drip, win-back), newsletter cadence and monetization, preference/frequency management, reactivation.

- **Deliver** — getting it into the inbox: send experiments (A/B), inbox-placement monitoring, cold outbound, and the pre-send quality gate.

### Capability taxonomy (16 sub-skills)

| Phase | Sub-skills |

| --- | --- |

| **Setup** | `deliverability-qa` · `list-segment-builder` · `list-growth-designer` · `list-hygiene-monitor` |

| **Engage** | `email-creative-builder` · `subject-line-lab` · `email-render-builder` · `dynamic-content-personalizer` |

| **Nurture** | `email-sequence-designer` · `newsletter-monetization-planner` · `preference-frequency-manager` · `reactivation-specialist` |

| **Deliver** | `send-experiment-designer` · `inbox-placement-monitor` · `cold-outbound-sequencer` · **`email-quality-auditor` ⛩ (the quality gate)** |

### The quality gate — `email-quality-auditor` ⛩

Before any send can be scheduled, it passes the **SEND** framework, which produces an **EQS** (Email Quality Score, 0–100) and a **SHIP / FIX / BLOCK** verdict:

- **S — Sender & auth**: SPF, DKIM, DMARC pass; correct from-identity.

- **E — Engagement risk**: segment quality, expected open/complaint behavior, re-permission for cold/lapsed lists.

- **N — Not spammy**: spam score, trigger words, link/image balance, working unsubscribe + physical address.

- **D — Deliverability**: inbox readiness against policy floors, IP/domain warm-up, render and dark-mode.

## App UI Screenshots

<table>

<tr>

<td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly Campaigns overview"></td>

<td width="50%"><img src="assets/screenshots/campaigns.webp" alt="Kelly Campaigns queue"></td>

</tr>

<tr>

<td><strong>Overview</strong><br>Send calendar plus list health — subscribers, bounce, churn, and complaint rates.</td>

<td><strong>Campaigns</strong><br>Draft and approval queue across campaigns, newsletters, and sequence steps.</td>

</tr>

<tr>

<td width="50%"><img src="assets/screenshots/deliverability.webp" alt="Kelly Campaigns deliverability QA"></td>

<td width="50%"><img src="assets/screenshots/performance.webp" alt="Kelly Campaigns performance"></td>

</tr>

<tr>

<td><strong>Deliverability</strong><br>Pre-send QA — SPF/DKIM/DMARC, spam score, and the EQS SHIP/FIX/BLOCK gate.</td>

<td><strong>Performance</strong><br>Open, click, and unsubscribe rates by campaign.</td>

</tr>

</table>

## Boundary

- The skill may build segments, draft sends, run deliverability/quality checks, and write it all to Busabase.

- The AirApp reads and writes Busabase records only. It must never send email, call an ESP, mutate a subscriber list, or perform any other external side effect.

- Sending is always approval-required (outbound + volume). Real scheduling/sending is performed by the configured ESP by the skill, only after the user approves the specific send in the app or in chat. `scripts/execute_decisions.mjs` only marks an approved send `done` in Busabase and reports the handoff operation the ESP still needs to perform; it performs no sending itself.

- Treat subscriber data as sensitive. Never commit real subscriber lists, ESP credentials, or Busabase credentials.

## Busabase Resources

Four Bases under one application Folder (`kelly-campaigns`), declared in

- `segments`: audience segments — id, name, description, audience size.

- `sends`: the review queue — campaign/newsletter/sequence-step/cold-outbound sends: type, phase, subject/preview/body, segment + audience size, deliverability, subject A/B variants, the `quality-gate` (EQS + SHIP/FIX/BLOCK), workflow `status`, and the human verdict fields `decision-note` / `decided-at`.

- `suppression`: the consent/suppression list — recipients or whole segments removed by unsubscribe, hard bounce, or complaint.

- `settings`: one row per `kind` — `kelly-campaigns-profile` (operator/brand/ESP/from-identities/sending-policy/style-tone/list-health) and `kelly-campaigns-lock`.

Resources provision lazily through an idempotent Busabase ChangeRequest the

first time the app runs in a Space; see `references/campaigns-schema.md` for

exact field shapes. Metrics, the pre-send deliverability-risk derivation, and

the consent/suppression pre-send check are computed client-side from the

`sends`/`suppression` Bases on every read — they are never stored. The EQS

score and SHIP/FIX/BLOCK verdict are authored per send by the

`email-quality-auditor` gate and stored on the record.

## First Run And Onboarding

On invocation, check the `kelly-campaigns-profile` settings row for

readiness. If it is absent, guide setup before doing real marketing work.

Ask for non-secret setup details only: operator profile (name, role, company, timezone), brand (name, homepage, unsubscribe URL), ESP provider name, from-identities (from-name/from-email/reply-to and when to use each), segments, sending policy (approval-required, daily/hourly caps, min inbox readiness, max spam score), risk keywords, and style/tone. Never ask the user to paste secret values into chat. Busabase authentication is ambient inside the deployed AirApp; ESP credentials belong to the trusted handoff process's own environment, never Busabase.

## Local App

Default behavior is AirApp-first — give the user the clickable AirApp URL.

requested.

Required app views (hash routes):

- `#/overview`: send desk. Human-attention counts, upcoming sends for the next weeks, list health (subscriber count, bounce/complaint/churn rates, avg open/click), and a SEND-phase breakdown.

- `#/campaigns` and `#/campaigns/<send_id>`: the review queue over drafted sends in workflow states `needs_review`, `changes_requested`, `approved`, `done`, `blocked`. Each item shows a stable row ref (`Send #1`), type + phase + quality-gate verdict badges, the segment and audience size, deliverability risk, subject + preview text, an editable body draft, an A/B subject picker when variants exist, a `Review note` textarea, and Approve / Request changes / Block buttons that write the verdict directly onto the send record.

- `#/deliverability`: pre-send QA table — SPF/DKIM/DMARC pass flags, spam score, inbox readiness, and the SEND verdict per send, plus the read-only suppression list, so weak auth or spammy copy is caught before scheduling.

- `#/performance`: open/click/unsub/bounce by sent campaign.

- `#/settings`: sanitized config summary — operator, brand, ESP + secret readiness, from-identities, segments, sending policy, and onboarding state. Never expose secret values.

Keep the sidebar workflow filters (All / Needs Review / Approved / Done / Blocked) as the primary nav, plus the views above.

Demo mode:

- `?demo=1` (or `?demo=overview`) opens a deterministic mock program ("Northwind Coffee") for documentation and screenshots.

- `?demo=overview`, `?demo=campaigns`, `?demo=deliverability`, `?demo=performance`, and `?demo=detail` select named mock scenes; `detail` deep-links to a send detail.

- `lang=en` or `lang=zh` forces UI chrome language for screenshots.

- Demo mode never reads or writes Busabase.

UI language: support English and Chinese chrome with `Auto` default. Keep subject lines, body copy, segment names, and drafts in their original language.

## Review Workflow

Read `references/campaigns-schema.md` before editing the app or its domain logic.

A human verdict (`approve` / `request_changes` / `block` / `revise`) writes

the new `status` plus `decision-note` / `decided-at` (and, for `approve`, the

edited `body` / chosen `chosen-variant`) directly onto the send record

through `busabase-sdk`. From a standalone local preview the write merges

immediately (trusted operator); from the deployed AirApp it creates a

pending ChangeRequest for the trusted process to merge.

## Normal Workflow

1. Detect mode. Default to App UI.

2. When Kelly asks for a campaign, newsletter, or sequence: build/refresh the relevant segment, draft the send(s) into Busabase's `sends` Base with `status: "needs_review"`, the correct `type` and SEND `phase`, a clear `reason`, risk badges, a `deliverability` object, subject variants when A/B is intended, and run the `email-quality-auditor` gate to attach `quality-gate` (EQS + verdict). Metrics, deliverability risk, and the consent/suppression check recompute automatically on every read.

3. Give Kelly the AirApp URL (or local preview URL) to review the queue, deliverability, and quality gates.

4. For a send moved to `changes_requested`, re-draft it per the review comment, re-run the gate, and write it back to `needs_review`.

5. On "schedule approved sends": run `node scripts/execute_decisions.mjs --apply` to re-read approved sends from Busabase, re-check the quality gate/deliverability risk/suppression list, and mark each `done`. Then perform the actual scheduling/sending through the configured ESP with the approved, possibly user-edited body and chosen variant, one send at a time.

6. Never schedule a send without an explicit `approve` decision, never schedule one whose gate is `BLOCK` or whose deliverability risk is `high`, and never re-schedule sends already recorded as scheduled/sent.

## Safety Defaults

- Treat every outbound send as approval-required (outbound + volume). Money offers, compliance-sensitive copy, cold outbound, and high send volume raise the bar further.

- A `BLOCK` verdict or `high` deliverability risk is a hard stop; fix authentication or copy before the send is eligible.

- Store only the minimum content needed for review; keep raw subscriber lists and PII out of Busabase (segments carry names + sizes, not rows).

- Redact the ESP API key and any credential-like strings from logs, reports, and UI state; expose only boolean readiness for configured env vars.

- Keep stable ids (`send_id`, `segment_id`) and `ref` numbers so repeated updates and executions are idempotent.