I would like to move this to a separate `specification.md` (or badge_design.md if we have a separate api_design.md). Then just link some files up from the README.