groundwork-mcp 0.3.0 → 0.4.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 +48 -2
- package/SPEC.md +12 -3
- package/dist/{chunk-DU4P7DDY.js → chunk-4F24STNS.js} +2 -2
- package/dist/{chunk-3YZLRKZH.js → chunk-TXXV5YDG.js} +143 -25
- package/dist/chunk-TXXV5YDG.js.map +1 -0
- package/dist/cli.js +18 -8
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +33 -12
- package/dist/index.js +13 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp.js +2 -2
- package/package.json +1 -1
- package/dist/chunk-3YZLRKZH.js.map +0 -1
- /package/dist/{chunk-DU4P7DDY.js.map → chunk-4F24STNS.js.map} +0 -0
package/README.md
CHANGED
|
@@ -17,6 +17,8 @@ insight ──▶ hypothesis ──▶ experiment ──▶ finding ──▶ re
|
|
|
17
17
|
|
|
18
18
|
## Quickstart (2 minutes)
|
|
19
19
|
|
|
20
|
+
### Claude Code
|
|
21
|
+
|
|
20
22
|
In your project folder:
|
|
21
23
|
|
|
22
24
|
```sh
|
|
@@ -30,7 +32,32 @@ Or install the plugin, which adds the MCP server and a skill that teaches Claude
|
|
|
30
32
|
/plugin install groundwork@groundwork
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
|
|
35
|
+
### Codex
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
codex mcp add groundwork -- npx -y groundwork-mcp
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Or add it to `~/.codex/config.toml` by hand:
|
|
42
|
+
|
|
43
|
+
```toml
|
|
44
|
+
[mcp_servers.groundwork]
|
|
45
|
+
command = "npx"
|
|
46
|
+
args = ["-y", "groundwork-mcp"]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
To teach Codex when to use it, copy the skill into your repo:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
mkdir -p .agents/skills/groundwork
|
|
53
|
+
curl -fsSL https://raw.githubusercontent.com/IdeatorlabsAB/groundwork/main/skills/groundwork/SKILL.md -o .agents/skills/groundwork/SKILL.md
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Start `codex` in your project folder, so Groundwork finds the project.
|
|
57
|
+
|
|
58
|
+
### Then
|
|
59
|
+
|
|
60
|
+
Talk to your agent as you normally would:
|
|
34
61
|
|
|
35
62
|
> Here are my notes from three customer interviews. Log the pains as insights.
|
|
36
63
|
>
|
|
@@ -42,6 +69,19 @@ Then talk to Claude as you normally would:
|
|
|
42
69
|
|
|
43
70
|
Groundwork writes files like `groundwork/insights/INS-0001-setup-takes-too-long.md`. Commit them like any other file.
|
|
44
71
|
|
|
72
|
+
## Requirements in two layers
|
|
73
|
+
|
|
74
|
+
Write requirements before you build, and keep them in two linked layers:
|
|
75
|
+
|
|
76
|
+
- **Stakeholder requirements** say who needs what and why, as user stories: *"As a medical secretary I want a view of all practitioners' calendars with their unbooked slots highlighted so that I can find them and book appointments easily."*
|
|
77
|
+
- **Solution requirements** say what the solution must do to meet those needs, as "shall" statements: *"The appointment view shall show the calendars of the selected practitioners with the free slots highlighted. It shall be possible to click a free slot to start the booking flow."*
|
|
78
|
+
|
|
79
|
+
Every solution requirement fulfils at least one stakeholder requirement, and Groundwork refuses one that doesn't. `groundwork validate` warns about stakeholder requirements that no solution requirement fulfils yet, and about stories that don't fit their layer. Linking findings is optional, so you can write requirements before there's any experiment behind them.
|
|
80
|
+
|
|
81
|
+
### Planning with Groundwork
|
|
82
|
+
|
|
83
|
+
When your agent plans a task, it first decides what kind of task it is. "Let's add a feature to book appointments" is a new need. "This path is broken, fix it" is a fix. It states the call in one line of the plan, such as *"New need: adds 2 stakeholder and 4 solution requirements"* or *"Bug fix under REQ-0007; no requirement changes"*. For a new need or a change, the plan records the requirements before any code. Tickets the workflow creates carry the REQ ids they implement. When a PM approves a requirement verbally, tell the agent and it records the approval on their behalf, noting who entered it.
|
|
84
|
+
|
|
45
85
|
## The CLI
|
|
46
86
|
|
|
47
87
|
```sh
|
|
@@ -126,7 +166,13 @@ npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-r
|
|
|
126
166
|
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app
|
|
127
167
|
```
|
|
128
168
|
|
|
129
|
-
Every item keeps its links, and its original id (`INS-0001`) is stored with it. Running the import again skips items already there (`--overwrite` replaces them). Afterwards `groundwork/config.yml` says `migrated:`, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server.
|
|
169
|
+
Every item keeps its links, and its original id (`INS-0001`) is stored with it. Running the import again skips items already there (`--overwrite` replaces them). Afterwards `groundwork/config.yml` says `migrated:`, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server. For Codex, run `codex mcp remove groundwork` and add this to `~/.codex/config.toml`:
|
|
170
|
+
|
|
171
|
+
```toml
|
|
172
|
+
[mcp_servers.groundwork]
|
|
173
|
+
url = "https://your-groundwork-app/api/mcp"
|
|
174
|
+
bearer_token_env_var = "GROUNDWORK_TOKEN"
|
|
175
|
+
```
|
|
130
176
|
|
|
131
177
|
## Contributing
|
|
132
178
|
|
package/SPEC.md
CHANGED
|
@@ -56,10 +56,16 @@ Required fields are in bold.
|
|
|
56
56
|
**Finding** (`findings/`, `FND-`): what was learned.
|
|
57
57
|
**`title`**, **`summary`**, `experimentIds`, `hypothesisIds`, `insightIds`, `confidence` (`low` | `medium` | `high`), `productArea`, `createdAt`.
|
|
58
58
|
|
|
59
|
-
**Requirement** (`requirements/`, `REQ-`):
|
|
60
|
-
**`title`**, **`story`**, **`acceptanceCriteria`** (a list), **`status`** (`draft` | `awaiting-approval` | `approved` | `in-delivery` | `obsolete`), `
|
|
59
|
+
**Requirement** (`requirements/`, `REQ-`): what is needed before building, in two layers.
|
|
60
|
+
**`title`**, **`kind`** (`stakeholder` | `solution`; files without it are read as `solution`), **`story`**, **`acceptanceCriteria`** (a list), **`status`** (`draft` | `awaiting-approval` | `approved` | `in-delivery` | `obsolete`), `stakeholder` (stakeholder requirements: who has the need), `stakeholderIds` (solution requirements: **required**, the stakeholder requirements it fulfils), `product` (solution requirements), `priority` (`must` | `should` | `could`), `findingIds`, `insightIds`, `hypothesisIds`, `origin` (`tender` | `regulation` | `contract` | `customer-need`) and `originNote`, `approver`, `approvedBy`, `approvedAt`, `recordedBy` (who entered an approval given by someone else), `approvalNote`, `obsoletedBy`, `obsoletedAt`, `productArea`, `createdAt`, `updatedAt`.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
The two layers:
|
|
63
|
+
|
|
64
|
+
- A **stakeholder requirement** says who needs what and why. Its `story` is a user story: "As a medical secretary I want a view of the calendars of all practitioners in the clinic with their unbooked slots highlighted so that I can find them and book appointments easily."
|
|
65
|
+
- A **solution requirement** describes the qualities and behaviour the solution must have to meet stakeholder needs. Its `story` is one or more "shall" statements: "The appointment view used by medical secretaries shall show the calendars of the selected practitioners with the free slots highlighted. It shall be possible to click a free slot to start the booking flow. It shall be possible to add or remove practitioners in the view."
|
|
66
|
+
- Every active solution requirement fulfils at least one stakeholder requirement (`stakeholderIds`). A stakeholder requirement is fulfilled by one or more solution requirements.
|
|
67
|
+
|
|
68
|
+
`findingIds`, `insightIds`, `hypothesisIds` and `origin` are optional: link them when the requirement rests on evidence or comes from a tender, regulation or contract.
|
|
63
69
|
|
|
64
70
|
### Links
|
|
65
71
|
|
|
@@ -79,6 +85,9 @@ These rules live in the core library, so every Groundwork tool applies them the
|
|
|
79
85
|
- Starting an experiment moves a `draft` hypothesis to `testing`.
|
|
80
86
|
- Recording results computes the verdict. It is **validated** when the primary metric reaches its target (`actual >= target` for `increase`, `<=` for `decrease`) and every guardrail holds. It is **invalidated** when either fails. The hypothesis moves to the same status.
|
|
81
87
|
- New hypotheses, findings and requirements without a `productArea` take the most common one among their linked evidence.
|
|
88
|
+
- A solution requirement can't be saved without at least one stakeholder requirement in `stakeholderIds`, and a stakeholder requirement can't have any. A stakeholder requirement can't be deleted while it is the only one a solution requirement fulfils. `validate` reports an active solution requirement without stakeholder links as an error.
|
|
89
|
+
- `validate` warns about an active stakeholder requirement that no solution requirement fulfils yet, and about a `story` that doesn't fit its layer: a stakeholder story without "As a … I want … so that …", or a solution requirement without "shall". The tools save these and return the same warnings.
|
|
90
|
+
- An approval given outside Groundwork (e.g. verbally) can be recorded with `approvedBy` and an optional note; the person recording it is stored as `recordedBy`.
|
|
82
91
|
- Requirements go from `draft` to `awaiting-approval` (with an `approver`) to `approved`. The approver can send one back to `draft`. Only `approved` requirements can become `obsolete`.
|
|
83
92
|
- Deleting an item removes links to it. Deleting a hypothesis also deletes its experiments.
|
|
84
93
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import {
|
|
2
2
|
buildServer,
|
|
3
3
|
findRoot
|
|
4
|
-
} from "./chunk-
|
|
4
|
+
} from "./chunk-TXXV5YDG.js";
|
|
5
5
|
|
|
6
6
|
// src/mcp/run.ts
|
|
7
7
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
@@ -13,4 +13,4 @@ async function runMcp() {
|
|
|
13
13
|
export {
|
|
14
14
|
runMcp
|
|
15
15
|
};
|
|
16
|
-
//# sourceMappingURL=chunk-
|
|
16
|
+
//# sourceMappingURL=chunk-4F24STNS.js.map
|
|
@@ -48,9 +48,29 @@ function kindOf(r) {
|
|
|
48
48
|
return r.kind ?? "solution";
|
|
49
49
|
}
|
|
50
50
|
var isObsolete = (r) => r.status === "obsolete";
|
|
51
|
+
var isActive = (r) => !isObsolete(r);
|
|
51
52
|
var canObsolete = (r) => r.status === "approved";
|
|
52
53
|
var canUpdateInPlace = (r) => r.status === "draft";
|
|
53
54
|
var canSendToDelivery = (r) => kindOf(r) === "solution" && r.status === "approved" && !r.delivery;
|
|
55
|
+
var STAKEHOLDER_STORY = /^\s*as\s+an?\s+.+?\bI\s+(want|need)\b.+?\bso\s+that\b/is;
|
|
56
|
+
var SOLUTION_STATEMENT = /\bshall\b/i;
|
|
57
|
+
function wordingWarnings(r) {
|
|
58
|
+
const story = r.story ?? "";
|
|
59
|
+
if (kindOf(r) === "stakeholder") {
|
|
60
|
+
return STAKEHOLDER_STORY.test(story) ? [] : ['a stakeholder requirement should be a user story: "As a <role> I want <need> so that <reason>"'];
|
|
61
|
+
}
|
|
62
|
+
return SOLUTION_STATEMENT.test(story) ? [] : ['a solution requirement should be written as "shall" statements, e.g. "The <system or part> shall \u2026"'];
|
|
63
|
+
}
|
|
64
|
+
function fulfilledBy(id, requirements) {
|
|
65
|
+
return requirements.filter((r) => kindOf(r) === "solution" && isActive(r) && r.stakeholderIds?.includes(id));
|
|
66
|
+
}
|
|
67
|
+
function layerProblem(r) {
|
|
68
|
+
if (kindOf(r) === "solution" && !r.stakeholderIds?.length) {
|
|
69
|
+
return "a solution requirement must fulfil at least one stakeholder requirement: add stakeholderIds (add the stakeholder requirement first if it doesn't exist)";
|
|
70
|
+
}
|
|
71
|
+
if (kindOf(r) === "stakeholder" && r.stakeholderIds?.length) return "stakeholderIds is only for solution requirements";
|
|
72
|
+
return void 0;
|
|
73
|
+
}
|
|
54
74
|
|
|
55
75
|
// src/core/verdict.ts
|
|
56
76
|
function metricPasses(m) {
|
|
@@ -332,13 +352,24 @@ function submitRequirement(s, c, id, approver) {
|
|
|
332
352
|
result: true
|
|
333
353
|
};
|
|
334
354
|
}
|
|
335
|
-
function approveRequirement(s, c, id) {
|
|
355
|
+
function approveRequirement(s, c, id, by) {
|
|
336
356
|
const r = s.requirements.find((x) => x.id === id);
|
|
337
357
|
if (!r || r.status === "approved" || r.status === "in-delivery" || r.status === "obsolete") return nothing(false);
|
|
358
|
+
const approvedBy = by?.approvedBy ?? c.actor;
|
|
359
|
+
const onBehalf = approvedBy !== c.actor;
|
|
360
|
+
const approved = {
|
|
361
|
+
...r,
|
|
362
|
+
status: "approved",
|
|
363
|
+
approvedBy,
|
|
364
|
+
approvedAt: c.now,
|
|
365
|
+
approver: r.approver ?? approvedBy,
|
|
366
|
+
...onBehalf ? { recordedBy: c.actor } : {},
|
|
367
|
+
...by?.note ? { approvalNote: by.note } : {}
|
|
368
|
+
};
|
|
338
369
|
return {
|
|
339
370
|
next: {
|
|
340
|
-
requirements: s.requirements.map((x) => x.id === id ?
|
|
341
|
-
activity: [log(c, "requirement", `approved "${r.title}"`, id), ...s.activity]
|
|
371
|
+
requirements: s.requirements.map((x) => x.id === id ? approved : x),
|
|
372
|
+
activity: [log(c, "requirement", onBehalf ? `approved "${r.title}" for ${approvedBy}` : `approved "${r.title}"`, id), ...s.activity]
|
|
342
373
|
},
|
|
343
374
|
result: true
|
|
344
375
|
};
|
|
@@ -490,21 +521,23 @@ function makeSchemas(id) {
|
|
|
490
521
|
productArea: area
|
|
491
522
|
});
|
|
492
523
|
const requirementInput3 = z.object({
|
|
493
|
-
kind: REQUIREMENT_KIND.
|
|
494
|
-
|
|
524
|
+
kind: REQUIREMENT_KIND.describe(
|
|
525
|
+
'stakeholder = who needs what and why, as a user story. solution = the qualities and behaviour the solution must have to meet stakeholder requirements, as "shall" statements.'
|
|
495
526
|
),
|
|
496
527
|
title: short(),
|
|
497
|
-
story: long(2e3).min(1).describe(
|
|
498
|
-
|
|
528
|
+
story: long(2e3).min(1).describe(
|
|
529
|
+
'Stakeholder: a user story, "As a <role> I want <need> so that <reason>". Solution: one or more "shall" statements, e.g. "The booking view shall show the calendars of the selected practitioners."'
|
|
530
|
+
),
|
|
531
|
+
stakeholder: z.string().trim().max(100).optional().describe('Stakeholder requirements: who has the need (the role in the story), e.g. "Medical secretaries".'),
|
|
499
532
|
product: z.string().trim().max(100).optional().describe("Solution requirements: the product that delivers it (one from get_workspace)."),
|
|
500
|
-
stakeholderIds: ids("
|
|
533
|
+
stakeholderIds: ids("Solution requirements: required, at least one. The stakeholder requirements this one fulfils").optional(),
|
|
501
534
|
acceptanceCriteria: z.array(short(500)).min(1).max(20),
|
|
502
535
|
priority: PRIORITY.default("should"),
|
|
503
536
|
findingIds: ids("the findings that justify it").default([]),
|
|
504
537
|
insightIds: ids("customer evidence linked directly").optional(),
|
|
505
538
|
hypothesisIds: ids("hypotheses it was committed from").optional(),
|
|
506
539
|
origin: REQUIREMENT_ORIGIN.optional().describe(
|
|
507
|
-
"
|
|
540
|
+
"Where a requirement decided outside the evidence loop comes from (tender, regulation, contract, customer-need). Optional."
|
|
508
541
|
),
|
|
509
542
|
originNote: z.string().trim().max(300).optional().describe('Where the decision comes from, e.g. "Region North tender 2026, section 4.2".'),
|
|
510
543
|
productArea: area
|
|
@@ -830,7 +863,7 @@ var STORED = {
|
|
|
830
863
|
hypothesis: hypothesisInput.extend({ status: HYPOTHESIS_STATUS, knowWhen: z3.string().optional() }).loose(),
|
|
831
864
|
experiment: experimentInput.extend({ status: EXPERIMENT_STATUS }).loose(),
|
|
832
865
|
finding: findingInput.loose(),
|
|
833
|
-
requirement: requirementInput.extend({ status: REQUIREMENT_STATUS, acceptanceCriteria: z3.array(z3.string()).default([]) }).loose()
|
|
866
|
+
requirement: requirementInput.extend({ kind: REQUIREMENT_KIND.optional(), status: REQUIREMENT_STATUS, acceptanceCriteria: z3.array(z3.string()).default([]) }).loose()
|
|
834
867
|
};
|
|
835
868
|
function validate(loaded, config) {
|
|
836
869
|
const out = loaded.problems.map((p) => ({ level: "error", ...p }));
|
|
@@ -883,8 +916,14 @@ function validate(loaded, config) {
|
|
|
883
916
|
const t = s.requirements.find((x) => x.id === id);
|
|
884
917
|
if (t && kindOf(t) !== "stakeholder") err(`stakeholderIds: ${id} is a solution requirement, not a stakeholder requirement`);
|
|
885
918
|
}
|
|
886
|
-
if (
|
|
887
|
-
|
|
919
|
+
if (isActive(r)) {
|
|
920
|
+
const problem = layerProblem(r);
|
|
921
|
+
if (problem) err(problem);
|
|
922
|
+
if (kindOf(r) === "stakeholder" && !fulfilledBy(r.id, s.requirements).length) {
|
|
923
|
+
warn("not yet fulfilled by any solution requirement");
|
|
924
|
+
}
|
|
925
|
+
wordingWarnings(r).forEach(warn);
|
|
926
|
+
}
|
|
888
927
|
if (r.product && config.products.length && !config.products.includes(r.product)) warn(`product "${r.product}" isn't in config.yml products`);
|
|
889
928
|
if (r.approver && !people.has(r.approver)) warn(`approver "${r.approver}" isn't in config.yml people`);
|
|
890
929
|
break;
|
|
@@ -950,7 +989,7 @@ function mergeProducts(existing, input) {
|
|
|
950
989
|
}
|
|
951
990
|
|
|
952
991
|
// src/mcp/server.ts
|
|
953
|
-
var VERSION = true ? "0.
|
|
992
|
+
var VERSION = true ? "0.4.0" : "0.0.0-dev";
|
|
954
993
|
var { insightInput: insightInput2, hypothesisInput: hypothesisInput2, experimentInput: experimentInput2, findingInput: findingInput2, requirementInput: requirementInput2, PATCHES } = localSchemas;
|
|
955
994
|
var INSTRUCTIONS = `Groundwork keeps this product's evidence and decisions as linked Markdown files in the groundwork/ folder, as a chain:
|
|
956
995
|
insight -> hypothesis -> experiment -> finding -> requirement.
|
|
@@ -959,15 +998,33 @@ insight -> hypothesis -> experiment -> finding -> requirement.
|
|
|
959
998
|
- Hypothesis: "We believe we will [outcome] if [forWhom] get [benefit] with [feature]", built on insights (insightIds), ideally with a successMetric (baseline, target, timeframe).
|
|
960
999
|
- Experiment: tests exactly one hypothesis (hypothesisId) with one primary metric and optional guardrails. Lifecycle: planned -> start_experiment -> record_experiment_results (Groundwork computes the verdict and updates the hypothesis).
|
|
961
1000
|
- Finding: what was learned, linked to the experiments, hypotheses and insights behind it.
|
|
962
|
-
- Requirement
|
|
1001
|
+
- Requirement, in two layers, written before building:
|
|
1002
|
+
- "stakeholder": who needs what and why, as a user story: "As a <role> I want <need> so that <reason>".
|
|
1003
|
+
- "solution": the qualities and behaviour the solution must have, as "shall" statements: "The <system or part> shall \u2026". Every solution requirement fulfils at least one stakeholder requirement (stakeholderIds); one stakeholder requirement is usually fulfilled by several solution requirements.
|
|
1004
|
+
Add the stakeholder requirements first, then the solution requirements that reference their ids. Link findingIds, insightIds or an origin (tender, regulation, contract, customer-need) when there is evidence or an outside source; they're optional.
|
|
963
1005
|
|
|
964
1006
|
How to work:
|
|
965
1007
|
1. Call get_workspace first: it gives product areas, products and people (for approvers). If an area or product you need is missing, add it with add_product_areas or add_products, after checking for an existing match.
|
|
966
1008
|
2. Before creating anything, search_items for duplicates and for evidence to link. Prefer linking to existing items over creating near-duplicates.
|
|
967
|
-
3. Always link evidence: hypotheses to insights, experiments to a hypothesis, findings to experiments/hypotheses/insights, requirements to findings.
|
|
1009
|
+
3. Always link evidence: hypotheses to insights, experiments to a hypothesis, findings to experiments/hypotheses/insights, solution requirements to the stakeholder requirements they fulfil, and requirements to findings when there are any.
|
|
968
1010
|
4. Ask the user before deleting items or approving requirements, unless they already told you to.
|
|
969
1011
|
5. Use these tools rather than editing the files directly: they keep ids unique and links valid. Each result includes the item's file: mention it so the user can open it.
|
|
970
|
-
6. The Markdown body under an item's frontmatter is the user's own notes. Read it, but don't overwrite it
|
|
1012
|
+
6. The Markdown body under an item's frontmatter is the user's own notes. Read it, but don't overwrite it.
|
|
1013
|
+
|
|
1014
|
+
When you plan work (a plan, plan mode, or a step in an autonomous workflow):
|
|
1015
|
+
1. Classify the task first. If unsure, search_items for related requirements.
|
|
1016
|
+
- New need: something users can't do today, e.g. "Let's add a feature to book appointments".
|
|
1017
|
+
- Change: existing behaviour that should work differently.
|
|
1018
|
+
- Fix: restores intended behaviour, e.g. "This path is broken, fix it". Refactors and dependency bumps count as fixes.
|
|
1019
|
+
2. State the call in one line of the plan, e.g. "New need: adds 2 stakeholder and 4 solution requirements" or "Bug fix under REQ-0007; no requirement changes".
|
|
1020
|
+
3. New need: the plan's first steps add the stakeholder requirements, then the solution requirements that fulfil them, before writing code.
|
|
1021
|
+
4. Change: update the requirement with update_item if it's a draft. If it's approved, add a new one, and once that's agreed make the old one obsolete with obsolete_requirement and replacedBy.
|
|
1022
|
+
5. Fix: don't write requirements. Name the requirement the fix restores when you can tell.
|
|
1023
|
+
6. With no person to review the plan (an autonomous workflow), follow your own call. The one-line call stays in the plan as the record.
|
|
1024
|
+
7. When the workflow creates tickets or user stories, use the solution requirements and the stakeholder stories they fulfil as a source. Put the REQ ids and each requirement's file path in the ticket. By default, one ticket per solution requirement.
|
|
1025
|
+
8. Approval given outside Groundwork (e.g. verbally by a PM): record it with approve_requirement, passing approvedBy and a note. Only do this when the user tells you who approved it.
|
|
1026
|
+
|
|
1027
|
+
Recording evidence or requirements directly isn't planning work. A product manager logging interview notes, drafting hypotheses, recording experiment results or writing requirements gets no new need / change / fix call: record what they ask for with the tools above.`;
|
|
971
1028
|
var UserError = class extends Error {
|
|
972
1029
|
};
|
|
973
1030
|
var an = (kind) => `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`;
|
|
@@ -1224,6 +1281,16 @@ function buildServer({ root }) {
|
|
|
1224
1281
|
for (const k of KIND.options) {
|
|
1225
1282
|
for (const item of items[COLLECTIONS[k]]) if (outgoing(k, item).includes(id)) linkedFrom.push(s.summary(k, item));
|
|
1226
1283
|
}
|
|
1284
|
+
if (hit.kind === "requirement" && kindOf(hit.item) === "stakeholder") {
|
|
1285
|
+
const fulfilling = fulfilledBy(id, items.requirements).map((x) => s.summary("requirement", x));
|
|
1286
|
+
return {
|
|
1287
|
+
item: s.full(hit.kind, hit.item),
|
|
1288
|
+
fulfilledBy: fulfilling,
|
|
1289
|
+
...fulfilling.length ? {} : { warnings: ["Not yet fulfilled by any solution requirement."] },
|
|
1290
|
+
linksTo,
|
|
1291
|
+
linkedFrom
|
|
1292
|
+
};
|
|
1293
|
+
}
|
|
1227
1294
|
return { item: s.full(hit.kind, hit.item), linksTo, linkedFrom };
|
|
1228
1295
|
})
|
|
1229
1296
|
);
|
|
@@ -1297,14 +1364,18 @@ function buildServer({ root }) {
|
|
|
1297
1364
|
"add_requirements",
|
|
1298
1365
|
{
|
|
1299
1366
|
title: "Add requirements",
|
|
1300
|
-
description:
|
|
1367
|
+
description: 'Add requirements as drafts. Stakeholder requirements are user stories ("As a <role> I want <need> so that <reason>"). Solution requirements are "shall" statements and must list the stakeholder requirements they fulfil in stakeholderIds, so add the stakeholder requirements first, in an earlier call. findingIds, insightIds and origin are optional evidence. The result lists wording warnings, if any. To ask for sign-off afterwards, use submit_requirement_for_approval.',
|
|
1301
1368
|
inputSchema: { requirements: z4.array(requirementInput2).min(1).max(30) }
|
|
1302
1369
|
},
|
|
1303
1370
|
write((s, state, c, { requirements }) => {
|
|
1304
1371
|
let next = state;
|
|
1305
1372
|
const created = [];
|
|
1306
1373
|
const derived = [];
|
|
1374
|
+
const warnings = [];
|
|
1307
1375
|
for (const r of requirements) {
|
|
1376
|
+
const problem = layerProblem(r);
|
|
1377
|
+
if (problem) throw new UserError(`"${r.title}": ${problem}.`);
|
|
1378
|
+
wordingWarnings(r).forEach((w) => warnings.push(`"${r.title}": ${w}.`));
|
|
1308
1379
|
s.check(state, "finding", r.findingIds, "findingIds");
|
|
1309
1380
|
s.check(state, "insight", r.insightIds, "insightIds");
|
|
1310
1381
|
s.check(state, "hypothesis", r.hypothesisIds, "hypothesisIds");
|
|
@@ -1317,7 +1388,6 @@ function buildServer({ root }) {
|
|
|
1317
1388
|
if (r.findingIds.length) {
|
|
1318
1389
|
derived.push(base);
|
|
1319
1390
|
} else {
|
|
1320
|
-
if (!r.origin) throw new UserError(`"${r.title}": link findingIds, or give an origin for a requirement decided elsewhere.`);
|
|
1321
1391
|
const { findingIds: _unused, ...direct } = base;
|
|
1322
1392
|
void _unused;
|
|
1323
1393
|
const [after, one] = apply(next, createRequirement(next, c, { ...direct, status: "draft" }));
|
|
@@ -1330,7 +1400,7 @@ function buildServer({ root }) {
|
|
|
1330
1400
|
next = after;
|
|
1331
1401
|
created.push(...many);
|
|
1332
1402
|
}
|
|
1333
|
-
return { state: next, result: { created: created.map((x) => s.summary("requirement", x)) } };
|
|
1403
|
+
return { state: next, result: { created: created.map((x) => s.summary("requirement", x)), ...warnings.length ? { warnings } : {} } };
|
|
1334
1404
|
})
|
|
1335
1405
|
);
|
|
1336
1406
|
server.registerTool(
|
|
@@ -1379,6 +1449,7 @@ function buildServer({ root }) {
|
|
|
1379
1449
|
const p = parsed.data;
|
|
1380
1450
|
if (!Object.keys(p).length) throw new UserError("The patch has no fields to change.");
|
|
1381
1451
|
if ("productArea" in p) p.productArea = s.area(p.productArea);
|
|
1452
|
+
const warnings = [];
|
|
1382
1453
|
let change;
|
|
1383
1454
|
switch (hit.kind) {
|
|
1384
1455
|
case "insight":
|
|
@@ -1412,13 +1483,23 @@ function buildServer({ root }) {
|
|
|
1412
1483
|
s.check(state, "insight", p.insightIds, "insightIds");
|
|
1413
1484
|
s.check(state, "hypothesis", p.hypothesisIds, "hypothesisIds");
|
|
1414
1485
|
s.checkStakeholders(state, p.stakeholderIds);
|
|
1486
|
+
const merged = { ...r, ...p };
|
|
1487
|
+
const problem = layerProblem(merged);
|
|
1488
|
+
if (problem) throw new UserError(`"${merged.title}": ${problem}.`);
|
|
1489
|
+
if (kindOf(r) === "stakeholder" && kindOf(merged) === "solution") {
|
|
1490
|
+
const fulfilling = fulfilledBy(id, state.requirements);
|
|
1491
|
+
if (fulfilling.length) {
|
|
1492
|
+
throw new UserError(`"${r.title}" is fulfilled by ${fulfilling.map((x) => x.id).join(", ")}, so it can't become a solution requirement.`);
|
|
1493
|
+
}
|
|
1494
|
+
}
|
|
1495
|
+
warnings.push(...wordingWarnings(merged).map((w) => `"${merged.title}": ${w}.`));
|
|
1415
1496
|
change = updateRequirement(state, id, { ...p, updatedAt: c.now });
|
|
1416
1497
|
break;
|
|
1417
1498
|
}
|
|
1418
1499
|
}
|
|
1419
1500
|
const [next] = apply(state, change);
|
|
1420
1501
|
const updated = find(next, id);
|
|
1421
|
-
return { state: next, result: { updated: s.full(updated.kind, updated.item) } };
|
|
1502
|
+
return { state: next, result: { updated: s.full(updated.kind, updated.item), ...warnings.length ? { warnings } : {} } };
|
|
1422
1503
|
})
|
|
1423
1504
|
);
|
|
1424
1505
|
server.registerTool(
|
|
@@ -1518,13 +1599,36 @@ function buildServer({ root }) {
|
|
|
1518
1599
|
"approve_requirement",
|
|
1519
1600
|
{
|
|
1520
1601
|
title: "Approve requirement",
|
|
1521
|
-
description: "Sign off a requirement that is awaiting your approval. Only the named approver can approve.",
|
|
1522
|
-
inputSchema: {
|
|
1602
|
+
description: "Sign off a requirement that is awaiting your approval. Only the named approver can approve. If the approver signed off outside Groundwork (e.g. verbally), pass approvedBy and a note. Groundwork records who entered it.",
|
|
1603
|
+
inputSchema: {
|
|
1604
|
+
id: itemId,
|
|
1605
|
+
approvedBy: z4.string().max(40).optional().describe("Who approved it, when they did so outside Groundwork, e.g. verbally. A person id from get_workspace."),
|
|
1606
|
+
note: z4.string().trim().max(300).optional().describe('How or where it was approved, e.g. "Approved by Maria in sprint planning".')
|
|
1607
|
+
},
|
|
1523
1608
|
annotations: { destructiveHint: false }
|
|
1524
1609
|
},
|
|
1525
|
-
write((s, state, c, { id }) => {
|
|
1610
|
+
write((s, state, c, { id, approvedBy, note }) => {
|
|
1526
1611
|
const r = requirementOf(state, id);
|
|
1527
|
-
if (
|
|
1612
|
+
if (approvedBy && approvedBy !== s.actor.id) {
|
|
1613
|
+
const person = s.config.people.find((m) => m.id === approvedBy);
|
|
1614
|
+
if (!person) throw new UserError(`${approvedBy} isn't in groundwork/config.yml people. Add them there first.`);
|
|
1615
|
+
if (person.role === "viewer") throw new UserError(`${person.name} is a viewer, so they can't approve.`);
|
|
1616
|
+
if (r.status !== "draft" && r.status !== "awaiting-approval") {
|
|
1617
|
+
throw new UserError(`"${r.title}" is ${r.status}; only drafts and requirements awaiting approval can be approved.`);
|
|
1618
|
+
}
|
|
1619
|
+
if (r.approver && r.approver !== approvedBy) {
|
|
1620
|
+
const asked = s.config.people.find((m) => m.id === r.approver)?.name ?? r.approver;
|
|
1621
|
+
throw new UserError(
|
|
1622
|
+
`"${r.title}" is waiting for ${asked}, not ${person.name}. Record ${asked}'s approval, or ask ${asked} to send it back so it can be submitted to ${person.name}.`
|
|
1623
|
+
);
|
|
1624
|
+
}
|
|
1625
|
+
const [next2] = apply(state, approveRequirement(state, c, id, { approvedBy, note }));
|
|
1626
|
+
return { state: next2, result: { approved: s.summary("requirement", requirementOf(next2, id)) } };
|
|
1627
|
+
}
|
|
1628
|
+
if (r.status !== "awaiting-approval") {
|
|
1629
|
+
const hint = r.status === "draft" ? " If someone approved it outside Groundwork, record it with approvedBy." : "";
|
|
1630
|
+
throw new UserError(`"${r.title}" is ${r.status}, not awaiting approval.${hint}`);
|
|
1631
|
+
}
|
|
1528
1632
|
if (r.approver !== s.actor.id) {
|
|
1529
1633
|
const name = s.config.people.find((m) => m.id === r.approver)?.name ?? r.approver ?? "someone else";
|
|
1530
1634
|
throw new UserError(`"${r.title}" is waiting for ${name}, not you (${s.actor.id}). Set GROUNDWORK_USER or your email in config.yml people if that's wrong.`);
|
|
@@ -1574,6 +1678,14 @@ function buildServer({ root }) {
|
|
|
1574
1678
|
write((_s, state, _c, { id }) => {
|
|
1575
1679
|
const hit = find(state, id);
|
|
1576
1680
|
if (!hit) throw new UserError(`No item with id ${id}.`);
|
|
1681
|
+
if (hit.kind === "requirement") {
|
|
1682
|
+
const orphaned = fulfilledBy(id, state.requirements).filter((r) => r.stakeholderIds?.length === 1);
|
|
1683
|
+
if (orphaned.length) {
|
|
1684
|
+
throw new UserError(
|
|
1685
|
+
`${orphaned.map((r) => `${r.id} "${r.title}"`).join(", ")} only fulfil${orphaned.length === 1 ? "s" : ""} "${hit.item.title}". Link ${orphaned.length === 1 ? "it" : "them"} to another stakeholder requirement or delete ${orphaned.length === 1 ? "it" : "them"} first.`
|
|
1686
|
+
);
|
|
1687
|
+
}
|
|
1688
|
+
}
|
|
1577
1689
|
const change = hit.kind === "insight" ? deleteInsight(state, id) : hit.kind === "hypothesis" ? deleteHypothesis(state, id) : hit.kind === "experiment" ? deleteExperiment(state, id) : hit.kind === "finding" ? deleteFinding(state, id) : deleteRequirement(state, id);
|
|
1578
1690
|
const [next] = apply(state, change);
|
|
1579
1691
|
const alsoDeleted = hit.kind === "hypothesis" ? state.experiments.filter((e) => e.hypothesisId === id).map((e) => e.id) : [];
|
|
@@ -1590,9 +1702,15 @@ export {
|
|
|
1590
1702
|
diffCollections,
|
|
1591
1703
|
kindOf,
|
|
1592
1704
|
isObsolete,
|
|
1705
|
+
isActive,
|
|
1593
1706
|
canObsolete,
|
|
1594
1707
|
canUpdateInPlace,
|
|
1595
1708
|
canSendToDelivery,
|
|
1709
|
+
STAKEHOLDER_STORY,
|
|
1710
|
+
SOLUTION_STATEMENT,
|
|
1711
|
+
wordingWarnings,
|
|
1712
|
+
fulfilledBy,
|
|
1713
|
+
layerProblem,
|
|
1596
1714
|
metricPasses,
|
|
1597
1715
|
computeVerdict,
|
|
1598
1716
|
fmtMetric,
|
|
@@ -1641,4 +1759,4 @@ export {
|
|
|
1641
1759
|
outgoing,
|
|
1642
1760
|
buildServer
|
|
1643
1761
|
};
|
|
1644
|
-
//# sourceMappingURL=chunk-
|
|
1762
|
+
//# sourceMappingURL=chunk-TXXV5YDG.js.map
|