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.
- scenescript-0.1.0/.claude/agents/copy-writer.md +65 -0
- scenescript-0.1.0/.claude/agents/product-owner.md +52 -0
- scenescript-0.1.0/.claude/agents/qa-tester.md +64 -0
- scenescript-0.1.0/.claude/agents/software-architect.md +64 -0
- scenescript-0.1.0/.claude/agents/software-engineer.md +55 -0
- scenescript-0.1.0/.claude/agents/ui-ux-specialist.md +68 -0
- scenescript-0.1.0/.claude/context/README.md +83 -0
- scenescript-0.1.0/.claude/context/accessibility-standard.md +68 -0
- scenescript-0.1.0/.claude/context/adr-index.md +66 -0
- scenescript-0.1.0/.claude/context/ci-pipeline.md +68 -0
- scenescript-0.1.0/.claude/context/competitor-positioning.md +60 -0
- scenescript-0.1.0/.claude/context/design-tokens.md +64 -0
- scenescript-0.1.0/.claude/context/device-matrix.md +71 -0
- scenescript-0.1.0/.claude/context/domain-glossary.md +62 -0
- scenescript-0.1.0/.claude/context/environment-map.md +58 -0
- scenescript-0.1.0/.claude/context/grounding-rules.md +124 -0
- scenescript-0.1.0/.claude/context/known-debt.md +58 -0
- scenescript-0.1.0/.claude/context/known-issues.md +55 -0
- scenescript-0.1.0/.claude/context/local-dev-setup.md +83 -0
- scenescript-0.1.0/.claude/context/nfr-targets.md +67 -0
- scenescript-0.1.0/.claude/context/observability-map.md +83 -0
- scenescript-0.1.0/.claude/context/personas.md +70 -0
- scenescript-0.1.0/.claude/context/research-repository.md +57 -0
- scenescript-0.1.0/.claude/context/severity-ladder.md +76 -0
- scenescript-0.1.0/.claude/context/system-map.md +81 -0
- scenescript-0.1.0/.claude/context/tech-radar.md +67 -0
- scenescript-0.1.0/.claude/context/test-data-catalog.md +66 -0
- scenescript-0.1.0/.claude/context/ui-string-catalog.md +81 -0
- scenescript-0.1.0/.claude/context/voice-guide.md +68 -0
- scenescript-0.1.0/.claude/skills/analyzing-trade-offs/SKILL.md +58 -0
- scenescript-0.1.0/.claude/skills/analyzing-trade-offs/references/worked-example.md +98 -0
- scenescript-0.1.0/.claude/skills/applying-design-system-conventions/SKILL.md +73 -0
- scenescript-0.1.0/.claude/skills/applying-design-system-conventions/references/drift-catalogue.md +101 -0
- scenescript-0.1.0/.claude/skills/applying-design-system-conventions/references/worked-resolution.md +112 -0
- scenescript-0.1.0/.claude/skills/auditing-accessibility/SKILL.md +75 -0
- scenescript-0.1.0/.claude/skills/auditing-accessibility/references/audit-checklist.md +98 -0
- scenescript-0.1.0/.claude/skills/auditing-accessibility/references/finding-template.md +102 -0
- scenescript-0.1.0/.claude/skills/auditing-accessibility/references/state-audit.md +103 -0
- scenescript-0.1.0/.claude/skills/automating-tests/SKILL.md +62 -0
- scenescript-0.1.0/.claude/skills/automating-tests/references/adversarial-cases.md +103 -0
- scenescript-0.1.0/.claude/skills/automating-tests/references/flake-cures.md +112 -0
- scenescript-0.1.0/.claude/skills/automating-tests/references/test-note.md +126 -0
- scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/SKILL.md +58 -0
- scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/references/heuristics.md +88 -0
- scenescript-0.1.0/.claude/skills/critiquing-with-heuristics/references/worked-example.md +115 -0
- scenescript-0.1.0/.claude/skills/debugging-and-incidents/SKILL.md +68 -0
- scenescript-0.1.0/.claude/skills/debugging-and-incidents/references/records.md +84 -0
- scenescript-0.1.0/.claude/skills/defining-voice-and-style/SKILL.md +63 -0
- scenescript-0.1.0/.claude/skills/defining-voice-and-style/references/worked-guide.md +104 -0
- scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/SKILL.md +64 -0
- scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/references/adversarial-catalogue.md +95 -0
- scenescript-0.1.0/.claude/skills/designing-tests-from-acceptance-criteria/references/worked-example.md +110 -0
- scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/SKILL.md +66 -0
- scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/references/branch-checklist.md +85 -0
- scenescript-0.1.0/.claude/skills/documenting-flows-and-ia/references/worked-flow.md +101 -0
- scenescript-0.1.0/.claude/skills/documenting-systems/SKILL.md +69 -0
- scenescript-0.1.0/.claude/skills/documenting-systems/references/evidence-ladder.md +69 -0
- scenescript-0.1.0/.claude/skills/documenting-systems/references/worked-diagram.md +112 -0
- scenescript-0.1.0/.claude/skills/drafting-from-a-brief/SKILL.md +61 -0
- scenescript-0.1.0/.claude/skills/drafting-from-a-brief/references/worked-brief.md +85 -0
- scenescript-0.1.0/.claude/skills/editing-copy/SKILL.md +76 -0
- scenescript-0.1.0/.claude/skills/editing-copy/references/deliverables.md +120 -0
- scenescript-0.1.0/.claude/skills/enforcing-terminology/SKILL.md +68 -0
- scenescript-0.1.0/.claude/skills/enforcing-terminology/references/deliverable.md +130 -0
- scenescript-0.1.0/.claude/skills/enforcing-terminology/references/sweep-recipe.md +99 -0
- scenescript-0.1.0/.claude/skills/enumerating-ui-states/SKILL.md +64 -0
- scenescript-0.1.0/.claude/skills/enumerating-ui-states/references/inventory-template.md +82 -0
- scenescript-0.1.0/.claude/skills/enumerating-ui-states/references/state-axes.md +106 -0
- scenescript-0.1.0/.claude/skills/managing-test-data/SKILL.md +62 -0
- scenescript-0.1.0/.claude/skills/managing-test-data/references/hostile-fixtures.md +81 -0
- scenescript-0.1.0/.claude/skills/managing-test-data/references/provisioning-routes.md +89 -0
- scenescript-0.1.0/.claude/skills/planning-implementation/SKILL.md +51 -0
- scenescript-0.1.0/.claude/skills/planning-implementation/references/worked-plan.md +51 -0
- scenescript-0.1.0/.claude/skills/planning-migrations/SKILL.md +69 -0
- scenescript-0.1.0/.claude/skills/planning-migrations/references/expand-contract.md +98 -0
- scenescript-0.1.0/.claude/skills/planning-migrations/references/worked-plan.md +97 -0
- scenescript-0.1.0/.claude/skills/planning-usability-tests/SKILL.md +82 -0
- scenescript-0.1.0/.claude/skills/planning-usability-tests/references/plan-template.md +113 -0
- scenescript-0.1.0/.claude/skills/planning-usability-tests/references/task-wording.md +75 -0
- scenescript-0.1.0/.claude/skills/prioritizing-work/SKILL.md +49 -0
- scenescript-0.1.0/.claude/skills/prioritizing-work/references/cost-of-delay.md +70 -0
- scenescript-0.1.0/.claude/skills/prioritizing-work/references/frameworks.md +86 -0
- scenescript-0.1.0/.claude/skills/prioritizing-work/references/worked-example.md +82 -0
- scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/SKILL.md +70 -0
- scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/adversarial-probes.md +57 -0
- scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/probe-types.md +100 -0
- scenescript-0.1.0/.claude/skills/probing-non-functional-behavior/references/worked-probe.md +107 -0
- scenescript-0.1.0/.claude/skills/refactoring/SKILL.md +52 -0
- scenescript-0.1.0/.claude/skills/refactoring/references/characterization-tests.md +81 -0
- scenescript-0.1.0/.claude/skills/refactoring/references/mechanical-moves.md +59 -0
- scenescript-0.1.0/.claude/skills/refining-the-backlog/SKILL.md +51 -0
- scenescript-0.1.0/.claude/skills/refining-the-backlog/references/split-axes.md +96 -0
- scenescript-0.1.0/.claude/skills/removing-ai-tells/SKILL.md +69 -0
- scenescript-0.1.0/.claude/skills/removing-ai-tells/references/catalogue.md +126 -0
- scenescript-0.1.0/.claude/skills/reporting-defects/SKILL.md +66 -0
- scenescript-0.1.0/.claude/skills/reporting-defects/references/report-template.md +116 -0
- scenescript-0.1.0/.claude/skills/reporting-defects/references/worked-examples.md +125 -0
- scenescript-0.1.0/.claude/skills/reviewing-code/SKILL.md +70 -0
- scenescript-0.1.0/.claude/skills/reviewing-code/references/correctness-probes.md +67 -0
- scenescript-0.1.0/.claude/skills/reviewing-code/references/worked-review.md +109 -0
- scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/SKILL.md +64 -0
- scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/references/quality-checklist.md +104 -0
- scenescript-0.1.0/.claude/skills/reviewing-design-against-nfrs/references/worked-review.md +82 -0
- scenescript-0.1.0/.claude/skills/reviewing-for-acceptance/SKILL.md +53 -0
- scenescript-0.1.0/.claude/skills/reviewing-for-acceptance/references/acceptance-record.md +66 -0
- scenescript-0.1.0/.claude/skills/reviewing-tests/SKILL.md +74 -0
- scenescript-0.1.0/.claude/skills/reviewing-tests/references/mutation-catalogue.md +103 -0
- scenescript-0.1.0/.claude/skills/reviewing-tests/references/tests-that-cannot-fail.md +122 -0
- scenescript-0.1.0/.claude/skills/reviewing-tests/references/worked-review.md +129 -0
- scenescript-0.1.0/.claude/skills/running-design-qa/SKILL.md +78 -0
- scenescript-0.1.0/.claude/skills/running-design-qa/references/check-matrix.md +93 -0
- scenescript-0.1.0/.claude/skills/running-design-qa/references/output-template.md +80 -0
- scenescript-0.1.0/.claude/skills/running-spikes/SKILL.md +59 -0
- scenescript-0.1.0/.claude/skills/running-spikes/references/spike-note.md +129 -0
- scenescript-0.1.0/.claude/skills/scoping-regression-tests/SKILL.md +65 -0
- scenescript-0.1.0/.claude/skills/scoping-regression-tests/references/reach-checklist.md +113 -0
- scenescript-0.1.0/.claude/skills/scoping-regression-tests/references/scope-note.md +110 -0
- scenescript-0.1.0/.claude/skills/specifying-interactions/SKILL.md +67 -0
- scenescript-0.1.0/.claude/skills/specifying-interactions/references/adversarial-read.md +93 -0
- scenescript-0.1.0/.claude/skills/specifying-interactions/references/spec-template.md +125 -0
- scenescript-0.1.0/.claude/skills/synthesizing-research/SKILL.md +65 -0
- scenescript-0.1.0/.claude/skills/synthesizing-research/references/no-research-yet.md +75 -0
- scenescript-0.1.0/.claude/skills/synthesizing-research/references/worked-synthesis.md +120 -0
- scenescript-0.1.0/.claude/skills/tdd-workflow/SKILL.md +61 -0
- scenescript-0.1.0/.claude/skills/tdd-workflow/references/reading-red.md +66 -0
- scenescript-0.1.0/.claude/skills/tdd-workflow/references/worked-cycle.md +136 -0
- scenescript-0.1.0/.claude/skills/testing-accessibility/SKILL.md +61 -0
- scenescript-0.1.0/.claude/skills/testing-accessibility/references/adversarial-conditions.md +106 -0
- scenescript-0.1.0/.claude/skills/testing-accessibility/references/finding-template.md +110 -0
- scenescript-0.1.0/.claude/skills/testing-accessibility/references/keyboard-pass.md +111 -0
- scenescript-0.1.0/.claude/skills/testing-accessibility/references/screen-reader-pass.md +100 -0
- scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/SKILL.md +74 -0
- scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/references/adversarial-catalogue.md +128 -0
- scenescript-0.1.0/.claude/skills/testing-apis-and-contracts/references/compatibility-matrix.md +64 -0
- scenescript-0.1.0/.claude/skills/triaging-bugs/SKILL.md +61 -0
- scenescript-0.1.0/.claude/skills/triaging-bugs/references/severity-and-priority.md +96 -0
- scenescript-0.1.0/.claude/skills/triaging-requests/SKILL.md +59 -0
- scenescript-0.1.0/.claude/skills/triaging-requests/references/triage-note.md +107 -0
- scenescript-0.1.0/.claude/skills/upgrading-dependencies/SKILL.md +67 -0
- scenescript-0.1.0/.claude/skills/upgrading-dependencies/references/silent-changes.md +48 -0
- scenescript-0.1.0/.claude/skills/upgrading-dependencies/references/upgrade-note.md +92 -0
- scenescript-0.1.0/.claude/skills/verifying-done/SKILL.md +55 -0
- scenescript-0.1.0/.claude/skills/verifying-done/references/completion-report.md +80 -0
- scenescript-0.1.0/.claude/skills/verifying-done/references/rationalizations.md +44 -0
- scenescript-0.1.0/.claude/skills/verifying-done/references/scaling-the-check.md +53 -0
- scenescript-0.1.0/.claude/skills/writing-adrs/SKILL.md +60 -0
- scenescript-0.1.0/.claude/skills/writing-adrs/references/adr-template.md +78 -0
- scenescript-0.1.0/.claude/skills/writing-adrs/references/worked-adr.md +121 -0
- scenescript-0.1.0/.claude/skills/writing-documentation/SKILL.md +64 -0
- scenescript-0.1.0/.claude/skills/writing-documentation/references/page-shapes.md +67 -0
- scenescript-0.1.0/.claude/skills/writing-documentation/references/worked-example.md +149 -0
- scenescript-0.1.0/.claude/skills/writing-exploratory-charters/SKILL.md +78 -0
- scenescript-0.1.0/.claude/skills/writing-exploratory-charters/references/lens-catalogue.md +144 -0
- scenescript-0.1.0/.claude/skills/writing-exploratory-charters/references/session-record.md +156 -0
- scenescript-0.1.0/.claude/skills/writing-marketing-copy/SKILL.md +69 -0
- scenescript-0.1.0/.claude/skills/writing-marketing-copy/references/awareness-and-formats.md +91 -0
- scenescript-0.1.0/.claude/skills/writing-marketing-copy/references/worked-examples.md +109 -0
- scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/SKILL.md +66 -0
- scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/references/content-set.md +56 -0
- scenescript-0.1.0/.claude/skills/writing-microcopy-in-context/references/worked-review.md +82 -0
- scenescript-0.1.0/.claude/skills/writing-plain-language/SKILL.md +70 -0
- scenescript-0.1.0/.claude/skills/writing-plain-language/references/text-accessibility-checks.md +98 -0
- scenescript-0.1.0/.claude/skills/writing-plain-language/references/worked-example.md +104 -0
- scenescript-0.1.0/.claude/skills/writing-seo-metadata/SKILL.md +68 -0
- scenescript-0.1.0/.claude/skills/writing-seo-metadata/references/surfaces.md +124 -0
- scenescript-0.1.0/.claude/skills/writing-ui-copy/SKILL.md +58 -0
- scenescript-0.1.0/.claude/skills/writing-ui-copy/references/constraints-and-variables.md +110 -0
- scenescript-0.1.0/.claude/skills/writing-ui-copy/references/string-types.md +128 -0
- scenescript-0.1.0/.claude/skills/writing-user-stories/SKILL.md +54 -0
- scenescript-0.1.0/.claude/skills/writing-user-stories/references/worked-example.md +58 -0
- scenescript-0.1.0/.gitignore +8 -0
- scenescript-0.1.0/LICENSE +21 -0
- scenescript-0.1.0/PKG-INFO +546 -0
- scenescript-0.1.0/README.md +526 -0
- scenescript-0.1.0/docs/adr/0001-pillow-numpy-composition-ffmpeg-at-boundaries.md +28 -0
- scenescript-0.1.0/docs/adr/0002-transition-timeline-model.md +44 -0
- scenescript-0.1.0/docs/adr/0003-single-ffmpeg-process-for-encode-and-audio.md +36 -0
- scenescript-0.1.0/docs/adr/0004-hand-written-validation.md +27 -0
- scenescript-0.1.0/docs/adr/0005-pillow-embedded-default-font.md +26 -0
- scenescript-0.1.0/docs/adr/0006-mcp-server-as-optional-extra.md +38 -0
- scenescript-0.1.0/docs/adr/0007-reusable-elements-expand-at-parse-time.md +54 -0
- scenescript-0.1.0/pyproject.toml +51 -0
- scenescript-0.1.0/src/scenescript/__init__.py +3 -0
- scenescript-0.1.0/src/scenescript/animation.py +43 -0
- scenescript-0.1.0/src/scenescript/audio.py +144 -0
- scenescript-0.1.0/src/scenescript/backgrounds.py +54 -0
- scenescript-0.1.0/src/scenescript/cli.py +136 -0
- scenescript-0.1.0/src/scenescript/colors.py +28 -0
- scenescript-0.1.0/src/scenescript/easing.py +40 -0
- scenescript-0.1.0/src/scenescript/encoder.py +108 -0
- scenescript-0.1.0/src/scenescript/errors.py +28 -0
- scenescript-0.1.0/src/scenescript/geometry.py +70 -0
- scenescript-0.1.0/src/scenescript/mcp_server.py +174 -0
- scenescript-0.1.0/src/scenescript/probe.py +69 -0
- scenescript-0.1.0/src/scenescript/progress.py +42 -0
- scenescript-0.1.0/src/scenescript/renderer.py +94 -0
- scenescript-0.1.0/src/scenescript/scenes.py +140 -0
- scenescript-0.1.0/src/scenescript/spec.py +607 -0
- scenescript-0.1.0/src/scenescript/sprites.py +109 -0
- scenescript-0.1.0/src/scenescript/timeline.py +97 -0
- scenescript-0.1.0/src/scenescript/transitions.py +84 -0
- scenescript-0.1.0/src/scenescript/validation.py +177 -0
- scenescript-0.1.0/src/scenescript/videoreader.py +96 -0
- scenescript-0.1.0/tests/__init__.py +0 -0
- scenescript-0.1.0/tests/conftest.py +65 -0
- scenescript-0.1.0/tests/test_animation.py +52 -0
- scenescript-0.1.0/tests/test_audio.py +150 -0
- scenescript-0.1.0/tests/test_backgrounds.py +60 -0
- scenescript-0.1.0/tests/test_cli.py +123 -0
- scenescript-0.1.0/tests/test_colors.py +31 -0
- scenescript-0.1.0/tests/test_defs.py +208 -0
- scenescript-0.1.0/tests/test_easing.py +41 -0
- scenescript-0.1.0/tests/test_geometry.py +74 -0
- scenescript-0.1.0/tests/test_mcp_server.py +176 -0
- scenescript-0.1.0/tests/test_probe.py +39 -0
- scenescript-0.1.0/tests/test_render.py +139 -0
- scenescript-0.1.0/tests/test_scenes.py +194 -0
- scenescript-0.1.0/tests/test_spec.py +337 -0
- scenescript-0.1.0/tests/test_sprites.py +105 -0
- scenescript-0.1.0/tests/test_timeline.py +100 -0
- scenescript-0.1.0/tests/test_transitions.py +82 -0
- scenescript-0.1.0/tests/test_validation.py +153 -0
- scenescript-0.1.0/tests/test_videoreader.py +64 -0
- 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.
|