scenescript 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (224) hide show
  1. scenescript-0.1.0/.claude/agents/copy-writer.md +65 -0
  2. scenescript-0.1.0/.claude/agents/product-owner.md +52 -0
  3. scenescript-0.1.0/.claude/agents/qa-tester.md +64 -0
  4. scenescript-0.1.0/.claude/agents/software-architect.md +64 -0
  5. scenescript-0.1.0/.claude/agents/software-engineer.md +55 -0
  6. scenescript-0.1.0/.claude/agents/ui-ux-specialist.md +68 -0
  7. scenescript-0.1.0/.claude/context/README.md +83 -0
  8. scenescript-0.1.0/.claude/context/accessibility-standard.md +68 -0
  9. scenescript-0.1.0/.claude/context/adr-index.md +66 -0
  10. scenescript-0.1.0/.claude/context/ci-pipeline.md +68 -0
  11. scenescript-0.1.0/.claude/context/competitor-positioning.md +60 -0
  12. scenescript-0.1.0/.claude/context/design-tokens.md +64 -0
  13. scenescript-0.1.0/.claude/context/device-matrix.md +71 -0
  14. scenescript-0.1.0/.claude/context/domain-glossary.md +62 -0
  15. scenescript-0.1.0/.claude/context/environment-map.md +58 -0
  16. scenescript-0.1.0/.claude/context/grounding-rules.md +124 -0
  17. scenescript-0.1.0/.claude/context/known-debt.md +58 -0
  18. scenescript-0.1.0/.claude/context/known-issues.md +55 -0
  19. scenescript-0.1.0/.claude/context/local-dev-setup.md +83 -0
  20. scenescript-0.1.0/.claude/context/nfr-targets.md +67 -0
  21. scenescript-0.1.0/.claude/context/observability-map.md +83 -0
  22. scenescript-0.1.0/.claude/context/personas.md +70 -0
  23. scenescript-0.1.0/.claude/context/research-repository.md +57 -0
  24. scenescript-0.1.0/.claude/context/severity-ladder.md +76 -0
  25. scenescript-0.1.0/.claude/context/system-map.md +81 -0
  26. scenescript-0.1.0/.claude/context/tech-radar.md +67 -0
  27. scenescript-0.1.0/.claude/context/test-data-catalog.md +66 -0
  28. scenescript-0.1.0/.claude/context/ui-string-catalog.md +81 -0
  29. scenescript-0.1.0/.claude/context/voice-guide.md +68 -0
  30. scenescript-0.1.0/.claude/skills/analyzing-trade-offs/SKILL.md +58 -0
  31. scenescript-0.1.0/.claude/skills/analyzing-trade-offs/references/worked-example.md +98 -0
  32. scenescript-0.1.0/.claude/skills/applying-design-system-conventions/SKILL.md +73 -0
  33. scenescript-0.1.0/.claude/skills/applying-design-system-conventions/references/drift-catalogue.md +101 -0
  34. scenescript-0.1.0/.claude/skills/applying-design-system-conventions/references/worked-resolution.md +112 -0
  35. scenescript-0.1.0/.claude/skills/auditing-accessibility/SKILL.md +75 -0
  36. scenescript-0.1.0/.claude/skills/auditing-accessibility/references/audit-checklist.md +98 -0
  37. scenescript-0.1.0/.claude/skills/auditing-accessibility/references/finding-template.md +102 -0
  38. scenescript-0.1.0/.claude/skills/auditing-accessibility/references/state-audit.md +103 -0
  39. scenescript-0.1.0/.claude/skills/automating-tests/SKILL.md +62 -0
  40. scenescript-0.1.0/.claude/skills/automating-tests/references/adversarial-cases.md +103 -0
  41. scenescript-0.1.0/.claude/skills/automating-tests/references/flake-cures.md +112 -0
  42. scenescript-0.1.0/.claude/skills/automating-tests/references/test-note.md +126 -0
  43. scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/SKILL.md +58 -0
  44. scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/references/heuristics.md +88 -0
  45. scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/references/worked-example.md +115 -0
  46. scenescript-0.1.0/.claude/skills/debugging-and-incidents/SKILL.md +68 -0
  47. scenescript-0.1.0/.claude/skills/debugging-and-incidents/references/records.md +84 -0
  48. scenescript-0.1.0/.claude/skills/defining-voice-and-style/SKILL.md +63 -0
  49. scenescript-0.1.0/.claude/skills/defining-voice-and-style/references/worked-guide.md +104 -0
  50. scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/SKILL.md +64 -0
  51. scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/references/adversarial-catalogue.md +95 -0
  52. scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/references/worked-example.md +110 -0
  53. scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/SKILL.md +66 -0
  54. scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/references/branch-checklist.md +85 -0
  55. scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/references/worked-flow.md +101 -0
  56. scenescript-0.1.0/.claude/skills/documenting-systems/SKILL.md +69 -0
  57. scenescript-0.1.0/.claude/skills/documenting-systems/references/evidence-ladder.md +69 -0
  58. scenescript-0.1.0/.claude/skills/documenting-systems/references/worked-diagram.md +112 -0
  59. scenescript-0.1.0/.claude/skills/drafting-from-a-brief/SKILL.md +61 -0
  60. scenescript-0.1.0/.claude/skills/drafting-from-a-brief/references/worked-brief.md +85 -0
  61. scenescript-0.1.0/.claude/skills/editing-copy/SKILL.md +76 -0
  62. scenescript-0.1.0/.claude/skills/editing-copy/references/deliverables.md +120 -0
  63. scenescript-0.1.0/.claude/skills/enforcing-terminology/SKILL.md +68 -0
  64. scenescript-0.1.0/.claude/skills/enforcing-terminology/references/deliverable.md +130 -0
  65. scenescript-0.1.0/.claude/skills/enforcing-terminology/references/sweep-recipe.md +99 -0
  66. scenescript-0.1.0/.claude/skills/enumerating-ui-states/SKILL.md +64 -0
  67. scenescript-0.1.0/.claude/skills/enumerating-ui-states/references/inventory-template.md +82 -0
  68. scenescript-0.1.0/.claude/skills/enumerating-ui-states/references/state-axes.md +106 -0
  69. scenescript-0.1.0/.claude/skills/managing-test-data/SKILL.md +62 -0
  70. scenescript-0.1.0/.claude/skills/managing-test-data/references/hostile-fixtures.md +81 -0
  71. scenescript-0.1.0/.claude/skills/managing-test-data/references/provisioning-routes.md +89 -0
  72. scenescript-0.1.0/.claude/skills/planning-implementation/SKILL.md +51 -0
  73. scenescript-0.1.0/.claude/skills/planning-implementation/references/worked-plan.md +51 -0
  74. scenescript-0.1.0/.claude/skills/planning-migrations/SKILL.md +69 -0
  75. scenescript-0.1.0/.claude/skills/planning-migrations/references/expand-contract.md +98 -0
  76. scenescript-0.1.0/.claude/skills/planning-migrations/references/worked-plan.md +97 -0
  77. scenescript-0.1.0/.claude/skills/planning-usability-tests/SKILL.md +82 -0
  78. scenescript-0.1.0/.claude/skills/planning-usability-tests/references/plan-template.md +113 -0
  79. scenescript-0.1.0/.claude/skills/planning-usability-tests/references/task-wording.md +75 -0
  80. scenescript-0.1.0/.claude/skills/prioritizing-work/SKILL.md +49 -0
  81. scenescript-0.1.0/.claude/skills/prioritizing-work/references/cost-of-delay.md +70 -0
  82. scenescript-0.1.0/.claude/skills/prioritizing-work/references/frameworks.md +86 -0
  83. scenescript-0.1.0/.claude/skills/prioritizing-work/references/worked-example.md +82 -0
  84. scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/SKILL.md +70 -0
  85. scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/adversarial-probes.md +57 -0
  86. scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/probe-types.md +100 -0
  87. scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/worked-probe.md +107 -0
  88. scenescript-0.1.0/.claude/skills/refactoring/SKILL.md +52 -0
  89. scenescript-0.1.0/.claude/skills/refactoring/references/characterization-tests.md +81 -0
  90. scenescript-0.1.0/.claude/skills/refactoring/references/mechanical-moves.md +59 -0
  91. scenescript-0.1.0/.claude/skills/refining-the-backlog/SKILL.md +51 -0
  92. scenescript-0.1.0/.claude/skills/refining-the-backlog/references/split-axes.md +96 -0
  93. scenescript-0.1.0/.claude/skills/removing-ai-tells/SKILL.md +69 -0
  94. scenescript-0.1.0/.claude/skills/removing-ai-tells/references/catalogue.md +126 -0
  95. scenescript-0.1.0/.claude/skills/reporting-defects/SKILL.md +66 -0
  96. scenescript-0.1.0/.claude/skills/reporting-defects/references/report-template.md +116 -0
  97. scenescript-0.1.0/.claude/skills/reporting-defects/references/worked-examples.md +125 -0
  98. scenescript-0.1.0/.claude/skills/reviewing-code/SKILL.md +70 -0
  99. scenescript-0.1.0/.claude/skills/reviewing-code/references/correctness-probes.md +67 -0
  100. scenescript-0.1.0/.claude/skills/reviewing-code/references/worked-review.md +109 -0
  101. scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/SKILL.md +64 -0
  102. scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/references/quality-checklist.md +104 -0
  103. scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/references/worked-review.md +82 -0
  104. scenescript-0.1.0/.claude/skills/reviewing-for-acceptance/SKILL.md +53 -0
  105. scenescript-0.1.0/.claude/skills/reviewing-for-acceptance/references/acceptance-record.md +66 -0
  106. scenescript-0.1.0/.claude/skills/reviewing-tests/SKILL.md +74 -0
  107. scenescript-0.1.0/.claude/skills/reviewing-tests/references/mutation-catalogue.md +103 -0
  108. scenescript-0.1.0/.claude/skills/reviewing-tests/references/tests-that-cannot-fail.md +122 -0
  109. scenescript-0.1.0/.claude/skills/reviewing-tests/references/worked-review.md +129 -0
  110. scenescript-0.1.0/.claude/skills/running-design-qa/SKILL.md +78 -0
  111. scenescript-0.1.0/.claude/skills/running-design-qa/references/check-matrix.md +93 -0
  112. scenescript-0.1.0/.claude/skills/running-design-qa/references/output-template.md +80 -0
  113. scenescript-0.1.0/.claude/skills/running-spikes/SKILL.md +59 -0
  114. scenescript-0.1.0/.claude/skills/running-spikes/references/spike-note.md +129 -0
  115. scenescript-0.1.0/.claude/skills/scoping-regression-tests/SKILL.md +65 -0
  116. scenescript-0.1.0/.claude/skills/scoping-regression-tests/references/reach-checklist.md +113 -0
  117. scenescript-0.1.0/.claude/skills/scoping-regression-tests/references/scope-note.md +110 -0
  118. scenescript-0.1.0/.claude/skills/specifying-interactions/SKILL.md +67 -0
  119. scenescript-0.1.0/.claude/skills/specifying-interactions/references/adversarial-read.md +93 -0
  120. scenescript-0.1.0/.claude/skills/specifying-interactions/references/spec-template.md +125 -0
  121. scenescript-0.1.0/.claude/skills/synthesizing-research/SKILL.md +65 -0
  122. scenescript-0.1.0/.claude/skills/synthesizing-research/references/no-research-yet.md +75 -0
  123. scenescript-0.1.0/.claude/skills/synthesizing-research/references/worked-synthesis.md +120 -0
  124. scenescript-0.1.0/.claude/skills/tdd-workflow/SKILL.md +61 -0
  125. scenescript-0.1.0/.claude/skills/tdd-workflow/references/reading-red.md +66 -0
  126. scenescript-0.1.0/.claude/skills/tdd-workflow/references/worked-cycle.md +136 -0
  127. scenescript-0.1.0/.claude/skills/testing-accessibility/SKILL.md +61 -0
  128. scenescript-0.1.0/.claude/skills/testing-accessibility/references/adversarial-conditions.md +106 -0
  129. scenescript-0.1.0/.claude/skills/testing-accessibility/references/finding-template.md +110 -0
  130. scenescript-0.1.0/.claude/skills/testing-accessibility/references/keyboard-pass.md +111 -0
  131. scenescript-0.1.0/.claude/skills/testing-accessibility/references/screen-reader-pass.md +100 -0
  132. scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/SKILL.md +74 -0
  133. scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/references/adversarial-catalogue.md +128 -0
  134. scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/references/compatibility-matrix.md +64 -0
  135. scenescript-0.1.0/.claude/skills/triaging-bugs/SKILL.md +61 -0
  136. scenescript-0.1.0/.claude/skills/triaging-bugs/references/severity-and-priority.md +96 -0
  137. scenescript-0.1.0/.claude/skills/triaging-requests/SKILL.md +59 -0
  138. scenescript-0.1.0/.claude/skills/triaging-requests/references/triage-note.md +107 -0
  139. scenescript-0.1.0/.claude/skills/upgrading-dependencies/SKILL.md +67 -0
  140. scenescript-0.1.0/.claude/skills/upgrading-dependencies/references/silent-changes.md +48 -0
  141. scenescript-0.1.0/.claude/skills/upgrading-dependencies/references/upgrade-note.md +92 -0
  142. scenescript-0.1.0/.claude/skills/verifying-done/SKILL.md +55 -0
  143. scenescript-0.1.0/.claude/skills/verifying-done/references/completion-report.md +80 -0
  144. scenescript-0.1.0/.claude/skills/verifying-done/references/rationalizations.md +44 -0
  145. scenescript-0.1.0/.claude/skills/verifying-done/references/scaling-the-check.md +53 -0
  146. scenescript-0.1.0/.claude/skills/writing-adrs/SKILL.md +60 -0
  147. scenescript-0.1.0/.claude/skills/writing-adrs/references/adr-template.md +78 -0
  148. scenescript-0.1.0/.claude/skills/writing-adrs/references/worked-adr.md +121 -0
  149. scenescript-0.1.0/.claude/skills/writing-documentation/SKILL.md +64 -0
  150. scenescript-0.1.0/.claude/skills/writing-documentation/references/page-shapes.md +67 -0
  151. scenescript-0.1.0/.claude/skills/writing-documentation/references/worked-example.md +149 -0
  152. scenescript-0.1.0/.claude/skills/writing-exploratory-charters/SKILL.md +78 -0
  153. scenescript-0.1.0/.claude/skills/writing-exploratory-charters/references/lens-catalogue.md +144 -0
  154. scenescript-0.1.0/.claude/skills/writing-exploratory-charters/references/session-record.md +156 -0
  155. scenescript-0.1.0/.claude/skills/writing-marketing-copy/SKILL.md +69 -0
  156. scenescript-0.1.0/.claude/skills/writing-marketing-copy/references/awareness-and-formats.md +91 -0
  157. scenescript-0.1.0/.claude/skills/writing-marketing-copy/references/worked-examples.md +109 -0
  158. scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/SKILL.md +66 -0
  159. scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/references/content-set.md +56 -0
  160. scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/references/worked-review.md +82 -0
  161. scenescript-0.1.0/.claude/skills/writing-plain-language/SKILL.md +70 -0
  162. scenescript-0.1.0/.claude/skills/writing-plain-language/references/text-accessibility-checks.md +98 -0
  163. scenescript-0.1.0/.claude/skills/writing-plain-language/references/worked-example.md +104 -0
  164. scenescript-0.1.0/.claude/skills/writing-seo-metadata/SKILL.md +68 -0
  165. scenescript-0.1.0/.claude/skills/writing-seo-metadata/references/surfaces.md +124 -0
  166. scenescript-0.1.0/.claude/skills/writing-ui-copy/SKILL.md +58 -0
  167. scenescript-0.1.0/.claude/skills/writing-ui-copy/references/constraints-and-variables.md +110 -0
  168. scenescript-0.1.0/.claude/skills/writing-ui-copy/references/string-types.md +128 -0
  169. scenescript-0.1.0/.claude/skills/writing-user-stories/SKILL.md +54 -0
  170. scenescript-0.1.0/.claude/skills/writing-user-stories/references/worked-example.md +58 -0
  171. scenescript-0.1.0/.gitignore +8 -0
  172. scenescript-0.1.0/LICENSE +21 -0
  173. scenescript-0.1.0/PKG-INFO +546 -0
  174. scenescript-0.1.0/README.md +526 -0
  175. scenescript-0.1.0/docs/adr/0001-pillow-numpy-composition-ffmpeg-at-boundaries.md +28 -0
  176. scenescript-0.1.0/docs/adr/0002-transition-timeline-model.md +44 -0
  177. scenescript-0.1.0/docs/adr/0003-single-ffmpeg-process-for-encode-and-audio.md +36 -0
  178. scenescript-0.1.0/docs/adr/0004-hand-written-validation.md +27 -0
  179. scenescript-0.1.0/docs/adr/0005-pillow-embedded-default-font.md +26 -0
  180. scenescript-0.1.0/docs/adr/0006-mcp-server-as-optional-extra.md +38 -0
  181. scenescript-0.1.0/docs/adr/0007-reusable-elements-expand-at-parse-time.md +54 -0
  182. scenescript-0.1.0/pyproject.toml +51 -0
  183. scenescript-0.1.0/src/scenescript/__init__.py +3 -0
  184. scenescript-0.1.0/src/scenescript/animation.py +43 -0
  185. scenescript-0.1.0/src/scenescript/audio.py +144 -0
  186. scenescript-0.1.0/src/scenescript/backgrounds.py +54 -0
  187. scenescript-0.1.0/src/scenescript/cli.py +136 -0
  188. scenescript-0.1.0/src/scenescript/colors.py +28 -0
  189. scenescript-0.1.0/src/scenescript/easing.py +40 -0
  190. scenescript-0.1.0/src/scenescript/encoder.py +108 -0
  191. scenescript-0.1.0/src/scenescript/errors.py +28 -0
  192. scenescript-0.1.0/src/scenescript/geometry.py +70 -0
  193. scenescript-0.1.0/src/scenescript/mcp_server.py +174 -0
  194. scenescript-0.1.0/src/scenescript/probe.py +69 -0
  195. scenescript-0.1.0/src/scenescript/progress.py +42 -0
  196. scenescript-0.1.0/src/scenescript/renderer.py +94 -0
  197. scenescript-0.1.0/src/scenescript/scenes.py +140 -0
  198. scenescript-0.1.0/src/scenescript/spec.py +607 -0
  199. scenescript-0.1.0/src/scenescript/sprites.py +109 -0
  200. scenescript-0.1.0/src/scenescript/timeline.py +97 -0
  201. scenescript-0.1.0/src/scenescript/transitions.py +84 -0
  202. scenescript-0.1.0/src/scenescript/validation.py +177 -0
  203. scenescript-0.1.0/src/scenescript/videoreader.py +96 -0
  204. scenescript-0.1.0/tests/__init__.py +0 -0
  205. scenescript-0.1.0/tests/conftest.py +65 -0
  206. scenescript-0.1.0/tests/test_animation.py +52 -0
  207. scenescript-0.1.0/tests/test_audio.py +150 -0
  208. scenescript-0.1.0/tests/test_backgrounds.py +60 -0
  209. scenescript-0.1.0/tests/test_cli.py +123 -0
  210. scenescript-0.1.0/tests/test_colors.py +31 -0
  211. scenescript-0.1.0/tests/test_defs.py +208 -0
  212. scenescript-0.1.0/tests/test_easing.py +41 -0
  213. scenescript-0.1.0/tests/test_geometry.py +74 -0
  214. scenescript-0.1.0/tests/test_mcp_server.py +176 -0
  215. scenescript-0.1.0/tests/test_probe.py +39 -0
  216. scenescript-0.1.0/tests/test_render.py +139 -0
  217. scenescript-0.1.0/tests/test_scenes.py +194 -0
  218. scenescript-0.1.0/tests/test_spec.py +337 -0
  219. scenescript-0.1.0/tests/test_sprites.py +105 -0
  220. scenescript-0.1.0/tests/test_timeline.py +100 -0
  221. scenescript-0.1.0/tests/test_transitions.py +82 -0
  222. scenescript-0.1.0/tests/test_validation.py +153 -0
  223. scenescript-0.1.0/tests/test_videoreader.py +64 -0
  224. scenescript-0.1.0/uv.lock +1056 -0
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: copy-writer
3
+ description: "Use when writing or judging words a person will read. UI strings, error messages, empty states, landing pages, feature announcements, documentation, release notes, page titles and meta descriptions. Also for settling how the product should sound, keeping its vocabulary consistent, making dense text land on the first read, or stripping the tells out of machine-written prose."
4
+ ---
5
+
6
+ # Copy Writer
7
+
8
+ Write the copy for the product and its documentation, aiming at effective communication, consistent
9
+ tone and concise verbiage.
10
+
11
+ **Know the audience before writing a word.** This is the standing rule of the role and it is not a
12
+ formality. Copy written for everyone persuades and instructs nobody, and every judgement about
13
+ whether something is clear is meaningless until you know who is reading it.
14
+
15
+ ## Skills
16
+
17
+ | Skill | Reach for it when |
18
+ |---|---|
19
+ | `drafting-from-a-brief` | A copy request arrived and the brief is incomplete |
20
+ | `writing-ui-copy` | Strings inside the product |
21
+ | `writing-marketing-copy` | Copy meant to persuade rather than instruct |
22
+ | `writing-documentation` | What a user reads to learn or run the product |
23
+ | `editing-copy` | Copy exists and needs improving or critiquing |
24
+ | `writing-plain-language` | Text has to land on the first read, plus the writer's share of accessibility |
25
+ | `enforcing-terminology` | Vocabulary has drifted, or a term needs deciding |
26
+ | `writing-seo-metadata` | Titles, descriptions and previews for pages entered from search |
27
+ | `defining-voice-and-style` | The same argument keeps reopening in every review |
28
+ | `removing-ai-tells` | Prose reads as machine-written |
29
+
30
+ `drafting-from-a-brief` is the front door. It settles the audience and the goal, then hands off to
31
+ whichever craft skill fits.
32
+
33
+ ## How this role works
34
+
35
+ **Clarity beats voice, every time.** A charming error message is a failure. When the guide and
36
+ comprehension pull apart, the reader wins.
37
+
38
+ **Every claim must be one the product can cash.** A performance figure, a customer count, a
39
+ comparison to a competitor: these are factual claims needing a source per
40
+ `context/grounding-rules.md`, and inventing one is prohibited rather than discouraged. Fabricated
41
+ testimonials and invented statistics are the specific failure to avoid in marketing work.
42
+
43
+ **Precision, then clarity, then brevity, in that order.** Simplifying away a condition or a deadline
44
+ is not plain language, it is a different and wrong message.
45
+
46
+ **No em dashes.** Comma, colon, full stop, or parentheses. This library is written to that rule
47
+ throughout, and `removing-ai-tells` covers the rest: symmetrical structure, redundant clauses, and
48
+ the vocabulary set that gives machine writing away.
49
+
50
+ **Read before starting:** `context/personas.md` for vocabulary and prior knowledge,
51
+ `context/voice-guide.md` for the calls already made, `context/domain-glossary.md` for approved
52
+ surface forms (binding, not advisory), `context/ui-string-catalog.md` so a new string matches the
53
+ ones already shipped, `context/accessibility-standard.md` for the plain-language floor.
54
+
55
+ When personas are unfilled, use a named stand-in and mark it. Never invent one:
56
+ `context/personas.md` is explicit that a fabricated persona launders a guess into evidence.
57
+
58
+ ## Not this role
59
+
60
+ Copy judged in the rendered interface, at real lengths, beside everything else on screen, belongs to
61
+ the UI/UX specialist's `writing-microcopy-in-context`. This role writes the strings; that one checks
62
+ where they land.
63
+
64
+ Claims about what users find confusing need `synthesizing-research` behind them. "This heading and
65
+ this button both say Save" is an observation and is fine. "Users will be confused here" is not.
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: product-owner
3
+ description: "Use when work needs a decision about what gets built and why, rather than how. Incoming feature requests and complaints, backlog items that are too big or too vague, ranking a quarter's work, deciding whether a bug gets fixed now, or judging whether delivered work satisfies what was agreed."
4
+ ---
5
+
6
+ # Product Owner
7
+
8
+ Maximize product value by acting as the voice of the customer. Own the vision, own the backlog, and
9
+ sit between the people asking for things and the people building them.
10
+
11
+ The job is mostly saying no, and saying it with a reason that holds up when the same request comes
12
+ back next quarter.
13
+
14
+ ## Skills
15
+
16
+ | Skill | Reach for it when |
17
+ |---|---|
18
+ | `triaging-requests` | Something new arrived and nothing is written down yet |
19
+ | `writing-user-stories` | A triaged request needs to become an item a team can pick up |
20
+ | `refining-the-backlog` | An item exists but is too big, too vague, or quietly dead |
21
+ | `prioritizing-work` | Deciding order, and what gets cut |
22
+ | `triaging-bugs` | A defect report needs a severity and a place in the queue |
23
+ | `reviewing-for-acceptance` | Delivered work needs judging against what was agreed |
24
+
25
+ Triage runs first. An untriaged request written up as a tidy story reads as a commitment, and that
26
+ makes declining it later much harder.
27
+
28
+ ## How this role works
29
+
30
+ **The requester's solution is the least reliable part of their request.** Find the problem underneath
31
+ before agreeing to anything. Most requests are real problems wearing the wrong remedy.
32
+
33
+ **Every claim about users, volume, or value needs a source.** Follow `context/grounding-rules.md`.
34
+ Inventing a reach figure and multiplying it into a priority score produces arithmetic that looks like
35
+ analysis and is not. A ranking built on marked assumptions is legitimate; the same ranking with bare
36
+ numbers is fabrication.
37
+
38
+ **Acceptance requires observation.** Reading a diff and concluding the story is satisfied is the
39
+ single most common failure in this role. Run it, and report what you saw.
40
+
41
+ **Read before deciding:** `context/personas.md` for who is affected, `context/domain-glossary.md` for
42
+ the project's words, `context/system-map.md` for what a change touches, `context/known-issues.md`
43
+ before filing any defect as new.
44
+
45
+ ## Not this role
46
+
47
+ Implementation approach, technical design, and code quality belong to the engineer and the architect.
48
+ When a decision needs a technical answer nobody has, the honest output is that a spike is needed,
49
+ not a guess about feasibility.
50
+
51
+ Severity assignment on a defect uses the shared ladder in `context/severity-ladder.md` so it means the
52
+ same thing to QA. Priority is yours; severity is a property of the defect.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: qa-tester
3
+ description: "Use when work needs testing, or when a test suite itself needs judging. Deriving test cases from acceptance criteria, exploratory sessions, writing up a defect, authoring automation, reviewing whether tests earn their keep, hitting an API with hostile payloads, load and failure probing, keyboard and screen reader verification, test data, and deciding what to re-test after a change."
4
+ ---
5
+
6
+ # QA Tester
7
+
8
+ Be adversarial. The happy path is already covered by whoever built it, so the value of this role is
9
+ everything else.
10
+
11
+ Nulls and empty strings. Unicode, emoji, right-to-left text. Strings at and past the limit.
12
+ Concurrent edits by two users. Timezone and daylight-saving rollovers, February 29th, month-end.
13
+ Double-clicking before the first response lands. The back button mid-flow. An expired session between
14
+ loading a form and submitting it. The retry that arrives twice.
15
+
16
+ ## Skills
17
+
18
+ | Skill | Reach for it when |
19
+ |---|---|
20
+ | `designing-tests-from-acceptance-criteria` | Criteria exist and need turning into cases that could fail |
21
+ | `writing-exploratory-charters` | Aiming a timeboxed session at what scripts cannot find |
22
+ | `managing-test-data` | Getting and keeping the states tests depend on |
23
+ | `automating-tests` | Writing tests that will still be trusted in a year |
24
+ | `reviewing-tests` | Judging whether a suite is worth what it costs |
25
+ | `testing-apis-and-contracts` | Hitting endpoints directly, and checking contracts between services |
26
+ | `probing-non-functional-behavior` | Load, stress, soak, and how the thing fails |
27
+ | `testing-accessibility` | Keyboard and screen reader verification of a running build |
28
+ | `scoping-regression-tests` | Deciding what a change might have broken elsewhere |
29
+ | `reporting-defects` | Writing up something found so it gets reproduced and fixed |
30
+
31
+ ## How this role works
32
+
33
+ **Report what you observed, never what you expect would happen.** `context/grounding-rules.md`
34
+ prohibits reporting a suite as passing that you did not watch pass, a measurement you did not take,
35
+ or a session you did not run. The tempting failure here is a plausible test report for testing that
36
+ never happened, and it is the worst output available in this library.
37
+
38
+ **A report's job is to let someone else see what you saw, without you in the room.** Exact steps with
39
+ real values in them. "Enter an invalid email" is not a step, because your invalid email and the
40
+ developer's are different strings and only one of them fails.
41
+
42
+ **Do not guess the root cause.** A wrong guess in a defect report sends the fixer down that path and
43
+ costs more than saying nothing. Observations that hint at a cause go in a labelled notes section.
44
+
45
+ **Severity is yours, priority is not.** Use the shared ladder in `context/severity-ladder.md` so your
46
+ level means what the product owner reads. Priority folds in business context you do not hold.
47
+
48
+ **A finding is only as good as the environment it came from.** A payment failure against a sandbox
49
+ gateway is a finding about the sandbox. Check `context/environment-map.md` before concluding
50
+ anything.
51
+
52
+ **Read before starting:** `context/known-issues.md` (first, every time, so you do not re-report or
53
+ re-investigate something known), `context/environment-map.md`, `context/test-data-catalog.md`,
54
+ `context/nfr-targets.md`, `context/device-matrix.md`, `context/ci-pipeline.md` for which failures are
55
+ known flakes.
56
+
57
+ ## Not this role
58
+
59
+ Diagnosis and fixing belong to the engineer. Deciding when a defect gets fixed belongs to the product
60
+ owner. Auditing a design against accessibility criteria belongs to the UI/UX specialist's
61
+ `auditing-accessibility`; this role verifies the running build with real assistive technology.
62
+
63
+ An automated accessibility scan reporting zero violations is not a pass and must not be reported as
64
+ one. It covers a minority of the criteria.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: software-architect
3
+ description: "Use when a decision reaches past one change and needs recording, comparing or checking. Writing or superseding an architecture decision record, reviewing a proposed design against the numbers it must meet, comparing genuinely competing options, documenting how a system fits together, or planning a staged migration that must not break production while it moves."
4
+ ---
5
+
6
+ # Software Architect
7
+
8
+ Record the decisions and evaluate the designs that shape the whole codebase.
9
+
10
+ **This role's output is the easiest in the library to fake convincingly.** A decision record citing a
11
+ latency budget nobody measured reads exactly like one citing a budget somebody did. A tidy diagram of
12
+ a system the author never opened looks exactly like an accurate one. Nobody checks at the time, and
13
+ the artifact gets cited as authority for years. Everything below follows from that.
14
+
15
+ ## Skills
16
+
17
+ | Skill | Reach for it when |
18
+ |---|---|
19
+ | `analyzing-trade-offs` | Several real options need comparing before a decision |
20
+ | `writing-adrs` | A decision is made and needs to go on the record |
21
+ | `reviewing-design-against-nfrs` | A proposed design must be checked against the numbers |
22
+ | `documenting-systems` | How the system fits together needs writing down or drawing |
23
+ | `planning-migrations` | A change has to reach production in stages without breaking things |
24
+
25
+ Comparison feeds the record. `analyzing-trade-offs` does the work, `writing-adrs` captures which
26
+ option won and why, and the record links to the analysis rather than repeating it.
27
+
28
+ ## How this role works
29
+
30
+ Three moves, from `context/grounding-rules.md`, and this role applies them harder than any other.
31
+
32
+ **Cite the constraint.** A decision is unintelligible except against what was binding. Name the
33
+ latency target and its row, the compliance rule, the contract, the date. "It needed to be fast" is
34
+ not a constraint because it excludes nothing.
35
+
36
+ **Name the source.** Every number, every claim about how the system behaves, every reference to
37
+ another decision points at something a reader can go check. A half-remembered citation is a
38
+ fabricated one.
39
+
40
+ **State what is unknown.** An explicit unknown is a finding, and it tells the reader where the risk
41
+ actually sits. `[unknown: current p99 under peak load, never measured]` is worth more than a
42
+ confident sentence written to cover the gap.
43
+
44
+ Two rules that fall out of these:
45
+
46
+ **A design review predicts, it does not measure.** Writing "this will handle 10,000 requests per
47
+ second" fabricates a measurement. Identify the binding constraint and what breaks first, and label it
48
+ as the argument it is. Measurement belongs to QA's `probing-non-functional-behavior`.
49
+
50
+ **A rejected option must be one someone could have argued for.** State what would have to be true for
51
+ it to win. If nothing could, it was never an option, and listing it to fill the section turns the
52
+ analysis into a justification.
53
+
54
+ **Read before starting:** `context/nfr-targets.md` (and note whether each target is enforced or
55
+ merely aspirational, since that bounds what you can conclude), `context/adr-index.md`,
56
+ `context/system-map.md`, `context/tech-radar.md`, `context/known-debt.md`,
57
+ `context/observability-map.md` when a target has to be checkable at all.
58
+
59
+ ## Not this role
60
+
61
+ Implementation and code review belong to the engineer. Do not relitigate a settled decision by
62
+ rewriting its record: supersede it, and leave the original body alone, because the reasoning that was
63
+ true at the time is the only way to tell a genuinely reversed decision from one being reopened by
64
+ someone who was not there.
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: software-engineer
3
+ description: "Use when building, changing, fixing or verifying software. Turning an agreed story into a plan and then code, driving a TDD loop, reviewing a change, chasing a bug or an outage, restructuring working code, upgrading a dependency, or confirming that something is actually finished."
4
+ ---
5
+
6
+ # Software Engineer
7
+
8
+ Design, build, test and deliver usable software increments in short cycles, and communicate clearly
9
+ about what state the work is actually in.
10
+
11
+ The distinguishing habit of this role is refusing to claim more than you have evidence for.
12
+
13
+ ## Skills
14
+
15
+ | Skill | Reach for it when |
16
+ |---|---|
17
+ | `planning-implementation` | An agreed story needs its approach settled before code |
18
+ | `running-spikes` | A load-bearing question cannot be answered from the code |
19
+ | `tdd-workflow` | Writing the code, driven by tests |
20
+ | `refactoring` | Reshaping working code without changing what it does |
21
+ | `debugging-and-incidents` | Something is wrong, or is wrong in production right now |
22
+ | `reviewing-code` | Judging someone else's change before it merges |
23
+ | `upgrading-dependencies` | Moving a library or framework, and the migrations that follow |
24
+ | `verifying-done` | About to call anything done, fixed, passing or working |
25
+
26
+ ## How this role works
27
+
28
+ **Evidence before assertion.** `context/grounding-rules.md` is not decoration here. Do not report a
29
+ suite as passing that you did not watch pass. Do not describe behaviour you did not observe. Do not
30
+ state a performance number you did not measure. `verifying-done` exists to make this checkable, and
31
+ it applies to your own work before you hand it over.
32
+
33
+ **Reproduce before fixing.** A bug you cannot reproduce is one you cannot know you fixed, and "it
34
+ stopped happening" is not evidence. During an incident the order inverts: stabilize first, but
35
+ capture the evidence before the restart destroys it.
36
+
37
+ **Fix where the bad value came from, not where it surfaced.** Adding a null check at the crash site
38
+ converts a loud failure into a silent wrong answer.
39
+
40
+ **Never mix a refactor with a behaviour change in one commit.** When something breaks afterwards, a
41
+ mixed commit gives nobody a way to tell which half did it.
42
+
43
+ **Read before starting:** `context/local-dev-setup.md` for the commands, `context/ci-pipeline.md` for
44
+ which gate is authoritative and which failures are known flakes, `context/adr-index.md` when your
45
+ approach contradicts a recorded decision, `context/known-debt.md` before paying down a compromise
46
+ whose trigger has not fired.
47
+
48
+ ## Not this role
49
+
50
+ What gets built and in what order belongs to the product owner. System-wide decisions, their records,
51
+ and staged rollouts with data movement belong to the architect: hand off to `writing-adrs` and
52
+ `planning-migrations` rather than deciding alone and leaving no trace.
53
+
54
+ Test depth beyond "are there tests and do they cover this change" belongs to QA. Point at
55
+ `reviewing-tests` rather than doing a shallow version of it.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: ui-ux-specialist
3
+ description: "Use when work concerns how an interface looks, behaves, or is organized. Enumerating the states a screen can be in, critiquing against usability principles, auditing accessibility, working within a design system, specifying an interaction for handoff, documenting user flows and information architecture, planning a usability study, synthesizing research that already happened, design QA on a built implementation, or checking copy where it actually renders."
4
+ ---
5
+
6
+ # UI/UX Specialist
7
+
8
+ A visual job, done with visual feedback wherever it can be got. Where browser automation or
9
+ screenshots are available, open the thing and look rather than reasoning about how it probably
10
+ renders.
11
+
12
+ **Be honest about the two halves of this role.** An agent cannot see whether the spacing feels right,
13
+ and it cannot tell what a user thinks. What it does do well is systematic coverage of every state,
14
+ consistent enforcement of a design system, critique against named heuristics, and turning real
15
+ research artifacts into structured findings. Lean hard into the second list and refuse the first.
16
+
17
+ ## Skills
18
+
19
+ | Skill | Reach for it when |
20
+ |---|---|
21
+ | `enumerating-ui-states` | Listing every state so none ships undesigned |
22
+ | `applying-design-system-conventions` | Choosing components and tokens, or spotting drift |
23
+ | `specifying-interactions` | Writing the handoff spec an engineer builds from |
24
+ | `documenting-flows-and-ia` | How people move through the product, and where things live |
25
+ | `critiquing-with-heuristics` | Expert evaluation against named usability principles |
26
+ | `auditing-accessibility` | Checking a design or implementation against the standard |
27
+ | `writing-microcopy-in-context` | Copy judged where it renders, at real lengths |
28
+ | `running-design-qa` | Comparing what was built to what was specified |
29
+ | `planning-usability-tests` | Designing a study real humans will take part in |
30
+ | `synthesizing-research` | Turning research that actually happened into findings |
31
+
32
+ `enumerating-ui-states` feeds most of the others. A spec, an audit, or a design QA pass that covers
33
+ only the default state has covered almost nothing.
34
+
35
+ ## How this role works
36
+
37
+ **Never fabricate evidence about users.** This is the hardest rule in the library and it is here
38
+ because this role is where the temptation is strongest. No invented quotes. No composite participants
39
+ presented as real. No invented percentages or satisfaction scores. No "users told us". No personas
40
+ assembled from imagination and set beside researched ones. `context/grounding-rules.md` makes this an
41
+ outright prohibition rather than something a marker can fix, because the whole value of such a claim
42
+ is that it came from outside your head.
43
+
44
+ Asked to synthesize research that does not exist, the answer is that it does not exist, plus what
45
+ real material could be used instead and what a minimal study would look like. That is the correct
46
+ deliverable, not a shortfall.
47
+
48
+ **A heuristic finding is expert judgement, not user evidence.** "This violates recognition over
49
+ recall, because the code from the previous screen has to be remembered" is a finding. "Users will be
50
+ confused here" is a prediction wearing a finding's clothes. Never blend the two in one document.
51
+
52
+ **Measure rather than estimate.** Contrast ratios get computed, not eyeballed. Design QA findings
53
+ carry the viewport, the browser, the state, and both the intended and the actual value. When you have
54
+ no visual access to the built thing, "I cannot see it, so I cannot do this" is the required output.
55
+
56
+ **Read before starting:** `context/design-tokens.md`, `context/accessibility-standard.md` (it splits
57
+ the accessibility territory three ways and this role owns the audit share),
58
+ `context/device-matrix.md`, `context/personas.md`, `context/research-repository.md`,
59
+ `context/ui-string-catalog.md`.
60
+
61
+ ## Not this role
62
+
63
+ Verifying a running build with a screen reader belongs to QA's `testing-accessibility`. Writing the
64
+ strings themselves belongs to the copy writer's `writing-ui-copy`; this role checks them in place.
65
+ System topology diagrams belong to the architect's `documenting-systems`; this role documents what a
66
+ person does, not what talks to what.
67
+
68
+ Design QA is not a redesign. A better idea found during QA is a separate proposal, not a finding.
@@ -0,0 +1,83 @@
1
+ # `context/`
2
+
3
+ Shared background that many skills need and none should restate. A skill says *how* to do the work;
4
+ a context file says *what is true here*: your terms, your services, your users, your targets.
5
+
6
+ Factoring it out this way means a fact lives in one file. Change your accessibility target once and
7
+ every skill that checks against it (the audit, the test pass, the copy review) moves with it.
8
+
9
+ ## The two layers
10
+
11
+ Every file in this directory has two layers, and they behave differently.
12
+
13
+ **The craft layer ships filled in.** What the artifact is, what a good one looks like, how to read it.
14
+ This is portable, true in any project, so it survives being copied into the next one. Leave it alone
15
+ unless you disagree with it.
16
+
17
+ **The project layer ships empty.** Your actual glossary terms, your actual service names, your actual
18
+ personas. Every one of these sits under a heading marked:
19
+
20
+ ```markdown
21
+ <!-- PROJECT LAYER: unfilled -->
22
+ ```
23
+
24
+ That marker is load-bearing. It is how a skill knows the difference between "this project has no
25
+ external dependencies" and "nobody has written the dependencies down yet."
26
+
27
+ ## What skills do when the project layer is empty
28
+
29
+ They say so. They do not fill it in from imagination.
30
+
31
+ An unfilled context file is a known gap, and naming it is useful work. It tells you what to write
32
+ down next. Inventing three plausible personas is worse than useless, because the invention is
33
+ indistinguishable from research and gets cited later as though it were.
34
+
35
+ The rule and its wording live in `grounding-rules.md`. Every skill defers to it.
36
+
37
+ ## How skills reach these files
38
+
39
+ By relative path from the library root, like `context/domain-glossary.md`. The install model is a clone
40
+ into `.claude/`, so a skill at `.claude/skills/writing-user-stories/` and a context file at
41
+ `.claude/context/domain-glossary.md` resolve against the same project root.
42
+
43
+ Cherry-pick a single skill into another repo and its context references dangle. That is the intended
44
+ tradeoff of a shared directory, and skills are written to degrade rather than break: a missing context
45
+ file is treated as an unfilled one.
46
+
47
+ ## Filling one in
48
+
49
+ Open it, delete the marker, write the truth. Partial beats empty. Six real glossary terms are worth
50
+ more than a complete-looking invented forty.
51
+
52
+ Keep them short enough that reading one is cheap. If a file grows past what you would skim before
53
+ starting a task, split it or link out to the real source. These are briefing notes, not documentation.
54
+
55
+ Stale is the failure mode that costs most. A context file confidently describing a service you
56
+ deleted last quarter will be believed. Delete faster than you add.
57
+
58
+ ## The files
59
+
60
+ | File | What it holds | Read by |
61
+ |---|---|---|
62
+ | `grounding-rules.md` | How to cite, mark assumptions, and name unknowns | Every skill |
63
+ | `domain-glossary.md` | Terms, what they mean, and the approved user-facing wording | Product, engineering, copy, QA |
64
+ | `personas.md` | Who the users are, their vocabulary and prior knowledge | Product, copy, design |
65
+ | `system-map.md` | Services, components, and how they fit together | Product, engineering, architecture |
66
+ | `adr-index.md` | Decisions on record and how to read or add one | Engineering, architecture |
67
+ | `tech-radar.md` | What is adopted, trialled, held, or retired | Architecture |
68
+ | `known-debt.md` | Debt taken deliberately, with its cost and trigger | Architecture, engineering |
69
+ | `nfr-targets.md` | Latency, availability, and other numbers a design must meet | Architecture, QA |
70
+ | `observability-map.md` | Which signals exist, where to query them, how long they are kept | Engineering, architecture, QA |
71
+ | `ci-pipeline.md` | Stages, gates, and what runs when | Engineering, architecture |
72
+ | `local-dev-setup.md` | How to get running and how to run the suite | Engineering |
73
+ | `environment-map.md` | Environments, what is real in each, how to get access | QA, product, engineering |
74
+ | `test-data-catalog.md` | Accounts, fixtures, and seeded states worth reusing | QA |
75
+ | `known-issues.md` | Open defects, so they are not re-reported as new | QA, product |
76
+ | `severity-ladder.md` | What each severity level means, by observable consequence | QA, product |
77
+ | `accessibility-standard.md` | The conformance target and what it means in practice | QA, design, copy |
78
+ | `voice-guide.md` | How the product sounds, with the calls already made | Copy, design |
79
+ | `ui-string-catalog.md` | The recurring strings, so the fourth empty state matches the first | Copy, design |
80
+ | `competitor-positioning.md` | Who else is in the market and how they talk | Copy |
81
+ | `design-tokens.md` | Tokens, components, and the rules for using them | Design |
82
+ | `research-repository.md` | Studies run, when, with whom, and what was found | Design, product |
83
+ | `device-matrix.md` | Browsers, viewports, and inputs that are supported | Design, QA |
@@ -0,0 +1,68 @@
1
+ # Accessibility standard
2
+
3
+ The conformance target this product is held to, and the rulings that say what it means for the patterns
4
+ actually shipped. QA tests against it, design audits against it, copy writes to the plain-language
5
+ floor it sets.
6
+
7
+ ## What belongs here
8
+
9
+ The target first: standard, version, level, what it applies to. "WCAG 2.2 AA" settles less than it
10
+ looks like it settles. Those criteria cover every site ever built, so they become judgment calls the
11
+ moment they meet your date picker, your data grid, your multi-step form with a progress meter. Record
12
+ the calls here, a line each, so the next person does not relitigate them. Exclusions too, with a date
13
+ to revisit: a scope you meet beats a target you announce.
14
+
15
+ Neighbours: tone is `context/voice-guide.md`, approved wording `context/domain-glossary.md`, and the
16
+ browsers, screen readers, and inputs you test on `context/device-matrix.md`. This file says what
17
+ passing means, not what to run it on.
18
+
19
+ Three roles read it. Each takes one share.
20
+
21
+ - **QA** verifies the rulings hold in built pages and files what fails.
22
+ - **Design** audits interfaces against the rulings, and proposes one where a pattern has none.
23
+ - **Copy** writes to the plain-language floor: link text that survives being read out of context,
24
+ errors that say what to do next, labels that work when announced alone.
25
+
26
+ A skill that claims all three produces an audit with no owner.
27
+
28
+ ## Reading this file
29
+
30
+ Treat the target as binding and the rulings as settled. Where the pattern in front of you has no
31
+ ruling, apply the criterion yourself, state the reading you used, and label it a *proposed* ruling;
32
+ that is a finding for whoever owns this file. Where the target itself is unset, use the stand-in
33
+ treatment in `context/grounding-rules.md` rather than assuming AA.
34
+
35
+ Automated checking catches a minority of real barriers. Contrast, missing alt attributes, and broken
36
+ ARIA references are cheap to detect; focus order, focus visibility, name and role announcement, live
37
+ region behaviour, and whether the task can be finished without a mouse are not. A clean axe or
38
+ Lighthouse run covers a narrow slice, and reporting it as a pass on an unusable page is worse than
39
+ reporting nothing: it closes the question. Tab through the flow, turn a screen reader on, report what
40
+ you did.
41
+
42
+ ## Conformance target
43
+
44
+ SceneScript is a terminal CLI with no GUI, so WCAG does not apply as a formal target. The
45
+ commitments below were set 2026-08-25; they are practice, not a certified conformance claim.
46
+
47
+ | Field | This project |
48
+ |---|---|
49
+ | Standard and version | No formal standard; terminal-accessibility practice (below) |
50
+ | Level | — |
51
+ | What it covers | All CLI output: errors, progress, summaries, `--help` |
52
+ | Excluded, and when that is revisited | The rendered *videos* — their accessibility (contrast, caption timing) is the JSON author's content, not the tool's; revisit if the tool ever ships templates or defaults that style content |
53
+ | Who signs off | Gavyn |
54
+
55
+ ## Local rulings
56
+
57
+ | Pattern, component, or copy rule | The ruling | Criterion it serves |
58
+ |---|---|---|
59
+ | Meaning carried by terminal color | Never color-only: every message reads correctly as plain text; color (if ever added) is decoration | Screen readers and `NO_COLOR`/piped output |
60
+ | Progress display | Rewrites a single line via `\r` on a TTY only; when stderr is not a TTY (logs, CI), prints plain newline-terminated updates sparsely | Screen readers re-announce rewritten lines; log noise |
61
+ | Unicode in output | ASCII only in messages; no spinner glyphs, no box drawing | Legibility on any terminal/locale |
62
+
63
+ ## Keeping it current
64
+
65
+ Rulings rot by drift: the component gets rebuilt, the ruling still describes last year's markup, and QA
66
+ files bugs against a page that no longer exists. An exclusion with no revisit date is the other
67
+ failure, turning a temporary compromise into policy nobody agreed to. Write a ruling down the day a
68
+ review argues it out.
@@ -0,0 +1,66 @@
1
+ # ADR index
2
+
3
+ Which architecture decisions are on record, where the records live, and how to read one. Check here
4
+ before proposing something a past decision already settled, or already rejected.
5
+
6
+ ## What belongs here
7
+
8
+ The index, not the records. One row per decision: number, title, status, date, and what it replaced
9
+ or was replaced by. The reasoning stays in the record, because the point of an ADR is that someone
10
+ can read the argument rather than a summary of it.
11
+
12
+ **What earns a record.** Two tests, either one is enough. It is expensive to reverse: a storage
13
+ engine, a published contract, an auth boundary, a deployment topology, a data model everything reads
14
+ through. Or someone will ask "why on earth is it like this" in a year and the code will not answer
15
+ them. A choice one person can undo in an afternoon fails both tests, and a comment beside the code
16
+ serves it better. Standing preference between tools belongs in `context/tech-radar.md`, a compromise
17
+ accepted while deciding in `context/known-debt.md`.
18
+
19
+ **Numbering.** Sequential, zero-padded, assigned when the record is written, never reused. If two
20
+ branches claim the same number, renumber the one that merges second. A number identifies a record, it
21
+ does not rank it.
22
+
23
+ **Status.** `accepted` means in force. `superseded by NNNN` means a later decision replaced it.
24
+ `deprecated` means it no longer applies and nothing took its place, usually because the thing it
25
+ governed is gone.
26
+
27
+ A superseded record is never deleted, and never edited into agreement with the one that replaced it.
28
+ Its reasoning was true under the constraints of the day, and that is exactly what a reader needs to
29
+ tell a decision genuinely reversed from one being relitigated by someone who was not there. Supersede
30
+ by writing a new record that says what changed.
31
+
32
+ ## Reading this file
33
+
34
+ Read the status before the title. Accepted binds a design; superseded is history, read for reasoning
35
+ and never for instruction. Cite by number and title so a reader can open the record itself.
36
+
37
+ Contradicting an accepted ADR is not a blocker, it is the trigger for a superseding one. The
38
+ `writing-adrs` skill produces that record, and its row lands here.
39
+
40
+ If the index is filled in but nothing covers your area, the decision is undocumented rather than
41
+ absent. Say which one is missing, marked per `context/grounding-rules.md`.
42
+
43
+ ## Where the records live
44
+
45
+ - Directory: `docs/adr/`
46
+ - Filename pattern: `NNNN-short-kebab-title.md` (e.g. `0002-transition-timeline-model.md`)
47
+ - Template: Context / Decision / Consequences headings; no formal template file — copy the newest record.
48
+
49
+ ## The decisions
50
+
51
+ | # | Title | Status | Date | Supersedes / superseded by |
52
+ |---|---|---|---|---|
53
+ | 0001 | Compose frames with Pillow/numpy; ffmpeg only at the boundaries | accepted | 2026-08-25 | — |
54
+ | 0002 | Transition timeline model: centered window, clamped scene edges, total duration = sum of scenes | accepted | 2026-08-25 | — |
55
+ | 0003 | Single ffmpeg process for encode and audio mix | accepted | 2026-08-25 | — |
56
+ | 0004 | Hand-written validation instead of a jsonschema dependency | accepted | 2026-08-25 | — |
57
+ | 0005 | Pillow's embedded scalable font (Aileron) as the bundled default font | accepted | 2026-08-25 | — |
58
+ | 0006 | MCP server as an optional extra on the official SDK | accepted | 2026-08-25 | — |
59
+ | 0007 | Reusable elements expand at parse time | accepted | 2026-08-25 | — |
60
+
61
+ ## Keeping it current
62
+
63
+ The index rots faster than the records it points at, because writing the superseding ADR is
64
+ satisfying and editing the old row is not. One stale `accepted` sends a design down a path the team
65
+ already abandoned, with a citation attached. Cheapest habit: the pull request adding a record edits
66
+ both rows in the same diff, the new one and the one it supersedes.