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.
- package/CHANGELOG.md +51 -0
- package/README.md +31 -1
- package/SHIPPED.md +1 -1
- package/adapters/bob/README.md +12 -1
- package/adapters/opencode/README.md +2 -1
- package/adapters/opencode/plugins/geneseed-context.js +71 -10
- package/adapters/opencode/plugins/geneseed-guard.js +101 -19
- package/adapters/opencode/plugins/geneseed-learn.js +641 -6
- package/bin/geneseed-cli.mjs +3 -0
- package/bin/geneseed-hook.mjs +2 -1
- package/docs/concepts/agents.md +13 -1
- package/docs/concepts/enforcement-table.md +1 -1
- package/docs/concepts/foreman-mode.md +22 -3
- package/docs/concepts/hook-gates.md +1 -1
- package/docs/concepts/hooks.md +22 -5
- package/docs/concepts/host-matrix.md +2 -2
- package/docs/concepts/hosts.md +1 -1
- package/docs/concepts/shared-tier.md +1 -1
- package/docs/concepts/skills.md +21 -1
- package/docs/concepts/themes.md +1 -1
- package/docs/extending.md +11 -2
- package/docs/guides/install-clone.md +18 -0
- package/docs/guides/install-scripted.md +8 -2
- package/docs/guides/install.md +19 -1
- package/docs/guides/upgrade.md +1 -1
- package/docs/reference/env-context.md +1 -1
- package/docs/reference/environment.md +1 -1
- package/docs/reference/plugin-learn.md +4 -0
- package/docs/reference/profiles.md +226 -0
- package/docs/token-footprint.md +9 -4
- package/docs/understand/design-choices-engineering.md +1 -1
- package/docs/web-ui.md +3 -1
- package/harness.config.json +1 -1
- package/js/README.md +9 -2
- package/js/build/args.mjs +4 -3
- package/js/build/catalog.mjs +11 -1
- package/js/build/driver.mjs +42 -11
- package/js/build/emit-claude.mjs +24 -1
- package/js/build/emit-opencode.mjs +3 -0
- package/js/build/export.mjs +12 -17
- package/js/build/generate.mjs +2 -1
- package/js/build/notes-migrate.mjs +99 -0
- package/js/build/profile.mjs +14 -6
- package/js/build/render.mjs +34 -10
- package/js/build/source.mjs +85 -2
- package/js/cli-table.json +164 -4
- package/js/hosts/agent-runs.mjs +205 -0
- package/js/hosts/done-checks.mjs +3 -1
- package/js/hosts/hooks-done.mjs +91 -16
- package/js/hosts/hooks-learn.mjs +85 -0
- package/js/hosts/hooks-prims.mjs +39 -1
- package/js/hosts/hooks.mjs +10 -4
- package/js/hosts/hosts.mjs +10 -0
- package/js/hosts/installs.mjs +25 -1
- package/js/hosts/link.mjs +45 -10
- package/js/hosts/native.mjs +42 -5
- package/js/hosts/opencode.mjs +1 -1
- package/js/hosts/settings.mjs +72 -0
- package/js/hosts/spec-feedback.mjs +538 -0
- package/js/hosts/usage.mjs +67 -8
- package/js/inspect/agent-scores.mjs +118 -0
- package/js/inspect/checks-authoring.mjs +2 -1
- package/js/inspect/checks-build.mjs +20 -4
- package/js/inspect/checks-repo.mjs +27 -2
- package/js/inspect/cost.mjs +6 -5
- package/js/inspect/diff.mjs +25 -5
- package/js/inspect/doctor.mjs +4 -0
- package/js/inspect/status.mjs +3 -1
- package/js/inspect/validate.mjs +1 -0
- package/js/lib/machine-dir.mjs +8 -0
- package/js/lib/paths.mjs +4 -1
- package/js/maintain/profile-scope.mjs +145 -0
- package/js/maintain/profiles.mjs +486 -0
- package/js/maintain/setup.mjs +409 -15
- package/js/maintain/uninstall.mjs +4 -1
- package/js/maintain/update.mjs +1 -1
- package/js/web/actions.mjs +28 -38
- package/js/web/api.mjs +7 -2
- package/js/web/handler.mjs +8 -0
- package/js/web/jobs.mjs +5 -4
- package/js/web/profiles-api.mjs +201 -0
- package/js/web/routes.mjs +5 -0
- package/package.json +2 -1
- package/profiles/autonomous.json +14 -0
- package/profiles/corporate.json +14 -0
- package/profiles/guillaume-claude-global.json +16 -0
- package/profiles/mentor.json +13 -0
- package/profiles/minimal.json +15 -0
- package/profiles/starter.json +14 -0
- package/src/AGENT.md.tmpl +1 -1
- package/src/agents/_self-improvement.md +15 -7
- package/src/agents/_template.md +4 -2
- package/src/agents/advocate.md +1 -1
- package/src/agents/architect.md +1 -1
- package/src/agents/developer.md +10 -3
- package/src/agents/devops-engineer.md +7 -6
- package/src/agents/docker-expert.md +1 -1
- package/src/agents/docs.md +1 -1
- package/src/agents/empiricist.md +1 -1
- package/src/agents/explorer.md +4 -2
- package/src/agents/framer.md +1 -1
- package/src/agents/historian.md +1 -1
- package/src/agents/kubernetes-specialist.md +4 -2
- package/src/agents/memory-curator.md +1 -1
- package/src/agents/operator.md +1 -1
- package/src/agents/performance.md +1 -1
- package/src/agents/pragmatist.md +1 -1
- package/src/agents/react-engineer.md +1 -1
- package/src/agents/react-reviewer.md +1 -1
- package/src/agents/researcher.md +1 -1
- package/src/agents/reviewer.md +10 -3
- package/src/agents/security.md +1 -1
- package/src/agents/skeptic.md +1 -1
- package/src/agents/spring-boot-engineer.md +4 -4
- package/src/agents/spring-reviewer.md +5 -3
- package/src/agents/spring-security.md +1 -1
- package/src/agents/steward.md +1 -1
- package/src/agents/tester.md +4 -2
- package/src/agents/user-advocate.md +1 -1
- package/src/agents/visionary.md +1 -1
- package/src/memory/README.md +12 -2
- package/src/modes/foreman.md +23 -10
- package/src/skill-descriptions.json +63 -0
- package/src/skills/_self-improvement.md +42 -26
- package/src/skills/_template.md +3 -1
- package/src/skills/brainstorm.md +35 -22
- package/src/skills/codebase-design.md +2 -2
- package/src/skills/daydream/VENDOR.md +6 -0
- package/src/skills/diagram-design/SKILL.md +12 -7
- package/src/skills/diagram-design/VENDOR.md +23 -14
- package/src/skills/diagram-design/references/layout-budget.md +7 -1
- package/src/skills/diagram-design/references/onboarding.md +1 -1
- package/src/skills/diagram-design/references/primitives-core.md +1 -1
- package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
- package/src/skills/diagram-design/references/style-guide.md +1 -1
- package/src/skills/diagram-design/references/type-dependency.md +69 -0
- package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
- package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
- package/src/skills/diagram-design/references/type-sbgn.md +80 -0
- package/src/skills/diagram-design/references/type-scatter.md +1 -1
- package/src/skills/diagram-design/references/type-steps.md +180 -0
- package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
- package/src/skills/explain-changes/VENDOR.md +5 -1
- package/src/skills/geneseed-code-review.md +2 -1
- package/src/skills/parallel-agents.md +12 -1
- package/src/skills/pipeline.md +3 -3
- package/src/skills/plan.md +5 -4
- package/src/skills/react-view-transitions/AGENTS.md +26 -26
- package/src/skills/react-view-transitions/SKILL.md +1 -1
- package/src/skills/react-view-transitions/VENDOR.md +19 -4
- package/src/skills/release.md +7 -2
- package/src/skills/rule/approve.md +2 -1
- package/src/skills/skill-forge.md +5 -3
- package/src/skills/spring-boot/cloud.md +19 -1
- package/src/skills/spring-boot/logging.md +5 -3
- package/src/skills/spring-boot/web.md +27 -2
- package/src/skills/spring-boot.md +4 -2
- package/src/skills/spring-data-jpa.md +18 -4
- package/src/skills/spring-testing.md +4 -0
- package/src/skills/token-report/VENDOR.md +5 -1
- package/src/upstreams.json +6 -6
- package/themes/README.md +3 -1
- package/web/dist/assets/{ActiveLoops-BJJN3P-V.js → ActiveLoops-DOJCPPPc.js} +1 -1
- package/web/dist/assets/{Activity-D2kOc3yi.js → Activity-bUSPM3Dl.js} +1 -1
- package/web/dist/assets/{ActivityDetail-By3xOr21.js → ActivityDetail-AHRoXeFN.js} +1 -1
- package/web/dist/assets/{Bonsai-CBWDTBA4.js → Bonsai-B5XY9pid.js} +1 -1
- package/web/dist/assets/{CopyButton-BVbpriMB.js → CopyButton-C0wwRR9H.js} +1 -1
- package/web/dist/assets/{Dashboard-CIJLPHM9.js → Dashboard-DPAA96EI.js} +2 -2
- package/web/dist/assets/{Docs-CiRRIELs.js → Docs-CpGDq165.js} +1 -1
- package/web/dist/assets/{Factories-DhyK0O8d.js → Factories-cNhETa5Q.js} +1 -1
- package/web/dist/assets/{GreenhouseView-DW3PgTPy.js → GreenhouseView-DO3ADmT9.js} +1 -1
- package/web/dist/assets/Installs-D3dDyq10.js +3 -0
- package/web/dist/assets/{JournalView-O65qEWfp.js → JournalView--W-Lw_V9.js} +1 -1
- package/web/dist/assets/{Kits-C5U-yT6Z.js → Kits-ChfehxY6.js} +1 -1
- package/web/dist/assets/Laws-CNxYmV36.js +4 -0
- package/web/dist/assets/{LibRows-D6-CVa3K.js → LibRows-CiPvsRYB.js} +1 -1
- package/web/dist/assets/{Library-CzPlerd6.js → Library-BxQvbwVU.js} +1 -1
- package/web/dist/assets/{Loops-CqNF_-nS.js → Loops-DAblKkyq.js} +1 -1
- package/web/dist/assets/{OperatorHudView-BNr8K5qj.js → OperatorHudView-QtSaSyYm.js} +1 -1
- package/web/dist/assets/{Personal-DeDb9e8O.js → Personal-DxSGv638.js} +1 -1
- package/web/dist/assets/{Settings-B8MPN_AD.js → Settings-CgTbhvRv.js} +1 -1
- package/web/dist/assets/{Tabs-DJzAez4h.js → Tabs-Cf4X1hdz.js} +1 -1
- package/web/dist/assets/api-CZ-x0iWG.js +1 -0
- package/web/dist/assets/{controls-D4wmg_pl.js → controls-CK7qHA8H.js} +1 -1
- package/web/dist/assets/{index-BL3P-9Rg.js → index-B_pTwZra.js} +4 -4
- package/web/dist/assets/index-CzfImiYb.css +1 -0
- package/web/dist/index.html +3 -3
- package/web/dist/assets/Installs-B6nlo-Ly.js +0 -3
- package/web/dist/assets/Laws-CuTw_XNf.js +0 -4
- package/web/dist/assets/api-DLDVY3K-.js +0 -1
- 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
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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.
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`situation:` bounds where the
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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 —
|
|
36
|
+
- No friction, nothing learned — no line; this loop earns no ceremony. Most
|
|
29
37
|
runs end here.
|
|
30
38
|
<!-- LEAN:else -->
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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 -->
|
package/src/skills/_template.md
CHANGED
|
@@ -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.
|
package/src/skills/brainstorm.md
CHANGED
|
@@ -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"
|
|
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
|
|
20
|
-
|
|
21
|
-
|
|
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
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
(
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
47
|
-
trade-offs, leading with your
|
|
48
|
-
|
|
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/`)
|
|
53
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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/` (
|
|
30
|
-
~
|
|
31
|
-
`references/primitive-icons.md` already holds);
|
|
32
|
-
`references/export-registry.md` (the Python/Playwright export
|
|
33
|
-
(Python and host-plugin diagnostics);
|
|
34
|
-
`references/import-mermaid.md
|
|
35
|
-
Python extractors). Upstream's
|
|
36
|
-
`docs/`, the repository-level
|
|
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
|
|
51
|
-
list of source formats, and step 1 reads the source file as text instead of
|
|
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
|
|
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;
|
|
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
|
|
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
|
|
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.
|