# AGENTS.md — email-marketing harness (email-strategist)

This is the working harness for the `email-strategist` master. `MANUAL.md` in
this directory holds the deep knowledge (the science, the schools, the
architecture, the failure modes). This file is the operating discipline —
read the manual for *what to know*, read this for *how to work*.

## Startup Workflow (every session, in order)

1. Read `progress.md` — the active feature, current status, and last verified state.
2. Read `feature_list.json` — the single source of truth for what's done and what's next.
3. Read `session-handoff.md` if present — anything not obvious from the two files above.
4. Run `./init.sh` — **the gate.** Never trust a prior "done" claim; re-run it every session. It re-proves the linter catches bullshit (passes `samples/good/*`, fails `samples/bad/*`) before you touch anything.
5. Pick up the **one** feature whose `status` is `in_progress`, or the first `todo` whose `dependencies` are all `done`.

## Working rules

- **One feature at a time.** Do not start a second deliverable type until the current one is `done` with evidence.
- **Stay in scope.** You are building this master's deliverable types (§8.1 of `MANUAL.md`), not the CRM schema, not the copy voice engine, not the funnel offer architecture — those belong to `crm-automation`, `copywriting`, and `funnel-psychology`. Consume their outputs; don't rebuild them.
- **Build deliverables inside `workspace/`.** Every artifact you produce for a feature goes in `workspace/<feature-id>.md` (or a dated variant). Never touch `MANUAL.md` — it's the fixed reference.
- **Reference `MANUAL.md`, do not inline it.** When building a deliverable, cite the section (`§8.1`, `§6.1`, etc.) and the playbook file — don't paste manual content into the artifact.
- **Reference the playbook, don't freelance the method.** Every deliverable type maps to a named playbook in `playbooks/` (see the table below). Follow its step-by-step build; it exists so you don't reinvent — or worse, cargo-cult — a school you don't fully understand.

## Definition of Done (per feature)

A feature is `done` only when ALL are true:

1. Its `verify` command in `feature_list.json` exits 0 against a real `workspace/` artifact (or the sample, for the harness's own bootstrap feature).
2. `./init.sh` still passes end-to-end — the anti-theater gate holds (good samples pass, bad samples fail).
3. `feature_list.json` is updated: `status: "done"` + a one-line `evidence` string naming the artifact path and the command that proved it.
4. `progress.md` "Last verified" line is updated.

**No evidence = NOT done.** If you cannot produce a passing `verify` run against a real artifact, leave the feature `in_progress` (or `todo`) and write the blocker in `progress.md`. Do not mark a feature done because the copy "looks right" — the linter is the judge, not your read of the prose.

## End of Session routine

1. Update `feature_list.json` status/evidence for anything you touched.
2. Update `progress.md`: active feature, last verified command + result, next step.
3. Write/refresh `session-handoff.md` with anything the next session needs that isn't obvious from the state files.
4. Leave the tree in a runnable state — `./init.sh` should pass when the next session starts.

---

## Deliverable types → playbooks (the multiple ways to run each one)

| Feature (deliverable type) | Playbook(s) | Primary source |
|---|---|---|
| `welcome-sequence` | `playbooks/soap-opera-sequence.md`, `playbooks/dinner-party-onboarding.md` | Chaperon (SOS), Geisler (onboarding frame) |
| `launch-sequence` | `playbooks/plf-launch-sequence.md` | Jeff Walker's Product Launch Formula |
| `ecom-flow-set` | `playbooks/klaviyo-flow-stack.md` | Klaviyo flow-stack canon |
| `daily-email` | `playbooks/daily-email.md` | Ben Settle / Matt Furey infotainment |
| `reactivation-campaign` | `playbooks/nine-word-reactivation.md` | Dean Jackson |
| `deliverability-audit` | `playbooks/deliverability-warmup.md` | SPF/DKIM/DMARC + Gmail/Yahoo 2024 rules |
| (meta, consulted by all) | `playbooks/rfm-segmented-sending.md` | Marshall's 80/20 + Rogers' adopter waves |
| (meta, consulted by all) | `playbooks/newsletter-growth-engine.md` | Morning Brew model (scaling the list itself) |

Every deliverable also answers to the decision frameworks in `MANUAL.md` §5
(segment gate → awareness gate → channel/trigger gate → price-point gate →
**permission/law gate, which has veto power over all the others**). Run the
permission/law gate first for any real send: if the postal address isn't
set, DMARC isn't published, or the domain isn't warmed, no deliverable in
this harness is cleared to actually fire, no matter how well it's built.

## The verify gate: `verify_email_marketing.py`

`verify_email_marketing.py <path/to/deliverable.md>` is the real linter. It:
- reads a `type:` value from the file's frontmatter to pick the right rubric,
- checks the concrete, enforceable rules from `MANUAL.md` §8.1 (counts, word
  limits, goal tags, single-CTA-target, loop closure, compliance merge tags,
  urgency tagging, missing evidence lines, etc.),
- prints every named check that failed, and exits 0 (pass) or 1 (fail).

`./init.sh` proves the linter itself is honest: it runs the linter against
`samples/good/*` (must PASS) and `samples/bad/*` (must FAIL). If either
direction breaks, `init.sh` exits nonzero — treat that as a stop-everything
signal and fix the linter before building anything on top of it.

## House-voice and compliance are non-negotiable

- The `daily-email` rubric enforces the brand-bible banned-vocabulary list
  (mirrored in `verify_email_marketing.py`'s `BANNED_VOCAB`) as a hard fail —
  see `~/.claude/skills/brand-bible/skill.md` for the full list and the "why."
- Every deliverable type carries CAN-SPAM compliance tags (`{{unsubscribe_link}}`,
  `{{postal_address}}`) on every single email. This is not a style choice —
  it is the law (`MANUAL.md` §2.8) and it is enforced mechanically.
- Never report an open rate as a success metric in any artifact — Apple MPP
  inflates it into near-uselessness (`MANUAL.md` §2.6). Lead with clicks, RPR,
  reply rate, and complaint rate.
- Never leave urgency/scarcity language untagged. Every claim of the form
  "cart closes," "only 3 left," "price rises" must carry an explicit
  `Urgency: real:<mechanism>` tag naming the actual enforcing mechanism —
  fake scarcity is the #3 tell in `MANUAL.md` §8.2 and the linter hard-fails
  untagged urgency language in `launch-sequence` deliverables.

## Bridge to the live 19Keys stack (context, not a blocker on this harness)

The real-world critical path (`MANUAL.md` §9.6) is: file the CAN-SPAM
postal-address + DMARC P0s with `owner-action-chaser` → run
`deliverability-warmup` → segment via `rfm-segmented-sending` → warm the
hottest buyers → stand up `daily-email` → launch ZIION Passport to the whale
wave → instrument on clicks/RPR. This harness's `deliverability-audit`
feature tracks that real blocker state; do not mark it `done` with an
optimistic checklist — mark each item `[verified|failed|todo]` honestly, with
real evidence, exactly as `playbooks/deliverability-warmup.md`'s worked
example does.