# AGENTS.md — crm-automation harness

This is the harness for the **crm-automator** master: CRM Automation & Orchestration.
The deep knowledge lives in `MANUAL.md` — this file governs *how a coding agent works
inside this master session after session*, without drift and without trusting its own
prior "done" claims.

## Startup Workflow (every session, in order)

1. Read `progress.md` — the active feature, current state, last verified command.
2. Read `feature_list.json` — the single source of truth for what's done and what's next.
3. Read `session-handoff.md` — anything not obvious from the two files above.
4. Run `./init.sh` — **the gate.** Never trust a prior "done" claim; re-run it. If it
   fails, nothing in this harness is trustworthy until it's green again.
5. Pick the **ONE** feature whose `status` is `in_progress`, or the first `todo` whose
   `dependencies` are all `done`.

## Working rules

- **One feature at a time.** Never start a second feature before the current one is
  `done` with evidence.
- **Stay in scope.** Build only the deliverable named by the active feature. Do not
  invent a 7th deliverable type or redesign the rubric without the user's go-ahead.
- **Build deliverables inside `workspace/`.** Every artifact this master produces
  (an automation-spec, a lead-scoring-model, etc.) is a file under `workspace/`.
  Never edit `MANUAL.md`, `verify_crm_automation.py`'s rubric logic, or `samples/`
  to make a deliverable pass — fix the deliverable, not the gate.
- **Reference `MANUAL.md`, do not inline it.** The manual holds the science, the
  schools, the decision frameworks. A deliverable cites what it's applying; it does
  not restate the manual's prose.

## Definition of Done (per feature)

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

1. Its `verify` command in `feature_list.json` (the linter against the workspace
   artifact it produced) exits 0.
2. `./init.sh` still passes end-to-end (the anti-theater gate: every sample in
   `samples/good/` still passes, every sample in `samples/bad/` still fails).
3. `feature_list.json` is updated: `status: "done"` + a one-line `evidence` string
   naming the exact command that proved it.
4. `progress.md` "Last verified" line is updated.

**NO evidence = NOT done.** If you cannot produce a passing verify command, leave the
feature `in_progress` and write the blocker in `progress.md`. A deliverable that "looks"
finished but hasn't cleared `verify_crm_automation.py` is a draft, not a feature.

## 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. Refresh `session-handoff.md` with anything the next session can't infer from the
   two files above.
4. Leave the tree in a runnable state — `./init.sh` green, or the broken feature
   clearly marked `in_progress` with the failure named.

---

## Operating the discipline (crm-automator specific)

### What this master actually does

Given a request for a CRM/automation deliverable, produce it as a markdown file under
`workspace/`, tagged `Deliverable-Type: <type>` on line 1, using the applicable
playbook(s) in `playbooks/` and the science in `MANUAL.md` §§1–9. Then run it through
`verify_crm_automation.py` before calling anything done.

### The six deliverable types (= the six features)

| Feature id | What it is | Playbook(s) that produce it |
|---|---|---|
| `automation-spec` | one fully-specified automation | speed-to-lead-sla, clay-enrichment-waterfall (branch), rfm-winback-engine (per-track), plg-product-signal-crm |
| `lead-scoring-model` | dual-axis fit + behavior score | lead-scoring-routing |
| `segmentation-plan` | RFM-based segments + treatments | rfm-winback-engine |
| `journey-map` | ordered lifecycle stages + triggers | lifecycle-stage-orchestration, predictable-revenue-pod, plg-product-signal-crm, cdp-event-journeys |
| `pipeline-audit` | sourced pipeline hygiene report | pipeline-hygiene-cadence |
| `integration-runbook` | per-integration sync contract | clay-enrichment-waterfall, cdp-event-journeys |

### Picking a playbook

Read `MANUAL.md` §5 (Decision Frameworks) first — it routes by data availability,
lead source (Seeds/Nets/Spears), trigger basis (form vs. product signal), audience
awareness, price point, and attribution reliability. Then open the matching file in
`playbooks/` for the named practitioner's exact build steps.

### The rubric is non-negotiable

`MANUAL.md` §8.2 is the enforced rubric per type. The tells in §8.1 (no exit, no
decay, no negatives, prose segments, untagged numbers, inline secrets, no
counter-metric) are exactly what `verify_crm_automation.py` checks for. If a
deliverable trips one of these, it is not a style preference — it is not done.

### Compliance is a hard entry condition, not a nice-to-have

Per `MANUAL.md` §9.3: any automation step that emails a contact must reference a
compliance-checked template ID, and the master treats `OUTREACH_POSTAL_ADDR` /
CAN-SPAM state as a gating fact. Never spec an automation that would send without
a compliant template + physical-address footer.

### Secrets

Every `integration-runbook` references auth by env var name or vault name — never an
inline key/token value. `verify_crm_automation.py` hard-fails on secret-shaped strings.
If a real key needs to be documented, name the env var, never paste the value.