Development¶
How Keryx is designed and built.
Specs (the source of truth)¶
| Spec | Status | What |
|---|---|---|
| 0001 — design | Intent | Purpose, port plan, posting research, providers, themes, authoring loop, persistence, roadmap. |
| 0002 — interface contracts | Intent | CLI + web UI + MCP contracts; the R-* requirements that anchor the tests. |
| 0003 — video panels | Deferred | The "video-shaped hole" — generated/uploaded video panels. |
| 0004 — long-form & capture | Future | Longer-form pieces + in-browser capture; the editing ceiling. |
New non-trivial work starts with a spec (docs/development/specs/NNNN-<feature>.md,
status DRAFT) — see the lifecycle in CLAUDE.md.
Ways of working¶
- TDD + BDD. Unit-test the deterministic core; godog
.featurescenarios for user-facing workflows. Providers + ffmpeg are faked behind interfaces. → spec §8 - Conventional Commits, releaser-pleaser cuts releases; no AI attribution.
- Quality at the MR gate via the
phpboyscout/cicdcomponents.
UI mockup¶
A clickable, non-functional prototype of the studio — built to validate the
web-UI contract (§4) and surface gaps before
implementation: mockups/studio/index.html.
Reference implementation¶
The blog's scripts/gen-*.py are the parity reference for generation behaviour;
Phase 1 ports them faithfully to Go.