diff --git a/spec/00-utils_spec.lua b/spec/01-utils_spec.lua
similarity index 100%
rename from spec/00-utils_spec.lua
rename to spec/01-utils_spec.lua
diff --git a/spec/00-utils_truncate_ellipsis_spec.lua b/spec/01-utils_truncate_ellipsis_spec.lua
similarity index 100%
rename from spec/00-utils_truncate_ellipsis_spec.lua
rename to spec/01-utils_truncate_ellipsis_spec.lua
diff --git a/spec/00-utils_utf8sub_col_spec.lua b/spec/01-utils_utf8sub_col_spec.lua
similarity index 100%
rename from spec/00-utils_utf8sub_col_spec.lua
rename to spec/01-utils_utf8sub_col_spec.lua
diff --git a/spec/00-utils_utf8sub_spec.lua b/spec/01-utils_utf8sub_spec.lua
similarity index 100%
rename from spec/00-utils_utf8sub_spec.lua
rename to spec/01-utils_utf8sub_spec.lua
diff --git a/spec/01-sequence_spec.lua b/spec/02-sequence_spec.lua
similarity index 100%
rename from spec/01-sequence_spec.lua
rename to spec/02-sequence_spec.lua
diff --git a/spec/09-editline-format_spec.lua b/spec/03-editline-format_spec.lua
similarity index 100%
rename from spec/09-editline-format_spec.lua
rename to spec/03-editline-format_spec.lua
diff --git a/spec/09-editline_spec.lua b/spec/03-editline_spec.lua
similarity index 100%
rename from spec/09-editline_spec.lua
rename to spec/03-editline_spec.lua
diff --git a/spec/02-input_spec.lua b/spec/04-input_spec.lua
similarity index 100%
rename from spec/02-input_spec.lua
rename to spec/04-input_spec.lua
diff --git a/spec/02a-keymap_spec.lua b/spec/05-keymap_spec.lua
similarity index 100%
rename from spec/02a-keymap_spec.lua
rename to spec/05-keymap_spec.lua
diff --git a/spec/03-clear_spec.lua b/spec/06-clear_spec.lua
similarity index 100%
rename from spec/03-clear_spec.lua
rename to spec/06-clear_spec.lua
diff --git a/spec/04-scroll_spec.lua b/spec/07-scroll_spec.lua
similarity index 100%
rename from spec/04-scroll_spec.lua
rename to spec/07-scroll_spec.lua
diff --git a/spec/05-scroll_stack_spec.lua b/spec/08-scroll_stack_spec.lua
similarity index 100%
rename from spec/05-scroll_stack_spec.lua
rename to spec/08-scroll_stack_spec.lua
diff --git a/spec/06-cursor_spec.lua b/spec/09-cursor_spec.lua
similarity index 100%
rename from spec/06-cursor_spec.lua
rename to spec/09-cursor_spec.lua
diff --git a/spec/07-color_spec.lua b/spec/10-color_spec.lua
similarity index 100%
rename from spec/07-color_spec.lua
rename to spec/10-color_spec.lua
diff --git a/spec/08-attr_spec.lua b/spec/11-attr_spec.lua
similarity index 100%
rename from spec/08-attr_spec.lua
rename to spec/11-attr_spec.lua
diff --git a/spec/10-panel_spec.lua b/spec/20-panel_spec.lua
similarity index 100%
rename from spec/10-panel_spec.lua
rename to spec/20-panel_spec.lua
diff --git a/spec/11-screen_spec.lua b/spec/21-screen_spec.lua
similarity index 100%
rename from spec/11-screen_spec.lua
rename to spec/21-screen_spec.lua
diff --git a/spec/13-bar_spec.lua b/spec/23-bar_spec.lua
similarity index 100%
rename from spec/13-bar_spec.lua
rename to spec/23-bar_spec.lua
diff --git a/spec/14-text_panel_spec.lua b/spec/24-text_panel_spec.lua
similarity index 100%
rename from spec/14-text_panel_spec.lua
rename to spec/24-text_panel_spec.lua
diff --git a/spec/15-key_bar_spec.lua b/spec/25-key_bar_spec.lua
similarity index 100%
rename from spec/15-key_bar_spec.lua
rename to spec/25-key_bar_spec.lua
diff --git a/spec/16-set_spec.lua b/spec/26-set_spec.lua
similarity index 100%
rename from spec/16-set_spec.lua
rename to spec/26-set_spec.lua
diff --git a/spec/17-tab_strip_spec.lua b/spec/27-tab_strip_spec.lua
similarity index 100%
rename from spec/17-tab_strip_spec.lua
rename to spec/27-tab_strip_spec.lua
diff --git a/spec/18-prompt_spec.lua b/spec/50-prompt_spec.lua
similarity index 100%
rename from spec/18-prompt_spec.lua
rename to spec/50-prompt_spec.lua
diff --git a/spec/README.md b/spec/README.md
new file mode 100644
index 00000000..e8480853
--- /dev/null
+++ b/spec/README.md
@@ -0,0 +1,19 @@
+# Test organization
+
+Tests are numbered for deterministic ordering when running. Ordered from fundamentals to more higher level. Specific domains are organizaed in ranges.
+
+## numbering scheme
+
+
+
+- 00 is for the test helpers
+- 01 - 19 are for generic utilities used everywhere
+  - 01 is for utils
+  - 02 is for `Sequence` class
+  - 03 is for `EditLine` class
+  - from there the ANSI sequence generating modules (color, cursor, etc)
+- 20 - 49 are for the `ui` modules in `terminal.ui.*` range
+  - 20 is for `Panel` base class
+  - from there the derived modules
+- 50 - 79 are for the `cli` modules in `terminal.cli.*` range
+  - no particular order