geneseed 5.4.0 → 5.5.1

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 (191) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/README.md +31 -1
  3. package/SHIPPED.md +1 -1
  4. package/adapters/bob/README.md +12 -1
  5. package/adapters/opencode/README.md +2 -1
  6. package/adapters/opencode/plugins/geneseed-context.js +71 -10
  7. package/adapters/opencode/plugins/geneseed-guard.js +101 -19
  8. package/adapters/opencode/plugins/geneseed-learn.js +641 -6
  9. package/bin/geneseed-cli.mjs +3 -0
  10. package/bin/geneseed-hook.mjs +2 -1
  11. package/docs/concepts/agents.md +13 -1
  12. package/docs/concepts/enforcement-table.md +1 -1
  13. package/docs/concepts/foreman-mode.md +22 -3
  14. package/docs/concepts/hook-gates.md +1 -1
  15. package/docs/concepts/hooks.md +22 -5
  16. package/docs/concepts/host-matrix.md +2 -2
  17. package/docs/concepts/hosts.md +1 -1
  18. package/docs/concepts/shared-tier.md +1 -1
  19. package/docs/concepts/skills.md +21 -1
  20. package/docs/concepts/themes.md +1 -1
  21. package/docs/extending.md +11 -2
  22. package/docs/guides/install-clone.md +18 -0
  23. package/docs/guides/install-scripted.md +8 -2
  24. package/docs/guides/install.md +19 -1
  25. package/docs/guides/upgrade.md +1 -1
  26. package/docs/reference/env-context.md +1 -1
  27. package/docs/reference/environment.md +1 -1
  28. package/docs/reference/plugin-learn.md +4 -0
  29. package/docs/reference/profiles.md +226 -0
  30. package/docs/token-footprint.md +9 -4
  31. package/docs/understand/design-choices-engineering.md +1 -1
  32. package/docs/web-ui.md +3 -1
  33. package/harness.config.json +1 -1
  34. package/js/README.md +9 -2
  35. package/js/build/args.mjs +4 -3
  36. package/js/build/catalog.mjs +11 -1
  37. package/js/build/driver.mjs +42 -11
  38. package/js/build/emit-claude.mjs +24 -1
  39. package/js/build/emit-opencode.mjs +3 -0
  40. package/js/build/export.mjs +12 -17
  41. package/js/build/generate.mjs +2 -1
  42. package/js/build/notes-migrate.mjs +99 -0
  43. package/js/build/profile.mjs +14 -6
  44. package/js/build/render.mjs +34 -10
  45. package/js/build/source.mjs +85 -2
  46. package/js/cli-table.json +164 -4
  47. package/js/hosts/agent-runs.mjs +205 -0
  48. package/js/hosts/done-checks.mjs +3 -1
  49. package/js/hosts/hooks-done.mjs +91 -16
  50. package/js/hosts/hooks-learn.mjs +85 -0
  51. package/js/hosts/hooks-prims.mjs +39 -1
  52. package/js/hosts/hooks.mjs +10 -4
  53. package/js/hosts/hosts.mjs +10 -0
  54. package/js/hosts/installs.mjs +25 -1
  55. package/js/hosts/link.mjs +45 -10
  56. package/js/hosts/native.mjs +42 -5
  57. package/js/hosts/opencode.mjs +1 -1
  58. package/js/hosts/settings.mjs +72 -0
  59. package/js/hosts/spec-feedback.mjs +538 -0
  60. package/js/hosts/usage.mjs +67 -8
  61. package/js/inspect/agent-scores.mjs +118 -0
  62. package/js/inspect/checks-authoring.mjs +2 -1
  63. package/js/inspect/checks-build.mjs +20 -4
  64. package/js/inspect/checks-repo.mjs +27 -2
  65. package/js/inspect/cost.mjs +6 -5
  66. package/js/inspect/diff.mjs +25 -5
  67. package/js/inspect/doctor.mjs +4 -0
  68. package/js/inspect/status.mjs +3 -1
  69. package/js/inspect/validate.mjs +1 -0
  70. package/js/lib/machine-dir.mjs +8 -0
  71. package/js/lib/paths.mjs +4 -1
  72. package/js/maintain/profile-scope.mjs +145 -0
  73. package/js/maintain/profiles.mjs +486 -0
  74. package/js/maintain/setup.mjs +409 -15
  75. package/js/maintain/uninstall.mjs +4 -1
  76. package/js/maintain/update.mjs +1 -1
  77. package/js/web/actions.mjs +28 -38
  78. package/js/web/api.mjs +7 -2
  79. package/js/web/handler.mjs +8 -0
  80. package/js/web/jobs.mjs +5 -4
  81. package/js/web/profiles-api.mjs +201 -0
  82. package/js/web/routes.mjs +5 -0
  83. package/package.json +2 -1
  84. package/profiles/autonomous.json +14 -0
  85. package/profiles/corporate.json +14 -0
  86. package/profiles/guillaume-claude-global.json +16 -0
  87. package/profiles/mentor.json +13 -0
  88. package/profiles/minimal.json +15 -0
  89. package/profiles/starter.json +14 -0
  90. package/src/AGENT.md.tmpl +1 -1
  91. package/src/agents/_self-improvement.md +15 -7
  92. package/src/agents/_template.md +4 -2
  93. package/src/agents/advocate.md +1 -1
  94. package/src/agents/architect.md +1 -1
  95. package/src/agents/developer.md +10 -3
  96. package/src/agents/devops-engineer.md +7 -6
  97. package/src/agents/docker-expert.md +1 -1
  98. package/src/agents/docs.md +1 -1
  99. package/src/agents/empiricist.md +1 -1
  100. package/src/agents/explorer.md +4 -2
  101. package/src/agents/framer.md +1 -1
  102. package/src/agents/historian.md +1 -1
  103. package/src/agents/kubernetes-specialist.md +4 -2
  104. package/src/agents/memory-curator.md +1 -1
  105. package/src/agents/operator.md +1 -1
  106. package/src/agents/performance.md +1 -1
  107. package/src/agents/pragmatist.md +1 -1
  108. package/src/agents/react-engineer.md +1 -1
  109. package/src/agents/react-reviewer.md +1 -1
  110. package/src/agents/researcher.md +1 -1
  111. package/src/agents/reviewer.md +10 -3
  112. package/src/agents/security.md +1 -1
  113. package/src/agents/skeptic.md +1 -1
  114. package/src/agents/spring-boot-engineer.md +4 -4
  115. package/src/agents/spring-reviewer.md +5 -3
  116. package/src/agents/spring-security.md +1 -1
  117. package/src/agents/steward.md +1 -1
  118. package/src/agents/tester.md +4 -2
  119. package/src/agents/user-advocate.md +1 -1
  120. package/src/agents/visionary.md +1 -1
  121. package/src/memory/README.md +12 -2
  122. package/src/modes/foreman.md +23 -10
  123. package/src/skill-descriptions.json +63 -0
  124. package/src/skills/_self-improvement.md +42 -26
  125. package/src/skills/_template.md +3 -1
  126. package/src/skills/brainstorm.md +35 -22
  127. package/src/skills/codebase-design.md +2 -2
  128. package/src/skills/daydream/VENDOR.md +6 -0
  129. package/src/skills/diagram-design/SKILL.md +12 -7
  130. package/src/skills/diagram-design/VENDOR.md +23 -14
  131. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  132. package/src/skills/diagram-design/references/onboarding.md +1 -1
  133. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  134. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  135. package/src/skills/diagram-design/references/style-guide.md +1 -1
  136. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  137. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  138. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  139. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  140. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  141. package/src/skills/diagram-design/references/type-steps.md +180 -0
  142. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  143. package/src/skills/explain-changes/VENDOR.md +5 -1
  144. package/src/skills/geneseed-code-review.md +2 -1
  145. package/src/skills/parallel-agents.md +12 -1
  146. package/src/skills/pipeline.md +3 -3
  147. package/src/skills/plan.md +5 -4
  148. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  149. package/src/skills/react-view-transitions/SKILL.md +1 -1
  150. package/src/skills/react-view-transitions/VENDOR.md +19 -4
  151. package/src/skills/release.md +7 -2
  152. package/src/skills/rule/approve.md +2 -1
  153. package/src/skills/skill-forge.md +5 -3
  154. package/src/skills/spring-boot/cloud.md +19 -1
  155. package/src/skills/spring-boot/logging.md +5 -3
  156. package/src/skills/spring-boot/web.md +27 -2
  157. package/src/skills/spring-boot.md +4 -2
  158. package/src/skills/spring-data-jpa.md +18 -4
  159. package/src/skills/spring-testing.md +4 -0
  160. package/src/skills/token-report/VENDOR.md +5 -1
  161. package/src/upstreams.json +6 -6
  162. package/themes/README.md +3 -1
  163. package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
  164. package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-bUSPM3Dl.js} +1 -1
  165. package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-AHRoXeFN.js} +1 -1
  166. package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-B5XY9pid.js} +1 -1
  167. package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-C0wwRR9H.js} +1 -1
  168. package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-DPAA96EI.js} +2 -2
  169. package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CpGDq165.js} +1 -1
  170. package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-cNhETa5Q.js} +1 -1
  171. package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-DO3ADmT9.js} +1 -1
  172. package/web/dist/assets/Installs-D3dDyq10.js +3 -0
  173. package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView--W-Lw_V9.js} +1 -1
  174. package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-ChfehxY6.js} +1 -1
  175. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  176. package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-CiPvsRYB.js} +1 -1
  177. package/web/dist/assets/{Library-CzPlerd6.js → Library-BxQvbwVU.js} +1 -1
  178. package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-DAblKkyq.js} +1 -1
  179. package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-QtSaSyYm.js} +1 -1
  180. package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-DxSGv638.js} +1 -1
  181. package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-CgTbhvRv.js} +1 -1
  182. package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-Cf4X1hdz.js} +1 -1
  183. package/web/dist/assets/api-CZ-x0iWG.js +1 -0
  184. package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
  185. package/web/dist/assets/{index-BL3P-9Rg.js → index-B_pTwZra.js} +4 -4
  186. package/web/dist/assets/index-CzfImiYb.css +1 -0
  187. package/web/dist/index.html +3 -3
  188. package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
  189. package/web/dist/assets/Laws-CuTw_XNf.js +0 -4
  190. package/web/dist/assets/api-DLDVY3K-.js +0 -1
  191. package/web/dist/assets/index-CRWqKxfY.css +0 -1
@@ -1,41 +1,57 @@
1
1
  ## Self-improvement
2
2
 
3
3
  <!-- LEAN:begin -->
4
- This {{SKILL}} keeps its own notes in `{{PATH_NOTES}}/skill-notes/<name>.md`,
5
- `<name>` being this {{SKILL}}'s name. When that file exists, read it before the
6
- first step — where it disagrees with this file, the notes win. They are yours to
7
- write, and no rebuild touches them.
4
+ This {{SKILL}} keeps notes in two scopes. Machine notes, true in every repo:
5
+ `{{PATH_NOTES}}/skill-notes/{{SKILL_NAME}}.md`, beside `{{PATH_NOTES}}/skill-notes/_general.md`,
6
+ which every {{SKILL}} shares. Project notes, true only in this repo: the same two files under
7
+ `{{PATH_PROJECT_NOTES}}/skill-notes/` at the project root (in a linked worktree, the main
8
+ checkout's). Read the four in that order, when they exist, before the
9
+ first step — where they disagree with this file, the notes win, and the project notes
10
+ win over the machine notes. No rebuild touches them.
8
11
 
9
12
  Close each run with one beat of reflection on the {{SKILL}} itself:
10
13
  - A step misled, a needed step was missing, or the trigger fired wrongly — that
11
- is a flaw in this file. Write the exact correction (trigger, procedure, or
12
- done-when) into the notes file on your own, with no prompt, as one line:
13
- `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened, against what you expected> (<date>)`.
14
- `situation:` bounds where the correction holds; `seen:` is the evidence it is
15
- later judged by; `general` marks one that would fix other {{SKILLS}} too. Never
16
- edit this file: it is a rendered copy, a rebuild overwrites it. A bundled script
17
- that is broken is the one exception: fix it in place, and tell the user which
18
- file you changed. `geneseed diff` carries the notes back to the source;
14
+ is a flaw in this file. End your reply with one line that names it, at the start
15
+ of a line and outside any code:
16
+ `spec-feedback: [skill:{{SKILL_NAME}}] <the one-line fix> [— situation: <when it applies>] — seen: <what happened, against what you expected>`.
17
+ `situation:` bounds where the fix holds; `seen:` is the evidence it is later
18
+ judged by. Ask one question first: is it true in any repo, or only here? Any repo:
19
+ `[skill:{{SKILL_NAME}}]`, or `[skill:{{SKILL_NAME}}:general]` for a fix other {{SKILLS}} need
20
+ too. Only here: `[skill:{{SKILL_NAME}}:project]`, or `[skill:{{SKILL_NAME}}:general:project]`.
21
+ When the turn ends, the harness hook copies the line, dated, into the notes —
22
+ no model call, so do not write the notes file yourself. On Bob, whose hook never
23
+ sees your reply, append it yourself: `- [skill] <the fix> … (<date>)` to the machine
24
+ or the project `skill-notes/{{SKILL_NAME}}.md` above, or `- [general] <the fix> … ({{SKILL_NAME}}, <date>)` to
25
+ that scope's `skill-notes/_general.md`; amend or delete a stale line before adding one, and keep
26
+ each file under about twenty lines.
27
+ Never edit this file: it is a rendered copy, a rebuild overwrites it. A bundled
28
+ script that is broken is the one exception: fix it in place, and tell the user
29
+ which file you changed. `geneseed diff` carries the notes back to the source;
19
30
  folding a note into the source is the user's call, through the skill-forge
20
31
  {{SKILL}} ({{LAW:one-intent-one-act}}).
21
- - Keep the notes sharp: amend or delete a line before adding one — a line with no
22
- `seen:`, or whose `seen:` no longer happens, goes first — and prune past about
23
- twenty lines.
24
32
  - A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
25
33
  clears {{DOCTRINE:persist-insight}}'s bar: it would change how a future session behaves, and a
26
34
  fresh read of the repo would not re-derive it. Update an existing memory over
27
35
  adding one; when in doubt, leave it out.
28
- - No friction, nothing learned — move on; this loop earns no ceremony. Most
36
+ - No friction, nothing learned — no line; this loop earns no ceremony. Most
29
37
  runs end here.
30
38
  <!-- LEAN:else -->
31
- One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
32
- wrong trigger is a flaw in this file — write the exact correction on your own, with no
33
- prompt, into `{{PATH_NOTES}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
34
- name) as `- [skill|general] <correction> [— situation: <when it applies>] — seen: <what happened vs expected> (<date>)`,
35
- never into this rendered file, which a rebuild overwrites. A bundled script that is
36
- broken is the one exception: fix it in place, and tell the user which file you
37
- changed. Folding a note into the source is the user's call ({{LAW:one-intent-one-act}}).
38
- Read that notes file before the first step when it exists; it wins where it disagrees.
39
- Keep it short. A lesson that is not about this file goes to {{MEMORY}} only if it
40
- clears {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
39
+ Before the first step read, when they exist, the machine notes
40
+ `{{PATH_NOTES}}/skill-notes/{{SKILL_NAME}}.md` and `{{PATH_NOTES}}/skill-notes/_general.md`, then the
41
+ same two project notes under `{{PATH_PROJECT_NOTES}}/skill-notes/` at the project root (a linked
42
+ worktree: the main checkout's). Notes win over this file, project notes over machine notes.
43
+ One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a wrong
44
+ trigger is a flaw in this file — end your reply with one line, at a line start and outside any code,
45
+ `spec-feedback: [skill:{{SKILL_NAME}}] <the one-line fix> [— situation: <when it applies>] — seen: <what happened vs expected>`.
46
+ True in any repo, or only here? Any repo: `[skill:{{SKILL_NAME}}]`, or `[skill:{{SKILL_NAME}}:general]`
47
+ for a fix other {{SKILLS}} need too; only here: `[skill:{{SKILL_NAME}}:project]`, or
48
+ `[skill:{{SKILL_NAME}}:general:project]`. The hook copies it into
49
+ the notes when the turn ends; do not write them yourself, except on Bob, whose hook never
50
+ sees the reply: there append `- [skill] <the fix> … (<date>)` to the machine or the project
51
+ `skill-notes/{{SKILL_NAME}}.md`, or `- [general] <the fix> … ({{SKILL_NAME}}, <date>)` to that scope's
52
+ `skill-notes/_general.md`, pruning stale lines first. Never edit this rendered file; a broken bundled script is the one
53
+ exception: fix it in place, and tell the user which file you changed. Folding a note
54
+ into the source is the user's call ({{LAW:one-intent-one-act}}). A lesson that is not
55
+ about this file goes to {{MEMORY}} only if it clears {{DOCTRINE:persist-insight}}'s bar.
56
+ Nothing learned — no line.
41
57
  <!-- LEAN:end -->
@@ -15,7 +15,9 @@
15
15
  files disagree, so neither can silently drift.
16
16
  Geneseed source repo only (skip in an installed harness):
17
17
  4. Define the DESC_<NAME> token (hyphens -> underscores, uppercased) in ALL theme
18
- JSONs under themes/ — the parity gate fails if any theme is missing it.
18
+ JSONs under themes/ — the parity gate fails if any theme is missing it. Add the
19
+ skill's line to src/skill-descriptions.json: purpose and trigger in at most 80
20
+ characters, theme-neutral. It is the emitted description; doctor fails without it.
19
21
  5. Bump the `skills-N` count badge in README.md (doctor checks it against the real
20
22
  file count; the test counts derive from src/ and need no edit), then run
21
23
  `./geneseed doctor --all` and the repository's test suites.
@@ -1,7 +1,6 @@
1
1
  # {{SKILL}}: brainstorm
2
2
 
3
3
  > {{DESC_BRAINSTORM}}
4
- <!-- aliases: grill-me -->
5
4
 
6
5
  {{CREDIT:superpowers:skills/brainstorming/SKILL.md}}
7
6
 
@@ -10,30 +9,38 @@
10
9
  {{CREDIT:mattpocock-skills:skills/productivity/to-questionnaire/SKILL.md}}
11
10
 
12
11
  **Trigger:** a new feature, behaviour change, or project arrives without a design, or the
13
- user says "brainstorm", "interview me" or "grill me". Also when goal, scope or success
12
+ user says "brainstorm" or "interview me". Also when goal, scope or success
14
13
  criteria are unstated ("let's design this", "clarify this first", "stress-test this plan"),
15
14
  and for non-design work (a refactor, a migration) whose *ask* is fuzzy: the interview runs,
16
15
  the design is skipped.
17
16
 
18
17
  ## Procedure
19
- 1. **Ground.** Read the current project state and its own docs ({{DOCTRINE:read-the-docs-first}})
20
- so every question is about the real thing ({{LAW:verify-before-asserting}}). If the request bundles
21
- several goals or systems, separate them and take one at a time.
18
+ 1. **Ground.** Read the current project state, its own docs ({{DOCTRINE:read-the-docs-first}})
19
+ and whatever the user pointed at (a spec, a handoff, files), until you can say how the
20
+ relevant parts work today and what the change would touch — so every question is about
21
+ the real thing ({{LAW:verify-before-asserting}}). Never ask what that already answers, nor
22
+ reopen what the user already decided. If the request bundles several goals or systems,
23
+ separate them and take one at a time.
22
24
  2. **Interpret charitably, then interview.** Read the request in its strongest
23
25
  reasonable form — do not manufacture ambiguity from a fair ask. If goal, scope and
24
26
  success criteria are already unambiguous, restate them in one line (naming any
25
- platform or language choice) and go to step 4. Otherwise ask ONE numbered round of
26
- every question answerable now, each with your recommended answer so "yes" accepts it;
27
- dependent questions wait a round. Drive at *why* (the outcome wanted), *scope* (in and
28
- out), *done* (how success is judged) and which build choices (platform, language, key
29
- libraries) the user wants to own. Existing work decides by default
30
- ({{DOCTRINE:respect-conventions}}); a choice you take goes in the ledger as **your
31
- call**, never as agreed. Stop when each is unambiguous. Facts are yours to find (read
32
- the code, dispatch a subagent), never the user's; a pending lookup holds back only the
33
- questions that depend on it. A decision someone else owns gets a drafted
34
- `questionnaire-<slug>.md` for them — ask the user only who and what they need back. Most
35
- important first (async gets one pass), one idea per question with an empty answer stub
36
- under it, and say "I don't know" is a useful answer.
27
+ platform or language choice, and any constraint, conflict or cheaper path you found),
28
+ get it confirmed — a handed-in spec is often incomplete — and go to step 4. Otherwise
29
+ ask ONE numbered round of every question answerable now, each with your recommended
30
+ answer so "yes" accepts it; dependent questions wait a round. Drive at *why* (the
31
+ outcome wanted), *scope* (in and out), *done* (how success is judged) and which build
32
+ choices (platform, language, key libraries) the user wants to own. Existing work
33
+ decides by default ({{DOCTRINE:respect-conventions}}); a choice you take goes in the
34
+ ledger as **your call**, never as agreed. Stop when each is unambiguous. Facts are
35
+ yours to find (read the code, dispatch a subagent), and so are process calls (where
36
+ the spec goes, writing it up): make them and say so. A pending lookup holds back only
37
+ the questions that depend on it. A decision someone else owns gets a drafted
38
+ `questionnaire-<slug>.md` for them — ask the user only who and what they need back.
39
+ Most important first (async gets one pass), one idea per question with an empty
40
+ answer stub under it, and say "I don't know" is a useful answer. When the skill
41
+ started on its own (no trigger phrase from the user), end your first message with a
42
+ one-line offer to just start; taken, the size is *Quick*: first state any platform,
43
+ language or tool you chose, in one line.
37
44
  3. **Ledger the decisions.** Name every KEY DECISION the answers imply or leave open —
38
45
  direction chosen, trade-offs accepted, load-bearing constraints, assumptions,
39
46
  non-goals. Surface each silent assumption as a decision to ratify, not a settled
@@ -43,19 +50,25 @@ the design is skipped.
43
50
  4. **Size it, then design.** Say the size; the user may override. *Quick* — exit and do
44
51
  it, no spec. *Small* — the confirmed ledger in chat is the spec; go to step 6.
45
52
  *Project* — design, spec file, builder check. If it grows mid-work, stop and step up.
46
- Design only when there is something to design: propose 2–3 approaches with
47
- trade-offs, leading with your recommendation. Present the chosen design in
48
- sections (purpose → components → data flow → failure modes → testing), getting an
53
+ For a *Project*, design only when there is something to design: propose 2–3
54
+ approaches grounded in what the project does, with trade-offs, leading with your
55
+ recommendation — in a message of their own; the user picks before any design is
56
+ written (one sensible way: say why the others do not fit). Present the chosen design
57
+ in sections (purpose → components → data flow → failure modes → testing), getting an
49
58
  explicit "looks right" after each; cut anything YAGNI. For a non-design ask, skip
50
59
  this step.
51
60
  5. **Write the spec.** One file the next session can find — `SPEC.md` beside the work,
52
- or the project's own spec home (e.g. `docs/specs/`): the goal in one line, the
53
- confirmed decision ledger, then the design (when there is one). Then run the builder
61
+ or the project's own spec home (e.g. `docs/specs/`). In a worktree, commit the spec on
62
+ the worktree's branch; where the spec home is git-ignored, use another tracked home, and
63
+ say where. The spec holds the goal in one line, the
64
+ confirmed decision ledger, then — when there is a design — the approaches weighed
65
+ (trade-offs, the pick and why) and the design. Then run the builder
54
66
  check: read [brainstorm/builder-check.md](brainstorm/builder-check.md) and follow it.
55
67
  6. **Exit — route, don't build.** Hand the spec to the {{SKILL}} the work now needs:
56
68
  [plan](plan.md) for a multi-step build whose route is known (sliced if too big for a
57
69
  session), [wayfinder](wayfinder.md) only when the route itself is still in the fog,
58
70
  [debug](debug.md) for a defect. Write no implementation code before that handoff.
71
+ A "go" on the ledger approves the ledger, not the build.
59
72
 
60
73
  ## Done when
61
74
  - A confirmed, ambiguity-free goal with its ratified decision ledger — and, where
@@ -27,8 +27,8 @@ a design talk that keeps stumbling over ambiguous terms, or another {{SKILL}} ne
27
27
  3. Aim for **deep modules** — much behaviour behind a small interface: callers
28
28
  get leverage, maintainers get locality. To find what to deepen, start from
29
29
  `git log` hot spots — what keeps changing. Design a new or reshaped interface
30
- twice before choosing: 2–3 radically different shapes (in parallel subagents
31
- where the host runs them), compared on depth, locality and seam placement;
30
+ twice before choosing: 2–3 radically different shapes (in parallel fresh
31
+ subagents, never forks, where the host runs them), compared on depth, locality and seam placement;
32
32
  recommend one — a hybrid if parts combine — never a menu.
33
33
  4. Seams sparingly: the interface is the test surface. Internal seams for the
34
34
  module's own tests are fine but never exposed; a test that must reach past
@@ -41,3 +41,9 @@ it is personal to one vault. Re-apply it on update.
41
41
  The cost line in `SKILL.md` reads "0.40-0.50 USD" where upstream writes a dollar sign before the
42
42
  number: Claude Code substitutes a dollar sign followed by a digit with the skill's arguments, so
43
43
  upstream's text renders mangled. Re-apply it on update.
44
+
45
+ At emit time the `description:` of `SKILL.md` is replaced with the skill's line in
46
+ `src/skill-descriptions.json` (at most 80 characters: the host's skill listing has a budget), and
47
+ the description written here is kept as the first body line, a blockquote
48
+ (`vendoredWithCatalogueLine`, `js/hosts/native.mjs`). This file is not changed; nothing to
49
+ re-apply on update.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: diagram-design
3
- description: "Branded HTML/SVG diagrams and charts — architecture, flowchart, sequence, ER, timeline, Gantt, Sankey and dozens more — with .drawio, Mermaid and .excalidraw import. Use when the user asks for a diagram, chart or visual map."
3
+ description: "Branded HTML/SVG diagrams and charts — architecture, flowchart, sequence, ER, timeline, Gantt, Sankey and dozens more — with .drawio, Mermaid, .excalidraw and PlantUML import. Use when the user asks for a diagram, chart or visual map."
4
4
  license: MIT
5
5
  metadata:
6
6
  version: "2.6"
@@ -10,7 +10,7 @@ metadata:
10
10
 
11
11
  Create diagrams as self-contained HTML files with inline SVG and an editorial design system.
12
12
 
13
- Forty-five visual types. Semantic patterns describe behavior; type references describe layout.
13
+ Fifty visual types. Semantic patterns describe behavior; type references describe layout.
14
14
 
15
15
  ---
16
16
 
@@ -49,7 +49,7 @@ Applied to schematics:
49
49
 
50
50
  ## 2. When to Use
51
51
 
52
- Use for any of the 45 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.
52
+ Use for any of the 50 visual types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.
53
53
 
54
54
  **Don't use for:**
55
55
 
@@ -80,7 +80,7 @@ When behavior, state, enforcement, or risk carries the meaning, first load [`ref
80
80
 
81
81
  The pattern owns semantic primitives and its tighter budget; the type owns layout grammar. Use [`references/animation.md`](references/animation.md) only when motion is requested or materially clarifies ordered change; static remains the default.
82
82
 
83
- ### Visual-type guide (45)
83
+ ### Visual-type guide (50)
84
84
 
85
85
  | If you're showing… | Use | Reference |
86
86
  |---|---|---|
@@ -91,6 +91,7 @@ The pattern owns semantic primitives and its tighter budget; the type owns layou
91
91
  | Time-ordered messages between actors | **Sequence** | [type-sequence.md](references/type-sequence.md) |
92
92
  | States + transitions + guards | **State machine** | [type-state.md](references/type-state.md) |
93
93
  | Entities + fields + relationships | **ER / data model** | [type-er.md](references/type-er.md) |
94
+ | A short ordered method with numbered stages, icons, and brief explanations | **Steps** | [type-steps.md](references/type-steps.md) |
94
95
  | Events positioned in time | **Timeline** | [type-timeline.md](references/type-timeline.md) |
95
96
  | Cross-functional process with handoffs | **Swimlane** | [type-swimlane.md](references/type-swimlane.md) |
96
97
  | Two-axis positioning / prioritization | **Quadrant** | [type-quadrant.md](references/type-quadrant.md) |
@@ -125,10 +126,14 @@ The pattern owns semantic primitives and its tighter budget; the type owns layou
125
126
  | What a person does across stages of an experience, and how it feels | **User journey** | [type-journey.md](references/type-journey.md) |
126
127
  | What the customer does vs what the service hides, across stages, with a line of visibility | **Service blueprint** | [type-service-blueprint.md](references/type-service-blueprint.md) |
127
128
  | Where software runs — zones, hosts, artifacts, replicas, ports | **Deployment** | [type-deployment.md](references/type-deployment.md) |
128
- | What depends on what, with fan-in and cycles a tree cannot express | **Dependency graph** | [type-dependency.md](references/type-dependency.md) |
129
+ | What depends on what, with fan-in and cycles a tree cannot express; arc diagram (nodes on a line, height is skip-span) variant | **Dependency graph** | [type-dependency.md](references/type-dependency.md) |
129
130
  | Classes with operations, inheritance, composition (other UML routes elsewhere) | **UML class** | [type-uml-class.md](references/type-uml-class.md) |
130
131
  | Narrative backbone sliced into releases, with the cut line | **Story map** | [type-story-map.md](references/type-story-map.md) |
131
132
  | Physical tables: SQL types, constraints, indexes, column-level FKs | **Database schema** | [type-db-schema.md](references/type-db-schema.md) |
133
+ | A biological process as a bipartite species/process graph | **SBGN** | [type-sbgn.md](references/type-sbgn.md) |
134
+ | Source requirements, design elements, and tests linked by stable IDs, with gaps explicit | **Requirement traceability** | [type-requirement-traceability.md](references/type-requirement-traceability.md) |
135
+ | Commands, resulting events, and read models across ordered stages | **Event modeling** | [type-event-modeling.md](references/type-event-modeling.md) |
136
+ | One bounded whole counted in equal discrete units out of 100 | **Unit Grid** | [type-unit-grid.md](references/type-unit-grid.md) |
132
137
 
133
138
  Rules of thumb:
134
139
 
@@ -338,9 +343,9 @@ Every diagram ships in three variants (see `assets/`):
338
343
 
339
344
  ---
340
345
 
341
- ## 11. Importing an Existing Diagram (draw.io), Mermaid, and Excalidraw
346
+ ## 11. Importing an Existing Diagram (draw.io), Mermaid, Excalidraw, and PlantUML
342
347
 
343
- Sources: `.drawio*`, `.mmd`, `.mermaid`, Markdown containing a fenced `mermaid` block, and `.excalidraw`. Follow this section for "convert this", "redraw this diagram", and "make this presentable".
348
+ Sources: `.drawio*`, `.mmd`, `.mermaid`, Markdown containing a fenced `mermaid` block, `.excalidraw`, `.puml`, `.plantuml`, `.pu`, and Markdown containing a fenced `plantuml` / `puml` block. Follow this section for "convert this", "redraw this diagram", and "make this presentable".
344
349
 
345
350
  The short version:
346
351
 
@@ -21,19 +21,20 @@ The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md`
21
21
 
22
22
  ## What was trimmed
23
23
 
24
- Upstream's `skills/diagram-design/` is about 5.9 MB. This copy keeps about 0.8 MB:
24
+ Upstream's `skills/diagram-design/` is about 6.4 MB. This copy keeps about 0.8 MB:
25
25
 
26
- - **Kept:** `SKILL.md`; every `references/*.md` except the six below; the five
26
+ - **Kept:** `SKILL.md`; every `references/*.md` except the seven below; the five
27
27
  `assets/template*.html` files (§10 tells the agent to copy them); two examples,
28
28
  `assets/example-venn.html` and `assets/example-architecture.html`.
29
- - **Dropped:** `scripts/` (six Python helpers — Geneseed carries no Python at runtime); the other
30
- ~218 `assets/example-*.html` files and `assets/icons.html` (a gallery of the icons
31
- `references/primitive-icons.md` already holds); `references/export.md` and
32
- `references/export-registry.md` (the Python/Playwright export helpers); `references/doctor.md`
33
- (Python and host-plugin diagnostics); `references/import-drawio.md`,
34
- `references/import-mermaid.md` and `references/import-excalidraw.md` (built around the
35
- Python extractors). Upstream's repository files (plugin manifests, `commands/`, `prompts/`,
36
- `docs/`, the repository-level `scripts/verify-*.py`) were never part of the skill folder.
29
+ - **Dropped:** `scripts/` (eight Python helpers — Geneseed carries no Python at runtime); the other
30
+ ~230 `assets/example-*.html` files, `assets/index.html` (the example gallery) and
31
+ `assets/icons.html` (a gallery of the icons `references/primitive-icons.md` already holds);
32
+ `references/export.md` and `references/export-registry.md` (the Python/Playwright export
33
+ helpers); `references/doctor.md` (Python and host-plugin diagnostics);
34
+ `references/import-drawio.md`, `references/import-mermaid.md`, `references/import-excalidraw.md`
35
+ and `references/import-plantuml.md` (built around the Python extractors). Upstream's
36
+ repository files (plugin manifests, `commands/`, `prompts/`, `docs/`, the repository-level
37
+ `scripts/verify-*.py`) were never part of the skill folder.
37
38
 
38
39
  SKILL.md §10 and some references still name `example-<type>.html` files and `assets/icons.html` in
39
40
  code spans; those files are not shipped. Many type references name upstream's repository-level
@@ -47,14 +48,19 @@ Each one removes a dependency on a dropped file. Re-apply them on update.
47
48
  tells the agent to run the geometry verifier.
48
49
  - `SKILL.md` §9: the geometry-verifier and motion-verifier runs are cut; the `self_check.py` item
49
50
  is now a check by hand of the same five properties.
50
- - `SKILL.md` §11: the route-by-source links to the three import references are replaced by the
51
- list of source formats, and step 1 reads the source file as text instead of running an extractor.
51
+ - `SKILL.md` §11: the route-by-source links to the four import references are replaced by the
52
+ list of source formats (PlantUML included), and step 1 reads the source file as text instead of
53
+ running an extractor.
52
54
  - `SKILL.md` §12: the "Exporting to PNG / SVG" body is replaced by one paragraph: this copy ships no
53
55
  export helpers, so an `.svg` is the `<svg>` node copied out of the `.html`, and a `.png` cannot be
54
56
  made.
55
57
  - `SKILL.md` frontmatter: the description is cut from upstream's ~850-character list of diagram
56
58
  types to a short summary plus a "Use when" trigger, because it is loaded in every session's
57
59
  skill catalogue. It says "HTML/SVG" where upstream says "HTML/SVG/PNG".
60
+ - At emit time, not in this folder: the `description:` of `SKILL.md` is replaced with the skill's
61
+ line in `src/skill-descriptions.json` (at most 80 characters: the host's skill listing has a
62
+ budget), and the description written here is kept as the first body line, a blockquote
63
+ (`vendoredWithCatalogueLine`, `js/hosts/native.mjs`). Nothing to re-apply on update.
58
64
  - `SKILL.md` §10: the Consultant-special row points at `type-quadrant.md` instead of the dropped
59
65
  `example-quadrant-consultant.html`.
60
66
  - `SKILL.md` §11: the Format dial marks `png` and `html+png` as not available.
@@ -68,9 +74,12 @@ Each one removes a dependency on a dropped file. Re-apply them on update.
68
74
  - `references/animation.md`: the three-command verifier block is replaced by "check these by hand".
69
75
  - `references/output-spec.md`: two links to `export.md` are removed; the render-linter
70
76
  command is named as upstream's and not shipped.
71
- - `references/primitives-core.md`: three geometry-verifier commands are cut.
77
+ - `references/primitives-core.md`: three geometry-verifier commands are cut, and the font
78
+ substitution paragraph says to check masks by hand instead of naming `self_check.py`; the
79
+ accessible-name rule names `scripts/self_check.py` as upstream's and not shipped.
72
80
  - `references/style-guide.md`: the export/self-check commands become "check that the Google Fonts
73
- link is no longer present".
81
+ link is no longer present"; the width-budget paragraph names `scripts/self_check.py` as
82
+ upstream's and not shipped, and makes its 0.3em label check one to hold by hand.
74
83
  - `references/type-architecture-delta.md`: the verifier commands are named as upstream's and not
75
84
  shipped.
76
85
  - `references/type-treemap.md`: the render-linter command is named as upstream's and not shipped.
@@ -17,7 +17,7 @@ Routed from SKILL.md §7 and §8. SKILL.md keeps the grid rule in one line, the
17
17
 
18
18
  ### Complexity budget (per diagram)
19
19
 
20
- These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 arrows or transitions, 2 coral elements, 2 annotation callouts, and the motion limits) apply to every type on top of these, and a semantic pattern's own budget in [semantic-patterns.md](semantic-patterns.md) can only tighten them.
20
+ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 arrows or transitions, 2 coral elements, 2 annotation callouts, and the motion limits) apply to every type on top of these, and a semantic pattern's own budget in [semantic-patterns.md](semantic-patterns.md) can only tighten them. One type is the exception: SBGN replaces the 9 nodes and 12 arrows rows with its own ceiling below, because a process square is a reaction marker rather than a node and every reaction needs its consumption and production arcs. Its other universal rows still apply, and no other type may exceed 9 nodes or 12 arrows by analogy.
21
21
 
22
22
  | Limit | Rule |
23
23
  |---|---|
@@ -50,6 +50,7 @@ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 a
50
50
  | Max cells (treemap) | 8 |
51
51
  | Max series (line chart) | 5 |
52
52
  | Max tasks (Gantt) | 12 |
53
+ | Max stages (steps) | 7, exactly 1 focal stage |
53
54
  | Max points (scatter plot) | 30 |
54
55
  | Max series / outliers (box plot) | 8 / 8, 1 focal series |
55
56
  | Max stages / nodes / flows (sankey) | 3 / 8 / 12 |
@@ -58,11 +59,16 @@ These are the per-type limits. The universal rows in SKILL.md §7 (9 nodes, 12 a
58
59
  | Max columns / cards (kanban) | 5 / 12 total, 4 per column |
59
60
  | Max stages / rows (user journey) | 6 / 3, 2 pain markers |
60
61
  | Max stages / layers (service blueprint) | 6 stages; required customer / frontstage / backstage; optional evidence / support; 1 focal cell |
62
+ | Unit Grid | 100 equal cells; 10 × 10; 4px gutters; 1 count; at most 1 focal completed cell |
61
63
  | Max zones / nodes / paths (deployment) | 3 / 6 / 8, 9 artifacts |
62
64
  | Max nodes / edges (dependency) | 9 / 14, 4 ranks, 1 cycle |
65
+ | Max nodes / arcs (arc diagram) | 9 / 14, 1 focal arc |
66
+ | Max requirement rows / primary design links / primary verification links (requirement traceability) | 6 / 1 per row / 1 per row, 1 focal row |
67
+ | Max stages / commands / events / read models (event modeling) | 6 / 1 per stage / 1 per stage / 1 per stage, 2 accent uses |
63
68
  | Max classes / relationships (UML class) | 7 / 8, 5 members per compartment |
64
69
  | Max activities / slices / cards (story map) | 5 / 3 / 12 |
65
70
  | Max tables / columns / FKs (db schema) | 5 / 8 shown / 6 |
71
+ | Max macromolecules / processes / compartments / source-sink / arcs (SBGN) | 7 / 6 / 1 / 2 / 16; replaces the 9 nodes and 12 arrows rows |
66
72
 
67
73
  If you exceed, split into two diagrams (overview + detail).
68
74
 
@@ -175,7 +175,7 @@ Write the new tokens to `style-guide.md`. Suggest rebuilding one example (upstre
175
175
 
176
176
  After onboarding, the user should:
177
177
 
178
- 1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 45 visual types.
178
+ 1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 50 visual types.
179
179
  2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
180
180
 
181
181
  ---
@@ -138,7 +138,7 @@ Every diagram is an accessible figure by default:
138
138
 
139
139
  1. Its `<svg>` carries `role="img"` and `aria-labelledby` naming the diagram's `<title>` and `<desc>`.
140
140
  2. `<title>` is the first child of `<svg>`, before `<defs>`. Assistive technology may ignore a title placed later.
141
- 3. The IDs are prefixed per diagram and variant: `<slug>-title` / `<slug>-desc`, where the slug matches the file (`loop`, `loop-dark`, `loop-full`). Bare `title` / `desc` IDs are banned — two inline diagrams would otherwise share one ID, and the second could be announced with the first's name. Each naming ID must also be unique across the whole document, including non-SVG elements; the packaged `scripts/self_check.py` rejects these collisions.
141
+ 3. The IDs are prefixed per diagram and variant: `<slug>-title` / `<slug>-desc`, where the slug matches the file (`loop`, `loop-dark`, `loop-full`). Bare `title` / `desc` IDs are banned — two inline diagrams would otherwise share one ID, and the second could be announced with the first's name. Each naming ID must also be unique across the whole document, including non-SVG elements; upstream's `scripts/self_check.py`, not shipped in this copy, rejects these collisions, so check them by hand.
142
142
  4. `<title>` is the short name of the subject — roughly the page `<h1>`, and about 60 characters or fewer.
143
143
  5. `<desc>` is one sentence stating what the diagram shows in terms a reader needs without the image. Describe the content, not the geometry: “Org chart showing a command center routing work to specialist agents and escalation owners,” not “A box at the top with five boxes below it.” A shape-by-shape narration is worse than no useful description.
144
144
  6. Decorative-only SVG, such as the specimen glyphs in `assets/icons.html`, carries `aria-hidden="true"` instead.
@@ -1,6 +1,6 @@
1
1
  # Semantic patterns
2
2
 
3
- Semantic patterns describe **what a system does**; the 45 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
3
+ Semantic patterns describe **what a system does**; the 50 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
4
4
 
5
5
  Use one primary pattern per figure. A second pattern may supply at most one supporting primitive; if both need full treatment, split overview and detail. Labels and outcomes must remain complete in a static frame.
6
6
 
@@ -132,7 +132,7 @@ Geist and Instrument Serif carry no Hangul. A Korean `<text>` element extends it
132
132
 
133
133
  Both Noto faces ship in the font link above, so the web font resolves before any locally installed one and the same file renders identically on macOS, Windows, and a reviewer's browser. The local families follow it for offline viewing. Page titles need the serif equivalent — `'Instrument Serif', 'Noto Serif KR', serif` — or a mixed Latin/Korean title resolves Hangul through the platform's generic serif and the two halves disagree. Google's `css2` endpoint slices Korean by unicode-range, so a diagram with a handful of Korean labels downloads only the slices it touches. The four templates carry both faces because a new diagram may contain Hangul; the shipped Latin-only examples keep the shorter link, since a file with no Hangul has nothing to resolve.
134
134
 
135
- **Width budget.** Measure per character, not per script: **every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance** (0.60em sans, 0.62em mono), and nonspacing/enclosing marks cost nothing. Sum over the string and multiply by the font size for the text width, then add padding and round the box up to the next multiple of 4. `verify-treemap.py` enforces exactly this text width for treemap cell labels; the padding and rounding are authoring convention, and no other type carries an automatic check, so on those the budget is yours to hold.
135
+ **Width budget.** Measure per character, not per script: **every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance** (0.60em sans, 0.62em mono), and nonspacing/enclosing marks cost nothing. Sum over the string and multiply by the font size for the text width, then add padding and round the box up to the next multiple of 4. `verify-treemap.py` enforces exactly this text width for treemap cell labels. Upstream's `scripts/self_check.py`, not shipped in this copy, applies the same width to text inside a visible box of any type, so here that check is yours: add any letter-spacing, and keep every label within 0.3em of its box edge. Padding, rounding, and labels on paper-coloured arrow-label masks stay yours to hold too.
136
136
 
137
137
  Counting by script is the trap. `주문 v2.1` is two full-width syllables and five narrow characters; a formula that tallies Hangul, Latin letters, and spaces silently drops `2`, `.`, and `1` and sizes the box for four of its seven characters. Every rendered character costs something — measure per character, never per script.
138
138
 
@@ -37,8 +37,77 @@ Over budget: collapse a leaf cluster into one aggregate node labelled with its c
37
37
  - Highlighting more than one cycle in a single diagram — pick the one that matters editorially; a second cycle competes with the first and neither reads.
38
38
  - Omitting the fan-in badges — without them the reader can't see at a glance where dependencies concentrate, which is the entire reason this type exists over a plain tree.
39
39
 
40
+ ### Arc diagram
41
+
42
+ **Best for:** pairwise imports among a handful of packages when the *skip* is the story — nodes on one baseline, each edge a rising semicircle whose height is how many seats it jumps. Use it when a ranked dependency graph would bury a skip-layer import inside the hairball: the shipped example lines seven packages left to right, and Checkout still importing Auth is the tallest arc.
43
+
44
+ Not for: a node with many parents that need rank rows (that is the parent dependency graph); a tree (every node has one parent — use Tree); a cycle that has to be routed around the stack (the parent marks that with one dashed back-edge). An arc diagram has no ranks and no back-edge grammar.
45
+
46
+ #### Layout conventions
47
+
48
+ - **One rail, left to right.** Nodes are `r=6` dots on a shared baseline at `y=400` inside `0 0 1000 500`, equally spaced (the shipped example uses a 140px pitch from `x=80`). Labels sit under the dots, `text-anchor="middle"`.
49
+ - **Node count: 4–9.** Below 4 there is no rail to skip along; above 9 split an overview from a cluster.
50
+ - **Rising semicircles only.** Each import is `M x1,y A r,r 0 0 1 x2,y` with `fill="none"`. Sweep 1 rises in SVG coordinates; sweep 0 would draw the import under the seats. `r` is half the endpoint distance, so height equals span × pitch / 2 — a neighbour cannot wear a skip's arc.
51
+ - **Span is the seat count.** `data-span` is `|i−j|` on the rail. A five-seat skip is five times a neighbour, not a decorative taller curve.
52
+ - **Paint back to front:** longer arcs first, neighbours next, the focal skip last so it is the stroke the eye hits.
53
+ - **4px grid** applies to the designed constants — baseline, label baseline, legend rows, node radius. Positions on the rail are pitch-scaled and exempt.
54
+
55
+ #### Colour
56
+
57
+ - **One accent arc, and one muted treatment for everyone else.** The shipped example accents Checkout → Auth — the skip that will hurt a split — not the package with the most edges.
58
+ - **Stroke, not fill.** An arc is a line. Filling it turns a skip into a wedge.
59
+ - **The nodes stay ink.** Accent lives on the skip, matching the parent's rule that the cycle is the accent and the nodes it touches are not.
60
+
61
+ #### Honest-data rule
62
+
63
+ **Arc height is the seat count, on one shared pitch.** `scripts/verify-arc-diagram.py` gates it.
64
+
65
+ - **One baseline, one pitch.** A node off the rail, or a seat that is a different width from its neighbours, makes two spans of the same count draw at two heights.
66
+ - **`data-span` equals `|i−j|`.** Declaring 2 for a five-seat skip, or drawing a neighbour at a skip's radius, is the type's unforgivable error.
67
+ - **Endpoints are the named nodes.** A path that names Auth and Checkout but lands on Catalog is a different import.
68
+ - **Direction reads off the rail.** Every muted arc runs left to right: its left seat imports its right one, so order the rail by import direction and say so in the caption. The one import against the rail is the accent arc, with a small accent arrowhead on the package it imports. Arrowheads on every arc would pile up at shared seats, where each arc lands vertically.
69
+
70
+ #### Declaring the values
71
+
72
+ **Every arc is bound to the two nodes it joins and the span it encodes.** `data-span` on a `<path>` is the arc-diagram contract — deliberately not `data-value` on a `<circle>` (beeswarm), `data-size` (bubble), `data-series` (slopegraph) or `data-ranks` (bump), so no sibling checker claims an arc-diagram file and this one claims none of theirs.
73
+
74
+ ```svg
75
+ <!-- Seat rail at y=400, pitch 140. Auth is seat 1, Checkout is seat 6. -->
76
+ <circle data-name="Auth" cx="220" cy="400" r="6"/>
77
+ <circle data-name="Checkout" cx="920" cy="400" r="6"/>
78
+ <path data-from="Checkout" data-to="Auth" data-span="5"
79
+ d="M 220,400 A 350,350 0 0 1 920,400"
80
+ fill="none" stroke="{accent}" stroke-width="1.6"/>
81
+ ```
82
+
83
+ What each binding buys, and what it costs to omit:
84
+
85
+ | Binding | Without it |
86
+ |---|---|
87
+ | `data-span` on the path | A decorative tall arc on a neighbour could not be caught — the drawn radius would be the only statement of the skip. |
88
+ | `data-from` / `data-to` | A path that names two packages but lands on two others still looks like their import. |
89
+ | `data-name` on the node circle and its label | Two labels exchanged along the rail rename both packages, with every span still correct in isolation. |
90
+
91
+ `scripts/verify-arc-diagram.py` derives the pitch from the nodes, requires a rising semicircle whose radius matches both the endpoint distance and `pitch · span / 2`, refuses a second accent arc or a muted arc that imports leftward, and checks every bound label against the node it names; `scripts/test-verify-arc-diagram.py` proves each check in both polarities and pins the sibling scope treaty in both directions.
92
+
93
+ **Nothing may position a mark except its own attributes.** The checker reads raw `cx`/`d`/`x`, so anything applied afterwards invalidates the check that passed. Every carrier is refused — the `transform` attribute, an inline `style="…"`, and a rule in a `<style>` block — on a node, on an arc, on a bound label, or on an ancestor `<g>`/`<svg>`. Bake the offset into the coordinates.
94
+
95
+ **Nothing may paint or hide a mark except its own attributes.** A `<style>` rule outranks every presentation attribute, so the checker refuses one that sets `stroke` or `fill`, and one that hides or resets (display, visibility, zero opacity, zero stroke width or `all`) the diagram's `<svg>`, anything inside it, or an element around it. A rule for page-only chrome, such as `.footer{display:none}` or a logo, is fine. The accent arc is read as the shipped orange or the active `--color-accent` set by a rule that reaches the diagram. Give each import its own literal `stroke`.
96
+
97
+ #### Anti-patterns
98
+
99
+ - Drawing a neighbour at a skip's height — the type's one unforgivable error.
100
+ - A ranked layout, a cycle routed around the stack, or fan-in badges (those are the parent).
101
+ - Filling an arc, or using sweep 0 so the import hangs under the seats.
102
+ - Uneven spacing so that height no longer equals span.
103
+ - A hue per edge instead of one muted treatment plus a single accent.
104
+ - Positioning a mark, a bound label or an ancestor group from CSS.
105
+
40
106
  ## Examples
41
107
 
42
108
  - `assets/example-dependency.html` — minimal light
43
109
  - `assets/example-dependency-dark.html` — minimal dark
44
110
  - `assets/example-dependency-full.html` — full editorial
111
+ - `assets/example-arc-diagram.html` — arc diagram, minimal light
112
+ - `assets/example-arc-diagram-dark.html` — arc diagram, minimal dark
113
+ - `assets/example-arc-diagram-full.html` — arc diagram, full editorial
@@ -0,0 +1,36 @@
1
+ # Event modeling
2
+
3
+ **Best for:** showing how commands, resulting domain events, and read models relate across ordered business stages. Use it when the supplied scenario names those elements and their links. The horizontal axis is scenario order unless timestamps or durations are supplied. An illustrative example must say so.
4
+
5
+ **Not this type:** Use [Sequence](type-sequence.md) for actor lifelines, message calls, and replies in temporal order. Use [Data flow](type-data-flow.md) for movement or transformation between systems when commands and resulting events are not the question. Use [Timeline](type-timeline.md) for dated occurrences without command and projection roles. Do not infer an event store, broker, or persistence mechanism from this view.
6
+
7
+ Keep the shipped SVG static: place each paper rectangle behind its own labels, use explicit house ink and readable text, and keep page styles off SVG marks. The verifier checks this bounded layout; the browser render gate checks the shipped pages. Draw each typed arrow with visible, nonzero straight path segments.
8
+
9
+ ## Layout grammar
10
+
11
+ - Arrange numbered stages left to right. Align **Command**, **Event**, and **Read model** in three fixed horizontal lanes. Within each stage, the command sits above the resulting event, and the read model sits below it.
12
+ - A command is an intent/request, named as an imperative. An event is a fact that occurred, named in past tense. A read model is a view or projection, not another event. Show each role explicitly in text and metadata.
13
+ - Draw a directed `emits` link from command to event and a directed `projects` link from event to read model. The diagram claims these links only when supplied by the source. If a link is unknown, label the gap; do not silently connect unrelated marks.
14
+ - Stage order does not encode elapsed time. Do not space stages proportionally to time without a measured axis. If a stage branches, split the scenario or use [Flowchart](type-flowchart.md) for the decision.
15
+
16
+ ### Machine-readable contract
17
+
18
+ Put `data-diagram-type="event-modeling"` on the accessible SVG. Each stage is a group with `data-event-stage="STAGE-ID"`, a unique ID, `data-stage-order` starting at `1`, and `data-diagram-role="timeframe"`. Each role node has `data-event-kind="command|event|read-model"`, a unique `data-event-id` printed in the node, and a matching `data-diagram-role`. Each link has `data-diagram-role="event-link"`, `data-event-rel="emits|projects"`, `data-from`, and `data-to` pointing to IDs in that stage. `scripts/verify-event-modeling.py` checks this structural contract for the shipped examples; it does not establish that an illustrated business event happened.
19
+
20
+ ## Complexity budget
21
+
22
+ - At most six stages. The overview uses one command, one event, and one read model per stage. Split richer scenarios into overview and detail views instead of shrinking labels.
23
+ - At most two accent uses. The event and link labels must carry meaning without color.
24
+
25
+ ## Anti-patterns
26
+
27
+ - Commands and events in the same lane, or an event named as a future instruction.
28
+ - A left-to-right stage layout presented as measured duration.
29
+ - A read model shown as proof of persistence, delivery guarantee, or test coverage.
30
+ - A generic producer-broker-consumer flow renamed as event modeling with no commands or projections.
31
+
32
+ ## Examples
33
+
34
+ - `assets/example-event-modeling.html` — minimal light, illustrative three-stage scenario.
35
+ - `assets/example-event-modeling-dark.html` — the same scenario on the dark skin.
36
+ - `assets/example-event-modeling-full.html` — full editorial page with reading notes.