@makerkit/prd 0.0.4 → 0.0.5
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/.turbo/turbo-build.log +78 -0
- package/.turbo/turbo-test.log +19 -0
- package/.turbo/turbo-typecheck.log +6 -0
- package/README.md +7 -1
- package/dist/README.md +71 -0
- package/dist/attachment-paths-BAhRGiib.js +112 -0
- package/dist/attachment-paths-C-SWgoSx.mjs +77 -0
- package/dist/index.d.ts +81 -0
- package/{index.js → dist/index.js} +155 -562
- package/{index.mjs → dist/index.mjs} +87 -497
- package/{mcp.d.ts → dist/mcp.d.ts} +2 -4
- package/{mcp.js → dist/mcp.js} +24 -24
- package/{mcp.mjs → dist/mcp.mjs} +24 -24
- package/{node.d.ts → dist/node.d.ts} +4 -4
- package/{node.js → dist/node.js} +28 -4
- package/{node.mjs → dist/node.mjs} +30 -6
- package/dist/operations.d.ts +141 -0
- package/dist/operations.js +22 -0
- package/dist/operations.mjs +1 -0
- package/dist/package.json +54 -0
- package/dist/prd-operations-BvFxo9bg.mjs +459 -0
- package/dist/prd-operations-CcahfbOy.js +584 -0
- package/dist/prd.service-CTwKZV-3.d.ts +114 -0
- package/{prompts-oI_6dxvx.js → dist/prompts-1qhax_dj.js} +113 -164
- package/{prompts-CPlFVutB.mjs → dist/prompts-BlsYD0gf.mjs} +96 -129
- package/{prd.service-CV0-aQHk.d.ts → dist/schema-BwTnt0B9.d.ts} +424 -336
- package/package.json +26 -2
- package/src/__tests__/agent-workflow.test.ts +417 -0
- package/src/__tests__/attachments.test.ts +505 -0
- package/src/__tests__/node.test.ts +199 -0
- package/src/__tests__/plan-check.test.ts +390 -0
- package/src/__tests__/planning.test.ts +1137 -0
- package/src/__tests__/prd-operations.test.ts +571 -0
- package/src/__tests__/prd.service.test.ts +652 -0
- package/src/__tests__/prd.tool.test.ts +282 -0
- package/src/__tests__/templates.test.ts +145 -0
- package/src/applicability.ts +73 -0
- package/src/attachment-paths.ts +83 -0
- package/src/attachments.ts +166 -0
- package/src/edge-cases.ts +61 -0
- package/src/index.ts +33 -0
- package/src/markdown.ts +297 -0
- package/src/mcp/index.ts +875 -0
- package/src/mcp/tool-response.ts +85 -0
- package/src/node.ts +184 -0
- package/src/open-questions.ts +98 -0
- package/src/plan-check.ts +385 -0
- package/src/planning-operations.ts +524 -0
- package/src/prd-operations.ts +769 -0
- package/src/prd.service.ts +1165 -0
- package/src/prompts.ts +161 -0
- package/src/safe-file-name.ts +42 -0
- package/src/schema.ts +1090 -0
- package/src/templates.ts +173 -0
- package/src/testing/fake-mcp-server.ts +81 -0
- package/src/types.ts +381 -0
- package/tsconfig.json +23 -0
- package/tsconfig.lib.json +8 -0
- package/tsconfig.spec.json +7 -0
- package/tsdown.config.mts +12 -0
- package/vitest.config.mts +8 -0
- package/index.d.ts +0 -233
- /package/{LICENSE → dist/LICENSE} +0 -0
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
import { isNotApplicable } from './applicability';
|
|
2
|
+
import { blockingQuestions } from './open-questions';
|
|
3
|
+
import type { NotApplicableTopic, StructuredPRD } from './types';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* What a plan is still missing, as items a UI can render as a checklist and an
|
|
7
|
+
* agent can act on. `required` items mean the plan is not ready to build;
|
|
8
|
+
* `recommended` items make it better but do not block.
|
|
9
|
+
*/
|
|
10
|
+
export interface PlanCheckItem {
|
|
11
|
+
/** Stable key, e.g. `stories` or `vague-stories`. */
|
|
12
|
+
id: string;
|
|
13
|
+
/** The PRD section to change, matching `update_prd_section` where possible. */
|
|
14
|
+
section: string;
|
|
15
|
+
message: string;
|
|
16
|
+
severity: 'required' | 'recommended';
|
|
17
|
+
/** Stories the item is about, when it is about specific stories. */
|
|
18
|
+
storyIds?: string[];
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The not-applicable topic each "missing" check is about. */
|
|
22
|
+
const CHECK_TOPICS: Record<string, NotApplicableTopic> = {
|
|
23
|
+
'edge-cases': 'edgeCases',
|
|
24
|
+
'design-guidance': 'design',
|
|
25
|
+
security: 'security',
|
|
26
|
+
permissions: 'security',
|
|
27
|
+
'global-acceptance-criteria': 'qualityBar',
|
|
28
|
+
'target-metrics': 'measurement',
|
|
29
|
+
rollout: 'rollout',
|
|
30
|
+
'data-models': 'dataModel',
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/** Above this many stories, grouping them into phases is recommended. */
|
|
34
|
+
const PHASE_THRESHOLD = 5;
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* From this many stories, the problem and solution should be written out:
|
|
38
|
+
* stories say what to build, the prose says what is meant. Fewer words than
|
|
39
|
+
* MIN_INTENT_WORDS rarely carries that.
|
|
40
|
+
*/
|
|
41
|
+
const INTENT_STORY_THRESHOLD = 3;
|
|
42
|
+
const MIN_INTENT_WORDS = 25;
|
|
43
|
+
|
|
44
|
+
function wordCount(text: string) {
|
|
45
|
+
return text.split(/\s+/).filter(Boolean).length;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function checkPlan(prd: StructuredPRD) {
|
|
49
|
+
const items: PlanCheckItem[] = [];
|
|
50
|
+
const stories = prd.userStories;
|
|
51
|
+
|
|
52
|
+
if (stories.length === 0) {
|
|
53
|
+
items.push({
|
|
54
|
+
id: 'stories',
|
|
55
|
+
section: 'userStories',
|
|
56
|
+
message: 'Add user stories to define specific functionality',
|
|
57
|
+
severity: 'required',
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const withoutCriteria = stories.filter(
|
|
62
|
+
(story) => story.acceptanceCriteria.length === 0,
|
|
63
|
+
);
|
|
64
|
+
|
|
65
|
+
if (withoutCriteria.length > 0) {
|
|
66
|
+
items.push({
|
|
67
|
+
id: 'stories-without-criteria',
|
|
68
|
+
section: 'userStories',
|
|
69
|
+
message: `${withoutCriteria.length} stories have no acceptance criteria`,
|
|
70
|
+
severity: 'required',
|
|
71
|
+
storyIds: withoutCriteria.map((story) => story.id),
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// What can go wrong is where agents guess most; a plan must say.
|
|
76
|
+
if (stories.length > 0 && prd.edgeCases.length === 0) {
|
|
77
|
+
items.push({
|
|
78
|
+
id: 'edge-cases',
|
|
79
|
+
section: 'edgeCases',
|
|
80
|
+
message:
|
|
81
|
+
'List what can go wrong (bad input, partial success, retries, permissions, limits, time zones) and what should happen',
|
|
82
|
+
severity: 'required',
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const openEdgeCases = prd.edgeCases.filter(
|
|
87
|
+
(edgeCase) => edgeCase.status === 'open',
|
|
88
|
+
);
|
|
89
|
+
|
|
90
|
+
if (openEdgeCases.length > 0) {
|
|
91
|
+
items.push({
|
|
92
|
+
id: 'open-edge-cases',
|
|
93
|
+
section: 'edgeCases',
|
|
94
|
+
message: `${openEdgeCases.length} edge cases are still open; decide what should happen`,
|
|
95
|
+
severity: 'required',
|
|
96
|
+
storyIds: [
|
|
97
|
+
...new Set(
|
|
98
|
+
openEdgeCases.flatMap((edgeCase) => edgeCase.storyIds ?? []),
|
|
99
|
+
),
|
|
100
|
+
],
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
if (stories.length > 0 && prd.designGuidance.length === 0) {
|
|
105
|
+
items.push({
|
|
106
|
+
id: 'design-guidance',
|
|
107
|
+
section: 'designGuidance',
|
|
108
|
+
message:
|
|
109
|
+
'Add design guidance: the components, layout and tone stories should follow, and how empty and error states look',
|
|
110
|
+
severity: 'recommended',
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// Who can do what must be stated once there is data or an outside service
|
|
115
|
+
// to protect; agents otherwise default to "any signed-in user".
|
|
116
|
+
if (
|
|
117
|
+
stories.length > 0 &&
|
|
118
|
+
prd.technicalContracts.permissions.length === 0 &&
|
|
119
|
+
(prd.technicalContracts.dataModels.length > 0 ||
|
|
120
|
+
prd.technicalRequirements.integrationNeeds.length > 0)
|
|
121
|
+
) {
|
|
122
|
+
items.push({
|
|
123
|
+
id: 'permissions',
|
|
124
|
+
section: 'technicalContracts',
|
|
125
|
+
message:
|
|
126
|
+
'Say who can see and change what (roles, ownership, other tenants) in technicalContracts.permissions',
|
|
127
|
+
severity: 'required',
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
if (stories.length > 0 && prd.securityConsiderations.length === 0) {
|
|
132
|
+
items.push({
|
|
133
|
+
id: 'security',
|
|
134
|
+
section: 'securityConsiderations',
|
|
135
|
+
message:
|
|
136
|
+
"Add security considerations: think like an attacker (inputs, access to other users' data, secrets, abuse, rate limits) and state the rules that prevent it",
|
|
137
|
+
severity: 'recommended',
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
if (prd.nonGoals.length === 0 && prd.outOfScope.length === 0) {
|
|
142
|
+
items.push({
|
|
143
|
+
id: 'scope',
|
|
144
|
+
section: 'nonGoals',
|
|
145
|
+
message:
|
|
146
|
+
'Define both non-goals and out-of-scope items to reduce implementation drift',
|
|
147
|
+
severity: 'required',
|
|
148
|
+
});
|
|
149
|
+
} else if (prd.nonGoals.length === 0 || prd.outOfScope.length === 0) {
|
|
150
|
+
items.push({
|
|
151
|
+
id: 'scope',
|
|
152
|
+
section: prd.nonGoals.length === 0 ? 'nonGoals' : 'outOfScope',
|
|
153
|
+
message:
|
|
154
|
+
'Define both non-goals and out-of-scope items to reduce implementation drift',
|
|
155
|
+
severity: 'recommended',
|
|
156
|
+
});
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
if (prd.solutionOverview.successMetrics.length === 0) {
|
|
160
|
+
items.push({
|
|
161
|
+
id: 'success-metrics',
|
|
162
|
+
section: 'solutionOverview',
|
|
163
|
+
message: 'Define success metrics to measure progress',
|
|
164
|
+
severity: 'recommended',
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
if (prd.acceptanceCriteria.global.length === 0) {
|
|
169
|
+
items.push({
|
|
170
|
+
id: 'global-acceptance-criteria',
|
|
171
|
+
section: 'acceptanceCriteria',
|
|
172
|
+
message: 'Add global acceptance criteria for quality standards',
|
|
173
|
+
severity: 'recommended',
|
|
174
|
+
});
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// A question that blocks a story must be answered before that story is
|
|
178
|
+
// built; the others improve the plan but can wait.
|
|
179
|
+
const blocking = blockingQuestions(prd);
|
|
180
|
+
const others = prd.openQuestions.filter(
|
|
181
|
+
(question) => !blocking.includes(question),
|
|
182
|
+
);
|
|
183
|
+
|
|
184
|
+
if (blocking.length > 0) {
|
|
185
|
+
items.push({
|
|
186
|
+
id: 'blocking-questions',
|
|
187
|
+
section: 'openQuestions',
|
|
188
|
+
message: `${blocking.length} open questions block stories; answer them before those stories are built`,
|
|
189
|
+
severity: 'required',
|
|
190
|
+
storyIds: [
|
|
191
|
+
...new Set(blocking.flatMap((question) => question.storyIds ?? [])),
|
|
192
|
+
],
|
|
193
|
+
});
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
if (others.length > 0) {
|
|
197
|
+
items.push({
|
|
198
|
+
id: 'open-questions',
|
|
199
|
+
section: 'openQuestions',
|
|
200
|
+
message: `${others.length} open questions remain unresolved`,
|
|
201
|
+
severity: 'recommended',
|
|
202
|
+
});
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
if (prd.measurementPlan.targetMetrics.length === 0) {
|
|
206
|
+
items.push({
|
|
207
|
+
id: 'target-metrics',
|
|
208
|
+
section: 'measurementPlan',
|
|
209
|
+
message:
|
|
210
|
+
'Define target metrics in measurementPlan to validate delivery impact',
|
|
211
|
+
severity: 'recommended',
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
if (prd.rolloutPlan.rolloutPhases.length === 0) {
|
|
216
|
+
items.push({
|
|
217
|
+
id: 'rollout',
|
|
218
|
+
section: 'rolloutPlan',
|
|
219
|
+
message: 'Add rollout phases and rollback conditions',
|
|
220
|
+
severity: 'recommended',
|
|
221
|
+
});
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
if (stories.length > 0 && prd.technicalContracts.dataModels.length === 0) {
|
|
225
|
+
items.push({
|
|
226
|
+
id: 'data-models',
|
|
227
|
+
section: 'technicalContracts',
|
|
228
|
+
message:
|
|
229
|
+
'Describe the main entities and how they relate in technicalContracts.dataModels',
|
|
230
|
+
severity: 'recommended',
|
|
231
|
+
});
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
// Stories with no criteria are already reported as required.
|
|
235
|
+
const vague = stories.filter(
|
|
236
|
+
(story) =>
|
|
237
|
+
story.acceptanceCriteria.length > 0 &&
|
|
238
|
+
story.acceptanceCriteria.length < 2,
|
|
239
|
+
);
|
|
240
|
+
|
|
241
|
+
if (vague.length > 0) {
|
|
242
|
+
items.push({
|
|
243
|
+
id: 'vague-stories',
|
|
244
|
+
section: 'userStories',
|
|
245
|
+
message: `${vague.length} stories need more detailed acceptance criteria`,
|
|
246
|
+
severity: 'recommended',
|
|
247
|
+
storyIds: vague.map((story) => story.id),
|
|
248
|
+
});
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const withoutSeams = stories.filter(
|
|
252
|
+
(story) => story.status !== 'completed' && !story.testSeams?.length,
|
|
253
|
+
);
|
|
254
|
+
|
|
255
|
+
if (withoutSeams.length > 0) {
|
|
256
|
+
items.push({
|
|
257
|
+
id: 'test-seams',
|
|
258
|
+
section: 'userStories',
|
|
259
|
+
message: `${withoutSeams.length} stories do not say where they are tested (testSeams)`,
|
|
260
|
+
severity: 'recommended',
|
|
261
|
+
storyIds: withoutSeams.map((story) => story.id),
|
|
262
|
+
});
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
// A criterion without a proof is one an agent can call done on belief.
|
|
266
|
+
const unproven = stories.filter(
|
|
267
|
+
(story) =>
|
|
268
|
+
story.status !== 'completed' &&
|
|
269
|
+
story.acceptanceCriteria.some(
|
|
270
|
+
(criterion) =>
|
|
271
|
+
!story.proofs?.some((proof) => proof.criterion === criterion),
|
|
272
|
+
),
|
|
273
|
+
);
|
|
274
|
+
|
|
275
|
+
if (unproven.length > 0) {
|
|
276
|
+
items.push({
|
|
277
|
+
id: 'unproven-criteria',
|
|
278
|
+
section: 'userStories',
|
|
279
|
+
message: `${unproven.length} stories have acceptance criteria with no proof; say how each is shown to work (proofs)`,
|
|
280
|
+
severity: 'recommended',
|
|
281
|
+
storyIds: unproven.map((story) => story.id),
|
|
282
|
+
});
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
// A hard test is a reason to prove it at a lower seam, not to skip one.
|
|
286
|
+
const unjustifiedE2e = stories.filter(
|
|
287
|
+
(story) =>
|
|
288
|
+
story.status !== 'completed' &&
|
|
289
|
+
story.proofs?.some((proof) => proof.kind === 'e2e' && !proof.reason),
|
|
290
|
+
);
|
|
291
|
+
|
|
292
|
+
if (unjustifiedE2e.length > 0) {
|
|
293
|
+
items.push({
|
|
294
|
+
id: 'e2e-proofs',
|
|
295
|
+
section: 'userStories',
|
|
296
|
+
message: `${unjustifiedE2e.length} stories rely on e2e proofs without saying why a lower seam (service, server action, route) will not do`,
|
|
297
|
+
severity: 'recommended',
|
|
298
|
+
storyIds: unjustifiedE2e.map((story) => story.id),
|
|
299
|
+
});
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
// When most of a story can only be checked by hand, the criteria are
|
|
303
|
+
// usually too vague to test, not truly untestable.
|
|
304
|
+
const mostlyManual = stories.filter((story) => {
|
|
305
|
+
const proofs = story.proofs ?? [];
|
|
306
|
+
const untested = proofs.filter(
|
|
307
|
+
(proof) => proof.kind === 'manual' || proof.kind === 'post-deploy',
|
|
308
|
+
);
|
|
309
|
+
|
|
310
|
+
return story.status !== 'completed' && untested.length * 2 > proofs.length;
|
|
311
|
+
});
|
|
312
|
+
|
|
313
|
+
if (mostlyManual.length > 0) {
|
|
314
|
+
items.push({
|
|
315
|
+
id: 'untested-proofs',
|
|
316
|
+
section: 'userStories',
|
|
317
|
+
message: `${mostlyManual.length} stories are mostly proven by hand; split the criteria so the testable parts get a test`,
|
|
318
|
+
severity: 'recommended',
|
|
319
|
+
storyIds: mostlyManual.map((story) => story.id),
|
|
320
|
+
});
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// Structure is precise; the prose is what keeps it accurate to the intent.
|
|
324
|
+
if (stories.length >= INTENT_STORY_THRESHOLD) {
|
|
325
|
+
if (wordCount(prd.problemStatement.problem) < MIN_INTENT_WORDS) {
|
|
326
|
+
items.push({
|
|
327
|
+
id: 'thin-problem',
|
|
328
|
+
section: 'problemStatement',
|
|
329
|
+
message:
|
|
330
|
+
'Describe the problem in a few sentences: who has it, when, and what it costs them. The stories are checked against it',
|
|
331
|
+
severity: 'recommended',
|
|
332
|
+
});
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
if (wordCount(prd.solutionOverview.description) < MIN_INTENT_WORDS) {
|
|
336
|
+
items.push({
|
|
337
|
+
id: 'thin-solution',
|
|
338
|
+
section: 'solutionOverview',
|
|
339
|
+
message:
|
|
340
|
+
'Describe the finished feature in a few sentences: what a person can do and how it feels. The stories are checked against it',
|
|
341
|
+
severity: 'recommended',
|
|
342
|
+
});
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
const phased = new Set(
|
|
347
|
+
prd.customPhases.flatMap((phase) => phase.userStoryIds),
|
|
348
|
+
);
|
|
349
|
+
const unphased = stories.filter((story) => !phased.has(story.id));
|
|
350
|
+
|
|
351
|
+
if (stories.length > PHASE_THRESHOLD && unphased.length > 0) {
|
|
352
|
+
items.push({
|
|
353
|
+
id: 'phases',
|
|
354
|
+
section: 'customPhases',
|
|
355
|
+
message: `${unphased.length} stories are not in a phase; group them into phases in build order`,
|
|
356
|
+
severity: 'recommended',
|
|
357
|
+
storyIds: unphased.map((story) => story.id),
|
|
358
|
+
});
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
const blocked = stories.filter((story) => story.status === 'blocked');
|
|
362
|
+
|
|
363
|
+
if (blocked.length > 0) {
|
|
364
|
+
items.push({
|
|
365
|
+
id: 'blocked-stories',
|
|
366
|
+
section: 'userStories',
|
|
367
|
+
message: `${blocked.length} stories are blocked and need attention`,
|
|
368
|
+
severity: 'recommended',
|
|
369
|
+
storyIds: blocked.map((story) => story.id),
|
|
370
|
+
});
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
// Parts marked not applicable are not asked for. Open edge cases still
|
|
374
|
+
// count: they were written down, so they need an answer.
|
|
375
|
+
const applicable = items.filter((item) => {
|
|
376
|
+
const topic = CHECK_TOPICS[item.id];
|
|
377
|
+
|
|
378
|
+
return !topic || !isNotApplicable(prd, topic);
|
|
379
|
+
});
|
|
380
|
+
|
|
381
|
+
return {
|
|
382
|
+
ready_to_build: !applicable.some((item) => item.severity === 'required'),
|
|
383
|
+
items: applicable,
|
|
384
|
+
};
|
|
385
|
+
}
|