Merge: TDD development workflow

README.md

@@ -65,6 +65,32 @@ account, decrypt and save files. Upload, sharing, deletion, and bidirectional
 sync are out of scope. Adding them later is straightforward; doing them right
 requires the protocol layer to be correct first.
 
+## Development workflow
+
+All work on quack is test-driven. No exceptions.
+
+1. Every change starts on a feature branch off `main`.
+2. The first commit on the branch is the test suite for what is being added or
+   changed. Those tests must fail at that commit; the branch is red until the
+   implementation lands.
+3. Subsequent commits add the implementation and any refactors needed to make
+   the tests pass.
+4. A feature branch can only be merged into `main` when `make check` is green.
+   `main` is always green. The Dockerfile runs `make check`, so a red branch
+   cannot pass CI.
+5. Tests are the canonical API documentation for this library. Every test file
+   is commented thoroughly enough that a reader who has never seen quack can
+   learn how to use it from the tests alone. Comments explain why a behavior
+   matters, not just what the assertion checks.
+6. Test fixtures (cryptographic vectors, recorded HTTP responses, sample files)
+   are committed alongside their tests. Where possible they are generated by
+   deterministic helpers in the `test/` tree so any reviewer can reproduce them
+   by running the helper.
+7. `git rebase -i` is allowed on a feature branch before merge to clean up the
+   test-then-implementation sequence into reviewable commits, but the final
+   history must still show tests landing before (or with) the matching
+   implementation.
+
 ## Design
 
 quack is a TypeScript library with a thin CLI wrapper. The library does the