@makerkit/prd 0.0.3 → 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} +257 -524
  10. package/{index.mjs → dist/index.mjs} +189 -462
  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-DJQ4FQ11.js → dist/prompts-1qhax_dj.js} +150 -167
  25. package/{prompts-B0VejF7q.mjs → dist/prompts-BlsYD0gf.mjs} +121 -132
  26. package/{prd.service-x5EpOoMv.d.ts → dist/schema-BwTnt0B9.d.ts} +545 -323
  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 -228
  63. /package/{LICENSE → dist/LICENSE} +0 -0
@@ -1,9 +1,7 @@
1
- import { r as PrdService } from "./prd.service-x5EpOoMv.js";
1
+ import { r as PrdService } from "./prd.service-CTwKZV-3.js";
2
2
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
- //#region src/mcp/index.d.ts
4
3
  /**
5
4
  * Registers the PRD tools on an MCP server. The caller builds the service, so
6
5
  * it decides where PRDs live and which checks gate a story's completion.
7
6
  */
8
- export declare function registerPRDTools(server: McpServer, service: PrdService): void;
9
- //#endregion
7
+ export declare function registerPRDTools(server: McpServer, service: PrdService): void;
@@ -1,7 +1,7 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_prompts = require("./prompts-DJQ4FQ11.js");
2
+ const require_prompts = require("./prompts-1qhax_dj.js");
3
3
  let zod_v3 = require("zod/v3");
4
- //#region src/mcp/tool-response.ts
4
+ // src/mcp/tool-response.ts
5
5
  /**
6
6
  * Standard annotation presets. Every registered tool must declare one so MCP
7
7
  * clients can gate permissions correctly (e.g. auto-approve read-only tools,
@@ -58,8 +58,7 @@ function buildTextContent(text) {
58
58
  text
59
59
  }];
60
60
  }
61
- //#endregion
62
- //#region src/mcp/index.ts
61
+ // src/mcp/index.ts
63
62
  /**
64
63
  * Registers the PRD tools on an MCP server. The caller builds the service, so
65
64
  * it decides where PRDs live and which checks gate a story's completion.
@@ -67,7 +66,7 @@ function buildTextContent(text) {
67
66
  function registerPRDTools(server, service) {
68
67
  server.registerTool("list_prds", {
69
68
  title: "List PRDs",
70
- description: "List Product Requirements Documents in .prds with title and story progress.",
69
+ description: "List PRDs with story progress and optional roadmap metadata, sorted by order, then criticality.",
71
70
  inputSchema: require_prompts.ListPrdsInputSchema,
72
71
  outputSchema: require_prompts.ListPrdsOutputSchema,
73
72
  annotations: READ_ONLY_TOOL
@@ -94,7 +93,7 @@ function registerPRDTools(server, service) {
94
93
  });
95
94
  server.registerTool("create_prd", {
96
95
  title: "Create a PRD",
97
- description: "Create a new structured PRD in .prds. The file name is derived from the title.",
96
+ description: "Create a new structured PRD in the configured directory. The file name is derived from the title.",
98
97
  inputSchema: require_prompts.CreatePrdInputSchema,
99
98
  outputSchema: require_prompts.CreatePrdOutputSchema,
100
99
  annotations: MUTATING_TOOL
@@ -136,7 +135,7 @@ function registerPRDTools(server, service) {
136
135
  });
137
136
  server.registerTool("update_story_status", {
138
137
  title: "Update story status",
139
- description: "Update a user story status. Marking a story \"completed\" runs the project checks (typecheck, lint) first and is rejected if they fail.",
138
+ description: "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.",
140
139
  inputSchema: require_prompts.UpdateStoryStatusInputSchema,
141
140
  outputSchema: require_prompts.UpdateStoryStatusOutputSchema,
142
141
  annotations: MUTATING_TOOL
@@ -220,7 +219,7 @@ function registerPRDTools(server, service) {
220
219
  });
221
220
  server.registerTool("get_implementation_prompts", {
222
221
  title: "Implementation prompts",
223
- description: "The implement_story instructions for the next unstarted stories, as text to paste into an agent that does not support MCP prompts.",
222
+ description: "One autonomous implementation prompt when there is work ready to start, as text to paste into an agent that does not support MCP prompts.",
224
223
  inputSchema: require_prompts.GetImplementationPromptsInputSchema,
225
224
  outputSchema: require_prompts.GetImplementationPromptsOutputSchema,
226
225
  annotations: READ_ONLY_TOOL
@@ -329,7 +328,7 @@ function registerPRDTools(server, service) {
329
328
  });
330
329
  server.registerTool("add_attachment", {
331
330
  title: "Add an attachment",
332
- description: "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 PRD folder, .prds/<prd file name without .json>/, first. get_story returns a story's attachments with their paths.",
331
+ description: "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.",
333
332
  inputSchema: require_prompts.AddAttachmentInputSchema,
334
333
  outputSchema: require_prompts.AddAttachmentOutputSchema,
335
334
  annotations: MUTATING_TOOL
@@ -485,36 +484,37 @@ function registerPRDTools(server, service) {
485
484
  });
486
485
  server.registerPrompt("shape_prd", {
487
486
  title: "Shape a PRD",
488
- description: "Interview the user round by round until the plan is clear, writing each decision into the PRD as it is made, then slice the work into stories and phases.",
487
+ description: "Shape a PRD with a detailed interview by default, or choose light to focus on decisions needed to define the stories.",
489
488
  argsSchema: {
490
489
  overview: zod_v3.z.string().optional().describe("What you want to build, in your own words: what it is, who it is for and what it should do"),
491
- filename: zod_v3.z.string().optional().describe("Existing PRD to keep shaping, inside .prds")
490
+ filename: zod_v3.z.string().optional().describe("Existing PRD to keep shaping, in the PRD directory"),
491
+ mode: zod_v3.z.enum(["light", "detailed"]).optional().describe("Interview depth. Defaults to detailed.")
492
492
  }
493
- }, ({ overview, filename }) => ({ messages: [{
493
+ }, ({ overview, filename, mode }) => ({ messages: [{
494
494
  role: "user",
495
495
  content: {
496
496
  type: "text",
497
- text: require_prompts.shapePrdPrompt(overview, filename)
497
+ text: require_prompts.shapePrdPrompt(overview, filename, mode, service.prdsPath)
498
498
  }
499
499
  }] }));
500
500
  server.registerPrompt("architect_prd", {
501
501
  title: "Architect a PRD",
502
502
  description: "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.",
503
- argsSchema: { filename: zod_v3.z.string().describe("PRD file name inside .prds") }
503
+ argsSchema: { filename: zod_v3.z.string().describe("PRD file name in the PRD directory") }
504
504
  }, ({ filename }) => ({ messages: [{
505
505
  role: "user",
506
506
  content: {
507
507
  type: "text",
508
- text: require_prompts.architectPrdPrompt(filename)
508
+ text: require_prompts.architectPrdPrompt(filename, service.prdsPath)
509
509
  }
510
510
  }] }));
511
511
  server.registerPrompt("review_story", {
512
512
  title: "Review a story against its spec",
513
513
  description: "Check the changes made for a story against its acceptance criteria, scope limits and test seams, and report a verdict.",
514
514
  argsSchema: {
515
- filename: zod_v3.z.string().describe("PRD file name inside .prds"),
515
+ filename: zod_v3.z.string().describe("PRD file name in the PRD directory"),
516
516
  storyId: zod_v3.z.string().describe("Story id such as US003"),
517
- base: zod_v3.z.string().optional().describe("Git ref the story started from. Defaults to HEAD.")
517
+ base: zod_v3.z.string().optional().describe("Git ref the story started from. Defaults to the recorded review scope.")
518
518
  }
519
519
  }, ({ filename, storyId, base }) => ({ messages: [{
520
520
  role: "user",
@@ -524,19 +524,19 @@ function registerPRDTools(server, service) {
524
524
  }
525
525
  }] }));
526
526
  server.registerPrompt("implement_story", {
527
- title: "Implement a PRD story",
528
- description: "Instructions for implementing one story end to end with the PRD tools.",
527
+ title: "Implement PRD stories",
528
+ description: "Implement, review, and complete ready stories in sequence with the PRD tools.",
529
529
  argsSchema: {
530
- filename: zod_v3.z.string().describe("PRD file name inside .prds"),
531
- storyId: zod_v3.z.string().optional().describe("Story id such as US003. Omit to take the next ready one.")
530
+ filename: zod_v3.z.string().describe("PRD file name in the PRD directory"),
531
+ storyId: zod_v3.z.string().optional().describe("Starting story id such as US003. Omit to select work automatically."),
532
+ singleStory: zod_v3.z.boolean().optional().describe("Stop after one story. Use this for parallel workers.")
532
533
  }
533
- }, ({ filename, storyId }) => ({ messages: [{
534
+ }, ({ filename, storyId, singleStory }) => ({ messages: [{
534
535
  role: "user",
535
536
  content: {
536
537
  type: "text",
537
- text: require_prompts.implementStoryPrompt(filename, storyId)
538
+ text: require_prompts.implementStoryPrompt(filename, storyId, singleStory)
538
539
  }
539
540
  }] }));
540
541
  }
541
- //#endregion
542
542
  exports.registerPRDTools = registerPRDTools;
@@ -1,6 +1,6 @@
1
- import { A as DeleteUserStoryOutputSchema, B as GetPrdOutputSchema, D as DeletePrdInputSchema, E as DeletePhaseInputSchema, F as GetImprovementSuggestionsInputSchema, G as ListPrdsInputSchema, H as GetProjectStatusOutputSchema, I as GetImprovementSuggestionsOutputSchema, J as ListTemplatesOutputSchema, K as ListPrdsOutputSchema, L as GetNextStoryInputSchema, M as ExportPrdMarkdownOutputSchema, N as GetImplementationPromptsInputSchema, O as DeletePrdOutputSchema, P as GetImplementationPromptsOutputSchema, Q as PhasesOutputSchema, R as GetNextStoryOutputSchema, S as CreatePrdOutputSchema, T as DecideEdgeCaseOutputSchema, U as GetStoryInputSchema, V as GetProjectStatusInputSchema, W as GetStoryOutputSchema, X as MarkNotApplicableOutputSchema, Y as MarkNotApplicableInputSchema, _ as CheckPlanInputSchema, _t as UpdateStoryStatusInputSchema, a as AddAttachmentInputSchema, at as ResolveOpenQuestionOutputSchema, b as CreateCustomPhaseOutputSchema, bt as UpdateUserStoryOutputSchema, c as AddDecisionOutputSchema, d as AddStoryLogInputSchema, f as AddStoryLogOutputSchema, ft as UpdateAttachmentInputSchema, g as AssignStoryToPhaseOutputSchema, gt as UpdatePrdSectionOutputSchema, h as AssignStoryToPhaseInputSchema, ht as UpdatePrdSectionInputSchema, i as shapePrdPrompt, it as ResolveOpenQuestionInputSchema, j as ExportPrdMarkdownInputSchema, k as DeleteUserStoryInputSchema, l as AddGlossaryTermInputSchema, m as AddUserStoryOutputSchema, mt as UpdatePhaseInputSchema, n as implementStoryPrompt, nt as RemoveAttachmentOutputSchema, o as AddAttachmentOutputSchema, p as AddUserStoryInputSchema, pt as UpdateAttachmentOutputSchema, q as ListTemplatesInputSchema, r as reviewStoryPrompt, rt as ReorderPhasesInputSchema, s as AddDecisionInputSchema, t as architectPrdPrompt, tt as RemoveAttachmentInputSchema, u as AddGlossaryTermOutputSchema, v as CheckPlanOutputSchema, vt as UpdateStoryStatusOutputSchema, w as DecideEdgeCaseInputSchema, x as CreatePrdInputSchema, y as CreateCustomPhaseInputSchema, yt as UpdateUserStoryInputSchema, z as GetPrdInputSchema } from "./prompts-B0VejF7q.mjs";
1
+ import { $ as PhasesOutputSchema, A as DeleteUserStoryInputSchema, B as GetPrdInputSchema, Ct as UpdateStoryStatusOutputSchema, D as DeletePhaseInputSchema, E as DecideEdgeCaseOutputSchema, F as GetImplementationPromptsOutputSchema, G as GetStoryOutputSchema, H as GetProjectStatusInputSchema, I as GetImprovementSuggestionsInputSchema, J as ListTemplatesInputSchema, K as ListPrdsInputSchema, L as GetImprovementSuggestionsOutputSchema, M as ExportPrdMarkdownInputSchema, N as ExportPrdMarkdownOutputSchema, O as DeletePrdInputSchema, P as GetImplementationPromptsInputSchema, R as GetNextStoryInputSchema, S as CreatePrdOutputSchema, St as UpdateStoryStatusInputSchema, T as DecideEdgeCaseInputSchema, Tt as UpdateUserStoryOutputSchema, U as GetProjectStatusOutputSchema, V as GetPrdOutputSchema, W as GetStoryInputSchema, X as MarkNotApplicableInputSchema, Y as ListTemplatesOutputSchema, Z as MarkNotApplicableOutputSchema, _ as CheckPlanInputSchema, _t as UpdateAttachmentInputSchema, a as AddAttachmentInputSchema, b as CreateCustomPhaseOutputSchema, bt as UpdatePrdSectionInputSchema, c as AddDecisionOutputSchema, ct as ReorderPhasesInputSchema, d as AddStoryLogInputSchema, f as AddStoryLogOutputSchema, g as AssignStoryToPhaseOutputSchema, h as AssignStoryToPhaseInputSchema, i as shapePrdPrompt, j as DeleteUserStoryOutputSchema, k as DeletePrdOutputSchema, l as AddGlossaryTermInputSchema, lt as ResolveOpenQuestionInputSchema, m as AddUserStoryOutputSchema, n as implementStoryPrompt, o as AddAttachmentOutputSchema, ot as RemoveAttachmentInputSchema, p as AddUserStoryInputSchema, q as ListPrdsOutputSchema, r as reviewStoryPrompt, s as AddDecisionInputSchema, st as RemoveAttachmentOutputSchema, t as architectPrdPrompt, u as AddGlossaryTermOutputSchema, ut as ResolveOpenQuestionOutputSchema, v as CheckPlanOutputSchema, vt as UpdateAttachmentOutputSchema, wt as UpdateUserStoryInputSchema, x as CreatePrdInputSchema, xt as UpdatePrdSectionOutputSchema, y as CreateCustomPhaseInputSchema, yt as UpdatePhaseInputSchema, z as GetNextStoryOutputSchema } from "./prompts-BlsYD0gf.mjs";
2
2
  import { z } from "zod/v3";
3
- //#region src/mcp/tool-response.ts
3
+ // src/mcp/tool-response.ts
4
4
  /**
5
5
  * Standard annotation presets. Every registered tool must declare one so MCP
6
6
  * clients can gate permissions correctly (e.g. auto-approve read-only tools,
@@ -57,8 +57,7 @@ function buildTextContent(text) {
57
57
  text
58
58
  }];
59
59
  }
60
- //#endregion
61
- //#region src/mcp/index.ts
60
+ // src/mcp/index.ts
62
61
  /**
63
62
  * Registers the PRD tools on an MCP server. The caller builds the service, so
64
63
  * it decides where PRDs live and which checks gate a story's completion.
@@ -66,7 +65,7 @@ function buildTextContent(text) {
66
65
  function registerPRDTools(server, service) {
67
66
  server.registerTool("list_prds", {
68
67
  title: "List PRDs",
69
- description: "List Product Requirements Documents in .prds with title and story progress.",
68
+ description: "List PRDs with story progress and optional roadmap metadata, sorted by order, then criticality.",
70
69
  inputSchema: ListPrdsInputSchema,
71
70
  outputSchema: ListPrdsOutputSchema,
72
71
  annotations: READ_ONLY_TOOL
@@ -93,7 +92,7 @@ function registerPRDTools(server, service) {
93
92
  });
94
93
  server.registerTool("create_prd", {
95
94
  title: "Create a PRD",
96
- description: "Create a new structured PRD in .prds. The file name is derived from the title.",
95
+ description: "Create a new structured PRD in the configured directory. The file name is derived from the title.",
97
96
  inputSchema: CreatePrdInputSchema,
98
97
  outputSchema: CreatePrdOutputSchema,
99
98
  annotations: MUTATING_TOOL
@@ -135,7 +134,7 @@ function registerPRDTools(server, service) {
135
134
  });
136
135
  server.registerTool("update_story_status", {
137
136
  title: "Update story status",
138
- description: "Update a user story status. Marking a story \"completed\" runs the project checks (typecheck, lint) first and is rejected if they fail.",
137
+ description: "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.",
139
138
  inputSchema: UpdateStoryStatusInputSchema,
140
139
  outputSchema: UpdateStoryStatusOutputSchema,
141
140
  annotations: MUTATING_TOOL
@@ -219,7 +218,7 @@ function registerPRDTools(server, service) {
219
218
  });
220
219
  server.registerTool("get_implementation_prompts", {
221
220
  title: "Implementation prompts",
222
- description: "The implement_story instructions for the next unstarted stories, as text to paste into an agent that does not support MCP prompts.",
221
+ description: "One autonomous implementation prompt when there is work ready to start, as text to paste into an agent that does not support MCP prompts.",
223
222
  inputSchema: GetImplementationPromptsInputSchema,
224
223
  outputSchema: GetImplementationPromptsOutputSchema,
225
224
  annotations: READ_ONLY_TOOL
@@ -328,7 +327,7 @@ function registerPRDTools(server, service) {
328
327
  });
329
328
  server.registerTool("add_attachment", {
330
329
  title: "Add an attachment",
331
- description: "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 PRD folder, .prds/<prd file name without .json>/, first. get_story returns a story's attachments with their paths.",
330
+ description: "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.",
332
331
  inputSchema: AddAttachmentInputSchema,
333
332
  outputSchema: AddAttachmentOutputSchema,
334
333
  annotations: MUTATING_TOOL
@@ -484,36 +483,37 @@ function registerPRDTools(server, service) {
484
483
  });
485
484
  server.registerPrompt("shape_prd", {
486
485
  title: "Shape a PRD",
487
- description: "Interview the user round by round until the plan is clear, writing each decision into the PRD as it is made, then slice the work into stories and phases.",
486
+ description: "Shape a PRD with a detailed interview by default, or choose light to focus on decisions needed to define the stories.",
488
487
  argsSchema: {
489
488
  overview: z.string().optional().describe("What you want to build, in your own words: what it is, who it is for and what it should do"),
490
- filename: z.string().optional().describe("Existing PRD to keep shaping, inside .prds")
489
+ filename: z.string().optional().describe("Existing PRD to keep shaping, in the PRD directory"),
490
+ mode: z.enum(["light", "detailed"]).optional().describe("Interview depth. Defaults to detailed.")
491
491
  }
492
- }, ({ overview, filename }) => ({ messages: [{
492
+ }, ({ overview, filename, mode }) => ({ messages: [{
493
493
  role: "user",
494
494
  content: {
495
495
  type: "text",
496
- text: shapePrdPrompt(overview, filename)
496
+ text: shapePrdPrompt(overview, filename, mode, service.prdsPath)
497
497
  }
498
498
  }] }));
499
499
  server.registerPrompt("architect_prd", {
500
500
  title: "Architect a PRD",
501
501
  description: "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.",
502
- argsSchema: { filename: z.string().describe("PRD file name inside .prds") }
502
+ argsSchema: { filename: z.string().describe("PRD file name in the PRD directory") }
503
503
  }, ({ filename }) => ({ messages: [{
504
504
  role: "user",
505
505
  content: {
506
506
  type: "text",
507
- text: architectPrdPrompt(filename)
507
+ text: architectPrdPrompt(filename, service.prdsPath)
508
508
  }
509
509
  }] }));
510
510
  server.registerPrompt("review_story", {
511
511
  title: "Review a story against its spec",
512
512
  description: "Check the changes made for a story against its acceptance criteria, scope limits and test seams, and report a verdict.",
513
513
  argsSchema: {
514
- filename: z.string().describe("PRD file name inside .prds"),
514
+ filename: z.string().describe("PRD file name in the PRD directory"),
515
515
  storyId: z.string().describe("Story id such as US003"),
516
- base: z.string().optional().describe("Git ref the story started from. Defaults to HEAD.")
516
+ base: z.string().optional().describe("Git ref the story started from. Defaults to the recorded review scope.")
517
517
  }
518
518
  }, ({ filename, storyId, base }) => ({ messages: [{
519
519
  role: "user",
@@ -523,19 +523,19 @@ function registerPRDTools(server, service) {
523
523
  }
524
524
  }] }));
525
525
  server.registerPrompt("implement_story", {
526
- title: "Implement a PRD story",
527
- description: "Instructions for implementing one story end to end with the PRD tools.",
526
+ title: "Implement PRD stories",
527
+ description: "Implement, review, and complete ready stories in sequence with the PRD tools.",
528
528
  argsSchema: {
529
- filename: z.string().describe("PRD file name inside .prds"),
530
- storyId: z.string().optional().describe("Story id such as US003. Omit to take the next ready one.")
529
+ filename: z.string().describe("PRD file name in the PRD directory"),
530
+ storyId: z.string().optional().describe("Starting story id such as US003. Omit to select work automatically."),
531
+ singleStory: z.boolean().optional().describe("Stop after one story. Use this for parallel workers.")
531
532
  }
532
- }, ({ filename, storyId }) => ({ messages: [{
533
+ }, ({ filename, storyId, singleStory }) => ({ messages: [{
533
534
  role: "user",
534
535
  content: {
535
536
  type: "text",
536
- text: implementStoryPrompt(filename, storyId)
537
+ text: implementStoryPrompt(filename, storyId, singleStory)
537
538
  }
538
539
  }] }));
539
540
  }
540
- //#endregion
541
541
  export { registerPRDTools };
@@ -1,6 +1,7 @@
1
- import { t as PrdDeps } from "./prd.service-x5EpOoMv.js";
2
- //#region src/node.d.ts
1
+ import { t as PrdDeps } from "./prd.service-CTwKZV-3.js";
3
2
  export interface NodePrdDepsOptions {
3
+ /** Absolute directory or a path relative to the project root. */
4
+ prdsDir?: string;
4
5
  /**
5
6
  * Decides whether a story may be marked completed. Defaults to running the
6
7
  * project's `typecheck` and `lint` scripts (see `createScriptVerifier`).
@@ -15,5 +16,4 @@ export declare function createNodePrdDeps(rootPath?: string, options?: NodePrdDe
15
16
  * file-and-line diagnostics. Scripts the project does not define are skipped,
16
17
  * so a repo without e.g. `lint` can still complete stories.
17
18
  */
18
- export declare function createScriptVerifier(rootPath: string, scripts?: string[]): PrdDeps['verifyCompletion'];
19
- //#endregion
19
+ export declare function createScriptVerifier(rootPath: string, scripts?: string[]): PrdDeps['verifyCompletion'];
@@ -1,22 +1,33 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
2
  let node_path = require("node:path");
3
3
  let _makerkit_repo_checks_node = require("@makerkit/repo-checks/node");
4
+ let node_crypto = require("node:crypto");
4
5
  let node_fs_promises = require("node:fs/promises");
5
- //#region src/node.ts
6
+ // src/node.ts
6
7
  /** Check-only scripts that gate marking a story as completed. */
7
8
  const DEFAULT_COMPLETION_CHECKS = ["typecheck", "lint"];
8
9
  /** PRD dependencies backed by the local filesystem, rooted at `rootPath`. */
9
10
  function createNodePrdDeps(rootPath = process.cwd(), options = {}) {
10
11
  return {
11
12
  rootPath,
13
+ prdsDir: options.prdsDir ? (0, node_path.resolve)(rootPath, options.prdsDir) : void 0,
12
14
  readdir(path) {
13
15
  return (0, node_fs_promises.readdir)(path);
14
16
  },
15
17
  readFile(path) {
16
18
  return (0, node_fs_promises.readFile)(path, "utf8");
17
19
  },
18
- writeFile(path, content) {
19
- return (0, node_fs_promises.writeFile)(path, content, "utf8");
20
+ async writeFile(path, content) {
21
+ const temporaryPath = `${path}.${(0, node_crypto.randomUUID)()}.tmp`;
22
+ try {
23
+ await (0, node_fs_promises.writeFile)(temporaryPath, content, {
24
+ encoding: "utf8",
25
+ flag: "wx"
26
+ });
27
+ await (0, node_fs_promises.rename)(temporaryPath, path);
28
+ } finally {
29
+ await (0, node_fs_promises.rm)(temporaryPath, { force: true });
30
+ }
20
31
  },
21
32
  async mkdir(path) {
22
33
  await (0, node_fs_promises.mkdir)(path, { recursive: true });
@@ -25,6 +36,20 @@ function createNodePrdDeps(rootPath = process.cwd(), options = {}) {
25
36
  return (0, node_fs_promises.unlink)(path);
26
37
  },
27
38
  fileExists,
39
+ async withWriteLock(path, write) {
40
+ const lockPath = `${path}.lock`;
41
+ try {
42
+ await (0, node_fs_promises.mkdir)(lockPath);
43
+ } catch (error) {
44
+ if (error.code === "EEXIST") throw new Error(`PRD write lock is held at "${lockPath}". Reload the PRD and retry. If a writer crashed, verify that no writer is active before removing the lock directory.`);
45
+ throw error;
46
+ }
47
+ try {
48
+ return await write();
49
+ } finally {
50
+ await (0, node_fs_promises.rmdir)(lockPath);
51
+ }
52
+ },
28
53
  now() {
29
54
  return /* @__PURE__ */ new Date();
30
55
  },
@@ -89,6 +114,5 @@ async function fileExists(path) {
89
114
  return false;
90
115
  }
91
116
  }
92
- //#endregion
93
117
  exports.createNodePrdDeps = createNodePrdDeps;
94
118
  exports.createScriptVerifier = createScriptVerifier;
@@ -1,21 +1,32 @@
1
- import { join } from "node:path";
1
+ import { join, resolve } from "node:path";
2
2
  import { createRepoChecksServices } from "@makerkit/repo-checks/node";
3
- import { access, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
4
- //#region src/node.ts
3
+ import { randomUUID } from "node:crypto";
4
+ import { access, mkdir, readFile, readdir, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
5
+ // src/node.ts
5
6
  /** Check-only scripts that gate marking a story as completed. */
6
7
  const DEFAULT_COMPLETION_CHECKS = ["typecheck", "lint"];
7
8
  /** PRD dependencies backed by the local filesystem, rooted at `rootPath`. */
8
9
  function createNodePrdDeps(rootPath = process.cwd(), options = {}) {
9
10
  return {
10
11
  rootPath,
12
+ prdsDir: options.prdsDir ? resolve(rootPath, options.prdsDir) : void 0,
11
13
  readdir(path) {
12
14
  return readdir(path);
13
15
  },
14
16
  readFile(path) {
15
17
  return readFile(path, "utf8");
16
18
  },
17
- writeFile(path, content) {
18
- return writeFile(path, content, "utf8");
19
+ async writeFile(path, content) {
20
+ const temporaryPath = `${path}.${randomUUID()}.tmp`;
21
+ try {
22
+ await writeFile(temporaryPath, content, {
23
+ encoding: "utf8",
24
+ flag: "wx"
25
+ });
26
+ await rename(temporaryPath, path);
27
+ } finally {
28
+ await rm(temporaryPath, { force: true });
29
+ }
19
30
  },
20
31
  async mkdir(path) {
21
32
  await mkdir(path, { recursive: true });
@@ -24,6 +35,20 @@ function createNodePrdDeps(rootPath = process.cwd(), options = {}) {
24
35
  return unlink(path);
25
36
  },
26
37
  fileExists,
38
+ async withWriteLock(path, write) {
39
+ const lockPath = `${path}.lock`;
40
+ try {
41
+ await mkdir(lockPath);
42
+ } catch (error) {
43
+ if (error.code === "EEXIST") throw new Error(`PRD write lock is held at "${lockPath}". Reload the PRD and retry. If a writer crashed, verify that no writer is active before removing the lock directory.`);
44
+ throw error;
45
+ }
46
+ try {
47
+ return await write();
48
+ } finally {
49
+ await rmdir(lockPath);
50
+ }
51
+ },
27
52
  now() {
28
53
  return /* @__PURE__ */ new Date();
29
54
  },
@@ -88,5 +113,4 @@ async function fileExists(path) {
88
113
  return false;
89
114
  }
90
115
  }
91
- //#endregion
92
116
  export { createNodePrdDeps, createScriptVerifier };
@@ -0,0 +1,141 @@
1
+ import { A as CreateCustomPhaseOutput, An as EdgeCase, Bn as StoryStatus, C as AssignStoryToPhaseOutput, En as CriterionProof, Nn as OpenQuestion, O as CreateCustomPhaseInput, Rn as StoryLogEntry, Sn as UpdateUserStoryOutput, Tn as Attachment, Un as StructuredPRD, Wn as UserStory, X as DeleteUserStoryOutput, bn as UpdateUserStoryInput, x as AssignStoryToPhaseInput } from "./schema-BwTnt0B9.js";
2
+ /**
3
+ * Pure PRD transforms.
4
+ *
5
+ * Everything here takes an already-loaded `StructuredPRD`, mutates it, and
6
+ * returns the tool payload. No filesystem, no clock, no deps — the service is
7
+ * left with load → transform → save, and every rule below is unit-testable
8
+ * without a harness.
9
+ */
10
+ /**
11
+ * Issues the next story id and advances the high-water mark.
12
+ *
13
+ * Deliberately not `max(existing) + 1`: delete the highest-numbered story and
14
+ * that hands its id straight to the next one, so a story id quoted in a commit
15
+ * or a decision-log topic would silently come to mean something else.
16
+ */
17
+ export declare function nextId(items: {
18
+ id: string;
19
+ }[], prefix: string): string;
20
+ export declare function nextStoryId(prd: StructuredPRD): string;
21
+ export declare function recomputeProgress(prd: StructuredPRD): void;
22
+ export declare function appendChangeLog(prd: StructuredPRD, entry: string, today: string): void;
23
+ export declare function findStory(prd: StructuredPRD, storyId: string): UserStory;
24
+ /** Splits the rendered sentence back into its parts so one can be patched. */
25
+ /** The parts of an "As a X, I want to Y so that Z" story, or undefined. */
26
+ export declare function splitUserStory(sentence: string): {
27
+ userType: string;
28
+ action: string;
29
+ benefit: string;
30
+ } | undefined;
31
+ export declare function renderUserStory(parts: {
32
+ userType: string;
33
+ action: string;
34
+ benefit: string;
35
+ }): string;
36
+ export declare function updateStory(prd: StructuredPRD, input: UpdateUserStoryInput, today: string): UpdateUserStoryOutput;
37
+ export declare function findAttachment(prd: StructuredPRD, attachmentId: string): Attachment;
38
+ /** Attachment ids must name attachments in the PRD. */
39
+ export declare function validateAttachmentIds(prd: StructuredPRD, ids: string[]): string[];
40
+ /**
41
+ * Each proof must name one of the story's criteria, at most once, and a proof
42
+ * no test makes must say why — the reason is what a reviewer judges.
43
+ */
44
+ export declare function validateProofs(criteria: string[], proofs: CriterionProof[]): CriterionProof[];
45
+ /**
46
+ * Dependencies must name real stories, never the story itself, and never form
47
+ * a cycle — an unsatisfiable order is worse than no order at all.
48
+ */
49
+ export declare function validateDependencies(prd: StructuredPRD, storyId: string, dependencies: string[]): string[];
50
+ export declare function deleteStory(prd: StructuredPRD, storyId: string, today: string): DeleteUserStoryOutput;
51
+ export declare function createPhase(prd: StructuredPRD, input: CreateCustomPhaseInput, today: string): CreateCustomPhaseOutput;
52
+ export declare function assignStoryToPhase(prd: StructuredPRD, input: AssignStoryToPhaseInput, today: string): AssignStoryToPhaseOutput;
53
+ /** Dependencies of `story` that are not completed yet. */
54
+ export declare function incompleteDependencies(prd: StructuredPRD, story: UserStory): string[];
55
+ /**
56
+ * A story cannot be worked on, reviewed or completed before the stories it
57
+ * depends on are completed. `not_started`, `research` and `blocked` stay
58
+ * available so a story can still be planned or parked.
59
+ */
60
+ export declare function assertCanEnterStatus(prd: StructuredPRD, story: UserStory, status: StoryStatus): void;
61
+ /**
62
+ * The next story to start: not started, every dependency completed, ordered
63
+ * by phase, then priority, then position in the PRD.
64
+ */
65
+ export declare function pickNextStory(prd: StructuredPRD): {
66
+ story: UserStory;
67
+ ready_count: number;
68
+ in_progress: string[];
69
+ waiting: {
70
+ id: string;
71
+ title: string;
72
+ waiting_on: string[];
73
+ }[];
74
+ };
75
+ /**
76
+ * Everything an agent needs to work on one story without loading the whole
77
+ * PRD: the story, the scope boundaries, its dependencies with their hand-off
78
+ * logs, and the log of the most recently completed story.
79
+ */
80
+ /** `filename` is the PRD's file name, used to give attachment paths. */
81
+ export declare function buildStoryContext(prd: StructuredPRD, storyId: string, filename: string, prdsPath?: string): {
82
+ prd: {
83
+ title: string;
84
+ overview: string;
85
+ non_goals: string[];
86
+ out_of_scope: string[];
87
+ global_acceptance_criteria: string[];
88
+ attachments: {
89
+ id: string;
90
+ title: string;
91
+ path?: string | undefined;
92
+ url?: string | undefined;
93
+ note?: string | undefined;
94
+ }[];
95
+ };
96
+ story: UserStory;
97
+ attachments: {
98
+ id: string;
99
+ title: string;
100
+ path?: string | undefined;
101
+ url?: string | undefined;
102
+ note?: string | undefined;
103
+ }[];
104
+ phase: {
105
+ id: string;
106
+ name: string;
107
+ } | null;
108
+ edge_cases: EdgeCase[];
109
+ open_questions: OpenQuestion[];
110
+ security: {
111
+ permissions: string[];
112
+ compliance: string[];
113
+ considerations: string[];
114
+ story_notes: string[];
115
+ };
116
+ not_applicable: Record<string, string>;
117
+ design: {
118
+ guidance: string[];
119
+ story_notes: string[];
120
+ decisions: {
121
+ id: string;
122
+ decision: string;
123
+ rationale: string;
124
+ }[];
125
+ };
126
+ dependencies: {
127
+ id: string;
128
+ title: string | null;
129
+ status: StoryStatus | null;
130
+ log: StoryLogEntry[];
131
+ }[];
132
+ previous_story: {
133
+ id: string;
134
+ title: string;
135
+ log: StoryLogEntry[];
136
+ } | null;
137
+ };
138
+ export declare function appendStoryLog(prd: StructuredPRD, storyId: string, entry: StoryLogEntry): {
139
+ story_id: string;
140
+ entries: number;
141
+ };
@@ -0,0 +1,22 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ const require_prd_operations = require("./prd-operations-CcahfbOy.js");
3
+ exports.appendChangeLog = require_prd_operations.appendChangeLog;
4
+ exports.appendStoryLog = require_prd_operations.appendStoryLog;
5
+ exports.assertCanEnterStatus = require_prd_operations.assertCanEnterStatus;
6
+ exports.assignStoryToPhase = require_prd_operations.assignStoryToPhase;
7
+ exports.buildStoryContext = require_prd_operations.buildStoryContext;
8
+ exports.createPhase = require_prd_operations.createPhase;
9
+ exports.deleteStory = require_prd_operations.deleteStory;
10
+ exports.findAttachment = require_prd_operations.findAttachment;
11
+ exports.findStory = require_prd_operations.findStory;
12
+ exports.incompleteDependencies = require_prd_operations.incompleteDependencies;
13
+ exports.nextId = require_prd_operations.nextId;
14
+ exports.nextStoryId = require_prd_operations.nextStoryId;
15
+ exports.pickNextStory = require_prd_operations.pickNextStory;
16
+ exports.recomputeProgress = require_prd_operations.recomputeProgress;
17
+ exports.renderUserStory = require_prd_operations.renderUserStory;
18
+ exports.splitUserStory = require_prd_operations.splitUserStory;
19
+ exports.updateStory = require_prd_operations.updateStory;
20
+ exports.validateAttachmentIds = require_prd_operations.validateAttachmentIds;
21
+ exports.validateDependencies = require_prd_operations.validateDependencies;
22
+ exports.validateProofs = require_prd_operations.validateProofs;
@@ -0,0 +1 @@
1
+ export { t as appendChangeLog, n as appendStoryLog, r as assertCanEnterStatus, i as assignStoryToPhase, a as buildStoryContext, o as createPhase, s as deleteStory, c as findAttachment, l as findStory, u as incompleteDependencies, d as nextId, f as nextStoryId, p as pickNextStory, m as recomputeProgress, h as renderUserStory, g as splitUserStory, _ as updateStory, v as validateAttachmentIds, y as validateDependencies, b as validateProofs } from "./prd-operations-BvFxo9bg.mjs";