campaign-preflight AGENTS.md

AGENTS.md

Working notes for anyone — human or agent — changing this repository. These are the conventions that are easy to break by accident because they look like mistakes until you know why they are there.

CLAUDE.md at the repo root is a one-line @AGENTS.md include, kept only because Claude Code auto-loads CLAUDE.md as project context and does not (yet) do the same for AGENTS.md. It is not shipped as plugin context — see the plugin-manifest warning under CI workflows below; a plugin install never sees it. Edit this file, never CLAUDE.md directly.

Self-descriptions go stale. This file has restated a checkable fact about the codebase in prose twice now — a test count and a test-coverage claim — and been wrong both times within weeks, caught only by an external audit rather than anything in the repo. When adding a sentence here that describes what the test suite or the code currently does, point at the file that holds the truth (see tests/unit/test_mcp_safety.py) rather than restating a count, a percentage, or a line number that the next commit can invalidate without touching this file.

What this is

campaign-preflight, a read-only linter for outbound email campaigns. It ships three ways: a Python CLI, an MCP server, and a Claude plugin.

Naming. The repository and the plugin share one name: campaign-preflight. Use it verbatim in prose, headings, install commands, and URLs.

Non-negotiables — this tool cannot write, and must never be able to

This is a pre-send safety tool. Its entire value is that it can be pointed at a real campaign and a real API key without any risk of the campaign changing. No change may weaken that, however small or however good the reason looks. Concretely, no change may:

• Add a code path that writes to a provider. There is no PATCH/PUT/ DELETE/mutating-POST call anywhere in this codebase, and there must never be one. ReadOnlyTransport in src/campaign_preflight/providers/instantly_transport.py matches every outbound (method, path) against READ_ONLY_ALLOWLIST — an explicit tuple of compiled patterns — and raises ReadOnlyViolation on anything else, before the request leaves the process. Exactly one entry is a POST (/api/v2/leads/list, a filter-body read modelled as a POST); the test suite asserts no second POST entry ever appears. Adding a provider call means adding an allowlist entry that a reviewer can see is a read — never widening the match to something broader like a whole path prefix.
• Let an MCP tool's name, description, or annotations imply a write. _assert_read_only() in src/campaign_preflight/mcp/server.py runs at server startup — not only in tests — and refuses to start if any tool name contains a mutating verb (MUTATING_VERBS), if its description doesn't start with the literal READ-ONLY. prefix, or if it isn't annotated readOnlyHint: True. This is a fail-closed guard specifically so a mistake in a fork can't ship a write tool to somebody's Cowork or Claude Desktop. All three failure branches are covered by tests/unit/test_mcp_safety.py, parametrized over every verb in MUTATING_VERBS, including the over-breadth direction — see Testing conventions below.
• Let missing or unreadable data produce a PASS. Every provider read returns data plus the reason it does or does not exist (ProviderResult in providers/base.py: ok, failed, forbidden, unsupported, misconfigured). Every rule declares the Capability values it requires, and engine.evaluate() short-circuits a rule to UNKNOWN before calling it if a required capability isn't available (_missing_capabilities()). Rules cannot opt out of this — there is no parameter that lets a rule run anyway and guess. There are four verdicts, not two, and INCOMPLETE is a first-class outcome, not an error state.
• Let a credential reach a log, a report, an exception, or a PR comment. The Instantly API key is read from the environment only — no CLI flag, no MCP tool argument accepts one (test_no_tool_accepts_a_credential_argument enforces the latter) — set once as an Authorization header, and never formatted into a message. redact_secrets() (errors.py) runs over every provider-facing error string, every log line, and every rendered report, unconditionally; --no-redact on the CLI disables contact-mailbox masking only, never credential masking.
• Accept a raw campaign edit, activation call, or send trigger as a feature request. This tool inspects; it does not act. If a request is "and then also send it" or "and then also pause it," the answer is no, not a design discussion — see What this repo deliberately does not do.