docs: spec-first TDD workflow

AGENTS.md

@@ -17,12 +17,14 @@ quickly, then defer to `CLAUDE.md` for complete repository guidance.
    objects only after collection, dry-run review, explicit confirmation, and
    the applicable ClickHouse cluster/replica preflight. Do not weaken these
    controls without explicit approval and matching tests and documentation.
-3. **Test coverage and required checks are mandatory.** For every feature,
-   bug fix, or material behaviour change, add a focused test when no existing
-   test covers it; use test-driven development for behaviour changes. Run the
-   relevant offline pytest suite and Kubernetes renderer/manifest dry-run
-   checks described in `CLAUDE.md`. Automated tests must not contact live
-   ClickHouse or object storage, or delete objects.
+3. **Spec-first TDD and required checks are mandatory.** For every feature,
+   bug fix, or material behaviour change, start with a short spec (problem +
+   acceptance criteria) in the starting commit. If the request doesn't already
+   answer that, run Spec Intake first (see `CLAUDE.md`). Then use test-driven
+   development to satisfy each criterion. Run the relevant offline pytest
+   suite and Kubernetes renderer/manifest dry-run checks described in
+   `CLAUDE.md`. Automated tests must not contact live ClickHouse or object
+   storage, or delete objects.
 4. **No secrets or customer data in Git.** Never commit credentials, customer
    configuration, target-cluster details, or rendered customer manifests. Use
    Kubernetes Secrets or workload identity for production credentials.

CLAUDE.md

@@ -14,11 +14,15 @@ tests, explicit delete controls, and conservative deployment defaults.
    not retry automatically. A behavior change in this path needs regression
    tests and matching README/deployment documentation.
 
-2. **Test coverage and TDD are mandatory.** For every new feature, bug fix, or
-   material operational behaviour change, identify the test that covers it; if
-   none exists, add a focused test in the same change. Start behaviour changes
-   with a failing test, and add a regression test for every defect. Purely
-   editorial changes are exempt.
+2. **Spec-first TDD is mandatory.** For every new feature, bug fix, or
+   material operational behaviour change, start with a short spec in the
+   commit that begins the change: one or two sentences on the problem or
+   intent, plus a short bullet list of acceptance criteria — what must be true
+   when it's done. If the request doesn't already answer these, run Spec
+   Intake first (see below). Then use TDD: for each acceptance criterion,
+   write the failing test that covers it before making it pass. Add a
+   regression test for every defect. Purely editorial changes are exempt from
+   both the spec and TDD.
 
 3. **Tests stay offline by default.** Install both requirements files, then
    run `pytest -v` for relevant changes. Tests must use fakes, local
@@ -50,6 +54,20 @@ tests, explicit delete controls, and conservative deployment defaults.
    for possible, interesting, and deliberately deferred improvements. Do not
    treat a TODO item as already implemented or use the changelog as a backlog.
 
+## Spec Intake
+
+When someone reports a bug or asks for a feature without enough detail to
+write a spec, ask:
+
+1. What's happening, and what should happen instead?
+2. How do you trigger it (steps or command)?
+3. Does this touch the delete lifecycle (collect → dry-run → delete → verify)
+   or a safety check?
+4. Any known edge cases, or things this must not break?
+
+Use the answers to write the spec's acceptance criteria. If the report
+already answers these, skip straight to the spec.
+
 ## Repository map
 
 | Path | Purpose |

README.md

@@ -84,6 +84,23 @@ For Claude Code, substitute `~/.claude/skills`. Invoke it with
 The skill does not permit an agent to supply the deletion confirmation; an
 authorized human must approve the reviewed dry-run result.
 
+## AI coding workflow
+
+This repo uses `CLAUDE.md` (full guide) and `AGENTS.md` (short pointer) to
+tell AI coding agents how to work here. If you ask an agent to fix a bug or
+add a feature, here's what it does:
+
+1. **Spec Intake** — if you didn't give enough detail, the agent asks a few
+   short questions: what's happening vs. what should happen, how to trigger
+   it, whether it touches the delete lifecycle, and any known edge cases.
+2. **Spec** — the agent writes a short spec (problem + acceptance criteria)
+   in the commit that starts the change.
+3. **TDD** — for each acceptance criterion, the agent writes a failing test,
+   then makes it pass.
+
+This applies to new features, bug fixes, and behaviour changes. Editorial
+changes (docs, comments) skip it. See `CLAUDE.md` for the full rules.
+
 ## Direct script examples
 
 The following is a non-secret target configuration. Replace every