@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.
- package/README.md +170 -2
- package/dist/cli.js +2244 -0
- package/dist/diagrams.css +991 -0
- package/dist/grid.d.ts +1 -0
- package/dist/grid.js +283 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2044 -0
- package/dist/skills/vds-aggregates/SKILL.md +115 -0
- package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
- package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
- package/dist/skills/vds-build-from-published/SKILL.md +89 -0
- package/dist/skills/vds-change/SKILL.md +113 -0
- package/dist/skills/vds-context-map/SKILL.md +125 -0
- package/dist/skills/vds-contexts/SKILL.md +134 -0
- package/dist/skills/vds-diagrams/SKILL.md +88 -0
- package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
- package/dist/skills/vds-language/SKILL.md +106 -0
- package/dist/skills/vds-model-review/SKILL.md +123 -0
- package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
- package/dist/skills/vds-publish/SKILL.md +123 -0
- package/dist/skills/vds-reframe/SKILL.md +122 -0
- package/dist/skills/vds-requirements/SKILL.md +128 -0
- package/dist/skills/vds-requirements-review/SKILL.md +121 -0
- package/dist/skills/vds-scenarios/SKILL.md +142 -0
- package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
- package/dist/skills/vds-story-walk/SKILL.md +128 -0
- package/dist/skills/vds-strip-invented/SKILL.md +130 -0
- package/dist/skills/vds-subdomains/SKILL.md +127 -0
- package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
- package/dist/skills/vds-which-skill/SKILL.md +125 -0
- package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
- package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
- package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
- package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
- package/dist/types/diagrams/src/grid/index.d.ts +5 -0
- package/dist/types/diagrams/src/grid/input.d.ts +93 -0
- package/dist/types/diagrams/src/grid/route.d.ts +21 -0
- package/dist/types/engine/js/bridge.d.ts +12 -0
- package/dist/types/engine/js/index.d.ts +73 -0
- package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
- package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
- package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
- package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
- package/dist/types/vds-diagrams/src/index.d.ts +6 -0
- package/dist/types/vds-diagrams/src/types.d.ts +39 -0
- package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
- package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
- package/dist/vds_engine.wasm +0 -0
- package/dist/workspace.d.ts +1 -0
- package/dist/workspace.js +113 -0
- package/package.json +68 -3
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-strip-invented
|
|
3
|
+
description: "Requirements and scenarios of one capability, once written and before any read-back: trace every requirement, scenario, limit value and term to something a person said, and remove or turn into a hot spot whatever has no source. Use after a requirement discovery session, when a draft looks too complete, or when nobody remembers saying a rule. During a live session use vds-ask-or-park; for the read-back and the ready or not-ready report use vds-requirements-review."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Strip invented
|
|
7
|
+
|
|
8
|
+
Every requirement, scenario, limit value and term in a capability traces to something a person said or gave, or it leaves the capability.
|
|
9
|
+
|
|
10
|
+
An agent writing requirements fills gaps with what typical apps do. The result reads as complete and nobody can tell which rules were stated. Event modeling (Dilger) warns that indirect communication "is always 'Stille Post'" (p133): each relay drifts from what the business person said. An invented rule is one more relay with no person at the start.
|
|
11
|
+
|
|
12
|
+
## When to use
|
|
13
|
+
|
|
14
|
+
- After a requirement discovery session, before the person hears the capability read back.
|
|
15
|
+
- Owned by a sibling: the live choice to ask or park during a session is vds-ask-or-park. Writing a requirement or scenario is vds-requirements or vds-scenarios. The read-back and the ready or not-ready report is vds-requirements-review, which runs after this pass.
|
|
16
|
+
- Run it in an agent that did not write the requirements. Review is never run by the agent that wrote the material; the writer reads its own inventions as stated.
|
|
17
|
+
|
|
18
|
+
## Where the source lives
|
|
19
|
+
|
|
20
|
+
The spec has no field for the source of a requirement. Nothing records who said it or in which session, so invented and stated rules look the same in the files. Trace against these, in order:
|
|
21
|
+
|
|
22
|
+
1. The session transcript, or notes the person kept of it.
|
|
23
|
+
2. A document the person gave: a brief, a screenshot, a policy, an email.
|
|
24
|
+
3. An open or addressed hot spot whose text the person gave.
|
|
25
|
+
|
|
26
|
+
Never add a source field or comment to a file to record the trace. Keep the trace in the report you hand on.
|
|
27
|
+
|
|
28
|
+
No transcript and no document: ask the person one question, "Is there a record of the session or a note you wrote?" If there is none, every rule is untraced. Remove nothing. Turn each untraced rule into a hot spot, so the person can confirm or drop it at the read-back.
|
|
29
|
+
|
|
30
|
+
## The pass
|
|
31
|
+
|
|
32
|
+
1. List every item: each requirement statement, each scenario's Given, When and Then lines, each limit name and value, each term a person would read. Done when the list counts every requirement and every scenario in the capability.
|
|
33
|
+
2. Trace each item to a quote or a document line. Write the quote beside it. A paraphrase that adds a number, a case or a field has no source for the addition. Done when every item has a quote or is marked untraced.
|
|
34
|
+
3. Sweep the untraced items for the marks below. They are the places to look hardest, and an item without a mark can still be invented. Done when every mark in the table has been looked for.
|
|
35
|
+
4. Decide each untraced item with the table under "Remove or park". Done when no untraced item is left as a rule.
|
|
36
|
+
5. Write the change through the vds tools in one checked change: `vds apply` (or the `vds_apply` tool), since removing a requirement also removes its scenario file and its exits. Run `vds check`. If the change is refused because a command, event or read model is left with no scenario naming it, stop and hand that block to vds-slice-blocks. Done when the check passes and every new hot spot points `on` the screen or a requirement that remains; when neither remains, it has no `on` and names the step in `text` (file format: vds-ask-or-park).
|
|
37
|
+
6. Hand on the trace: what was kept with its quote, what was removed, what became a hot spot. Done when vds-requirements-review has the list. Ask the person nothing more in this pass.
|
|
38
|
+
|
|
39
|
+
## The marks an agent leaves
|
|
40
|
+
|
|
41
|
+
| Mark | Looks like | Ask |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| Round-number limit nobody gave | `lockMinutes: 15`, `passwordMinLength: 8`, "within 24 hours" | Who said the number? A rule with a stated name and no stated value keeps the name; the value becomes a hot spot. |
|
|
44
|
+
| "Standard" security rule | lock after N tries, session timeout, password strength, rate limits | Did a person ask for it, or does every app have it? |
|
|
45
|
+
| Error case nobody raised | "SHALL show an error when the network fails" | Did anyone mention this failure? Failures nobody raised are questions. |
|
|
46
|
+
| Field copied from typical apps | name, email, phone, avatar, date of birth on a screen nobody listed | Did the person name each field? |
|
|
47
|
+
| Tidy symmetry | a create with a delete, an add with an edit, a login with a logout | Did anyone ask for the other half? |
|
|
48
|
+
| Term nobody used | "user" where the person says "investor"; "OTP" where they say "code" | Use the person's word. Recording terms is vds-language. |
|
|
49
|
+
| Then line with an extra outcome | an event or a screen in a scenario the person never described | Trace each Then line on its own. |
|
|
50
|
+
|
|
51
|
+
## Remove or park
|
|
52
|
+
|
|
53
|
+
| The untraced item... | Do |
|
|
54
|
+
|---|---|
|
|
55
|
+
| hides a choice the business must make (a number, a failure, a rule, a field) | remove the rule; write a hot spot with the question it hides |
|
|
56
|
+
| hides no choice: a restatement, a duplicate, padding words | remove it |
|
|
57
|
+
| has a stated rule and an unstated value | keep the rule and its number (the check needs it); a hot spot on that requirement says nobody gave the number, and vds-requirements-review reports it as not ready |
|
|
58
|
+
| was said by the agent and agreed to by nobody | treat as untraced; a person staying silent is no source |
|
|
59
|
+
|
|
60
|
+
Write the question in the person's words and from their example. A hot spot is storming (Brandolini): an inconclusive point gets one, and "it won't be forgotten" (p95-96). The person may answer it at the read-back. vds-requirements-review writes nothing: the owning skill records the answer afterwards, and vds-ask-or-park marks the hot spot addressed.
|
|
61
|
+
|
|
62
|
+
## Right and wrong
|
|
63
|
+
|
|
64
|
+
A security rule nobody stated, left as a requirement:
|
|
65
|
+
|
|
66
|
+
```yaml
|
|
67
|
+
# wrong
|
|
68
|
+
- id: REQ-AUTH-0040
|
|
69
|
+
title: Expire idle sessions
|
|
70
|
+
type: nfr
|
|
71
|
+
statement: The system SHALL end the session after 30 minutes without activity.
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Removed, and the question it hid parked on the screen where it would apply:
|
|
75
|
+
|
|
76
|
+
```yaml
|
|
77
|
+
# right
|
|
78
|
+
id: HOT-AUTH--idle-session
|
|
79
|
+
text: "Should an investor be signed out after some time without activity?"
|
|
80
|
+
"on": SCR-AUTH-07
|
|
81
|
+
status: open
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
A stated rule with an invented value. The person said "lock it after too many wrong MPINs" and gave no number:
|
|
85
|
+
|
|
86
|
+
```yaml
|
|
87
|
+
# wrong: the number stands with no hot spot, so it reads as decided
|
|
88
|
+
limits:
|
|
89
|
+
lockAfterWrong: 5
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```yaml
|
|
93
|
+
# right: the rule stays; the number is asked (and stays in `limits:`, see below)
|
|
94
|
+
id: HOT-AUTH--lock-count
|
|
95
|
+
text: "After how many wrong MPINs is the account locked?"
|
|
96
|
+
"on": REQ-AUTH-0028
|
|
97
|
+
status: open
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Keep the number in `limits:` while any statement or scenario names `{lockAfterWrong}`: removing it is refused as `unknown limit {lockAfterWrong}`. Say in the hot spot's `text` that nobody gave the number.
|
|
101
|
+
|
|
102
|
+
A scenario with an outcome nobody described:
|
|
103
|
+
|
|
104
|
+
```gherkin
|
|
105
|
+
# wrong: the email nobody asked for
|
|
106
|
+
Then EVT-AUTH--code-sent with channel mobile, purpose SignIn
|
|
107
|
+
And EVT-AUTH--welcome-email-sent
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Drop the last line. If someone wondered about a welcome message, park it: "Do new investors get a welcome email?"
|
|
111
|
+
|
|
112
|
+
## Symptoms
|
|
113
|
+
|
|
114
|
+
| What you see or hear | Do |
|
|
115
|
+
|---|---|
|
|
116
|
+
| The capability has a delete for every create | trace each delete; park the untraced ones as "Can an investor remove X?" |
|
|
117
|
+
| Limits are all round numbers and one session produced them | trace which numbers a person gave; park the rest |
|
|
118
|
+
| Every screen has an error requirement | keep the failures someone raised; park the others as questions |
|
|
119
|
+
| "We never talked about that" at any point | the rule is invented; remove or park it, then rerun the pass on its neighbours |
|
|
120
|
+
|
|
121
|
+
## Never
|
|
122
|
+
|
|
123
|
+
Never leave a plausible rule nobody stated. Never answer a hidden question yourself to keep a rule; the question goes into a hot spot.
|
|
124
|
+
|
|
125
|
+
## Not covered
|
|
126
|
+
|
|
127
|
+
- How to ask a question live in a session: vds-ask-or-park.
|
|
128
|
+
- Reading the capability back and saying ready or not: vds-requirements-review.
|
|
129
|
+
- Invented commands, events or read models in the model: vds-model-review.
|
|
130
|
+
- The book notes give no method for tracing a requirement to its source; the trace rules here are VDS's own.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: vds-subdomains
|
|
3
|
+
description: "Subdomain of a VDS workspace: one part of the business this product needs, marked core, supporting or generic. Use when the day-1 working subdomain needs its real name, when a person names a part of the business the product leans on, when a mark is unclear or disputed, or when a context serves no subdomain. Boundaries and the day-1 working context belong to vds-contexts; relations between contexts to vds-context-map; terms to vds-language."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Subdomains
|
|
7
|
+
|
|
8
|
+
Name each part of the business this product needs, in the business's words, and give it one mark that says how much effort it deserves.
|
|
9
|
+
|
|
10
|
+
Use it in strategic design, between requirement discovery sessions. On day 1 vds-contexts opens one working subdomain beside the working context, with a working mark from the person's answer to one question; this skill refines name and mark later from what the sessions left.
|
|
11
|
+
Siblings own the neighbours. Where a boundary goes, and the day-1 pair, is vds-contexts. Who depends on whom is vds-context-map. A word and its meaning is vds-language. A question nobody can answer is vds-ask-or-park.
|
|
12
|
+
|
|
13
|
+
When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
|
|
14
|
+
## Method
|
|
15
|
+
|
|
16
|
+
1. **Read what exists.** Read every subdomain and every context's `serves:` line (`vds show <ID>`). Done when each subdomain is listed beside the contexts that serve it.
|
|
17
|
+
2. **List the parts this product needs.** Take them from what people said in the sessions: what the product does itself, and what it leans on from elsewhere. A workspace is one product, and Vernon sets the problem space per initiative, "usually different from project to project" (p56). Done when every part on the list traces to something a person said, and no part is there only because the business has it.
|
|
18
|
+
3. **Name each part in the business's words.** Use the words the domain expert uses for that part. Done when each name is a phrase a person said, and `does:` is one sentence a product team member would agree with.
|
|
19
|
+
4. **Mark each part** with the table below. Ask the person; Vernon's instruction is "Ask the Domain Experts!" (p52). One question at a time. Done when each part has one mark and `why:` gives the person's reason for it.
|
|
20
|
+
5. **Tie each part to a context.** Each subdomain is served by at least one context, and each context of kind ours serves a subdomain. One subdomain to one context is the goal (p57). Done when no subdomain and no context of kind ours is left untied.
|
|
21
|
+
6. **Land it in one checked change.** Read the revision with `vds status`. Write the subdomains and the changed `serves:` lines together with `vds apply --base <rev>`. Done when the change is accepted and `vds check` reports 0 problems.
|
|
22
|
+
7. **Tell the person what the marks change.** Say which part gets the most care and which is bought or reused. Done when the person has confirmed the marks or named the one to change.
|
|
23
|
+
|
|
24
|
+
## Pick the mark
|
|
25
|
+
|
|
26
|
+
Ask in order. Take the first yes.
|
|
27
|
+
|
|
28
|
+
| # | Question to the person | Yes means | Source |
|
|
29
|
+
|---|---|---|---|
|
|
30
|
+
| 1 | Is this why the business wins, the part it must be better at than anyone? | core | Vernon p51-52: primary importance, the business must excel |
|
|
31
|
+
| 2 | Is it something any business needs in the same form, with nothing special to this one? | generic | Vernon p51-52: "captures nothing special", still required |
|
|
32
|
+
| 3 | Is it essential and specific to this business, without being what it competes on? | supporting | Vernon p51-52: essential, "somewhat specialized", so it is created |
|
|
33
|
+
|
|
34
|
+
No yes on any row: the part may not be needed by this product. Ask what breaks without it, or drop it.
|
|
35
|
+
|
|
36
|
+
What the mark changes:
|
|
37
|
+
|
|
38
|
+
| Mark | Effect |
|
|
39
|
+
|---|---|
|
|
40
|
+
| core | The best developers, the domain experts and first priority go here (p51-52). Model it most carefully. |
|
|
41
|
+
| supporting | Built in-house because it is specialized. Needed, with no need to excel (p52). |
|
|
42
|
+
| generic | Buy or reuse where a provider sells it. Its context is then usually of kind external. This is VDS's reading of the example: both generic subdomains there are served by external contexts. |
|
|
43
|
+
|
|
44
|
+
Rules for the mark:
|
|
45
|
+
- The mark is relative to this business. Mapping is generic for a company that uses maps and core for the company that sells them (p61).
|
|
46
|
+
- The mark depends on use. A bought module can be generic as a whole and work as supporting where it is used (p60).
|
|
47
|
+
- The marks are a moment in time. Review them when the business's goals change (p52).
|
|
48
|
+
- Supporting and generic never mean unimportant (p52). Say so when a person hears a mark as a put-down.
|
|
49
|
+
|
|
50
|
+
## What the check enforces
|
|
51
|
+
|
|
52
|
+
Tested on a copy of the example:
|
|
53
|
+
- `type` is core, supporting or generic. Anything else is a problem.
|
|
54
|
+
- `does` and `why` must be filled. `name` is not checked; write it anyway.
|
|
55
|
+
- Every subdomain needs a context that serves it. A subdomain written alone is refused, so it lands with its context's `serves:` line in one change.
|
|
56
|
+
- A context of kind ours or legacy must serve a subdomain. A context of kind external may serve none.
|
|
57
|
+
- `serves:` naming an id with no subdomain file is a problem.
|
|
58
|
+
- A context may serve several subdomains. The check accepts it; Vernon sees it mostly in legacy systems (p48).
|
|
59
|
+
- The check never judges whether a mark is true. That is this skill's work.
|
|
60
|
+
|
|
61
|
+
## Right and wrong
|
|
62
|
+
|
|
63
|
+
Right (the example):
|
|
64
|
+
```yaml
|
|
65
|
+
id: SD-AUTH--investor-access
|
|
66
|
+
name: Investor Access
|
|
67
|
+
type: supporting
|
|
68
|
+
does: Lets an investor sign up, log in and reset their MPIN.
|
|
69
|
+
why: Essential before investing and specific to investors, but it is not what the business competes on.
|
|
70
|
+
```
|
|
71
|
+
Wrong (named after the software, marked core to sound important, reason is no reason):
|
|
72
|
+
```yaml
|
|
73
|
+
id: SD-AUTH--auth-service
|
|
74
|
+
name: Auth Service
|
|
75
|
+
type: core
|
|
76
|
+
does: Handles JWT sessions and the login API.
|
|
77
|
+
why: It is critical.
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Right (a generic part, served by a context of kind external):
|
|
81
|
+
```yaml
|
|
82
|
+
id: SD-AUTH--identity-data-lookup
|
|
83
|
+
name: Identity Data Lookup
|
|
84
|
+
type: generic
|
|
85
|
+
does: Fills in an investor's profile (email, bank account, gender, income) from an outside data provider.
|
|
86
|
+
why: Any business onboarding people can use it, and a provider sells it; we integrate Cybrilla's APIs rather than build it.
|
|
87
|
+
```
|
|
88
|
+
```yaml
|
|
89
|
+
id: BC-AUTH--cybrilla
|
|
90
|
+
name: Cybrilla Context
|
|
91
|
+
serves: [SD-AUTH--identity-data-lookup]
|
|
92
|
+
kind: external
|
|
93
|
+
```
|
|
94
|
+
Wrong (one part cut by who builds it):
|
|
95
|
+
```yaml
|
|
96
|
+
id: SD-AUTH--investor-access-frontend
|
|
97
|
+
name: Investor Access Frontend
|
|
98
|
+
type: supporting
|
|
99
|
+
does: The screens the mobile team builds for sign up and login.
|
|
100
|
+
why: The mobile team owns it.
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Symptoms
|
|
104
|
+
|
|
105
|
+
| The person says, or the draft shows | Do |
|
|
106
|
+
|---|---|
|
|
107
|
+
| "Everything is core" | Ask question 1 about each part, one at a time. Mark core only on a yes. |
|
|
108
|
+
| No part gets a yes on question 1 | Write no core. The example has none: two supporting, two generic. Tell the person the product has no core subdomain yet and ask whether that is true of the product. |
|
|
109
|
+
| A name that is a system, a team or a vendor | Ask what the business calls that part. The vendor's name belongs on the context. |
|
|
110
|
+
| "We also have billing, HR, ..." | Ask whether this product needs it. A part the product never touches stays out. |
|
|
111
|
+
| The working subdomain from day 1 still has its working name, or a `why:` that starts "Working mark:" | Rename it from the sessions' words and ask the three mark questions; change every `serves:` line in the same change. |
|
|
112
|
+
| A subdomain with no context | Ask which context does this work. None yet: hand to vds-contexts. |
|
|
113
|
+
| A tiny part, a few rules or a calculation | Vernon: it can be a module inside a context, no subdomain of its own (p48). |
|
|
114
|
+
| The person cannot say why the business wins | Park it as a hot spot through vds-ask-or-park. Never pick the mark yourself. |
|
|
115
|
+
|
|
116
|
+
## Never
|
|
117
|
+
|
|
118
|
+
Never split a subdomain to hand out work. Split only when the business names two parts, or two parts earn two different marks. Vernon gives this rule for bounded contexts: splitting to give tasks to developers makes fake contexts and a fragmented language (p68-71). Applying it to subdomains is VDS's reading.
|
|
119
|
+
|
|
120
|
+
Never assess the whole business. The subdomains are the parts this one product needs (p56).
|
|
121
|
+
|
|
122
|
+
## Not covered
|
|
123
|
+
|
|
124
|
+
- Several core subdomains in one product. Vernon words the problem space around one new core (p56); the Vernon notes do not say two are forbidden.
|
|
125
|
+
- A product with no core at all. Vernon anchors the problem space on a new Core Domain (p56) and the example has none. The check asks `no core subdomain: what is this product for?`; put that question to the person.
|
|
126
|
+
- "Could it be bought" as a test for generic. Vernon's test is "captures nothing special"; buying appears in his solution space questions (p59-60) and in the example's `why:` lines.
|
|
127
|
+
- Writes go through `vds apply` or `vds write` (MCP: `vds_apply`, `vds_write`); read with `vds show <ID>` and `vds status`; check with `vds check`.
|
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
# File shapes
|
|
2
|
+
|
|
3
|
+
Paths change when folders are renamed; trust the workspace's VDS.md over this file.
|
|
4
|
+
|
|
5
|
+
Every file below is copied whole from the repo's examples (`packages/spec/workspace/0.1/examples/mini` and `investor-auth`), which pass `vds check`. Paths are relative to the workspace's `domain/`. `<BC>` is a context folder like `BC-NOM--nominees`; `<CAP>` is a capability folder like `CAP-NOM`.
|
|
6
|
+
|
|
7
|
+
A file's `id` must match its file name. Never write `flows/` or `diagrams/` folders; `vds compile` does.
|
|
8
|
+
|
|
9
|
+
## Capability and requirement
|
|
10
|
+
|
|
11
|
+
Lives in `contexts/<BC>/<CAP>/problem/capability.yaml`. Every requirement is an entry in `requirements:` of that one file. There is no file per requirement.
|
|
12
|
+
|
|
13
|
+
```yaml
|
|
14
|
+
# Every REQ lives here. screen and exits place it; entries, a screen's REQs, Commands and Shows are generated.
|
|
15
|
+
id: CAP-NOM
|
|
16
|
+
title: Add a nominee
|
|
17
|
+
requirements:
|
|
18
|
+
- id: REQ-NOM-0001
|
|
19
|
+
title: Show the nominees
|
|
20
|
+
type: state_view
|
|
21
|
+
screen: SCR-NOM-01
|
|
22
|
+
start: SCN-NOM-0001-01
|
|
23
|
+
read_model: [RM-NOM--nominees]
|
|
24
|
+
statement: The system SHALL show how many nominees the account has.
|
|
25
|
+
- id: REQ-NOM-0002
|
|
26
|
+
title: Add a nominee
|
|
27
|
+
type: state_change
|
|
28
|
+
screen: SCR-NOM-01
|
|
29
|
+
exits:
|
|
30
|
+
- { scn: SCN-NOM-0002-01, to: none }
|
|
31
|
+
statement: The system SHALL add a nominee the holder names.
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Refused most often: an `exits` scn that is not one of the requirement's scenarios. A `screen` with no screen file yet ("unknown screen SCR-NOM-09") is listed as a step not modelled yet, and publish refuses it.
|
|
35
|
+
|
|
36
|
+
Other requirement types (all in `investor-auth`, same file): `automation` (has `trigger`, `command`, `read_model`, `sees`; every field its command carries is in `sees`), `translation` (has `external`, `command` and `event`), `nfr` (has `limits` or nothing), `analytics`:
|
|
37
|
+
|
|
38
|
+
```yaml
|
|
39
|
+
- id: REQ-AUTH-0046
|
|
40
|
+
title: Track mobile entry
|
|
41
|
+
type: analytics
|
|
42
|
+
"on": CMD-AUTH--submit-mobile
|
|
43
|
+
sends: investor.auth.mobile_entry.submitted
|
|
44
|
+
attributes: [screen, attempt, mobile_valid]
|
|
45
|
+
statement: When the investor submits a mobile, the system SHALL send investor.auth.mobile_entry.submitted with the screen, the attempt and whether the mobile is valid, never the number.
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Scenario file
|
|
49
|
+
|
|
50
|
+
Lives in `contexts/<BC>/<CAP>/problem/scenarios/REQ-<id>.feature`. One file per requirement, one or more scenarios in it. Each scenario has an `@SCN-` tag.
|
|
51
|
+
|
|
52
|
+
```gherkin
|
|
53
|
+
@CAP-NOM @REQ-NOM-0002
|
|
54
|
+
Feature: Add a nominee
|
|
55
|
+
|
|
56
|
+
@SCN-NOM-0002-01
|
|
57
|
+
Scenario: A nominee is added
|
|
58
|
+
Given no EVT-NOM--nominee-added
|
|
59
|
+
When CMD-NOM--add-nominee
|
|
60
|
+
Then EVT-NOM--nominee-submitted
|
|
61
|
+
And EVT-NOM--nominee-added
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Refused most often: an event after Then that the command does not produce ("CMD-NOM--add-nominee does not produce EVT-NOM--ghost"). An event or command named before its file is written is listed as a step not modelled yet.
|
|
65
|
+
|
|
66
|
+
## Screen
|
|
67
|
+
|
|
68
|
+
Lives in `contexts/<BC>/<CAP>/solution/screens/SCR-<SCOPE>-<nn>.yaml`. Only id and title are written. Its requirements, entries, exits, commands and shows are generated.
|
|
69
|
+
|
|
70
|
+
```yaml
|
|
71
|
+
# REQs, Entries, Exits, Commands and Shows are generated.
|
|
72
|
+
id: SCR-NOM-01
|
|
73
|
+
title: Nominees
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
"a screen needs an actor, found none" is a step not modelled yet: who acts on the screen comes from the `by` of the commands the screen's requirements use, so a screen saved before its command is accepted in the draft and refused by publish. Commands by two people raise an open question. It also shows up when the screen id does not match its file.
|
|
77
|
+
|
|
78
|
+
## Subdomain
|
|
79
|
+
|
|
80
|
+
Lives in `subdomains/SD-<SCOPE>--<code>.yaml`.
|
|
81
|
+
|
|
82
|
+
```yaml
|
|
83
|
+
id: SD-NOM--nominees
|
|
84
|
+
name: Nominees
|
|
85
|
+
type: supporting
|
|
86
|
+
does: Keeps who receives an account's holdings when its holder dies.
|
|
87
|
+
why: Required for every account, but not what the business competes on.
|
|
88
|
+
```
|
|
89
|
+
Refused most often: `type` other than core, supporting or generic.
|
|
90
|
+
|
|
91
|
+
## Bounded context
|
|
92
|
+
|
|
93
|
+
Lives in `contexts/<BC>/context.yaml`, with its terms in `contexts/<BC>/language.yaml`.
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
id: BC-NOM--nominees
|
|
97
|
+
name: Nominees Context
|
|
98
|
+
serves: [SD-NOM--nominees]
|
|
99
|
+
kind: ours
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
An outside system is `kind: external`:
|
|
103
|
+
|
|
104
|
+
```yaml
|
|
105
|
+
id: BC-AUTH--captcha-provider
|
|
106
|
+
name: Captcha Provider Context
|
|
107
|
+
serves: [SD-AUTH--bot-protection]
|
|
108
|
+
kind: external
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```yaml
|
|
112
|
+
terms:
|
|
113
|
+
- term: Account Holder
|
|
114
|
+
means: "The person who owns the account and names its nominees."
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Refused most often: `kind` other than ours, external or legacy.
|
|
118
|
+
|
|
119
|
+
The relationships between contexts live in one file, `context-map.yaml`. A workspace with one context has `relationships: []`. From `investor-auth`:
|
|
120
|
+
|
|
121
|
+
```yaml
|
|
122
|
+
relationships:
|
|
123
|
+
- type: upstream-downstream
|
|
124
|
+
upstream:
|
|
125
|
+
context: BC-AUTH--captcha-provider
|
|
126
|
+
downstream:
|
|
127
|
+
context: BC-AUTH--investor-access
|
|
128
|
+
roles: [ACL]
|
|
129
|
+
via: [sync]
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## People
|
|
133
|
+
|
|
134
|
+
Lives in `people/PPL-<SCOPE>--<code>.yaml`. A command names its person in `by`.
|
|
135
|
+
|
|
136
|
+
```yaml
|
|
137
|
+
id: PPL-NOM--holder
|
|
138
|
+
name: Account Holder
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Refused most often: a command whose `by` names a person with no file ("unknown person PPL-NOM--nobody").
|
|
142
|
+
|
|
143
|
+
## External event
|
|
144
|
+
|
|
145
|
+
Lives in `contexts/<outside BC>/EVT-<SCOPE>--<code>.yaml`, directly in the external context's folder, not in a model. `source: system` and `system` name the outside context. A `translation` requirement turns it into one of our events.
|
|
146
|
+
|
|
147
|
+
```yaml
|
|
148
|
+
id: EVT-AUTH--captcha-result
|
|
149
|
+
name: Captcha Result
|
|
150
|
+
source: system
|
|
151
|
+
system: BC-AUTH--captcha-provider
|
|
152
|
+
attributes:
|
|
153
|
+
- name: occurredOn
|
|
154
|
+
type: date
|
|
155
|
+
- name: valid
|
|
156
|
+
type: boolean
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Command
|
|
160
|
+
|
|
161
|
+
Lives in `contexts/<BC>/<CAP>/solution/commands/CMD-<SCOPE>--<code>.yaml`.
|
|
162
|
+
|
|
163
|
+
```yaml
|
|
164
|
+
id: CMD-NOM--add-nominee
|
|
165
|
+
name: Add Nominee
|
|
166
|
+
does: Take the nominee the holder names
|
|
167
|
+
to: [BC-NOM--nominees]
|
|
168
|
+
by: PPL-NOM--holder
|
|
169
|
+
attributes:
|
|
170
|
+
- name: nomineeName
|
|
171
|
+
type: string
|
|
172
|
+
produces:
|
|
173
|
+
- EVT-NOM--nominee-submitted
|
|
174
|
+
- EVT-NOM--nominee-added
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Refused most often: a scenario Then that names an event missing from `produces`; an unknown `by`.
|
|
178
|
+
|
|
179
|
+
A command sent to another context names it in `to:` and the person it reaches as one id, as in investor-auth's `CMD-AUTH--send-code.yaml`: `to: [BC-AUTH--neptune]` and `reaches: PPL-AUTH--investor`. Such a command still produces an event of ours, filed under our aggregate: `to` says who is asked, our aggregate records that it asked. The pair needs a relation on the context map; its `via:` is optional and, when written, holds `sync`, `async` or both.
|
|
180
|
+
|
|
181
|
+
## Domain event
|
|
182
|
+
|
|
183
|
+
Two homes.
|
|
184
|
+
|
|
185
|
+
- An event an aggregate stores: `contexts/<BC>/solution/model/<MOD>/<AGG>/EVT-<SCOPE>--<code>.yaml`.
|
|
186
|
+
- An event no aggregate owns yet: `contexts/<BC>/<CAP>/solution/events/EVT-<SCOPE>--<code>.yaml`, with a comment saying so.
|
|
187
|
+
|
|
188
|
+
```yaml
|
|
189
|
+
id: EVT-NOM--nominee-added
|
|
190
|
+
name: Nominee Added
|
|
191
|
+
attributes:
|
|
192
|
+
- name: occurredOn
|
|
193
|
+
type: date
|
|
194
|
+
- name: nomineeId
|
|
195
|
+
type: string
|
|
196
|
+
- name: nomineeName
|
|
197
|
+
type: string
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
An optional attribute adds `optional: true`; an attribute typed by a value object writes `type: VO-AUTH--email`. For the no-aggregate home, the file starts with `# It has no Aggregate yet.` (see `EVT-AUTH--security-limits-overridden`).
|
|
201
|
+
|
|
202
|
+
Refused most often: "no scenario uses it" for an event no scenario names.
|
|
203
|
+
|
|
204
|
+
## Read model
|
|
205
|
+
|
|
206
|
+
Lives in `contexts/<BC>/<CAP>/solution/read-models/RM-<SCOPE>--<code>.yaml`. Each attribute has a `kind`: copy, count, exists or computed. `of` lists the events (or event attributes) it is built from.
|
|
207
|
+
|
|
208
|
+
```yaml
|
|
209
|
+
id: RM-NOM--nominees
|
|
210
|
+
name: Nominees
|
|
211
|
+
attributes:
|
|
212
|
+
- name: count
|
|
213
|
+
type: integer
|
|
214
|
+
kind: count
|
|
215
|
+
of: [EVT-NOM--nominee-added]
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
A computed attribute adds a `rule`:
|
|
219
|
+
|
|
220
|
+
```yaml
|
|
221
|
+
id: RM-AUTH--code-status
|
|
222
|
+
name: Code Status
|
|
223
|
+
attributes:
|
|
224
|
+
- name: maskedTarget
|
|
225
|
+
type: string
|
|
226
|
+
kind: computed
|
|
227
|
+
of: [EVT-AUTH--mobile-submitted.mobile, EVT-AUTH--email-submitted.email]
|
|
228
|
+
rule: the submitted mobile or email, masked
|
|
229
|
+
- name: resendAvailableAt
|
|
230
|
+
type: date
|
|
231
|
+
kind: computed
|
|
232
|
+
of: [EVT-AUTH--code-sent.occurredOn, EVT-AUTH--code-resent.resendAvailableAt]
|
|
233
|
+
rule: "{resendAfterSeconds} seconds after the code was sent, or the latest resend"
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Refused most often: `kind` outside copy, count, exists, computed.
|
|
237
|
+
|
|
238
|
+
## Aggregate
|
|
239
|
+
|
|
240
|
+
Lives in `contexts/<BC>/solution/model/<MOD>/<AGG>/aggregate.yaml`. The module's `module.yaml` (id, name) sits one folder up.
|
|
241
|
+
|
|
242
|
+
```yaml
|
|
243
|
+
id: AGG-NOM--nominee
|
|
244
|
+
name: Nominee
|
|
245
|
+
module: MOD-NOM--nomination
|
|
246
|
+
root: ENT-NOM--nominee
|
|
247
|
+
invariants: [REQ-NOM-0002]
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Refused most often: `root` naming an entity that does not exist, or one in another aggregate's folder ("its root ... does not sit in its folder").
|
|
251
|
+
|
|
252
|
+
## Entity
|
|
253
|
+
|
|
254
|
+
Lives beside its aggregate: `.../<MOD>/<AGG>/ENT-<SCOPE>--<code>.yaml`. The root entity is the one `aggregate.yaml` names. Any other entity in that folder is held inside the aggregate and reached only through the root; it has the same fields, and the command that creates it inside the root carries `creates: true` on it. An entity outside an aggregate's folder is refused.
|
|
255
|
+
|
|
256
|
+
```yaml
|
|
257
|
+
id: ENT-NOM--nominee
|
|
258
|
+
name: Nominee
|
|
259
|
+
why: Each nominee is its own, and is added and later changed over time.
|
|
260
|
+
identity:
|
|
261
|
+
attributes: [nomineeId]
|
|
262
|
+
source: application
|
|
263
|
+
timing: early
|
|
264
|
+
attributes:
|
|
265
|
+
- name: nomineeName
|
|
266
|
+
type: string
|
|
267
|
+
required: true
|
|
268
|
+
commands:
|
|
269
|
+
- command: CMD-NOM--add-nominee
|
|
270
|
+
creates: true
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Value object
|
|
274
|
+
|
|
275
|
+
Lives beside the aggregate that uses it, in the module when two aggregates share it, or in `solution/model/` when the whole context shares it: `VO-<SCOPE>--<code>.yaml`.
|
|
276
|
+
|
|
277
|
+
```yaml
|
|
278
|
+
id: VO-AUTH--channel
|
|
279
|
+
name: Channel
|
|
280
|
+
describes: Where a code goes.
|
|
281
|
+
values: [mobile, email]
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
## Port and adapter
|
|
285
|
+
|
|
286
|
+
Lives in `contexts/<BC>/solution/ports/<PORT>/port.yaml`, with adapters in `contexts/<BC>/solution/ports/<PORT>/adapters/ADP-*.yaml`. VDS.md says a port has name, side (driving or driven), with and does, and an adapter has name and does.
|
|
287
|
+
|
|
288
|
+
No example in the repo. Neither example folder has a port or adapter file. Do not guess the fields beyond what VDS.md lists.
|
|
289
|
+
|
|
290
|
+
## Hot spot
|
|
291
|
+
|
|
292
|
+
Lives in `contexts/<BC>/<CAP>/problem/hot-spots/HOT-<SCOPE>--<code>.yaml`, beside the capability, not in the model. `on` names the block the question is about. `on` is quoted, as the example does.
|
|
293
|
+
|
|
294
|
+
```yaml
|
|
295
|
+
id: HOT-AUTH--resend-limit
|
|
296
|
+
text: "Is there a limit on resends?"
|
|
297
|
+
"on": CMD-AUTH--resend-code
|
|
298
|
+
status: open
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Refused most often: an `on` that names nothing in the workspace ("on names unknown CMD-NOM--nope").
|
|
302
|
+
|
|
303
|
+
## Several files in one change
|
|
304
|
+
|
|
305
|
+
`vds apply --base <rev> --from changes.json` (or the JSON on stdin) reads one JSON object. Each key is a path under `domain/`, and each value is the file's whole text, or `null` to delete the file. Any problem the change adds refuses the whole change.
|
|
306
|
+
|
|
307
|
+
```json
|
|
308
|
+
{
|
|
309
|
+
"contexts/BC-NOM--nominees/CAP-NOM/problem/capability.yaml": "id: CAP-NOM\ntitle: Add a nominee\nrequirements: []\n",
|
|
310
|
+
"contexts/BC-NOM--nominees/CAP-NOM/solution/screens/SCR-NOM-02.yaml": null
|
|
311
|
+
}
|
|
312
|
+
```
|