# AGENTS.md — master-copywriter harness

This is the harness for the **master-copywriter** (Conversion Copywriting discipline). It turns
`MANUAL.md` (the deep knowledge) into a disciplined, gate-checked workspace for producing real
persuasion-surface deliverables — sales pages, VSL scripts, ad sets, email subject banks, landing
hero variants — one at a time, without drift, across sessions.

## Startup Workflow (every session, in order)

1. Read `progress.md` — the active deliverable, its current status, and the last verified state.
2. Read `feature_list.json` — the single source of truth for what's done, what's todo, and each
   feature's `verify` command.
3. Read `session-handoff.md` if present — it captures anything not obvious from the two files above.
4. Run `./init.sh` — **the gate**. Never trust a prior "done" claim; re-run it. This proves the
   linter itself still discriminates good copy from bad copy before you trust it on new work.
5. Pick the **one** `in_progress` feature, or the first `todo` feature whose `dependencies` are all
   `done`. (All five deliverable-type features are independent capabilities — there is no forced
   build order between them — but never work two at once.)

## 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.** The unit of work is ONE surface — a page, a beat sheet, a variant set — never a
  funnel, never a send calendar, never the offer terms themselves. Funnel structure comes in from
  `funnel-psychology`; cadence and list mechanics go out to `email-marketing`. If a brief is missing
  the awareness/sophistication spec, **stop and request it** — do not guess (MANUAL.md §1.2, §3.1).
- **Build deliverables inside `workspace/`.** Every artifact the agent produces lives at
  `workspace/<feature-id>.md` (e.g. `workspace/sales-page.md`). Never edit `MANUAL.md`,
  `verify_copywriting.py`, or the `samples/` fixtures as part of doing feature work — those are the
  gate, not the deliverable.
- **Reference `MANUAL.md`, do not inline it.** The manual holds the science, the schools, the
  decision grid, and the §8 rubrics. Read it, cite it (the "Because:" rationale on hero variants must
  cite a named school from it), and write fresh copy — never paste manual text into a deliverable.
- **Voice gate on 19Keys-brand surfaces.** Before drafting a line for ZIION, Supermind, CWK, or
  HIGH LVL, load the `brand-bible` skill and enforce house register + forbidden vocabulary on top of
  the linter's local hype/vocab lists (MANUAL.md §5.4, §9.2).

## 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 the workspace artifact.
2. `./init.sh` still passes end-to-end (the anti-theater gate still holds — no regressions).
3. `feature_list.json` is updated: `status: "done"` + a one-line `evidence` string (the literal
   command you ran and its result, e.g. `python3 verify_copywriting.py sales-page workspace/sales-page.md → RESULT: PASS (19 checks passed)`).
4. `progress.md` "Last verified" line is updated.

**No evidence = NOT done.** If the verify command fails, leave the feature `in_progress` and write
the specific failing check names in `progress.md` — not a vague "needs work."

## End of Session routine

1. Update `feature_list.json` status/evidence for anything touched this session.
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 two files above (blockers, half-finished drafts, brief gaps waiting on funnel-psychology).
4. Leave `workspace/` in a runnable state — a half-built deliverable should be clearly `in_progress`
   in `feature_list.json`, not silently abandoned.

## Producing a deliverable (operating sequence)

This is the sequence MANUAL.md Appendix A compresses into ten steps. Apply it to whichever feature
is active:

1. **Locate** the prospect on Awareness × Sophistication (Schwartz, MANUAL.md §3.1). This must come
   from the brief (funnel-psychology) — if missing, stop and ask.
2. **Select the lead type** keyed to awareness (Masterson/Forde's six — MANUAL.md §3.1, §6.5).
3. **Pick a playbook** from `playbooks/` that matches the awareness/sophistication/channel
   combination (MANUAL.md §5.2 has the full decision table).
4. **Draft** to the deliverable's required structure (MANUAL.md §3.2/§3.3 for sales-page/VSL; §8 for
   the exact machine-checkable shape of all five types).
5. **Attach proof to every claim carrying a number** — tag it `[testimonial|data|demo|authority|story]`
   or cut the number. This is the single hardest gate and the most common reason a draft fails.
6. **Self-score before running the linter**: Flesch Reading Ease, banned vocabulary, paragraph
   length, em-dash density, single CTA, lead/awareness tags present and consistent (MANUAL.md §7.1,
   §8.6).
7. **Run the feature's `verify` command.** Fix named failures, not vibes — the linter prints exactly
   which check failed.
8. **Run `./init.sh`** to confirm the gate itself still holds, then mark the feature done with
   evidence.

## Hard lines (non-negotiable, mirrors MANUAL.md §8.7)

- Never fabricate a proof element (a testimonial, a stat, a case) that doesn't exist. Untagged or
  invented numbers are the #1 way practitioners fake competence — the linter catches untagged ones;
  fabricated-but-tagged ones are a human/editorial integrity failure the linter cannot catch, and are
  never acceptable.
- Never guess the awareness/sophistication stage when the brief doesn't supply it.
- Never ship more than one distinct CTA target on a single surface.
- Never inline MANUAL.md content into a deliverable — cite it, don't paste it.