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

@@ -146,6 +146,21 @@ ln -s /path/to/s3gc/skills/altinity-clickhouse-s3gc \
 The skill never supplies the delete confirmation. An authorized human must
 approve the reviewed dry-run result.
 
+## AI coding workflow
+
+`CLAUDE.md` (full guide) and `AGENTS.md` (short pointer) tell AI coding
+agents how to work here. For a new feature, bug fix, or behaviour change:
+
+1. **Spec Intake** — if the request is underspecified, the agent asks what
+   should happen instead, how to trigger it, whether it touches the delete
+   lifecycle, and known edge cases.
+2. **Spec** — a short problem statement and acceptance criteria, in the
+   commit that starts the change.
+3. **TDD** — a failing test per acceptance criterion, then made to pass.
+
+Editorial changes (docs, comments) skip this. See `CLAUDE.md` for the full
+rules.
+
 ## Development checks
 
 Run offline tests: