@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.
Files changed (63) hide show
  1. package/.turbo/turbo-build.log +78 -0
  2. package/.turbo/turbo-test.log +19 -0
  3. package/.turbo/turbo-typecheck.log +6 -0
  4. package/README.md +7 -1
  5. package/dist/README.md +71 -0
  6. package/dist/attachment-paths-BAhRGiib.js +112 -0
  7. package/dist/attachment-paths-C-SWgoSx.mjs +77 -0
  8. package/dist/index.d.ts +81 -0
  9. package/{index.js → dist/index.js} +155 -562
  10. package/{index.mjs → dist/index.mjs} +87 -497
  11. package/{mcp.d.ts → dist/mcp.d.ts} +2 -4
  12. package/{mcp.js → dist/mcp.js} +24 -24
  13. package/{mcp.mjs → dist/mcp.mjs} +24 -24
  14. package/{node.d.ts → dist/node.d.ts} +4 -4
  15. package/{node.js → dist/node.js} +28 -4
  16. package/{node.mjs → dist/node.mjs} +30 -6
  17. package/dist/operations.d.ts +141 -0
  18. package/dist/operations.js +22 -0
  19. package/dist/operations.mjs +1 -0
  20. package/dist/package.json +54 -0
  21. package/dist/prd-operations-BvFxo9bg.mjs +459 -0
  22. package/dist/prd-operations-CcahfbOy.js +584 -0
  23. package/dist/prd.service-CTwKZV-3.d.ts +114 -0
  24. package/{prompts-oI_6dxvx.js → dist/prompts-1qhax_dj.js} +113 -164
  25. package/{prompts-CPlFVutB.mjs → dist/prompts-BlsYD0gf.mjs} +96 -129
  26. package/{prd.service-CV0-aQHk.d.ts → dist/schema-BwTnt0B9.d.ts} +424 -336
  27. package/package.json +26 -2
  28. package/src/__tests__/agent-workflow.test.ts +417 -0
  29. package/src/__tests__/attachments.test.ts +505 -0
  30. package/src/__tests__/node.test.ts +199 -0
  31. package/src/__tests__/plan-check.test.ts +390 -0
  32. package/src/__tests__/planning.test.ts +1137 -0
  33. package/src/__tests__/prd-operations.test.ts +571 -0
  34. package/src/__tests__/prd.service.test.ts +652 -0
  35. package/src/__tests__/prd.tool.test.ts +282 -0
  36. package/src/__tests__/templates.test.ts +145 -0
  37. package/src/applicability.ts +73 -0
  38. package/src/attachment-paths.ts +83 -0
  39. package/src/attachments.ts +166 -0
  40. package/src/edge-cases.ts +61 -0
  41. package/src/index.ts +33 -0
  42. package/src/markdown.ts +297 -0
  43. package/src/mcp/index.ts +875 -0
  44. package/src/mcp/tool-response.ts +85 -0
  45. package/src/node.ts +184 -0
  46. package/src/open-questions.ts +98 -0
  47. package/src/plan-check.ts +385 -0
  48. package/src/planning-operations.ts +524 -0
  49. package/src/prd-operations.ts +769 -0
  50. package/src/prd.service.ts +1165 -0
  51. package/src/prompts.ts +161 -0
  52. package/src/safe-file-name.ts +42 -0
  53. package/src/schema.ts +1090 -0
  54. package/src/templates.ts +173 -0
  55. package/src/testing/fake-mcp-server.ts +81 -0
  56. package/src/types.ts +381 -0
  57. package/tsconfig.json +23 -0
  58. package/tsconfig.lib.json +8 -0
  59. package/tsconfig.spec.json +7 -0
  60. package/tsdown.config.mts +12 -0
  61. package/vitest.config.mts +8 -0
  62. package/index.d.ts +0 -233
  63. /package/{LICENSE → dist/LICENSE} +0 -0
@@ -0,0 +1,875 @@
1
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ import { z } from 'zod/v3';
3
+
4
+ import type { PrdService } from '../prd.service';
5
+ import {
6
+ architectPrdPrompt,
7
+ implementStoryPrompt,
8
+ reviewStoryPrompt,
9
+ shapePrdPrompt,
10
+ } from '../prompts';
11
+ import {
12
+ AddAttachmentInputSchema,
13
+ AddAttachmentOutputSchema,
14
+ AddUserStoryInputSchema,
15
+ AddUserStoryOutputSchema,
16
+ CreatePrdInputSchema,
17
+ CreatePrdOutputSchema,
18
+ DeletePrdInputSchema,
19
+ DeletePrdOutputSchema,
20
+ ExportPrdMarkdownInputSchema,
21
+ ExportPrdMarkdownOutputSchema,
22
+ GetImplementationPromptsInputSchema,
23
+ GetImplementationPromptsOutputSchema,
24
+ GetImprovementSuggestionsInputSchema,
25
+ GetImprovementSuggestionsOutputSchema,
26
+ GetPrdInputSchema,
27
+ GetPrdOutputSchema,
28
+ GetProjectStatusInputSchema,
29
+ RemoveAttachmentInputSchema,
30
+ RemoveAttachmentOutputSchema,
31
+ GetProjectStatusOutputSchema,
32
+ ListPrdsInputSchema,
33
+ ListPrdsOutputSchema,
34
+ UpdateStoryStatusInputSchema,
35
+ UpdateStoryStatusOutputSchema,
36
+ UpdateUserStoryInputSchema,
37
+ UpdateUserStoryOutputSchema,
38
+ DeleteUserStoryInputSchema,
39
+ DeleteUserStoryOutputSchema,
40
+ CreateCustomPhaseInputSchema,
41
+ CreateCustomPhaseOutputSchema,
42
+ AssignStoryToPhaseInputSchema,
43
+ AssignStoryToPhaseOutputSchema,
44
+ GetNextStoryInputSchema,
45
+ GetNextStoryOutputSchema,
46
+ GetStoryInputSchema,
47
+ GetStoryOutputSchema,
48
+ AddStoryLogInputSchema,
49
+ AddStoryLogOutputSchema,
50
+ UpdatePrdSectionInputSchema,
51
+ UpdatePrdSectionOutputSchema,
52
+ AddDecisionInputSchema,
53
+ AddDecisionOutputSchema,
54
+ DecideEdgeCaseInputSchema,
55
+ UpdateAttachmentInputSchema,
56
+ UpdateAttachmentOutputSchema,
57
+ DecideEdgeCaseOutputSchema,
58
+ MarkNotApplicableInputSchema,
59
+ MarkNotApplicableOutputSchema,
60
+ ResolveOpenQuestionInputSchema,
61
+ ResolveOpenQuestionOutputSchema,
62
+ AddGlossaryTermInputSchema,
63
+ AddGlossaryTermOutputSchema,
64
+ UpdatePhaseInputSchema,
65
+ DeletePhaseInputSchema,
66
+ ReorderPhasesInputSchema,
67
+ PhasesOutputSchema,
68
+ CheckPlanInputSchema,
69
+ CheckPlanOutputSchema,
70
+ ListTemplatesInputSchema,
71
+ ListTemplatesOutputSchema,
72
+ } from '../schema';
73
+ import {
74
+ DESTRUCTIVE_TOOL,
75
+ IDEMPOTENT_MUTATING_TOOL,
76
+ MUTATING_TOOL,
77
+ READ_ONLY_TOOL,
78
+ buildErrorResponse,
79
+ buildStructuredResponse,
80
+ } from './tool-response';
81
+
82
+ /**
83
+ * Registers the PRD tools on an MCP server. The caller builds the service, so
84
+ * it decides where PRDs live and which checks gate a story's completion.
85
+ */
86
+ export function registerPRDTools(server: McpServer, service: PrdService) {
87
+ server.registerTool(
88
+ 'list_prds',
89
+ {
90
+ title: 'List PRDs',
91
+ description:
92
+ 'List PRDs with story progress and optional roadmap metadata, sorted by order, then criticality.',
93
+ inputSchema: ListPrdsInputSchema,
94
+ outputSchema: ListPrdsOutputSchema,
95
+ annotations: READ_ONLY_TOOL,
96
+ },
97
+ async () => {
98
+ try {
99
+ return buildStructuredResponse(await service.list());
100
+ } catch (error) {
101
+ return buildErrorResponse('list_prds', error);
102
+ }
103
+ },
104
+ );
105
+
106
+ server.registerTool(
107
+ 'get_prd',
108
+ {
109
+ title: 'Read a PRD',
110
+ description: 'Get the full contents of one PRD file.',
111
+ inputSchema: GetPrdInputSchema,
112
+ outputSchema: GetPrdOutputSchema,
113
+ annotations: READ_ONLY_TOOL,
114
+ },
115
+ async (input) => {
116
+ try {
117
+ const parsed = GetPrdInputSchema.parse(input);
118
+
119
+ return buildStructuredResponse(await service.get(parsed));
120
+ } catch (error) {
121
+ return buildErrorResponse('get_prd', error);
122
+ }
123
+ },
124
+ );
125
+
126
+ server.registerTool(
127
+ 'create_prd',
128
+ {
129
+ title: 'Create a PRD',
130
+ description:
131
+ 'Create a new structured PRD in the configured directory. The file name is derived from the title.',
132
+ inputSchema: CreatePrdInputSchema,
133
+ outputSchema: CreatePrdOutputSchema,
134
+ annotations: MUTATING_TOOL,
135
+ },
136
+ async (input) => {
137
+ try {
138
+ const parsed = CreatePrdInputSchema.parse(input);
139
+
140
+ return buildStructuredResponse(await service.create(parsed));
141
+ } catch (error) {
142
+ return buildErrorResponse('create_prd', error);
143
+ }
144
+ },
145
+ );
146
+
147
+ server.registerTool(
148
+ 'delete_prd',
149
+ {
150
+ title: 'Delete a PRD',
151
+ description:
152
+ 'Permanently delete a PRD file. Its folder of attachments, if any, is kept.',
153
+ inputSchema: DeletePrdInputSchema,
154
+ outputSchema: DeletePrdOutputSchema,
155
+ annotations: DESTRUCTIVE_TOOL,
156
+ },
157
+ async (input) => {
158
+ try {
159
+ const parsed = DeletePrdInputSchema.parse(input);
160
+
161
+ return buildStructuredResponse(await service.delete(parsed));
162
+ } catch (error) {
163
+ return buildErrorResponse('delete_prd', error);
164
+ }
165
+ },
166
+ );
167
+
168
+ server.registerTool(
169
+ 'add_user_story',
170
+ {
171
+ title: 'Add a user story',
172
+ description:
173
+ 'Append a user story with acceptance criteria to a PRD. A story is one commit-sized change: one behaviour a test can check (not a single button, field or migration), leaving the build passing.',
174
+ inputSchema: AddUserStoryInputSchema,
175
+ outputSchema: AddUserStoryOutputSchema,
176
+ annotations: MUTATING_TOOL,
177
+ },
178
+ async (input) => {
179
+ try {
180
+ const parsed = AddUserStoryInputSchema.parse(input);
181
+
182
+ return buildStructuredResponse(await service.addUserStory(parsed));
183
+ } catch (error) {
184
+ return buildErrorResponse('add_user_story', error);
185
+ }
186
+ },
187
+ );
188
+
189
+ server.registerTool(
190
+ 'update_story_status',
191
+ {
192
+ title: 'Update story status',
193
+ description:
194
+ 'Update a user story status. Pass workerId with "in_progress" to claim a story, or with "review" to claim an existing review. A claimed story requires the same workerId for status and log changes. Completion runs the project checks and can record accepted deviations.',
195
+ inputSchema: UpdateStoryStatusInputSchema,
196
+ outputSchema: UpdateStoryStatusOutputSchema,
197
+ // Re-running "completed" re-executes the checks and rewrites the
198
+ // verification timestamp, so it is not idempotent.
199
+ annotations: MUTATING_TOOL,
200
+ },
201
+ async (input) => {
202
+ try {
203
+ const parsed = UpdateStoryStatusInputSchema.parse(input);
204
+
205
+ return buildStructuredResponse(await service.updateStoryStatus(parsed));
206
+ } catch (error) {
207
+ return buildErrorResponse('update_story_status', error);
208
+ }
209
+ },
210
+ );
211
+
212
+ server.registerTool(
213
+ 'update_user_story',
214
+ {
215
+ title: 'Update a user story',
216
+ description:
217
+ "Edit an existing story's content. Every field is optional; only the ones supplied change. Use update_story_status for status.",
218
+ inputSchema: UpdateUserStoryInputSchema,
219
+ outputSchema: UpdateUserStoryOutputSchema,
220
+ annotations: IDEMPOTENT_MUTATING_TOOL,
221
+ },
222
+ async (input) => {
223
+ try {
224
+ const parsed = UpdateUserStoryInputSchema.parse(input);
225
+
226
+ return buildStructuredResponse(await service.updateUserStory(parsed));
227
+ } catch (error) {
228
+ return buildErrorResponse('update_user_story', error);
229
+ }
230
+ },
231
+ );
232
+
233
+ server.registerTool(
234
+ 'delete_user_story',
235
+ {
236
+ title: 'Delete a user story',
237
+ description:
238
+ "Remove a story and clean up references to it in other stories' dependencies and in phases. Story ids are never reissued.",
239
+ inputSchema: DeleteUserStoryInputSchema,
240
+ outputSchema: DeleteUserStoryOutputSchema,
241
+ annotations: DESTRUCTIVE_TOOL,
242
+ },
243
+ async (input) => {
244
+ try {
245
+ const parsed = DeleteUserStoryInputSchema.parse(input);
246
+
247
+ return buildStructuredResponse(await service.deleteUserStory(parsed));
248
+ } catch (error) {
249
+ return buildErrorResponse('delete_user_story', error);
250
+ }
251
+ },
252
+ );
253
+
254
+ server.registerTool(
255
+ 'create_custom_phase',
256
+ {
257
+ title: 'Create a delivery phase',
258
+ description:
259
+ 'Create a named phase (e.g. "MVP", "Fast follow") that stories can be grouped into.',
260
+ inputSchema: CreateCustomPhaseInputSchema,
261
+ outputSchema: CreateCustomPhaseOutputSchema,
262
+ annotations: MUTATING_TOOL,
263
+ },
264
+ async (input) => {
265
+ try {
266
+ const parsed = CreateCustomPhaseInputSchema.parse(input);
267
+
268
+ return buildStructuredResponse(await service.createCustomPhase(parsed));
269
+ } catch (error) {
270
+ return buildErrorResponse('create_custom_phase', error);
271
+ }
272
+ },
273
+ );
274
+
275
+ server.registerTool(
276
+ 'assign_story_to_phase',
277
+ {
278
+ title: 'Assign a story to a phase',
279
+ description:
280
+ 'Move a story into a phase, or pass phaseId null to remove it from every phase. A story belongs to at most one phase.',
281
+ inputSchema: AssignStoryToPhaseInputSchema,
282
+ outputSchema: AssignStoryToPhaseOutputSchema,
283
+ annotations: IDEMPOTENT_MUTATING_TOOL,
284
+ },
285
+ async (input) => {
286
+ try {
287
+ const parsed = AssignStoryToPhaseInputSchema.parse(input);
288
+
289
+ return buildStructuredResponse(
290
+ await service.assignStoryToPhase(parsed),
291
+ );
292
+ } catch (error) {
293
+ return buildErrorResponse('assign_story_to_phase', error);
294
+ }
295
+ },
296
+ );
297
+
298
+ server.registerTool(
299
+ 'export_prd_markdown',
300
+ {
301
+ title: 'Export PRD as Markdown',
302
+ description:
303
+ 'Write a Markdown rendering of the PRD next to the JSON file.',
304
+ inputSchema: ExportPrdMarkdownInputSchema,
305
+ outputSchema: ExportPrdMarkdownOutputSchema,
306
+ annotations: IDEMPOTENT_MUTATING_TOOL,
307
+ },
308
+ async (input) => {
309
+ try {
310
+ const parsed = ExportPrdMarkdownInputSchema.parse(input);
311
+
312
+ return buildStructuredResponse(await service.exportMarkdown(parsed));
313
+ } catch (error) {
314
+ return buildErrorResponse('export_prd_markdown', error);
315
+ }
316
+ },
317
+ );
318
+
319
+ server.registerTool(
320
+ 'get_implementation_prompts',
321
+ {
322
+ title: 'Implementation prompts',
323
+ description:
324
+ 'One autonomous implementation prompt when there is work ready to start, as text to paste into an agent that does not support MCP prompts.',
325
+ inputSchema: GetImplementationPromptsInputSchema,
326
+ outputSchema: GetImplementationPromptsOutputSchema,
327
+ annotations: READ_ONLY_TOOL,
328
+ },
329
+ async (input) => {
330
+ try {
331
+ const { filename } = GetImplementationPromptsInputSchema.parse(input);
332
+
333
+ return buildStructuredResponse(
334
+ await service.getImplementationPrompts(filename),
335
+ );
336
+ } catch (error) {
337
+ return buildErrorResponse('get_implementation_prompts', error);
338
+ }
339
+ },
340
+ );
341
+
342
+ server.registerTool(
343
+ 'get_improvement_suggestions',
344
+ {
345
+ title: 'PRD completeness checks',
346
+ description:
347
+ 'Rule-based suggestions for missing PRD sections (stories, metrics, scope guardrails, rollout plan).',
348
+ inputSchema: GetImprovementSuggestionsInputSchema,
349
+ outputSchema: GetImprovementSuggestionsOutputSchema,
350
+ annotations: READ_ONLY_TOOL,
351
+ },
352
+ async (input) => {
353
+ try {
354
+ const { filename } = GetImprovementSuggestionsInputSchema.parse(input);
355
+
356
+ return buildStructuredResponse(
357
+ await service.getImprovementSuggestions(filename),
358
+ );
359
+ } catch (error) {
360
+ return buildErrorResponse('get_improvement_suggestions', error);
361
+ }
362
+ },
363
+ );
364
+
365
+ server.registerTool(
366
+ 'get_project_status',
367
+ {
368
+ title: 'PRD project status',
369
+ description:
370
+ 'Progress, next steps, blockers, open questions and high risks for a PRD.',
371
+ inputSchema: GetProjectStatusInputSchema,
372
+ outputSchema: GetProjectStatusOutputSchema,
373
+ annotations: READ_ONLY_TOOL,
374
+ },
375
+ async (input) => {
376
+ try {
377
+ const { filename } = GetProjectStatusInputSchema.parse(input);
378
+
379
+ return buildStructuredResponse(
380
+ await service.getProjectStatus(filename),
381
+ );
382
+ } catch (error) {
383
+ return buildErrorResponse('get_project_status', error);
384
+ }
385
+ },
386
+ );
387
+
388
+ server.registerTool(
389
+ 'list_templates',
390
+ {
391
+ title: 'List PRD templates',
392
+ description:
393
+ 'Starting points for create_prd (e.g. a SaaS feature, an internal tool, an integration, a first version). Each says when to use it.',
394
+ inputSchema: ListTemplatesInputSchema,
395
+ outputSchema: ListTemplatesOutputSchema,
396
+ annotations: READ_ONLY_TOOL,
397
+ },
398
+ async () => {
399
+ try {
400
+ return buildStructuredResponse(service.listTemplates());
401
+ } catch (error) {
402
+ return buildErrorResponse('list_templates', error);
403
+ }
404
+ },
405
+ );
406
+
407
+ server.registerTool(
408
+ 'check_plan',
409
+ {
410
+ title: 'Check what the plan is missing',
411
+ description:
412
+ 'A checklist of what the PRD still needs before and during the build. "required" items (no stories, stories without acceptance criteria, no scope limits) mean it is not ready to build; "recommended" items improve it. Each item names the section to change and, when relevant, the stories.',
413
+ inputSchema: CheckPlanInputSchema,
414
+ outputSchema: CheckPlanOutputSchema,
415
+ annotations: READ_ONLY_TOOL,
416
+ },
417
+ async (input) => {
418
+ try {
419
+ const { filename } = CheckPlanInputSchema.parse(input);
420
+
421
+ return buildStructuredResponse(await service.checkPlan(filename));
422
+ } catch (error) {
423
+ return buildErrorResponse('check_plan', error);
424
+ }
425
+ },
426
+ );
427
+
428
+ server.registerTool(
429
+ 'get_next_story',
430
+ {
431
+ title: 'Next story to work on',
432
+ description:
433
+ 'The next not-started story whose dependencies are all completed, ordered by phase, priority and position. Also lists stories in progress and stories waiting on dependencies.',
434
+ inputSchema: GetNextStoryInputSchema,
435
+ outputSchema: GetNextStoryOutputSchema,
436
+ annotations: READ_ONLY_TOOL,
437
+ },
438
+ async (input) => {
439
+ try {
440
+ const { filename } = GetNextStoryInputSchema.parse(input);
441
+
442
+ return buildStructuredResponse(await service.getNextStory(filename));
443
+ } catch (error) {
444
+ return buildErrorResponse('get_next_story', error);
445
+ }
446
+ },
447
+ );
448
+
449
+ server.registerTool(
450
+ 'get_story',
451
+ {
452
+ title: 'Story with context',
453
+ description:
454
+ 'One story with what is needed to implement it: PRD summary and scope limits, its phase, its dependencies and their hand-off logs, and the log of the most recently completed story. Prefer this over get_prd when working on a single story.',
455
+ inputSchema: GetStoryInputSchema,
456
+ outputSchema: GetStoryOutputSchema,
457
+ annotations: READ_ONLY_TOOL,
458
+ },
459
+ async (input) => {
460
+ try {
461
+ return buildStructuredResponse(
462
+ await service.getStory(GetStoryInputSchema.parse(input)),
463
+ );
464
+ } catch (error) {
465
+ return buildErrorResponse('get_story', error);
466
+ }
467
+ },
468
+ );
469
+
470
+ server.registerTool(
471
+ 'add_story_log',
472
+ {
473
+ title: 'Log work on a story',
474
+ description:
475
+ 'Append a hand-off entry to a story: what a person can now try (whatsNew), notes for the next agent (technicalNotes) and where the work departed from the PRD (deviations). Write one when you finish a work session on a story.',
476
+ inputSchema: AddStoryLogInputSchema,
477
+ outputSchema: AddStoryLogOutputSchema,
478
+ annotations: MUTATING_TOOL,
479
+ },
480
+ async (input) => {
481
+ try {
482
+ return buildStructuredResponse(
483
+ await service.addStoryLog(AddStoryLogInputSchema.parse(input)),
484
+ );
485
+ } catch (error) {
486
+ return buildErrorResponse('add_story_log', error);
487
+ }
488
+ },
489
+ );
490
+
491
+ server.registerTool(
492
+ 'add_attachment',
493
+ {
494
+ title: 'Add an attachment',
495
+ description:
496
+ "Record a file or link the plan refers to (a mockup, a screenshot, reference docs) and link it to the stories that use it. Save files in the folder named after the PRD file beside its JSON first. get_story returns a story's attachments with their paths.",
497
+ inputSchema: AddAttachmentInputSchema,
498
+ outputSchema: AddAttachmentOutputSchema,
499
+ annotations: MUTATING_TOOL,
500
+ },
501
+ async (input) => {
502
+ try {
503
+ return buildStructuredResponse(
504
+ await service.addAttachment(AddAttachmentInputSchema.parse(input)),
505
+ );
506
+ } catch (error) {
507
+ return buildErrorResponse('add_attachment', error);
508
+ }
509
+ },
510
+ );
511
+
512
+ server.registerTool(
513
+ 'remove_attachment',
514
+ {
515
+ title: 'Remove an attachment',
516
+ description:
517
+ 'Remove an attachment from the PRD and from every story that uses it. The file itself is kept.',
518
+ inputSchema: RemoveAttachmentInputSchema,
519
+ outputSchema: RemoveAttachmentOutputSchema,
520
+ annotations: DESTRUCTIVE_TOOL,
521
+ },
522
+ async (input) => {
523
+ try {
524
+ return buildStructuredResponse(
525
+ await service.removeAttachment(
526
+ RemoveAttachmentInputSchema.parse(input),
527
+ ),
528
+ );
529
+ } catch (error) {
530
+ return buildErrorResponse('remove_attachment', error);
531
+ }
532
+ },
533
+ );
534
+
535
+ server.registerTool(
536
+ 'update_prd_section',
537
+ {
538
+ title: 'Update a PRD section',
539
+ description:
540
+ 'Change one section of a PRD after it was created: scope (nonGoals, outOfScope), assumptions, open questions, risks, edge cases (what can go wrong and what should happen), security considerations, design guidance, external dependencies, technical requirements and contracts (including permissions and compliance), global acceptance criteria, constraints, rollout and measurement plans, or the introduction, problem and solution. For risks, edge cases and security, think adversarially: assume things fail and that someone is actively trying to abuse the feature, and write down the specific failure or attack with what should happen.',
541
+ inputSchema: UpdatePrdSectionInputSchema,
542
+ outputSchema: UpdatePrdSectionOutputSchema,
543
+ annotations: IDEMPOTENT_MUTATING_TOOL,
544
+ },
545
+ async (input) => {
546
+ try {
547
+ return buildStructuredResponse(
548
+ await service.updatePrdSection(
549
+ UpdatePrdSectionInputSchema.parse(input),
550
+ ),
551
+ );
552
+ } catch (error) {
553
+ return buildErrorResponse('update_prd_section', error);
554
+ }
555
+ },
556
+ );
557
+
558
+ server.registerTool(
559
+ 'add_decision',
560
+ {
561
+ title: 'Record a decision',
562
+ description:
563
+ 'Add an entry to the PRD decision log. Use it for choices that are hard to reverse or would surprise someone reading the code later. Pass supersedes to replace an earlier decision.',
564
+ inputSchema: AddDecisionInputSchema,
565
+ outputSchema: AddDecisionOutputSchema,
566
+ annotations: MUTATING_TOOL,
567
+ },
568
+ async (input) => {
569
+ try {
570
+ return buildStructuredResponse(
571
+ await service.addDecision(AddDecisionInputSchema.parse(input)),
572
+ );
573
+ } catch (error) {
574
+ return buildErrorResponse('add_decision', error);
575
+ }
576
+ },
577
+ );
578
+
579
+ server.registerTool(
580
+ 'mark_not_applicable',
581
+ {
582
+ title: 'Mark a part of the PRD not applicable',
583
+ description:
584
+ 'Mark an optional part of a PRD (dataModel, outsideServices, security, design, qualityBar, edgeCases, rollout, measurement, glossary, risks) as not applicable, with a reason, so the plan check stops asking for it and agents do not invent it. Pass notApplicable false to undo. Do not mark security or edgeCases not applicable for features that take input from people or store their data.',
585
+ inputSchema: MarkNotApplicableInputSchema,
586
+ outputSchema: MarkNotApplicableOutputSchema,
587
+ annotations: IDEMPOTENT_MUTATING_TOOL,
588
+ },
589
+ async (input) => {
590
+ try {
591
+ return buildStructuredResponse(
592
+ await service.markNotApplicable(
593
+ MarkNotApplicableInputSchema.parse(input),
594
+ ),
595
+ );
596
+ } catch (error) {
597
+ return buildErrorResponse('mark_not_applicable', error);
598
+ }
599
+ },
600
+ );
601
+
602
+ server.registerTool(
603
+ 'resolve_open_question',
604
+ {
605
+ title: 'Answer an open question',
606
+ description:
607
+ 'Answer an open question (by questionId, or by its exact text): it is removed from the PRD and, by default, the answer is recorded in the decision log.',
608
+ inputSchema: ResolveOpenQuestionInputSchema,
609
+ outputSchema: ResolveOpenQuestionOutputSchema,
610
+ annotations: MUTATING_TOOL,
611
+ },
612
+ async (input) => {
613
+ try {
614
+ return buildStructuredResponse(
615
+ await service.resolveOpenQuestion(
616
+ ResolveOpenQuestionInputSchema.parse(input),
617
+ ),
618
+ );
619
+ } catch (error) {
620
+ return buildErrorResponse('resolve_open_question', error);
621
+ }
622
+ },
623
+ );
624
+
625
+ server.registerTool(
626
+ 'update_attachment',
627
+ {
628
+ title: 'Update an attachment',
629
+ description:
630
+ "Change an attachment's title or note, or which stories use it (storyIds: links are added and removed to match).",
631
+ inputSchema: UpdateAttachmentInputSchema,
632
+ outputSchema: UpdateAttachmentOutputSchema,
633
+ annotations: IDEMPOTENT_MUTATING_TOOL,
634
+ },
635
+ async (input) => {
636
+ try {
637
+ return buildStructuredResponse(
638
+ await service.updateAttachment(
639
+ UpdateAttachmentInputSchema.parse(input),
640
+ ),
641
+ );
642
+ } catch (error) {
643
+ return buildErrorResponse('update_attachment', error);
644
+ }
645
+ },
646
+ );
647
+
648
+ server.registerTool(
649
+ 'decide_edge_case',
650
+ {
651
+ title: 'Decide an open edge case',
652
+ description:
653
+ 'Record what should happen for an open edge case; it becomes decided and binding for the stories it applies to.',
654
+ inputSchema: DecideEdgeCaseInputSchema,
655
+ outputSchema: DecideEdgeCaseOutputSchema,
656
+ annotations: IDEMPOTENT_MUTATING_TOOL,
657
+ },
658
+ async (input) => {
659
+ try {
660
+ return buildStructuredResponse(
661
+ await service.decideEdgeCase(DecideEdgeCaseInputSchema.parse(input)),
662
+ );
663
+ } catch (error) {
664
+ return buildErrorResponse('decide_edge_case', error);
665
+ }
666
+ },
667
+ );
668
+
669
+ server.registerTool(
670
+ 'add_glossary_term',
671
+ {
672
+ title: 'Define a glossary term',
673
+ description:
674
+ 'Add or redefine a term in the PRD glossary, with words to avoid, so people and agents use the same names for the same things.',
675
+ inputSchema: AddGlossaryTermInputSchema,
676
+ outputSchema: AddGlossaryTermOutputSchema,
677
+ annotations: IDEMPOTENT_MUTATING_TOOL,
678
+ },
679
+ async (input) => {
680
+ try {
681
+ return buildStructuredResponse(
682
+ await service.addGlossaryTerm(
683
+ AddGlossaryTermInputSchema.parse(input),
684
+ ),
685
+ );
686
+ } catch (error) {
687
+ return buildErrorResponse('add_glossary_term', error);
688
+ }
689
+ },
690
+ );
691
+
692
+ server.registerTool(
693
+ 'update_phase',
694
+ {
695
+ title: 'Update a phase',
696
+ description: 'Rename a phase or change its description or colour.',
697
+ inputSchema: UpdatePhaseInputSchema,
698
+ outputSchema: PhasesOutputSchema,
699
+ annotations: IDEMPOTENT_MUTATING_TOOL,
700
+ },
701
+ async (input) => {
702
+ try {
703
+ return buildStructuredResponse(
704
+ await service.updatePhase(UpdatePhaseInputSchema.parse(input)),
705
+ );
706
+ } catch (error) {
707
+ return buildErrorResponse('update_phase', error);
708
+ }
709
+ },
710
+ );
711
+
712
+ server.registerTool(
713
+ 'delete_phase',
714
+ {
715
+ title: 'Delete a phase',
716
+ description:
717
+ 'Delete a phase. Its stories stay in the PRD without a phase.',
718
+ inputSchema: DeletePhaseInputSchema,
719
+ outputSchema: PhasesOutputSchema,
720
+ annotations: DESTRUCTIVE_TOOL,
721
+ },
722
+ async (input) => {
723
+ try {
724
+ return buildStructuredResponse(
725
+ await service.deletePhase(DeletePhaseInputSchema.parse(input)),
726
+ );
727
+ } catch (error) {
728
+ return buildErrorResponse('delete_phase', error);
729
+ }
730
+ },
731
+ );
732
+
733
+ server.registerTool(
734
+ 'reorder_phases',
735
+ {
736
+ title: 'Reorder phases',
737
+ description:
738
+ 'Set the order of all phases. get_next_story works through phases in this order.',
739
+ inputSchema: ReorderPhasesInputSchema,
740
+ outputSchema: PhasesOutputSchema,
741
+ annotations: IDEMPOTENT_MUTATING_TOOL,
742
+ },
743
+ async (input) => {
744
+ try {
745
+ return buildStructuredResponse(
746
+ await service.reorderPhases(ReorderPhasesInputSchema.parse(input)),
747
+ );
748
+ } catch (error) {
749
+ return buildErrorResponse('reorder_phases', error);
750
+ }
751
+ },
752
+ );
753
+
754
+ server.registerPrompt(
755
+ 'shape_prd',
756
+ {
757
+ title: 'Shape a PRD',
758
+ description:
759
+ 'Shape a PRD with a detailed interview by default, or choose light to focus on decisions needed to define the stories.',
760
+ argsSchema: {
761
+ overview: z
762
+ .string()
763
+ .optional()
764
+ .describe(
765
+ 'What you want to build, in your own words: what it is, who it is for and what it should do',
766
+ ),
767
+ filename: z
768
+ .string()
769
+ .optional()
770
+ .describe('Existing PRD to keep shaping, in the PRD directory'),
771
+ mode: z
772
+ .enum(['light', 'detailed'])
773
+ .optional()
774
+ .describe('Interview depth. Defaults to detailed.'),
775
+ },
776
+ },
777
+ ({ overview, filename, mode }) => ({
778
+ messages: [
779
+ {
780
+ role: 'user',
781
+ content: {
782
+ type: 'text',
783
+ text: shapePrdPrompt(overview, filename, mode, service.prdsPath),
784
+ },
785
+ },
786
+ ],
787
+ }),
788
+ );
789
+
790
+ server.registerPrompt(
791
+ 'architect_prd',
792
+ {
793
+ title: 'Architect a PRD',
794
+ description:
795
+ 'Design the shape all stories share (data model, modules, entry points, test seams) before any is built, and record it in the PRD as the contract to build against.',
796
+ argsSchema: {
797
+ filename: z.string().describe('PRD file name in the PRD directory'),
798
+ },
799
+ },
800
+ ({ filename }) => ({
801
+ messages: [
802
+ {
803
+ role: 'user',
804
+ content: {
805
+ type: 'text',
806
+ text: architectPrdPrompt(filename, service.prdsPath),
807
+ },
808
+ },
809
+ ],
810
+ }),
811
+ );
812
+
813
+ server.registerPrompt(
814
+ 'review_story',
815
+ {
816
+ title: 'Review a story against its spec',
817
+ description:
818
+ 'Check the changes made for a story against its acceptance criteria, scope limits and test seams, and report a verdict.',
819
+ argsSchema: {
820
+ filename: z.string().describe('PRD file name in the PRD directory'),
821
+ storyId: z.string().describe('Story id such as US003'),
822
+ base: z
823
+ .string()
824
+ .optional()
825
+ .describe(
826
+ 'Git ref the story started from. Defaults to the recorded review scope.',
827
+ ),
828
+ },
829
+ },
830
+ ({ filename, storyId, base }) => ({
831
+ messages: [
832
+ {
833
+ role: 'user',
834
+ content: {
835
+ type: 'text',
836
+ text: reviewStoryPrompt(filename, storyId, base),
837
+ },
838
+ },
839
+ ],
840
+ }),
841
+ );
842
+
843
+ server.registerPrompt(
844
+ 'implement_story',
845
+ {
846
+ title: 'Implement PRD stories',
847
+ description:
848
+ 'Implement, review, and complete ready stories in sequence with the PRD tools.',
849
+ argsSchema: {
850
+ filename: z.string().describe('PRD file name in the PRD directory'),
851
+ storyId: z
852
+ .string()
853
+ .optional()
854
+ .describe(
855
+ 'Starting story id such as US003. Omit to select work automatically.',
856
+ ),
857
+ singleStory: z
858
+ .boolean()
859
+ .optional()
860
+ .describe('Stop after one story. Use this for parallel workers.'),
861
+ },
862
+ },
863
+ ({ filename, storyId, singleStory }) => ({
864
+ messages: [
865
+ {
866
+ role: 'user',
867
+ content: {
868
+ type: 'text',
869
+ text: implementStoryPrompt(filename, storyId, singleStory),
870
+ },
871
+ },
872
+ ],
873
+ }),
874
+ );
875
+ }