@teurons/vds-diagrams 0.0.0-stage → 0.3.0

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 (51) hide show
  1. package/README.md +170 -2
  2. package/dist/cli.js +2244 -0
  3. package/dist/diagrams.css +991 -0
  4. package/dist/grid.d.ts +1 -0
  5. package/dist/grid.js +283 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2044 -0
  8. package/dist/skills/vds-aggregates/SKILL.md +115 -0
  9. package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
  10. package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
  11. package/dist/skills/vds-build-from-published/SKILL.md +89 -0
  12. package/dist/skills/vds-change/SKILL.md +113 -0
  13. package/dist/skills/vds-context-map/SKILL.md +125 -0
  14. package/dist/skills/vds-contexts/SKILL.md +134 -0
  15. package/dist/skills/vds-diagrams/SKILL.md +88 -0
  16. package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
  17. package/dist/skills/vds-language/SKILL.md +106 -0
  18. package/dist/skills/vds-model-review/SKILL.md +123 -0
  19. package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
  20. package/dist/skills/vds-publish/SKILL.md +123 -0
  21. package/dist/skills/vds-reframe/SKILL.md +122 -0
  22. package/dist/skills/vds-requirements/SKILL.md +128 -0
  23. package/dist/skills/vds-requirements-review/SKILL.md +121 -0
  24. package/dist/skills/vds-scenarios/SKILL.md +142 -0
  25. package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
  26. package/dist/skills/vds-story-walk/SKILL.md +128 -0
  27. package/dist/skills/vds-strip-invented/SKILL.md +130 -0
  28. package/dist/skills/vds-subdomains/SKILL.md +127 -0
  29. package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
  30. package/dist/skills/vds-which-skill/SKILL.md +125 -0
  31. package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
  32. package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
  33. package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
  34. package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
  35. package/dist/types/diagrams/src/grid/index.d.ts +5 -0
  36. package/dist/types/diagrams/src/grid/input.d.ts +93 -0
  37. package/dist/types/diagrams/src/grid/route.d.ts +21 -0
  38. package/dist/types/engine/js/bridge.d.ts +12 -0
  39. package/dist/types/engine/js/index.d.ts +73 -0
  40. package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
  41. package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
  42. package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
  43. package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
  44. package/dist/types/vds-diagrams/src/index.d.ts +6 -0
  45. package/dist/types/vds-diagrams/src/types.d.ts +39 -0
  46. package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
  47. package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
  48. package/dist/vds_engine.wasm +0 -0
  49. package/dist/workspace.d.ts +1 -0
  50. package/dist/workspace.js +113 -0
  51. package/package.json +68 -3
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: vds-aggregates
3
+ description: "Aggregate and module (MOD) in a VDS bounded context's model: consistency boundaries, their root, and which aggregate owns each domain event. Use when deciding one aggregate or two, when a capability's event has no aggregate yet, when an aggregate grows or lists no invariant, or when aggregates need grouping into modules. Commands, events and read models from a requirement belong to vds-slice-blocks; root and value detail to vds-entities-and-values; judging the finished model to vds-model-review."
4
+ ---
5
+
6
+ # Aggregates
7
+
8
+ Draw each aggregate around the rules that must hold together after one command, keep it as small as those rules allow, and file every domain event under the aggregate whose command produced it.
9
+
10
+ Use it in tactical modeling (Vernon), once a step's requirement, scenarios, command and events exist. vds-slice-blocks owns deriving the command, events and read model. vds-entities-and-values owns the root's identity, attributes and value objects. vds-ports-and-adapters owns what sits outside the model. vds-contexts owns where the context's boundary goes. vds-model-review judges the result. The developer decides the model; ask one question at a time.
11
+
12
+ ## Method
13
+
14
+ 1. List the true invariants. From the capability's requirements, take each rule that must be true right after one command (Vernon p353: "a business rule that must always be consistent"). Done when every candidate rule is a requirement id, or a hot spot through vds-ask-or-park.
15
+ 2. Decide the boundaries with the table below, one pair of things at a time. Done when every rule from step 1 sits in exactly one aggregate's `invariants:`.
16
+ 3. Name the root. One entity per aggregate is its root (p380), and its `commands:` lists the commands this aggregate handles, exactly one of them with `creates: true`. This skill decides that list; vds-entities-and-values writes the rest of the entity (`why`, identity, attributes). Done when each command of the step sits on exactly one root.
17
+ 4. Reference other aggregates by identity. Write `refers_to:` with the other aggregate and the value object that carries its id (p361). Done when no aggregate holds another aggregate's entity.
18
+ 5. File each event. A domain event sits in the folder of the aggregate whose root lists the command that `produces:` it (p289: the event states what occurred in that aggregate). Done when every event of the step sits under an aggregate, or stays in the capability's events with a reason.
19
+ 6. Group into modules. One module holds one or a few aggregates that belong together (p334), named with a term from the context's language. Done when every aggregate's `module:` matches the module it sits in.
20
+ 7. Land it. The check refuses an aggregate whose root entity has no file, so run vds-entities-and-values steps 2 and 3 on the root first; it drafts the entity and writes nothing. Then this skill lands one checked change (`vds apply --base <rev>`): the module, the aggregate, the root entity, the language terms that name them, and each event moved (its new path with the text, its old path with `null`). Done when the check reports valid and no command touched is listed as "on no Entity".
21
+
22
+ ## One aggregate or two
23
+
24
+ Ask in order; the first answer that says two ends it.
25
+
26
+ | # | Question | Two when | Source |
27
+ |---|---|---|---|
28
+ | 1 | Is there a rule that involves both and must be true right after one command? | no such rule | p353-354 |
29
+ | 2 | Is it the job of the person running the command to make both consistent? | it is another person's job, or the system's | p367 (Evans) |
30
+ | 3 | Do different people or the system change them at the same time? | yes | p350-351, p373 |
31
+ | 4 | Would one boundary hold a list that only grows? | yes | p356 |
32
+ | 5 | None of the above says two | one aggregate | p355 |
33
+
34
+ Two aggregates are kept consistent later, by an event (p364-365). Ask the person how long a delay is acceptable and record it in a scenario (p359). Do not settle that delay yourself.
35
+
36
+ ## Rules
37
+
38
+ - **One command changes one aggregate** (p354). A command whose events land in two aggregates means a boundary is wrong or a rule was missed (p360).
39
+ - Keep the aggregate to the root and the fewest attributes its rules need (p356-357). A large cluster fails under concurrent use (p350).
40
+ - An entity besides the root goes in the aggregate's folder only when a rule of the aggregate needs it changed in the same transaction as the root; outside code reaches it only through the root. Otherwise it is its own aggregate, referred to by identity (`refers_to`).
41
+ - A rule that only developers want is a false invariant (p351). Every `invariants:` entry is a requirement someone stated.
42
+ - A requirement that keeps two aggregates consistent at once may be missing a rule (p359). Ask before you merge them.
43
+ - Name the module for what its aggregates mean; never for a kind of file (p334).
44
+ - Rename or split a module when the model changes (p335).
45
+
46
+ Right: a small aggregate that names its rule and points at the investor by id.
47
+ ```yaml
48
+ id: AGG-AUTH--session
49
+ name: Session
50
+ module: MOD-AUTH--access
51
+ root: ENT-AUTH--session
52
+ invariants: [REQ-AUTH-0026]
53
+ refers_to:
54
+ - aggregate: AGG-AUTH--investor
55
+ by: VO-AUTH--investor-id
56
+ ```
57
+ Wrong: one aggregate for the signup screens, holding every rule of the step and referring by a bare attribute. The check refuses `by: investorId`.
58
+ ```yaml
59
+ id: AGG-AUTH--signup
60
+ name: Signup
61
+ root: ENT-AUTH--investor
62
+ invariants: [REQ-AUTH-0011, REQ-AUTH-0015, REQ-AUTH-0019, REQ-AUTH-0026]
63
+ refers_to:
64
+ - aggregate: AGG-AUTH--mpin-credential
65
+ by: investorId
66
+ ```
67
+
68
+ Right: Code Locked sits under Attempt Counter, whose root lists Count Failure, the command that produces it.
69
+ ```yaml
70
+ # root of the attempt counter
71
+ commands:
72
+ - command: CMD-AUTH--count-failure
73
+ creates: true
74
+ ```
75
+ Wrong: the same event filed under Investor because "the investor is locked". The check may refuse it only indirectly, when the event takes an attribute from the wrong aggregate (`Code Locked.subject: no command supplies it`); catch it yourself by reading which root lists the producing command.
76
+
77
+ Right module, as in the example:
78
+ ```yaml
79
+ # Knows nothing about who is verified or why, so transactions and distributor signup can use it.
80
+ id: MOD-AUTH--verification
81
+ name: Verification
82
+ ```
83
+ Wrong: `name: Aggregates` or `name: Signup Screens`. A module named for a file kind or a screen tells nothing of the model, and the check refuses a name the language lacks.
84
+
85
+ ## An event with no aggregate yet
86
+
87
+ The capability's events hold an event the step needs before any aggregate owns it (the example: Security Limits Overridden).
88
+ 1. Find the command that produces it, and the requirement it serves.
89
+ 2. Find a stated rule that the command must keep. None found: leave the event where it is, and park the question with vds-ask-or-park.
90
+ 3. A rule found: walk the table above against the existing aggregates. Move the event into the owning aggregate, list the command on its root, all in one change. A new aggregate also needs its name added to the language first, through vds-language.
91
+
92
+ ## Symptoms
93
+
94
+ | The person says, or the draft shows | Do |
95
+ |---|---|
96
+ | "one aggregate per screen" | draw boundaries from rules; screens read from read models |
97
+ | an aggregate with no `invariants:` | find its rule; none stated, it is no aggregate |
98
+ | one command produces events in two aggregates | walk the table; ask for the missing rule |
99
+ | "it must update straight away" about two things | ask whose job it is (p367), then the acceptable delay |
100
+ | an aggregate whose list of parts only grows | split it; refer by identity |
101
+ | a module named for a kind of file | rename it with a term from the language |
102
+ | the check says "on no Entity" | list the command on the root that owns it |
103
+
104
+ ## Never
105
+
106
+ Never make one aggregate per screen. A screen shows many aggregates through read models; a boundary comes from the rules that must hold together.
107
+
108
+ ## Not covered
109
+
110
+ - An aggregate drawn from code before any story walk: it needs a requirement for its rule and a command that creates the root.
111
+
112
+ - The check refuses: an aggregate with no invariant, an invariant that is no requirement id, `refers_to` by anything but a value object, an aggregate outside its module's folder, an entity outside any aggregate's folder, a root that sits in another aggregate's folder, a module that holds neither an aggregate nor a value object, and a name the language lacks. It does not check that an event sits under the aggregate that produces it.
113
+ - Factories, repositories and domain services have no file in spec 0.1. Vernon's event modeled as its own aggregate (ch. 8, p294) has no field either.
114
+ - Concurrency and storage mechanics (p385-387) are architecture; the notes mark them `[arch]`.
115
+ - The notes give no rule for how small a module must be beyond "one or a few aggregates" (p334).
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: vds-ask-or-park
3
+ description: "Hot spot: what the agent does at any gap in a VDS spec. Use when a step, rule, limit, failure or term has no answer from a person; when deciding whether to ask now, park it or stop; when writing or closing a hot spot; when an engine open question needs a person. To trace written requirements to a source use vds-strip-invented; to walk the story use vds-story-walk; when the premise is wrong use vds-reframe."
4
+ ---
5
+
6
+ # Ask or park
7
+
8
+ At every gap the agent has three moves: ask one question built from a concrete example, park the gap as a hot spot and move on, or stop. **Never fill a gap from the model's own knowledge.**
9
+
10
+ A gap is anything the spec needs that no person has said: a branch, a failure, a limit value, a field, who acts, what a word means. Use this skill in any phase; it is first needed in requirement discovery.
11
+
12
+ Siblings own the neighbours. Walking the story to its end is vds-story-walk. Checking that written requirements trace to something a person said is vds-strip-invented. A person saying the whole premise is wrong is vds-reframe.
13
+
14
+ When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
15
+ ## Hot spot and open question are two things
16
+
17
+ - A hot spot is a file: a question a person raised, or a gap the agent parked because no person answered it. Storming (Brandolini): "visible place-holders for problems not solved yet" (p188).
18
+ - An open question is asked by the engine from the shape of the spec and printed by `vds check` after "valid". Some of its forms: "<event>: nothing follows it; what happens next?", "<command>: one outcome only; what if it fails?", "<flow>: ends on <requirement>, which shows nothing", "<screen>: nothing is tracked here; what should analytics send?", "<context>: no port to <context>".
19
+ - An open question is never copied into a hot spot file. Turn it into a question for the person (step 2). Park it only if the person cannot answer.
20
+
21
+ ## Method
22
+
23
+ 1. **Name the gap.** Say in one line what is missing and which requirement, screen, command or step it sits on. Check first that no person already said it in this session or in a file.
24
+ Done when the gap is one line and has a place in the spec.
25
+ 2. **Choose the move.** Walk the table top to bottom; the first row that fits wins.
26
+
27
+ | The gap | Move |
28
+ |---|---|
29
+ | A person already answered it | none: write their answer |
30
+ | Every next step depends on it, and no one here can answer | stop |
31
+ | The step being written now cannot be written without it, and the person here can answer | ask |
32
+ | It is a branch, failure, limit or detail the walk can pass | park |
33
+ | The person cannot answer, or two questions on it reached no conclusion | park |
34
+ | The session is short of time | park |
35
+
36
+ Done when one move is chosen and the row that chose it can be named.
37
+ 3. **Ask.** One question, built from one concrete case in the person's words: a named person, a value, a moment. Offer no answer inside the question. Wait for the reply before the next question.
38
+ Done when the question names a concrete case and holds one question mark.
39
+ 4. **Park.** Write one hot spot (format below), say in one line to the person what was parked, and continue the walk.
40
+ Done when `vds check` passes with the new file and the walk has moved to the next step.
41
+ 5. **Stop.** Write nothing more. Tell the person what is blocked, the one question that unblocks it, and what is parked so far.
42
+ Done when the person has the question and nothing was written on a guess.
43
+ 6. **Close.** A hot spot becomes addressed only when a person's answer is written into the spec (a requirement, scenario, screen or language term), or a person says it no longer matters. The owning skill writes the answer, then this skill sets `status: addressed` and keeps the text. An answer given at a read-back is recorded the same way afterwards; vds-requirements-review writes nothing.
44
+ Done when the answer can be found in the file it landed in, and the hot spot is still on disk.
45
+
46
+ ## Rules
47
+
48
+ - One question at a time. A person given three questions answers one and the rest are lost.
49
+ - Park rather than argue. A discussion with no conclusion gets a hot spot, so "it won't be forgotten", and the walk moves on (Brandolini p95-96).
50
+ - Under time pressure give up depth before the end of the story (Brandolini p98). Example mapping captures a question nobody can answer so the group can "move on" (research finding 4).
51
+ - Many hot spots on one step mean too much is unknown there (example mapping red cards, finding 4). Tell the person; do not push the step deeper.
52
+ - Point the hot spot at the nearest thing. Cockburn writes the question in the step it belongs to ("4a1. (What do we do here?)", p4). A hot spot on a requirement, its screen or its command shows on that step of the walk.
53
+ - A hot spot with no `on` is about the whole spec or the method (the example's "What is a Process now"), or about a step not written yet. A step that could not be saved in a session is parked this way, so nothing stays only in the conversation.
54
+ - A limit nobody gave a value for never gets a default. A new requirement that needs it is held and the question parked. A limit already written keeps its number (the check needs it) with a hot spot saying nobody gave it.
55
+ - A limit value the person did give, on a step that is held for another reason, goes into the held step's hot spot text with its name and the person's words ("lockMinutes: 15, Ops said so on 2026-11-14"). It moves into `limits:` in the change that saves the step.
56
+ - A hot spot is for an unanswered question only. A saved step whose command, events or read model are not written needs none: `vds check` lists it as not modelled yet.
57
+ - Never delete a hot spot. Done means every hot spot is addressed (Brandolini p184, p188).
58
+ - Never mark a hot spot addressed from the agent's own reasoning. Only a person's answer closes it.
59
+
60
+ ## The hot spot file
61
+
62
+ One file per question, in the capability's hot spots, where it was raised. Fields: `id` (`HOT-<SCOPE>--<slug>`), `text`, `"on"` (optional), `status` (`open` or `addressed`). Quote the `"on"` key, as the example does; the check does not catch a bare one. `vds check` fails if `text` is blank, `status` is anything else, or `on` names an id that does not exist. `on` names any id already written: a requirement, scenario, screen, capability, subdomain, context, people file or model block. For a thing removed or not written yet, point at its screen, or leave `on` out, and name the step in `text`. Write it with `vds_write` (or `vds_apply` for several files) and run `vds check`.
63
+
64
+ Right: the person's question, on the command it was raised at.
65
+
66
+ ```yaml
67
+ id: HOT-AUTH--resend-limit
68
+ text: "Is there a limit on resends?"
69
+ "on": CMD-AUTH--resend-code
70
+ status: open
71
+ ```
72
+
73
+ Wrong: a guessed rule written as the hot spot text, with a bare `on` key.
74
+
75
+ ```yaml
76
+ id: HOT-AUTH--resend-limit
77
+ text: "Resends are limited to 3 per hour."
78
+ on: CMD-AUTH--resend-code
79
+ status: open
80
+ ```
81
+
82
+ Right question: "An investor taps Resend a fourth time within a minute. What happens?"
83
+ Wrong question: "What are the rate limiting and error handling requirements for resend? I would suggest 3 per hour."
84
+
85
+ ## Symptoms
86
+
87
+ | What you see | Do |
88
+ |---|---|
89
+ | A requirement holds a number, a limit or a failure no person said | Take it out; ask or park it. A limit number that statements name stays, with a hot spot |
90
+ | "I don't know, the bank decides that" | Park, on the step; move on |
91
+ | The person answers with a question back | Ask the same case again with one value changed; if still open, park |
92
+ | `vds check` prints open questions after "valid" | Ask each one as a concrete case; park what the person cannot answer |
93
+ | The agent asks three questions in one message | Send the first; hold the rest |
94
+ | A hot spot set to addressed with nothing new in any requirement or scenario | Set it back to open |
95
+ | Every answer the person gives changes the premise | Stop; use vds-reframe |
96
+
97
+ ## Not covered
98
+
99
+ - Who can answer a hot spot, and what the answer was: spec 0.1 has no field for either. The answer lives only in the file it landed in.
100
+ - Voting on or ranking hot spots (Brandolini's problems and opportunities, p101-106).
101
+ - A timebox length for a VDS session: the notes give example mapping's 25 minutes a story, from an article, and nothing for VDS.
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: vds-book-to-spec
3
+ description: Turn a method book (Vernon's DDD, Brandolini's event storming, Dilger's event modeling) into VDS YAML specs, the way the book's DDD page was built. Use when studying a new chapter or method so it becomes part of VDS's spec, when adding a concept page, a spec card or an FAQ to the book (apps/book), or when deciding whether a concept gets its own spec file. For VDS trials and the session routine, use vds-development.
4
+ ---
5
+
6
+ # Book to spec
7
+
8
+ A method enters VDS in this order: read the book, keep notes, teach from
9
+ the notes in one picture, write a YAML spec for each concept, check it
10
+ with an independent agent, then record the decision. The learner (the
11
+ product lead) cannot judge a rule by feel, so the book page is always the
12
+ check. vds-development owns the rules on inventing and mixing methods;
13
+ this skill applies them.
14
+
15
+ ## The output
16
+
17
+ ```
18
+ /Users/rajiv/Projects/Teurons/vds-research/_docs/refs/learn/
19
+ ├── notes/<author>/chNN-<topic>.md terse notes, page-cited
20
+ └── problem-solution-book/examples/<name>.md worked examples, facts from the learner
21
+
22
+ /Users/rajiv/Projects/Teurons/vds/apps/book/
23
+ ├── app/components/ddd/ddd-picture.tsx the one picture (DDD); storming/, modeling/ hold theirs
24
+ ├── app/components/ddd/concepts.ts hover tip + source per part
25
+ ├── app/components/ddd/lessons.tsx Learn tab, FAQS, Reference
26
+ ├── app/components/vds/specs.tsx Spec tab: one card per spec 0.1 file kind, example read
27
+ │ from packages/spec's investor-auth at build
28
+ ├── content/docs/<page>.mdx one page per book
29
+ └── CHANGELOG.md decisions, dated, with the page
30
+ ```
31
+
32
+ One concept, one clickable part, one sheet with two tabs:
33
+
34
+ | Tab | Holds |
35
+ |---|---|
36
+ | Learn | the theory, then that concept's FAQ cards, then a Reference block (book, author, chapter, pages) |
37
+ | Spec | the YAML spec: file path, every field with a one-line meaning, an example |
38
+
39
+ ## Steps, per chapter
40
+
41
+ 1. **Pick one authority.** One book per method: Vernon for DDD, Brandolini
42
+ for event storming, Dilger for event modeling. Look up the page offset
43
+ in vds-development's book table. A second book on the same method is
44
+ parked until the learner asks for it. Read the book's `STATUS.md` in its
45
+ notes folder first, and update it when a chapter's status changes. Done
46
+ when the chapter, book and offset are named.
47
+ 2. **Read the whole chapter.** `pdftotext -f <pdf page> -l <pdf page>`
48
+ over every page, never the opening alone. A Sonnet agent may read and
49
+ write the notes; then you check one page for each finding against the
50
+ PDF yourself. Done when `notes/<author>/chNN-<topic>.md` exists and
51
+ every line in it carries a printed page.
52
+ 3. **Keep the book's hedges.** "Generally", "typically", "in most cases",
53
+ "preferred" stay in the notes and in every page that repeats them. A
54
+ hedge dropped becomes a false absolute. Done when each rule in the
55
+ notes reads as strong as the book, no stronger.
56
+ 4. **Place it before defining fields.** Say where the concept sits:
57
+ problem or solution space, strategic or tactical, inside the model or
58
+ outside it. "Inside the model" means the middle of the hexagon; storage,
59
+ messaging and screens sit outside. Never say "core" for this; core means
60
+ the core subdomain. Done when the picture shows the concept in its place.
61
+ 5. **Draw it into the one picture.** Add it to the page's picture (`ddd-picture.tsx` for DDD) with
62
+ placeholder IDs (BC-A, MOD-A, AGG-A, ENT-A, VO-A). Draw the many as two
63
+ or more boxes. Label every relation with its count in words: "has
64
+ exactly one", "has many", "typically one or a few". Draw each relation
65
+ one way; add the reverse only when it says something new. Done when every
66
+ count in the picture matches a page.
67
+ 6. **Write the Learn tab.** Define it, place it, then how it is done
68
+ (`how-rajiv-learns.md`). One block at a time. No page numbers in the
69
+ text: sources sit in JSX comments and in the Reference block at the end.
70
+ A sentence the notes do not support says "our reading" or goes. Done
71
+ when every sentence maps to a note line or carries the label.
72
+ 7. **One spec per building block, never per surface.** Specs describe the
73
+ method's building blocks, not the wall, board or canvas they are drawn on;
74
+ layout is the canvas's job. If the DDD book already has a spec for a block,
75
+ name it and link it; never write a second one. (2026-11-08: a first storming
76
+ spec stored a "wall" holding every sticky; the product lead rejected it as
77
+ presentation.)
78
+ 8. **Decide whether it gets a file.** A concept gets its own spec file only
79
+ when a team designs one per thing (an Entity, an Aggregate, a Domain
80
+ Event). A concept that serves another adds fields to it: a Factory adds
81
+ `creates` to a command, a Repository adds `finders` to the Aggregate.
82
+ Done when the choice is written down with the page that drove it.
83
+ 9. **Write the spec.** Stripe-style card in `app/components/vds/specs.tsx` (`SpecCard`), its example a real spec 0.1 example file:
84
+ - IDs are `<PREFIX>-{CODE}`, CODE 1-6 uppercase letters, unique inside
85
+ a BC (our convention).
86
+ - Folders follow the model's own grouping: Module, then Aggregate.
87
+ Never a folder per kind (Vernon p.334).
88
+ - Each field names its page or says "our convention".
89
+ - Names are the book's: "Value Object", never "Value".
90
+ Done when every field has a meaning line, a source, and appears in the
91
+ example.
92
+ 10. **Run an independent check.** A Sonnet agent, not the author, checks
93
+ the new Learn text, tip and spec sentence by sentence against the
94
+ notes, and reports over-absolutes, unsourced claims and mixed methods.
95
+ Fix every finding. Done when the agent's list is empty or each item is
96
+ fixed.
97
+ 11. **Ask what was missed.** A second Sonnet agent compares the chapter
98
+ notes with the pages and lists concepts the book teaches that the
99
+ picture and specs leave out. Add them, then check the additions as in
100
+ step 10. Done when every listed gap is added or parked with a reason.
101
+ 12. **Turn every question into an FAQ.** Each question the learner asks
102
+ becomes an entry in `FAQS` with `on: [<concept ids>]`, so it shows only
103
+ on its own concept's Learn tab. No global FAQ page. Done when the
104
+ question is in `FAQS` with its settled answer.
105
+ 13. **Record and commit.** Decisions go in `apps/book/CHANGELOG.md` with the date and
106
+ the page. Commit from the repo root, only your own paths
107
+ (`git commit -- <paths>`), with `pnpm --filter @vds/book build` passing. Done when the tree is clean
108
+ and the CHANGELOG names the next chapter.
109
+
110
+ ## When two methods meet
111
+
112
+ A word one book uses that another book also uses (a storming "command"
113
+ and a model command) is two concepts until a page joins them. Use the
114
+ author's own word for the other method: Brandolini calls the blue sticky
115
+ an action (Introducing EventStorming p.201). Write the bridge as "our
116
+ convention" and record it in the CHANGELOG. Done when the FAQ says which
117
+ book each word comes from.
118
+
119
+ ## The how-many map
120
+
121
+ When the product lead says "draw a how-many map", draw what the DDD book's tactical
122
+ panel shows (`apps/book/app/components/ddd/ddd-picture.tsx`, "Inside one BC"):
123
+
124
+ - **Left, the map:** nested boxes with placeholder IDs (MOD-A, AGG-A, ENT-A, VO-A),
125
+ the many drawn as two or more boxes, labelled relations and arrows, one short
126
+ note per box.
127
+ - **Right, "How many":** one row per relation, `A ── has many ──> B`, "many"
128
+ meaning 0 or more, each count from a page or marked proposal.
129
+ - Relations one way only; the reverse only when it says something new.
130
+
131
+ ## Worked examples
132
+
133
+ A worked example uses the learner's own domain facts and maps each choice
134
+ to a page (`examples/mf-account.md`). The picture keeps placeholder IDs;
135
+ examples live in their own file. Keep an example to the question asked;
136
+ stop before it grows into a second model.
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: vds-build-from-published
3
+ description: "Evidence, and the published scenario flow versions code is built against. Use when a developer or coding agent is asked to build or test something a VDS workspace describes, when tests have run and the run must be recorded with vds evidence, or when the code needs something the published copy does not say. Publishing belongs to vds-publish; changing something published, a missing or wrong scenario included, to vds-change; judging the model to vds-model-review."
4
+ ---
5
+
6
+ # Build from published
7
+
8
+ Build only what the published copy says: each scenario is one test, each model file is one shape in code, and each test run is recorded as evidence.
9
+
10
+ Use it in the build phase, when a person says "build it" or "the tests ran". The code lives outside the workspace; this skill writes nothing in the spec.
11
+ A capability that is not published goes to vds-publish. A gap or a wrong rule goes to vds-ask-or-park or vds-change. A missing or wrong scenario in a published capability goes to vds-change, never straight to vds-scenarios.
12
+
13
+ ## Method
14
+
15
+ 1. **Find what is published.** Run `vds status` (MCP: `vds_status`). It prints the published version (`p1`, or "nothing yet") and each capability as never-published, equal or differs.
16
+ Never-published: stop and tell the person; vds-publish owns the next move. Differs: say so, and build from the published copy all the same.
17
+ Done when you can name the published version and the capability's state.
18
+ 2. **Read the published copy and pin the flow versions.** `vds show` and `vds_show` read the draft only. Read the published copy in the studio with the switch on Published (`vds run local`), or from the files `vds publish` keeps inside the workspace under `.vds/published/<version>/`: the spec as published, the compiled scenario flows, and `flows.json` with each flow's versions.
19
+ Write down each scenario flow you build as id and version: `DGSF-AUTH-5b88996a version 1`.
20
+ Done when every flow in scope has an id and a version, and no file you read came from the draft.
21
+ 3. **Write one test per scenario.** Each step of a published scenario flow carries its requirement, its scenario lines (Given, When, Then), its screen, command, read models, events and limits. Given sets up the events, When sends the command, Then asserts the outcome. Put the scenario id in the test's name.
22
+ Done when every scenario in the pinned flows has exactly one test, and every such test names one scenario id.
23
+ 4. **Implement the shapes.** Commands, domain events, read models, aggregates, entities and value objects become code with the same attributes and types. Take every name from the model files and the context's ubiquitous language. A limit keeps its name (`resendAfterSeconds`); the declaring requirement holds a default only, so nothing may assume the number.
24
+ Done when every name in the code traces to a published file or a term.
25
+ 5. **Send gaps back.** When the code needs a field, a rule, a failure or a value the published copy does not say, stop that piece. Hand it to vds-ask-or-park as a hot spot, or to vds-change when the published copy is wrong. Go on with the pieces that have no gap.
26
+ Done when no decision about behaviour was made in code.
27
+ 6. **Record the run.** Have the test runner write a JUnit XML or Vitest/Jest JSON report, then run `vds evidence <report> [folder] [--env <name>]`. It prints "N scenarios recorded in <file>; M tests matched no scenario".
28
+ Done when the recorded count equals the scenarios you tested, and each unmatched test is one you meant to leave without a scenario.
29
+
30
+ ## What `vds evidence` does
31
+
32
+ - A test counts when its name carries a scenario id tagged in a scenario file. In JUnit the classname counts too. `SCN-AUTH-0004-01` and `scn_auth_0004_01` name the same scenario.
33
+ - A scenario with any failed test is failed. A skipped test is left out. A test naming no known scenario is counted as unmatched.
34
+ - One run is one file: when, `env` (default `local`), and each scenario as passed or failed.
35
+ - A file that is no report, or holds no tests, records nothing and exits 1.
36
+
37
+ Gaps today, none fixed here:
38
+
39
+ - Scenario ids are matched against the draft's scenario files. A scenario added to the draft after the publish still gets a result.
40
+ - A run stores no flow id, flow version or published version. Say the pinned versions in your report to the person.
41
+ - No MCP tool records evidence; the CLI is the only way.
42
+ - The studio does not show evidence yet. It is planned (`.plans/architecture.md` 2.2); the run file is the record.
43
+
44
+ ## Right and wrong
45
+
46
+ Wrong, no scenario id, two scenarios in one test, the number assumed:
47
+
48
+ ```ts
49
+ it('resend works and is blocked before 30 seconds', async () => { /* ... */ });
50
+ ```
51
+
52
+ Right, one test per scenario, id in the name, the limit by name:
53
+
54
+ ```ts
55
+ it('SCN-AUTH-0004-01 resend after resendAfterSeconds', async () => { /* ... */ });
56
+ it('SCN-AUTH-0004-02 no resend before resendAfterSeconds', async () => { /* ... */ });
57
+ ```
58
+
59
+ Wrong, a name and a field nobody published (the term is Code; the command has `channel` only):
60
+
61
+ ```ts
62
+ type ResendOtp = { channel: Channel; deviceId: string };
63
+ ```
64
+
65
+ Right, the command as the model file has it (`CMD-AUTH--resend-code`, attribute `channel: VO-AUTH--channel`, produces `EVT-AUTH--code-resent`):
66
+
67
+ ```ts
68
+ type ResendCode = { channel: Channel };
69
+ ```
70
+
71
+ ## Symptoms
72
+
73
+ | What you see or hear | Do |
74
+ |---|---|
75
+ | "just build from what's in the files now" | run `vds status`; build from the published copy, name what differs |
76
+ | the capability is never-published | stop; vds-publish |
77
+ | the code needs a field, failure or value the spec lacks | stop that piece; vds-ask-or-park or vds-change |
78
+ | a rule has no scenario to test, or its scenario is wrong | vds-change, which reruns vds-scenarios; then a new publish |
79
+ | "0 scenarios recorded" | the test names carry no known scenario id; rename and rerun |
80
+ | a test covers two scenarios | split it; one would hide the other's failure |
81
+
82
+ Never build against the draft.
83
+
84
+ ## Not covered
85
+
86
+ - Book pages: none. Build and evidence are VDS's own (language sections 1 and 3); the notes were not read for this skill.
87
+ - Which test runner, folder layout or architecture the code uses.
88
+ - Hosted evidence through an API: planned, not built.
89
+ - Pruning old published versions.
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: vds-change
3
+ description: "Change to something published in a VDS workspace. Use when a person says 'this has to change' about a published requirement, scenario, limit, step, term, boundary or model block, or when a capability shows 'differs' with no list why. Classifies it, lists what it touches, reruns the owning skills in order, in the draft only. A wrong premise in a never-published draft belongs to vds-reframe; the publish itself to vds-publish; recording a renamed term to vds-language."
4
+ ---
5
+
6
+ # Change
7
+
8
+ Classify the change, show the person everything it touches, then make it in the draft through the skills that built the material; the published copy moves only at the next publish.
9
+
10
+ Use it when the thing the person points at sits in a capability whose state is `equal` or `differs`. A capability that is `never-published` has nothing published to protect: go straight to the building skill. vds-reframe owns a wrong premise in a capability never published. A wrong premise in a published capability stays here, classed as a premise change: this skill owns it and runs vds-reframe's listing and rebuild steps on the draft only; it is never handed back. vds-publish owns the preview, the person's yes and the publish. The building skills (vds-story-walk to vds-ports-and-adapters) own how each material is written; this skill only orders them.
11
+
12
+ ## Method
13
+
14
+ 1. Confirm it is published. Run `vds status` (MCP: `vds_status`). Done when the capability reads `equal` or `differs`; on `never-published`, leave this skill.
15
+ 2. Restate the change in one sentence: "Today <what is published>. After the change <what holds>." Ask for a yes. Done when the person said yes to that sentence, or corrected it and said yes to the corrected one.
16
+ 3. Classify it with the table. Take every row that fits; a change that fits two rows is two changes, each with its own line. Done when each part has exactly one class.
17
+ 4. Find what it touches. Run `vds show <ID>` (MCP: `vds_show`) on each item named; it lists every file that mentions it. Add the "Touches" column of the class. Done when the list names each requirement, scenario, model block, shared file, other context and other published capability involved, by id.
18
+ 5. Show the list and ask one question: "These change. Go ahead?" Done when the person said yes to the list. Edit nothing before this yes.
19
+ 6. Edit the draft only, through the skills in the "Rerun" column, in that order. Each change lands checked (`vds apply --base <revision>`, MCP: `vds_apply`). Done when `vds check` reports no problem and every item on the list is edited or struck off with a reason.
20
+ 7. Report the state. Run `vds status` again and say what it shows, plus any shared file that changed (see "What the tools show"). Done when the person has heard which capabilities now differ from published.
21
+ 8. Hand on to the reviews, then to vds-publish. A review is needed for each half the change edited (requirements, scenarios and screens; the model); an untouched half needs none. Done when the review skills in the row have been named to run; this skill never publishes.
22
+
23
+ ## Classify
24
+
25
+ Ask the tests top to bottom. "Meaning" is what a scenario's Given, When, Then would have to say.
26
+
27
+ | Class | Test | Touches | Rerun, in order |
28
+ |---|---|---|---|
29
+ | Wording fix | every scenario stays word for word true; no value, step or outcome moves | the title or statement; the scenario file's Feature title when the title changes | vds-requirements, vds-requirements-review, vds-publish |
30
+ | Changed rule or limit value | a Then changes, or a number changes | the requirement, its scenarios, the capability's limits requirement, language terms that name the limit, a field if the rule needs new data | vds-requirements, vds-scenarios, vds-slice-blocks if a field changes, vds-entities-and-values if the rule sits on a value object, vds-requirements-review, vds-model-review if a block changed, vds-publish |
31
+ | New step or outcome | something happens that no requirement or scenario states | a new requirement or scenario, the exits of the step before it, its screen, then its command, events and read model | vds-story-walk, vds-requirements, vds-scenarios, vds-slice-blocks, vds-aggregates if a new event needs an owner, both reviews, vds-publish |
32
+ | Removed step | a requirement or an outcome stops existing | the requirement, its scenario file, every exit that points at its scenarios, each block `vds show` says nothing else mentions | vds-requirements, vds-scenarios, vds-slice-blocks, vds-requirements-review, vds-model-review if a block was removed, vds-publish |
33
+ | Renamed term | the word changes, the meaning stays; a changed meaning is never this row | the language entry, then every statement, scenario, people file and block name that uses the word | vds-language, which records the term and renames it everywhere in one change; then the review of each half the rename touched, vds-publish |
34
+ | Premise change | what the capability is for, who it is for, or what a core term means reads differently | every part vds-reframe's listing step marks hit | vds-reframe's steps 2 to 7, run from here on the draft only; both reviews, vds-publish |
35
+ | Moved boundary | a term, rule or step now belongs to another context | both contexts, the context map, both languages, every capability in either context, commands and events that now cross | vds-contexts, vds-subdomains if a new context serves a new part, vds-context-map, vds-language, vds-slice-blocks, vds-ports-and-adapters, both reviews, vds-publish for every capability touched |
36
+ | Model-only | requirements and scenarios stay word for word; only how it is built changes | commands, events, read models, aggregates, entities, value objects, ports | vds-slice-blocks, vds-aggregates, vds-entities-and-values or vds-ports-and-adapters, whichever owns the block; vds-model-review, vds-publish |
37
+
38
+ ## Rules
39
+
40
+ - Expect the change. Modeling (Dilger): the first flow "won't" be the final one (p66); "change will happen" (p92-93). A change is ordinary work, never a failure to hide.
41
+ - Work forward from the requirement. A rule change that starts in a command leaves the scenarios saying the old rule. Tactical modeling on a step starts after its requirement and scenarios exist.
42
+ - A wording fix that needs a scenario edited is a changed rule. Reclassify and show the longer list.
43
+ - In a premise change the person is asked once: vds-reframe's restated sentence (its step 2) is this skill's step 2, and its shown list (its step 4) is this skill's step 5.
44
+ - Where a row writes a new requirement or scenario, vds-strip-invented runs before vds-requirements-review.
45
+ - Removing or renaming a field on an event breaks whoever reads it; adding an optional field does not (Dilger p93-94). List every read model, automation and other context that reads the event before a field is removed or renamed.
46
+ - A moved boundary updates the context map in the same change: the map shows the present (Vernon p89).
47
+ - A shared file (language, people, aggregate, value object, context map, another context's external event) has one published copy for all capabilities. Name every published capability that uses it on the list.
48
+
49
+ ## What the tools show
50
+
51
+ Read from the code and run on a scratch copy of the example, 2026-11-14.
52
+
53
+ - `vds status` gives each capability one of `never-published`, `equal`, `differs`. It compares only the capability's own files, text for text.
54
+ - A changed shared file leaves the capability on `equal`. It appears only in the publish preview, as "shared files carried". Tell the person yourself in step 7.
55
+ - `vds show` reads the draft only. No command prints the published copy of one item, and no command prints a difference between draft and published.
56
+ - The publish preview lists: scenario flows that change, shared files carried, capabilities removed, the count of open questions.
57
+ - A publish records who, when, the capabilities, the scenario flows that changed, the shared files carried and the open questions. A scenario flow gets its next version number only when its compiled content differs from the last published one.
58
+ - A statement or title edit gives a new version to every scenario flow that passes that requirement. Rewording the first step of the example changed all 8.
59
+ - **A limit value edit gives no new version.** Changing `lockMinutes` from 15 to 30 showed `differs`, and the preview said "scenario flows that change: none". Say this to the person before the hand-off to vds-publish: the published rule will change and no scenario flow number will.
60
+ - A new alternative at a screen can give a scenario flow a new id. The new id starts at version 1; the old id keeps its recorded versions. A flow that disappears is not listed as changed.
61
+
62
+ ## Right and wrong
63
+
64
+ A changed limit value. Right: the value changes once, on the limits requirement; statements keep `{lockMinutes}`.
65
+ ```yaml
66
+ - id: REQ-AUTH-0028
67
+ title: Apply the current limits
68
+ type: nfr
69
+ limits:
70
+ lockAfterWrong: 5
71
+ lockMinutes: 30
72
+ ```
73
+ Wrong: the number written into a statement (the check refuses a bare number with a unit), and the scenarios left untouched.
74
+ ```yaml
75
+ statement: The system SHALL lock for 30 minutes after {lockAfterWrong} wrong codes.
76
+ ```
77
+
78
+ A rule change passed off as wording. Published:
79
+ ```yaml
80
+ statement: The system SHALL accept a mobile number to start signup or login.
81
+ ```
82
+ Wrong, filed as a wording fix: it adds a rule nobody could test before.
83
+ ```yaml
84
+ statement: The system SHALL accept an Indian mobile number to start signup or login.
85
+ ```
86
+ Right: class "changed rule". The list shows REQ-AUTH-0001, a new scenario for a refused number, and the exit that scenario takes; vds-scenarios writes it.
87
+
88
+ ## Symptoms
89
+
90
+ | The person says, or the draft shows | Do |
91
+ |---|---|
92
+ | "just a small tweak" | restate it in one sentence and run the tests; size picks no class |
93
+ | "make it 30 minutes" | changed limit value; warn that no scenario flow version will move |
94
+ | "we don't do that step any more" | removed step; list every exit that points at its scenarios |
95
+ | "call it passcode from now on" | renamed term; show the list, then vds-language renames it everywhere in one change |
96
+ | "that belongs to the payments side" | moved boundary; vds-contexts first |
97
+ | "same behaviour, store it differently" | model-only; requirements and scenarios stay untouched |
98
+ | "you have this wrong", about a draft never published | vds-reframe |
99
+ | "you have this wrong", about something published | premise change; it stays here |
100
+ | a capability on `differs` and no list was ever shown | stop editing; rebuild the list from steps 2 to 5 and show it |
101
+ | the person asks "what did we publish before?" | say no command shows one published item; the published copy is read in the studio's published view |
102
+
103
+ ## Never
104
+
105
+ Never edit a published meaning without a new version. Edit the draft and let the next publish carry it. Never write into the published copy by hand. When the preview will show no scenario flow change for a change in meaning (a limit value), tell the person before vds-publish runs.
106
+
107
+ ## Not covered
108
+
109
+ - "Copy the model and adjust it" as Event Modeling's way to handle change: the research names it with no page, and the Dilger notes do not hold it. Not covered.
110
+ - Dilger's event versioning (p92-98) is about stored and external events in running software. Whether spec 0.1 gives an event file a version: not confirmed. Not covered.
111
+ - Carrying a scenario flow's old versions over to a new id: planned in the architecture notes, absent from the publish code.
112
+ - Undoing a publish, or going back to an earlier published copy: no command.
113
+ - Code and evidence already built against the old version: vds-build-from-published.