@makerkit/prd 0.0.1 → 0.0.3

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 CHANGED
@@ -7,7 +7,7 @@ Structured product requirements documents (PRDs) stored as JSON files in `.prds/
7
7
  - **Completion gate**: a story can only be marked `completed` when the project's checks pass, so "done" means the code verifies.
8
8
  - **MCP tools**: the same operations exposed to Claude Code, Codex, OpenCode or any MCP client.
9
9
  - **Attachments**: files (mockups, screenshots, reference docs) live in a folder next to the PRD, `.prds/<prd name>/`, and links can be recorded too. Stories reference them by id, and `get_story` returns them with their paths.
10
- - **Prompts**: `shape_prd` interviews you round by round (numbered questions, each with a recommended answer and its reason) and writes every decision into the PRD; `implement_story` walks an agent through one story and its hand-off log. The same text is exported (`implementStoryPrompt`, `shapePrdPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
10
+ - **Prompts**: `shape_prd` interviews you round by round (numbered questions, each with a recommended answer and its reason) and writes every decision into the PRD; `architect_prd` designs the shape all stories share (using the project's `architect` skill when it has one) and records it as an attachment the story agents build against; `implement_story` walks an agent through one story and its hand-off log; `review_story` checks the result against the spec. The same text is exported (`shapePrdPrompt`, `architectPrdPrompt`, `implementStoryPrompt`, `reviewStoryPrompt`) for UIs and agents without MCP prompt support.
11
11
 
12
12
  ## Install
13
13
 
package/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { $ as DeletePrdOutputSchema, $t as ResolveOpenQuestionOutput, A as AssignStoryToPhaseOutput, An as DecisionLogEntry, At as ListPrdsOutputSchema, B as CreatePrdInputSchema, Bn as StoryTraceabilityMap, Bt as PhasesOutputSchema, C as AddStoryLogOutputSchema, Cn as UpdateUserStoryInputSchema, Ct as GetProjectStatusOutputSchema, D as AddUserStoryOutputSchema, Dn as Attachment, Dt as GetStoryOutputSchema, E as AddUserStoryOutput, En as AgentTaskPacket, Et as GetStoryOutput, F as CreateCustomPhaseInput, Fn as RiskItem, Ft as MarkNotApplicableInputSchema, G as DecideEdgeCaseInputSchema, Gt as RemoveAttachmentInput, H as CreatePrdOutputSchema, Hn as StructuredPRD, Ht as PrdSectionValueSchemas, I as CreateCustomPhaseInputSchema, In as StoryComplexity, It as MarkNotApplicableOutput, J as DeletePhaseInput, Jt as RemoveAttachmentOutputSchema, K as DecideEdgeCaseOutput, Kt as RemoveAttachmentInputSchema, L as CreateCustomPhaseOutput, Ln as StoryLogEntry, Lt as MarkNotApplicableOutputSchema, M as CheckPlanInputSchema, Mn as GlossaryTerm, Mt as ListTemplatesOutput, N as CheckPlanOutput, Nn as NotApplicableTopic, Nt as ListTemplatesOutputSchema, O as AssignStoryToPhaseInput, On as CrossDependency, Ot as ListPrdsInputSchema, P as CheckPlanOutputSchema, Pn as OpenQuestion, Pt as MarkNotApplicableInput, Q as DeletePrdOutput, Qt as ResolveOpenQuestionInputSchema, R as CreateCustomPhaseOutputSchema, Rn as StoryPriority, Rt as NotApplicableTopicSchema, S as AddStoryLogOutput, Sn as UpdateUserStoryInput, St as GetProjectStatusOutput, T as AddUserStoryInputSchema, Tn as UpdateUserStoryOutputSchema, Tt as GetStoryInputSchema, U as CustomPhaseSchema, Un as UserStory, Ut as PrdSummary, V as CreatePrdOutput, Vn as StoryVerification, Vt as PrdSection, W as DecideEdgeCaseInput, Wt as PrdSummarySchema, X as DeletePrdInput, Xt as ReorderPhasesInputSchema, Y as DeletePhaseInputSchema, Yt as ReorderPhasesInput, Z as DeletePrdInputSchema, Zt as ResolveOpenQuestionInput, _ as AddGlossaryTermInputSchema, _n as UpdatePrdSectionOutputSchema, _t as GetPrdInput, a as PrdVerificationResult, an as StoryPrioritySchema, at as ExportPrdMarkdownInputSchema, b as AddStoryLogInput, bn as UpdateStoryStatusOutput, bt as GetPrdOutputSchema, c as AddAttachmentInput, cn as UpdateAttachmentInput, ct as GetImplementationPromptsInputSchema, d as AddAttachmentOutputSchema, dn as UpdateAttachmentOutputSchema, dt as GetImprovementSuggestionsInputSchema, en as ResolveOpenQuestionOutputSchema, et as DeleteUserStoryInput, f as AddDecisionInput, fn as UpdatePhaseInput, ft as GetImprovementSuggestionsOutput, g as AddGlossaryTermInput, gn as UpdatePrdSectionOutput, gt as GetNextStoryOutputSchema, h as AddDecisionOutputSchema, hn as UpdatePrdSectionInputSchema, ht as GetNextStoryOutput, i as PrdVerificationDiagnostic, in as StoryLogEntrySchema, it as ExportPrdMarkdownInput, j as AssignStoryToPhaseOutputSchema, jn as EdgeCase, jt as ListTemplatesInputSchema, k as AssignStoryToPhaseInputSchema, kn as CustomPhase, kt as ListPrdsOutput, l as AddAttachmentInputSchema, ln as UpdateAttachmentInputSchema, lt as GetImplementationPromptsOutput, m as AddDecisionOutput, mn as UpdatePrdSectionInput, mt as GetNextStoryInputSchema, n as PrdRevisionConflictError, nn as StoryAttachmentSchema, nt as DeleteUserStoryOutput, o as createPrdService, on as StoryStatusSchema, ot as ExportPrdMarkdownOutput, p as AddDecisionInputSchema, pn as UpdatePhaseInputSchema, pt as GetImprovementSuggestionsOutputSchema, q as DecideEdgeCaseOutputSchema, qt as RemoveAttachmentOutput, r as PrdService, rn as StoryComplexitySchema, rt as DeleteUserStoryOutputSchema, s as normalizePrd, sn as StoryVerificationSchema, st as ExportPrdMarkdownOutputSchema, t as PrdDeps, tn as StoryAttachment, tt as DeleteUserStoryInputSchema, u as AddAttachmentOutput, un as UpdateAttachmentOutput, ut as GetImplementationPromptsOutputSchema, v as AddGlossaryTermOutput, vn as UpdateStoryStatusInput, vt as GetPrdInputSchema, w as AddUserStoryInput, wn as UpdateUserStoryOutput, wt as GetStoryInput, x as AddStoryLogInputSchema, xn as UpdateStoryStatusOutputSchema, xt as GetProjectStatusInputSchema, y as AddGlossaryTermOutputSchema, yn as UpdateStoryStatusInputSchema, yt as GetPrdOutput, z as CreatePrdInput, zn as StoryStatus, zt as PhasesOutput } from "./prd.service-DSBp8sMl.js";
1
+ import { $ as DeletePrdOutputSchema, $t as ResolveOpenQuestionOutput, A as AssignStoryToPhaseOutput, An as DecisionLogEntry, At as ListPrdsOutputSchema, B as CreatePrdInputSchema, Bn as StoryTraceabilityMap, Bt as PhasesOutputSchema, C as AddStoryLogOutputSchema, Cn as UpdateUserStoryInputSchema, Ct as GetProjectStatusOutputSchema, D as AddUserStoryOutputSchema, Dn as Attachment, Dt as GetStoryOutputSchema, E as AddUserStoryOutput, En as AgentTaskPacket, Et as GetStoryOutput, F as CreateCustomPhaseInput, Fn as RiskItem, Ft as MarkNotApplicableInputSchema, G as DecideEdgeCaseInputSchema, Gt as RemoveAttachmentInput, H as CreatePrdOutputSchema, Hn as StructuredPRD, Ht as PrdSectionValueSchemas, I as CreateCustomPhaseInputSchema, In as StoryComplexity, It as MarkNotApplicableOutput, J as DeletePhaseInput, Jt as RemoveAttachmentOutputSchema, K as DecideEdgeCaseOutput, Kt as RemoveAttachmentInputSchema, L as CreateCustomPhaseOutput, Ln as StoryLogEntry, Lt as MarkNotApplicableOutputSchema, M as CheckPlanInputSchema, Mn as GlossaryTerm, Mt as ListTemplatesOutput, N as CheckPlanOutput, Nn as NotApplicableTopic, Nt as ListTemplatesOutputSchema, O as AssignStoryToPhaseInput, On as CrossDependency, Ot as ListPrdsInputSchema, P as CheckPlanOutputSchema, Pn as OpenQuestion, Pt as MarkNotApplicableInput, Q as DeletePrdOutput, Qt as ResolveOpenQuestionInputSchema, R as CreateCustomPhaseOutputSchema, Rn as StoryPriority, Rt as NotApplicableTopicSchema, S as AddStoryLogOutput, Sn as UpdateUserStoryInput, St as GetProjectStatusOutput, T as AddUserStoryInputSchema, Tn as UpdateUserStoryOutputSchema, Tt as GetStoryInputSchema, U as CustomPhaseSchema, Un as UserStory, Ut as PrdSummary, V as CreatePrdOutput, Vn as StoryVerification, Vt as PrdSection, W as DecideEdgeCaseInput, Wt as PrdSummarySchema, X as DeletePrdInput, Xt as ReorderPhasesInputSchema, Y as DeletePhaseInputSchema, Yt as ReorderPhasesInput, Z as DeletePrdInputSchema, Zt as ResolveOpenQuestionInput, _ as AddGlossaryTermInputSchema, _n as UpdatePrdSectionOutputSchema, _t as GetPrdInput, a as PrdVerificationResult, an as StoryPrioritySchema, at as ExportPrdMarkdownInputSchema, b as AddStoryLogInput, bn as UpdateStoryStatusOutput, bt as GetPrdOutputSchema, c as AddAttachmentInput, cn as UpdateAttachmentInput, ct as GetImplementationPromptsInputSchema, d as AddAttachmentOutputSchema, dn as UpdateAttachmentOutputSchema, dt as GetImprovementSuggestionsInputSchema, en as ResolveOpenQuestionOutputSchema, et as DeleteUserStoryInput, f as AddDecisionInput, fn as UpdatePhaseInput, ft as GetImprovementSuggestionsOutput, g as AddGlossaryTermInput, gn as UpdatePrdSectionOutput, gt as GetNextStoryOutputSchema, h as AddDecisionOutputSchema, hn as UpdatePrdSectionInputSchema, ht as GetNextStoryOutput, i as PrdVerificationDiagnostic, in as StoryLogEntrySchema, it as ExportPrdMarkdownInput, j as AssignStoryToPhaseOutputSchema, jn as EdgeCase, jt as ListTemplatesInputSchema, k as AssignStoryToPhaseInputSchema, kn as CustomPhase, kt as ListPrdsOutput, l as AddAttachmentInputSchema, ln as UpdateAttachmentInputSchema, lt as GetImplementationPromptsOutput, m as AddDecisionOutput, mn as UpdatePrdSectionInput, mt as GetNextStoryInputSchema, n as PrdRevisionConflictError, nn as StoryAttachmentSchema, nt as DeleteUserStoryOutput, o as createPrdService, on as StoryStatusSchema, ot as ExportPrdMarkdownOutput, p as AddDecisionInputSchema, pn as UpdatePhaseInputSchema, pt as GetImprovementSuggestionsOutputSchema, q as DecideEdgeCaseOutputSchema, qt as RemoveAttachmentOutput, r as PrdService, rn as StoryComplexitySchema, rt as DeleteUserStoryOutputSchema, s as normalizePrd, sn as StoryVerificationSchema, st as ExportPrdMarkdownOutputSchema, t as PrdDeps, tn as StoryAttachment, tt as DeleteUserStoryInputSchema, u as AddAttachmentOutput, un as UpdateAttachmentOutput, ut as GetImplementationPromptsOutputSchema, v as AddGlossaryTermOutput, vn as UpdateStoryStatusInput, vt as GetPrdInputSchema, w as AddUserStoryInput, wn as UpdateUserStoryOutput, wt as GetStoryInput, x as AddStoryLogInputSchema, xn as UpdateStoryStatusOutputSchema, xt as GetProjectStatusInputSchema, y as AddGlossaryTermOutputSchema, yn as UpdateStoryStatusInputSchema, yt as GetPrdOutput, z as CreatePrdInput, zn as StoryStatus, zt as PhasesOutput } from "./prd.service-x5EpOoMv.js";
2
2
  //#region src/prd-operations.d.ts
3
3
  /**
4
4
  * Pure PRD transforms.
@@ -164,6 +164,37 @@ export declare function isNotApplicable(prd: StructuredPRD, topic: NotApplicable
164
164
  */
165
165
  export declare function formatPrdMarkdown(prd: StructuredPRD, filename?: string): string;
166
166
  //#endregion
167
+ //#region src/prompts.d.ts
168
+ /**
169
+ * The instructions behind the MCP prompts, exported so other tools (e.g. a
170
+ * UI that shows what to ask the agent) give exactly the same text.
171
+ */
172
+ export declare function shapePrdPrompt(overview?: string, filename?: string): string;
173
+ export declare function architectPrdPrompt(filename: string): string;
174
+ export declare function reviewStoryPrompt(filename: string, storyId: string, base?: string): string;
175
+ export declare function implementStoryPrompt(filename: string, storyId?: string): string;
176
+ //#endregion
177
+ //#region src/plan-check.d.ts
178
+ /**
179
+ * What a plan is still missing, as items a UI can render as a checklist and an
180
+ * agent can act on. `required` items mean the plan is not ready to build;
181
+ * `recommended` items make it better but do not block.
182
+ */
183
+ interface PlanCheckItem {
184
+ /** Stable key, e.g. `stories` or `vague-stories`. */
185
+ id: string;
186
+ /** The PRD section to change, matching `update_prd_section` where possible. */
187
+ section: string;
188
+ message: string;
189
+ severity: 'required' | 'recommended';
190
+ /** Stories the item is about, when it is about specific stories. */
191
+ storyIds?: string[];
192
+ }
193
+ export declare function checkPlan(prd: StructuredPRD): {
194
+ ready_to_build: boolean;
195
+ items: PlanCheckItem[];
196
+ };
197
+ //#endregion
167
198
  //#region src/templates.d.ts
168
199
  /**
169
200
  * Starting points for new PRDs. A template fills sections the author would
@@ -194,34 +225,4 @@ type TemplateId = (typeof TEMPLATE_IDS)[number];
194
225
  export declare const PRD_TEMPLATES: readonly PrdTemplate[];
195
226
  export declare function getTemplate(id: TemplateId): PrdTemplate;
196
227
  //#endregion
197
- //#region src/prompts.d.ts
198
- /**
199
- * The instructions behind the MCP prompts, exported so other tools (e.g. a
200
- * UI that shows what to ask the agent) give exactly the same text.
201
- */
202
- export declare function shapePrdPrompt(idea?: string, filename?: string, templateId?: TemplateId): string;
203
- export declare function reviewStoryPrompt(filename: string, storyId: string, base?: string): string;
204
- export declare function implementStoryPrompt(filename: string, storyId?: string): string;
205
- //#endregion
206
- //#region src/plan-check.d.ts
207
- /**
208
- * What a plan is still missing, as items a UI can render as a checklist and an
209
- * agent can act on. `required` items mean the plan is not ready to build;
210
- * `recommended` items make it better but do not block.
211
- */
212
- interface PlanCheckItem {
213
- /** Stable key, e.g. `stories` or `vague-stories`. */
214
- id: string;
215
- /** The PRD section to change, matching `update_prd_section` where possible. */
216
- section: string;
217
- message: string;
218
- severity: 'required' | 'recommended';
219
- /** Stories the item is about, when it is about specific stories. */
220
- storyIds?: string[];
221
- }
222
- export declare function checkPlan(prd: StructuredPRD): {
223
- ready_to_build: boolean;
224
- items: PlanCheckItem[];
225
- };
226
- //#endregion
227
228
  export { AddAttachmentInput, AddAttachmentInputSchema, AddAttachmentOutput, AddAttachmentOutputSchema, AddDecisionInput, AddDecisionInputSchema, AddDecisionOutput, AddDecisionOutputSchema, AddGlossaryTermInput, AddGlossaryTermInputSchema, AddGlossaryTermOutput, AddGlossaryTermOutputSchema, AddStoryLogInput, AddStoryLogInputSchema, AddStoryLogOutput, AddStoryLogOutputSchema, AddUserStoryInput, AddUserStoryInputSchema, AddUserStoryOutput, AddUserStoryOutputSchema, type AgentTaskPacket, AssignStoryToPhaseInput, AssignStoryToPhaseInputSchema, AssignStoryToPhaseOutput, AssignStoryToPhaseOutputSchema, type Attachment, CheckPlanInputSchema, CheckPlanOutput, CheckPlanOutputSchema, CreateCustomPhaseInput, CreateCustomPhaseInputSchema, CreateCustomPhaseOutput, CreateCustomPhaseOutputSchema, CreatePrdInput, CreatePrdInputSchema, CreatePrdOutput, CreatePrdOutputSchema, type CrossDependency, type CustomPhase, CustomPhaseSchema, DecideEdgeCaseInput, DecideEdgeCaseInputSchema, DecideEdgeCaseOutput, DecideEdgeCaseOutputSchema, type DecisionLogEntry, DeletePhaseInput, DeletePhaseInputSchema, DeletePrdInput, DeletePrdInputSchema, DeletePrdOutput, DeletePrdOutputSchema, DeleteUserStoryInput, DeleteUserStoryInputSchema, DeleteUserStoryOutput, DeleteUserStoryOutputSchema, type EdgeCase, ExportPrdMarkdownInput, ExportPrdMarkdownInputSchema, ExportPrdMarkdownOutput, ExportPrdMarkdownOutputSchema, GetImplementationPromptsInputSchema, GetImplementationPromptsOutput, GetImplementationPromptsOutputSchema, GetImprovementSuggestionsInputSchema, GetImprovementSuggestionsOutput, GetImprovementSuggestionsOutputSchema, GetNextStoryInputSchema, GetNextStoryOutput, GetNextStoryOutputSchema, GetPrdInput, GetPrdInputSchema, GetPrdOutput, GetPrdOutputSchema, GetProjectStatusInputSchema, GetProjectStatusOutput, GetProjectStatusOutputSchema, GetStoryInput, GetStoryInputSchema, GetStoryOutput, GetStoryOutputSchema, type GlossaryTerm, ListPrdsInputSchema, ListPrdsOutput, ListPrdsOutputSchema, ListTemplatesInputSchema, ListTemplatesOutput, ListTemplatesOutputSchema, MarkNotApplicableInput, MarkNotApplicableInputSchema, MarkNotApplicableOutput, MarkNotApplicableOutputSchema, type NotApplicableTopic, NotApplicableTopicSchema, type OpenQuestion, PhasesOutput, PhasesOutputSchema, type PlanCheckItem, type PrdDeps, PrdRevisionConflictError, PrdSection, PrdSectionValueSchemas, PrdService, PrdSummary, PrdSummarySchema, type PrdTemplate, type PrdVerificationDiagnostic, type PrdVerificationResult, RemoveAttachmentInput, RemoveAttachmentInputSchema, RemoveAttachmentOutput, RemoveAttachmentOutputSchema, ReorderPhasesInput, ReorderPhasesInputSchema, ResolveOpenQuestionInput, ResolveOpenQuestionInputSchema, ResolveOpenQuestionOutput, ResolveOpenQuestionOutputSchema, type RiskItem, StoryAttachment, StoryAttachmentSchema, type StoryComplexity, StoryComplexitySchema, type StoryLogEntry, StoryLogEntrySchema, type StoryPriority, StoryPrioritySchema, type StoryStatus, StoryStatusSchema, type StoryTraceabilityMap, type StoryVerification, StoryVerificationSchema, type StructuredPRD, type TemplateId, UpdateAttachmentInput, UpdateAttachmentInputSchema, UpdateAttachmentOutput, UpdateAttachmentOutputSchema, UpdatePhaseInput, UpdatePhaseInputSchema, UpdatePrdSectionInput, UpdatePrdSectionInputSchema, UpdatePrdSectionOutput, UpdatePrdSectionOutputSchema, UpdateStoryStatusInput, UpdateStoryStatusInputSchema, UpdateStoryStatusOutput, UpdateStoryStatusOutputSchema, UpdateUserStoryInput, UpdateUserStoryInputSchema, UpdateUserStoryOutput, UpdateUserStoryOutputSchema, type UserStory, createPrdService, normalizePrd };
package/index.js CHANGED
@@ -1,84 +1,6 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_prompts = require("./prompts-CIX8IeAx.js");
2
+ const require_prompts = require("./prompts-DJQ4FQ11.js");
3
3
  let node_path = require("node:path");
4
- //#region src/safe-file-name.ts
5
- /**
6
- * Accept only a bare file name. Anything that could escape the intended
7
- * directory (path separators, parent references, hidden files) is rejected
8
- * before the filesystem is touched.
9
- */
10
- function assertSafeFileName(value, label = "file name") {
11
- const name = value.trim();
12
- if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
13
- return name;
14
- }
15
- /**
16
- * Accept only a relative path that stays inside the directory it is joined
17
- * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
18
- * This is a check on the text only; code that serves the file must still
19
- * resolve symlinks before reading it.
20
- */
21
- function assertSafeRelativePath(value, label = "path") {
22
- const path = value.trim();
23
- const segments = path.split("/");
24
- if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
25
- return path;
26
- }
27
- //#endregion
28
- //#region src/attachment-paths.ts
29
- /**
30
- * The folder for a PRD's files, relative to `.prds`: the PRD file name
31
- * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
32
- */
33
- function attachmentsFolder(filename) {
34
- return filename.replace(/\.json$/, "");
35
- }
36
- /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
37
- function attachmentProjectPath(filename, path) {
38
- return `.prds/${attachmentsFolder(filename)}/${path}`;
39
- }
40
- /** Attachments as an agent needs them: file paths from the project root. */
41
- function resolveAttachments(filename, attachments) {
42
- return attachments.map(({ path, ...attachment }) => ({
43
- ...attachment,
44
- ...path ? { path: attachmentProjectPath(filename, path) } : {}
45
- }));
46
- }
47
- /**
48
- * Attachments as stored, with hand-edited entries that would break readers
49
- * or point outside the PRD folder dropped: each needs a string id and title
50
- * and either a safe relative path or an http(s) url.
51
- */
52
- function normalizeAttachments(value) {
53
- if (!Array.isArray(value)) return [];
54
- return value.flatMap((entry) => {
55
- if (typeof entry !== "object" || entry === null) return [];
56
- const { id, title, path, url, note } = entry;
57
- if (typeof id !== "string" || typeof title !== "string") return [];
58
- const base = {
59
- id,
60
- title,
61
- ...typeof note === "string" && note ? { note } : {}
62
- };
63
- if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
64
- ...base,
65
- path
66
- }];
67
- if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
68
- ...base,
69
- url
70
- }];
71
- return [];
72
- });
73
- }
74
- function isSafePath(path) {
75
- try {
76
- return assertSafeRelativePath(path) === path;
77
- } catch {
78
- return false;
79
- }
80
- }
81
- //#endregion
82
4
  //#region src/edge-cases.ts
83
5
  /**
84
6
  * Edge cases as stored, with hand-edited entries that would break readers
@@ -446,10 +368,10 @@ function buildStoryContext(prd, storyId, filename) {
446
368
  non_goals: prd.nonGoals,
447
369
  out_of_scope: prd.outOfScope,
448
370
  global_acceptance_criteria: prd.acceptanceCriteria.global,
449
- attachments: resolveAttachments(filename, prd.attachments)
371
+ attachments: require_prompts.resolveAttachments(filename, prd.attachments)
450
372
  },
451
373
  story,
452
- attachments: resolveAttachments(filename, prd.attachments.filter((attachment) => linked.has(attachment.id))),
374
+ attachments: require_prompts.resolveAttachments(filename, prd.attachments.filter((attachment) => linked.has(attachment.id))),
453
375
  phase: phase ? {
454
376
  id: phase.id,
455
377
  name: phase.name
@@ -545,66 +467,6 @@ function setNotApplicable(prd, input, today) {
545
467
  };
546
468
  }
547
469
  //#endregion
548
- //#region src/open-questions.ts
549
- /**
550
- * Open questions as stored. Older files hold plain strings; they become
551
- * questions with ids in list order. Entries without question text are dropped.
552
- */
553
- function normalizeOpenQuestions(value) {
554
- if (!Array.isArray(value)) return [];
555
- const questions = [];
556
- for (const entry of value) {
557
- if (typeof entry === "string") {
558
- if (entry.trim()) questions.push({
559
- id: "",
560
- question: entry
561
- });
562
- continue;
563
- }
564
- if (typeof entry !== "object" || entry === null) continue;
565
- const { id, question, why, options, recommended, storyIds } = entry;
566
- if (typeof question !== "string" || !question.trim()) continue;
567
- const strings = (list) => Array.isArray(list) ? list.filter((item) => typeof item === "string" && item.length > 0) : [];
568
- questions.push({
569
- id: typeof id === "string" ? id : "",
570
- question,
571
- ...typeof why === "string" && why ? { why } : {},
572
- ...strings(options).length ? { options: strings(options) } : {},
573
- ...typeof recommended === "string" && recommended ? { recommended } : {},
574
- ...strings(storyIds).length ? { storyIds: strings(storyIds) } : {}
575
- });
576
- }
577
- let highest = questions.reduce((max, question) => {
578
- const match = /^Q(\d+)$/.exec(question.id);
579
- return match ? Math.max(max, Number(match[1])) : max;
580
- }, 0);
581
- return questions.map((question) => question.id ? question : {
582
- ...question,
583
- id: formatQuestionId(++highest)
584
- });
585
- }
586
- function formatQuestionId(number) {
587
- return `Q${String(number).padStart(3, "0")}`;
588
- }
589
- /**
590
- * The next question id. Answered questions are quoted in decisions, so an id
591
- * is never handed out twice: the high-water mark is kept in metadata.
592
- */
593
- function nextQuestionId(prd, extra = []) {
594
- const present = [...prd.openQuestions, ...extra].reduce((max, question) => {
595
- const match = /^Q(\d+)$/.exec(question.id);
596
- return match ? Math.max(max, Number(match[1])) : max;
597
- }, 0);
598
- const next = Math.max(prd.metadata.lastQuestionNumber ?? 0, present) + 1;
599
- prd.metadata.lastQuestionNumber = next;
600
- return formatQuestionId(next);
601
- }
602
- /** Open questions that block a story that is not completed yet. */
603
- function blockingQuestions(prd) {
604
- const unfinished = new Set(prd.userStories.filter((story) => story.status !== "completed").map((story) => story.id));
605
- return prd.openQuestions.filter((question) => question.storyIds?.some((id) => unfinished.has(id)));
606
- }
607
- //#endregion
608
470
  //#region src/attachments.ts
609
471
  /**
610
472
  * Adds an attachment and links it to the given stories. The caller checks
@@ -613,7 +475,7 @@ function blockingQuestions(prd) {
613
475
  function addAttachment(prd, input, today) {
614
476
  if (Boolean(input.path) === Boolean(input.url)) throw new Error("Give either path or url for an attachment, not both.");
615
477
  if (input.url && !/^https?:\/\//i.test(input.url)) throw new Error("An attachment url must start with http:// or https://.");
616
- const path = input.path ? assertSafeRelativePath(input.path, "attachment path") : void 0;
478
+ const path = input.path ? require_prompts.assertSafeRelativePath(input.path, "attachment path") : void 0;
617
479
  const stories = (input.storyIds ?? []).map((id) => findStory(prd, id));
618
480
  const id = nextAttachmentId(prd);
619
481
  prd.attachments.push({
@@ -626,7 +488,7 @@ function addAttachment(prd, input, today) {
626
488
  appendChangeLog(prd, `Added attachment ${id} (${input.title})`, today);
627
489
  return {
628
490
  attachment_id: id,
629
- path: path ? attachmentProjectPath(input.filename, path) : null,
491
+ path: path ? require_prompts.attachmentProjectPath(input.filename, path) : null,
630
492
  stories_updated: stories.map((story) => story.id),
631
493
  total_attachments: prd.attachments.length
632
494
  };
@@ -799,7 +661,7 @@ function formatStory(story) {
799
661
  }
800
662
  function formatAttachment(attachment, filename) {
801
663
  const title = oneLine(attachment.title).replace(/[[\]]/g, "\\$&");
802
- const target = attachment.url ? linkTarget(attachment.url) : filename ? linkTarget(encodeURI(`${attachmentsFolder(filename)}/${attachment.path}`)) : void 0;
664
+ const target = attachment.url ? linkTarget(attachment.url) : filename ? linkTarget(encodeURI(`${require_prompts.attachmentsFolder(filename)}/${attachment.path}`)) : void 0;
803
665
  const label = target ? `[${title}](${target})` : `${title} (${attachment.path})`;
804
666
  const note = attachment.note ? ` - ${oneLine(attachment.note)}` : "";
805
667
  return `- ${attachment.id}: ${label}${note}`;
@@ -817,6 +679,66 @@ function bullets(items, emptyLabel) {
817
679
  return items.map((item) => `- ${item}`);
818
680
  }
819
681
  //#endregion
682
+ //#region src/open-questions.ts
683
+ /**
684
+ * Open questions as stored. Older files hold plain strings; they become
685
+ * questions with ids in list order. Entries without question text are dropped.
686
+ */
687
+ function normalizeOpenQuestions(value) {
688
+ if (!Array.isArray(value)) return [];
689
+ const questions = [];
690
+ for (const entry of value) {
691
+ if (typeof entry === "string") {
692
+ if (entry.trim()) questions.push({
693
+ id: "",
694
+ question: entry
695
+ });
696
+ continue;
697
+ }
698
+ if (typeof entry !== "object" || entry === null) continue;
699
+ const { id, question, why, options, recommended, storyIds } = entry;
700
+ if (typeof question !== "string" || !question.trim()) continue;
701
+ const strings = (list) => Array.isArray(list) ? list.filter((item) => typeof item === "string" && item.length > 0) : [];
702
+ questions.push({
703
+ id: typeof id === "string" ? id : "",
704
+ question,
705
+ ...typeof why === "string" && why ? { why } : {},
706
+ ...strings(options).length ? { options: strings(options) } : {},
707
+ ...typeof recommended === "string" && recommended ? { recommended } : {},
708
+ ...strings(storyIds).length ? { storyIds: strings(storyIds) } : {}
709
+ });
710
+ }
711
+ let highest = questions.reduce((max, question) => {
712
+ const match = /^Q(\d+)$/.exec(question.id);
713
+ return match ? Math.max(max, Number(match[1])) : max;
714
+ }, 0);
715
+ return questions.map((question) => question.id ? question : {
716
+ ...question,
717
+ id: formatQuestionId(++highest)
718
+ });
719
+ }
720
+ function formatQuestionId(number) {
721
+ return `Q${String(number).padStart(3, "0")}`;
722
+ }
723
+ /**
724
+ * The next question id. Answered questions are quoted in decisions, so an id
725
+ * is never handed out twice: the high-water mark is kept in metadata.
726
+ */
727
+ function nextQuestionId(prd, extra = []) {
728
+ const present = [...prd.openQuestions, ...extra].reduce((max, question) => {
729
+ const match = /^Q(\d+)$/.exec(question.id);
730
+ return match ? Math.max(max, Number(match[1])) : max;
731
+ }, 0);
732
+ const next = Math.max(prd.metadata.lastQuestionNumber ?? 0, present) + 1;
733
+ prd.metadata.lastQuestionNumber = next;
734
+ return formatQuestionId(next);
735
+ }
736
+ /** Open questions that block a story that is not completed yet. */
737
+ function blockingQuestions(prd) {
738
+ const unfinished = new Set(prd.userStories.filter((story) => story.status !== "completed").map((story) => story.id));
739
+ return prd.openQuestions.filter((question) => question.storyIds?.some((id) => unfinished.has(id)));
740
+ }
741
+ //#endregion
820
742
  //#region src/plan-check.ts
821
743
  /** The not-applicable topic each "missing" check is about. */
822
744
  const CHECK_TOPICS = {
@@ -1509,7 +1431,8 @@ var PrdService = class {
1509
1431
  id: template.id,
1510
1432
  name: template.name,
1511
1433
  description: template.description,
1512
- when_to_use: template.whenToUse
1434
+ when_to_use: template.whenToUse,
1435
+ interview_focus: template.interviewFocus
1513
1436
  })) };
1514
1437
  }
1515
1438
  async checkPlan(filename) {
@@ -1591,8 +1514,8 @@ var PrdService = class {
1591
1514
  async addAttachment(input) {
1592
1515
  const filename = this.safeName(input.filename);
1593
1516
  if (input.path) {
1594
- const folder = attachmentsFolder(filename);
1595
- const path = assertSafeRelativePath(input.path, "attachment path");
1517
+ const folder = require_prompts.attachmentsFolder(filename);
1518
+ const path = require_prompts.assertSafeRelativePath(input.path, "attachment path");
1596
1519
  if (!await this.deps.fileExists((0, node_path.join)(this.prdsDir, folder, path))) throw new Error(`File ".prds/${folder}/${path}" not found. Save it in .prds/${folder}/ first.`);
1597
1520
  }
1598
1521
  return this.mutate(filename, (prd) => addAttachment(prd, {
@@ -1665,7 +1588,7 @@ var PrdService = class {
1665
1588
  }
1666
1589
  }
1667
1590
  safeName(filename) {
1668
- return assertSafeFileName(filename, "PRD file name");
1591
+ return require_prompts.assertSafeFileName(filename, "PRD file name");
1669
1592
  }
1670
1593
  today() {
1671
1594
  return this.deps.now().toISOString().slice(0, 10);
@@ -1749,7 +1672,7 @@ function normalizePrd(input, today) {
1749
1672
  designGuidance: Array.isArray(prd.designGuidance) ? prd.designGuidance.filter((item) => typeof item === "string") : [],
1750
1673
  decisionLog: prd.decisionLog ?? [],
1751
1674
  glossary: prd.glossary ?? [],
1752
- attachments: normalizeAttachments(prd.attachments),
1675
+ attachments: require_prompts.normalizeAttachments(prd.attachments),
1753
1676
  agentTaskPackets: prd.agentTaskPackets ?? [],
1754
1677
  changeLog: prd.changeLog ?? [],
1755
1678
  metadata: {
@@ -1866,10 +1789,11 @@ exports.UpdateUserStoryInputSchema = require_prompts.UpdateUserStoryInputSchema;
1866
1789
  exports.UpdateUserStoryOutputSchema = require_prompts.UpdateUserStoryOutputSchema;
1867
1790
  exports.appendChangeLog = appendChangeLog;
1868
1791
  exports.appendStoryLog = appendStoryLog;
1792
+ exports.architectPrdPrompt = require_prompts.architectPrdPrompt;
1869
1793
  exports.assertCanEnterStatus = assertCanEnterStatus;
1870
1794
  exports.assignStoryToPhase = assignStoryToPhase;
1871
- exports.attachmentProjectPath = attachmentProjectPath;
1872
- exports.attachmentsFolder = attachmentsFolder;
1795
+ exports.attachmentProjectPath = require_prompts.attachmentProjectPath;
1796
+ exports.attachmentsFolder = require_prompts.attachmentsFolder;
1873
1797
  exports.buildStoryContext = buildStoryContext;
1874
1798
  exports.checkPlan = checkPlan;
1875
1799
  exports.createPhase = createPhase;
@@ -1888,7 +1812,7 @@ exports.normalizePrd = normalizePrd;
1888
1812
  exports.pickNextStory = pickNextStory;
1889
1813
  exports.recomputeProgress = recomputeProgress;
1890
1814
  exports.renderUserStory = renderUserStory;
1891
- exports.resolveAttachments = resolveAttachments;
1815
+ exports.resolveAttachments = require_prompts.resolveAttachments;
1892
1816
  exports.reviewStoryPrompt = require_prompts.reviewStoryPrompt;
1893
1817
  exports.shapePrdPrompt = require_prompts.shapePrdPrompt;
1894
1818
  exports.splitUserStory = splitUserStory;
package/index.mjs CHANGED
@@ -1,83 +1,5 @@
1
- import { $ as PrdSummarySchema, A as ExportPrdMarkdownInputSchema, B as GetProjectStatusInputSchema, C as DecideEdgeCaseInputSchema, D as DeletePrdOutputSchema, E as DeletePrdInputSchema, F as GetImprovementSuggestionsOutputSchema, G as ListPrdsOutputSchema, H as GetStoryInputSchema, I as GetNextStoryInputSchema, J as MarkNotApplicableInputSchema, K as ListTemplatesInputSchema, L as GetNextStoryOutputSchema, M as GetImplementationPromptsInputSchema, N as GetImplementationPromptsOutputSchema, O as DeleteUserStoryInputSchema, P as GetImprovementSuggestionsInputSchema, Q as PrdSectionValueSchemas, R as GetPrdInputSchema, S as CustomPhaseSchema, St as getTemplate, T as DeletePhaseInputSchema, U as GetStoryOutputSchema, V as GetProjectStatusOutputSchema, W as ListPrdsInputSchema, X as NotApplicableTopicSchema, Y as MarkNotApplicableOutputSchema, Z as PhasesOutputSchema, _ as CheckPlanOutputSchema, _t as UpdateStoryStatusOutputSchema, a as AddAttachmentOutputSchema, at as StoryAttachmentSchema, b as CreatePrdInputSchema, bt as PRD_TEMPLATES, c as AddGlossaryTermInputSchema, ct as StoryPrioritySchema, d as AddStoryLogOutputSchema, dt as UpdateAttachmentInputSchema, et as RemoveAttachmentInputSchema, f as AddUserStoryInputSchema, ft as UpdateAttachmentOutputSchema, g as CheckPlanInputSchema, gt as UpdateStoryStatusInputSchema, h as AssignStoryToPhaseOutputSchema, ht as UpdatePrdSectionOutputSchema, i as AddAttachmentInputSchema, it as ResolveOpenQuestionOutputSchema, j as ExportPrdMarkdownOutputSchema, k as DeleteUserStoryOutputSchema, l as AddGlossaryTermOutputSchema, lt as StoryStatusSchema, m as AssignStoryToPhaseInputSchema, mt as UpdatePrdSectionInputSchema, n as reviewStoryPrompt, nt as ReorderPhasesInputSchema, o as AddDecisionInputSchema, ot as StoryComplexitySchema, p as AddUserStoryOutputSchema, pt as UpdatePhaseInputSchema, q as ListTemplatesOutputSchema, r as shapePrdPrompt, rt as ResolveOpenQuestionInputSchema, s as AddDecisionOutputSchema, st as StoryLogEntrySchema, t as implementStoryPrompt, tt as RemoveAttachmentOutputSchema, u as AddStoryLogInputSchema, ut as StoryVerificationSchema, v as CreateCustomPhaseInputSchema, vt as UpdateUserStoryInputSchema, w as DecideEdgeCaseOutputSchema, x as CreatePrdOutputSchema, xt as TEMPLATE_IDS, y as CreateCustomPhaseOutputSchema, yt as UpdateUserStoryOutputSchema, z as GetPrdOutputSchema } from "./prompts-Bber0S1Z.mjs";
1
+ import { $ as PrdSectionValueSchemas, A as DeleteUserStoryOutputSchema, B as GetPrdOutputSchema, C as CustomPhaseSchema, Ct as getTemplate, D as DeletePrdInputSchema, Dt as resolveAttachments, E as DeletePhaseInputSchema, Et as normalizeAttachments, 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, Ot as assertSafeFileName, P as GetImplementationPromptsOutputSchema, Q as PhasesOutputSchema, R as GetNextStoryOutputSchema, S as CreatePrdOutputSchema, St as TEMPLATE_IDS, T as DecideEdgeCaseOutputSchema, Tt as attachmentsFolder, U as GetStoryInputSchema, V as GetProjectStatusInputSchema, W as GetStoryOutputSchema, X as MarkNotApplicableOutputSchema, Y as MarkNotApplicableInputSchema, Z as NotApplicableTopicSchema, _ as CheckPlanInputSchema, _t as UpdateStoryStatusInputSchema, a as AddAttachmentInputSchema, at as ResolveOpenQuestionOutputSchema, b as CreateCustomPhaseOutputSchema, bt as UpdateUserStoryOutputSchema, c as AddDecisionOutputSchema, ct as StoryLogEntrySchema, d as AddStoryLogInputSchema, dt as StoryVerificationSchema, et as PrdSummarySchema, 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, kt as assertSafeRelativePath, l as AddGlossaryTermInputSchema, lt as StoryPrioritySchema, m as AddUserStoryOutputSchema, mt as UpdatePhaseInputSchema, n as implementStoryPrompt, nt as RemoveAttachmentOutputSchema, o as AddAttachmentOutputSchema, ot as StoryAttachmentSchema, p as AddUserStoryInputSchema, pt as UpdateAttachmentOutputSchema, q as ListTemplatesInputSchema, r as reviewStoryPrompt, rt as ReorderPhasesInputSchema, s as AddDecisionInputSchema, st as StoryComplexitySchema, t as architectPrdPrompt, tt as RemoveAttachmentInputSchema, u as AddGlossaryTermOutputSchema, ut as StoryStatusSchema, v as CheckPlanOutputSchema, vt as UpdateStoryStatusOutputSchema, w as DecideEdgeCaseInputSchema, wt as attachmentProjectPath, x as CreatePrdInputSchema, xt as PRD_TEMPLATES, y as CreateCustomPhaseInputSchema, yt as UpdateUserStoryInputSchema, z as GetPrdInputSchema } from "./prompts-B0VejF7q.mjs";
2
2
  import { join } from "node:path";
3
- //#region src/safe-file-name.ts
4
- /**
5
- * Accept only a bare file name. Anything that could escape the intended
6
- * directory (path separators, parent references, hidden files) is rejected
7
- * before the filesystem is touched.
8
- */
9
- function assertSafeFileName(value, label = "file name") {
10
- const name = value.trim();
11
- if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
12
- return name;
13
- }
14
- /**
15
- * Accept only a relative path that stays inside the directory it is joined
16
- * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
17
- * This is a check on the text only; code that serves the file must still
18
- * resolve symlinks before reading it.
19
- */
20
- function assertSafeRelativePath(value, label = "path") {
21
- const path = value.trim();
22
- const segments = path.split("/");
23
- if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
24
- return path;
25
- }
26
- //#endregion
27
- //#region src/attachment-paths.ts
28
- /**
29
- * The folder for a PRD's files, relative to `.prds`: the PRD file name
30
- * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
31
- */
32
- function attachmentsFolder(filename) {
33
- return filename.replace(/\.json$/, "");
34
- }
35
- /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
36
- function attachmentProjectPath(filename, path) {
37
- return `.prds/${attachmentsFolder(filename)}/${path}`;
38
- }
39
- /** Attachments as an agent needs them: file paths from the project root. */
40
- function resolveAttachments(filename, attachments) {
41
- return attachments.map(({ path, ...attachment }) => ({
42
- ...attachment,
43
- ...path ? { path: attachmentProjectPath(filename, path) } : {}
44
- }));
45
- }
46
- /**
47
- * Attachments as stored, with hand-edited entries that would break readers
48
- * or point outside the PRD folder dropped: each needs a string id and title
49
- * and either a safe relative path or an http(s) url.
50
- */
51
- function normalizeAttachments(value) {
52
- if (!Array.isArray(value)) return [];
53
- return value.flatMap((entry) => {
54
- if (typeof entry !== "object" || entry === null) return [];
55
- const { id, title, path, url, note } = entry;
56
- if (typeof id !== "string" || typeof title !== "string") return [];
57
- const base = {
58
- id,
59
- title,
60
- ...typeof note === "string" && note ? { note } : {}
61
- };
62
- if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
63
- ...base,
64
- path
65
- }];
66
- if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
67
- ...base,
68
- url
69
- }];
70
- return [];
71
- });
72
- }
73
- function isSafePath(path) {
74
- try {
75
- return assertSafeRelativePath(path) === path;
76
- } catch {
77
- return false;
78
- }
79
- }
80
- //#endregion
81
3
  //#region src/edge-cases.ts
82
4
  /**
83
5
  * Edge cases as stored, with hand-edited entries that would break readers
@@ -544,66 +466,6 @@ function setNotApplicable(prd, input, today) {
544
466
  };
545
467
  }
546
468
  //#endregion
547
- //#region src/open-questions.ts
548
- /**
549
- * Open questions as stored. Older files hold plain strings; they become
550
- * questions with ids in list order. Entries without question text are dropped.
551
- */
552
- function normalizeOpenQuestions(value) {
553
- if (!Array.isArray(value)) return [];
554
- const questions = [];
555
- for (const entry of value) {
556
- if (typeof entry === "string") {
557
- if (entry.trim()) questions.push({
558
- id: "",
559
- question: entry
560
- });
561
- continue;
562
- }
563
- if (typeof entry !== "object" || entry === null) continue;
564
- const { id, question, why, options, recommended, storyIds } = entry;
565
- if (typeof question !== "string" || !question.trim()) continue;
566
- const strings = (list) => Array.isArray(list) ? list.filter((item) => typeof item === "string" && item.length > 0) : [];
567
- questions.push({
568
- id: typeof id === "string" ? id : "",
569
- question,
570
- ...typeof why === "string" && why ? { why } : {},
571
- ...strings(options).length ? { options: strings(options) } : {},
572
- ...typeof recommended === "string" && recommended ? { recommended } : {},
573
- ...strings(storyIds).length ? { storyIds: strings(storyIds) } : {}
574
- });
575
- }
576
- let highest = questions.reduce((max, question) => {
577
- const match = /^Q(\d+)$/.exec(question.id);
578
- return match ? Math.max(max, Number(match[1])) : max;
579
- }, 0);
580
- return questions.map((question) => question.id ? question : {
581
- ...question,
582
- id: formatQuestionId(++highest)
583
- });
584
- }
585
- function formatQuestionId(number) {
586
- return `Q${String(number).padStart(3, "0")}`;
587
- }
588
- /**
589
- * The next question id. Answered questions are quoted in decisions, so an id
590
- * is never handed out twice: the high-water mark is kept in metadata.
591
- */
592
- function nextQuestionId(prd, extra = []) {
593
- const present = [...prd.openQuestions, ...extra].reduce((max, question) => {
594
- const match = /^Q(\d+)$/.exec(question.id);
595
- return match ? Math.max(max, Number(match[1])) : max;
596
- }, 0);
597
- const next = Math.max(prd.metadata.lastQuestionNumber ?? 0, present) + 1;
598
- prd.metadata.lastQuestionNumber = next;
599
- return formatQuestionId(next);
600
- }
601
- /** Open questions that block a story that is not completed yet. */
602
- function blockingQuestions(prd) {
603
- const unfinished = new Set(prd.userStories.filter((story) => story.status !== "completed").map((story) => story.id));
604
- return prd.openQuestions.filter((question) => question.storyIds?.some((id) => unfinished.has(id)));
605
- }
606
- //#endregion
607
469
  //#region src/attachments.ts
608
470
  /**
609
471
  * Adds an attachment and links it to the given stories. The caller checks
@@ -816,6 +678,66 @@ function bullets(items, emptyLabel) {
816
678
  return items.map((item) => `- ${item}`);
817
679
  }
818
680
  //#endregion
681
+ //#region src/open-questions.ts
682
+ /**
683
+ * Open questions as stored. Older files hold plain strings; they become
684
+ * questions with ids in list order. Entries without question text are dropped.
685
+ */
686
+ function normalizeOpenQuestions(value) {
687
+ if (!Array.isArray(value)) return [];
688
+ const questions = [];
689
+ for (const entry of value) {
690
+ if (typeof entry === "string") {
691
+ if (entry.trim()) questions.push({
692
+ id: "",
693
+ question: entry
694
+ });
695
+ continue;
696
+ }
697
+ if (typeof entry !== "object" || entry === null) continue;
698
+ const { id, question, why, options, recommended, storyIds } = entry;
699
+ if (typeof question !== "string" || !question.trim()) continue;
700
+ const strings = (list) => Array.isArray(list) ? list.filter((item) => typeof item === "string" && item.length > 0) : [];
701
+ questions.push({
702
+ id: typeof id === "string" ? id : "",
703
+ question,
704
+ ...typeof why === "string" && why ? { why } : {},
705
+ ...strings(options).length ? { options: strings(options) } : {},
706
+ ...typeof recommended === "string" && recommended ? { recommended } : {},
707
+ ...strings(storyIds).length ? { storyIds: strings(storyIds) } : {}
708
+ });
709
+ }
710
+ let highest = questions.reduce((max, question) => {
711
+ const match = /^Q(\d+)$/.exec(question.id);
712
+ return match ? Math.max(max, Number(match[1])) : max;
713
+ }, 0);
714
+ return questions.map((question) => question.id ? question : {
715
+ ...question,
716
+ id: formatQuestionId(++highest)
717
+ });
718
+ }
719
+ function formatQuestionId(number) {
720
+ return `Q${String(number).padStart(3, "0")}`;
721
+ }
722
+ /**
723
+ * The next question id. Answered questions are quoted in decisions, so an id
724
+ * is never handed out twice: the high-water mark is kept in metadata.
725
+ */
726
+ function nextQuestionId(prd, extra = []) {
727
+ const present = [...prd.openQuestions, ...extra].reduce((max, question) => {
728
+ const match = /^Q(\d+)$/.exec(question.id);
729
+ return match ? Math.max(max, Number(match[1])) : max;
730
+ }, 0);
731
+ const next = Math.max(prd.metadata.lastQuestionNumber ?? 0, present) + 1;
732
+ prd.metadata.lastQuestionNumber = next;
733
+ return formatQuestionId(next);
734
+ }
735
+ /** Open questions that block a story that is not completed yet. */
736
+ function blockingQuestions(prd) {
737
+ const unfinished = new Set(prd.userStories.filter((story) => story.status !== "completed").map((story) => story.id));
738
+ return prd.openQuestions.filter((question) => question.storyIds?.some((id) => unfinished.has(id)));
739
+ }
740
+ //#endregion
819
741
  //#region src/plan-check.ts
820
742
  /** The not-applicable topic each "missing" check is about. */
821
743
  const CHECK_TOPICS = {
@@ -1508,7 +1430,8 @@ var PrdService = class {
1508
1430
  id: template.id,
1509
1431
  name: template.name,
1510
1432
  description: template.description,
1511
- when_to_use: template.whenToUse
1433
+ when_to_use: template.whenToUse,
1434
+ interview_focus: template.interviewFocus
1512
1435
  })) };
1513
1436
  }
1514
1437
  async checkPlan(filename) {
@@ -1788,4 +1711,4 @@ function assessComplexity(criteria) {
1788
1711
  return "XL";
1789
1712
  }
1790
1713
  //#endregion
1791
- export { AddAttachmentInputSchema, AddAttachmentOutputSchema, AddDecisionInputSchema, AddDecisionOutputSchema, AddGlossaryTermInputSchema, AddGlossaryTermOutputSchema, AddStoryLogInputSchema, AddStoryLogOutputSchema, AddUserStoryInputSchema, AddUserStoryOutputSchema, AssignStoryToPhaseInputSchema, AssignStoryToPhaseOutputSchema, CheckPlanInputSchema, CheckPlanOutputSchema, CreateCustomPhaseInputSchema, CreateCustomPhaseOutputSchema, CreatePrdInputSchema, CreatePrdOutputSchema, CustomPhaseSchema, DecideEdgeCaseInputSchema, DecideEdgeCaseOutputSchema, DeletePhaseInputSchema, DeletePrdInputSchema, DeletePrdOutputSchema, DeleteUserStoryInputSchema, DeleteUserStoryOutputSchema, ExportPrdMarkdownInputSchema, ExportPrdMarkdownOutputSchema, GetImplementationPromptsInputSchema, GetImplementationPromptsOutputSchema, GetImprovementSuggestionsInputSchema, GetImprovementSuggestionsOutputSchema, GetNextStoryInputSchema, GetNextStoryOutputSchema, GetPrdInputSchema, GetPrdOutputSchema, GetProjectStatusInputSchema, GetProjectStatusOutputSchema, GetStoryInputSchema, GetStoryOutputSchema, ListPrdsInputSchema, ListPrdsOutputSchema, ListTemplatesInputSchema, ListTemplatesOutputSchema, MarkNotApplicableInputSchema, MarkNotApplicableOutputSchema, NOT_APPLICABLE_TOPICS, NotApplicableTopicSchema, PRD_TEMPLATES, PhasesOutputSchema, PrdRevisionConflictError, PrdSectionValueSchemas, PrdService, PrdSummarySchema, RemoveAttachmentInputSchema, RemoveAttachmentOutputSchema, ReorderPhasesInputSchema, ResolveOpenQuestionInputSchema, ResolveOpenQuestionOutputSchema, StoryAttachmentSchema, StoryComplexitySchema, StoryLogEntrySchema, StoryPrioritySchema, StoryStatusSchema, StoryVerificationSchema, TEMPLATE_IDS, UpdateAttachmentInputSchema, UpdateAttachmentOutputSchema, UpdatePhaseInputSchema, UpdatePrdSectionInputSchema, UpdatePrdSectionOutputSchema, UpdateStoryStatusInputSchema, UpdateStoryStatusOutputSchema, UpdateUserStoryInputSchema, UpdateUserStoryOutputSchema, appendChangeLog, appendStoryLog, assertCanEnterStatus, assignStoryToPhase, attachmentProjectPath, attachmentsFolder, buildStoryContext, checkPlan, createPhase, createPrdService, deleteStory, findAttachment, findStory, formatPrdMarkdown, getTemplate, implementStoryPrompt, incompleteDependencies, isNotApplicable, nextId, nextStoryId, normalizePrd, pickNextStory, recomputeProgress, renderUserStory, resolveAttachments, reviewStoryPrompt, shapePrdPrompt, splitUserStory, updateStory, validateAttachmentIds, validateDependencies };
1714
+ export { AddAttachmentInputSchema, AddAttachmentOutputSchema, AddDecisionInputSchema, AddDecisionOutputSchema, AddGlossaryTermInputSchema, AddGlossaryTermOutputSchema, AddStoryLogInputSchema, AddStoryLogOutputSchema, AddUserStoryInputSchema, AddUserStoryOutputSchema, AssignStoryToPhaseInputSchema, AssignStoryToPhaseOutputSchema, CheckPlanInputSchema, CheckPlanOutputSchema, CreateCustomPhaseInputSchema, CreateCustomPhaseOutputSchema, CreatePrdInputSchema, CreatePrdOutputSchema, CustomPhaseSchema, DecideEdgeCaseInputSchema, DecideEdgeCaseOutputSchema, DeletePhaseInputSchema, DeletePrdInputSchema, DeletePrdOutputSchema, DeleteUserStoryInputSchema, DeleteUserStoryOutputSchema, ExportPrdMarkdownInputSchema, ExportPrdMarkdownOutputSchema, GetImplementationPromptsInputSchema, GetImplementationPromptsOutputSchema, GetImprovementSuggestionsInputSchema, GetImprovementSuggestionsOutputSchema, GetNextStoryInputSchema, GetNextStoryOutputSchema, GetPrdInputSchema, GetPrdOutputSchema, GetProjectStatusInputSchema, GetProjectStatusOutputSchema, GetStoryInputSchema, GetStoryOutputSchema, ListPrdsInputSchema, ListPrdsOutputSchema, ListTemplatesInputSchema, ListTemplatesOutputSchema, MarkNotApplicableInputSchema, MarkNotApplicableOutputSchema, NOT_APPLICABLE_TOPICS, NotApplicableTopicSchema, PRD_TEMPLATES, PhasesOutputSchema, PrdRevisionConflictError, PrdSectionValueSchemas, PrdService, PrdSummarySchema, RemoveAttachmentInputSchema, RemoveAttachmentOutputSchema, ReorderPhasesInputSchema, ResolveOpenQuestionInputSchema, ResolveOpenQuestionOutputSchema, StoryAttachmentSchema, StoryComplexitySchema, StoryLogEntrySchema, StoryPrioritySchema, StoryStatusSchema, StoryVerificationSchema, TEMPLATE_IDS, UpdateAttachmentInputSchema, UpdateAttachmentOutputSchema, UpdatePhaseInputSchema, UpdatePrdSectionInputSchema, UpdatePrdSectionOutputSchema, UpdateStoryStatusInputSchema, UpdateStoryStatusOutputSchema, UpdateUserStoryInputSchema, UpdateUserStoryOutputSchema, appendChangeLog, appendStoryLog, architectPrdPrompt, assertCanEnterStatus, assignStoryToPhase, attachmentProjectPath, attachmentsFolder, buildStoryContext, checkPlan, createPhase, createPrdService, deleteStory, findAttachment, findStory, formatPrdMarkdown, getTemplate, implementStoryPrompt, incompleteDependencies, isNotApplicable, nextId, nextStoryId, normalizePrd, pickNextStory, recomputeProgress, renderUserStory, resolveAttachments, reviewStoryPrompt, shapePrdPrompt, splitUserStory, updateStory, validateAttachmentIds, validateDependencies };
package/mcp.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { r as PrdService } from "./prd.service-DSBp8sMl.js";
1
+ import { r as PrdService } from "./prd.service-x5EpOoMv.js";
2
2
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3
3
  //#region src/mcp/index.d.ts
4
4
  /**
package/mcp.js CHANGED
@@ -1,5 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_prompts = require("./prompts-CIX8IeAx.js");
2
+ const require_prompts = require("./prompts-DJQ4FQ11.js");
3
3
  let zod_v3 = require("zod/v3");
4
4
  //#region src/mcp/tool-response.ts
5
5
  /**
@@ -122,7 +122,7 @@ function registerPRDTools(server, service) {
122
122
  });
123
123
  server.registerTool("add_user_story", {
124
124
  title: "Add a user story",
125
- description: "Append a user story with acceptance criteria to a PRD.",
125
+ description: "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.",
126
126
  inputSchema: require_prompts.AddUserStoryInputSchema,
127
127
  outputSchema: require_prompts.AddUserStoryOutputSchema,
128
128
  annotations: MUTATING_TOOL
@@ -487,15 +487,25 @@ function registerPRDTools(server, service) {
487
487
  title: "Shape a PRD",
488
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.",
489
489
  argsSchema: {
490
- idea: zod_v3.z.string().optional().describe("What to build, in a sentence or two"),
491
- filename: zod_v3.z.string().optional().describe("Existing PRD to keep shaping, inside .prds"),
492
- template: zod_v3.z.enum(require_prompts.TEMPLATE_IDS).optional().describe("Kind of work, see list_templates")
490
+ 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")
493
492
  }
494
- }, ({ idea, filename, template }) => ({ messages: [{
493
+ }, ({ overview, filename }) => ({ messages: [{
495
494
  role: "user",
496
495
  content: {
497
496
  type: "text",
498
- text: require_prompts.shapePrdPrompt(idea, filename, template)
497
+ text: require_prompts.shapePrdPrompt(overview, filename)
498
+ }
499
+ }] }));
500
+ server.registerPrompt("architect_prd", {
501
+ title: "Architect a PRD",
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") }
504
+ }, ({ filename }) => ({ messages: [{
505
+ role: "user",
506
+ content: {
507
+ type: "text",
508
+ text: require_prompts.architectPrdPrompt(filename)
499
509
  }
500
510
  }] }));
501
511
  server.registerPrompt("review_story", {
package/mcp.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { A as ExportPrdMarkdownInputSchema, B as GetProjectStatusInputSchema, C as DecideEdgeCaseInputSchema, D as DeletePrdOutputSchema, E as DeletePrdInputSchema, F as GetImprovementSuggestionsOutputSchema, G as ListPrdsOutputSchema, H as GetStoryInputSchema, I as GetNextStoryInputSchema, J as MarkNotApplicableInputSchema, K as ListTemplatesInputSchema, L as GetNextStoryOutputSchema, M as GetImplementationPromptsInputSchema, N as GetImplementationPromptsOutputSchema, O as DeleteUserStoryInputSchema, P as GetImprovementSuggestionsInputSchema, R as GetPrdInputSchema, T as DeletePhaseInputSchema, U as GetStoryOutputSchema, V as GetProjectStatusOutputSchema, W as ListPrdsInputSchema, Y as MarkNotApplicableOutputSchema, Z as PhasesOutputSchema, _ as CheckPlanOutputSchema, _t as UpdateStoryStatusOutputSchema, a as AddAttachmentOutputSchema, b as CreatePrdInputSchema, c as AddGlossaryTermInputSchema, d as AddStoryLogOutputSchema, dt as UpdateAttachmentInputSchema, et as RemoveAttachmentInputSchema, f as AddUserStoryInputSchema, ft as UpdateAttachmentOutputSchema, g as CheckPlanInputSchema, gt as UpdateStoryStatusInputSchema, h as AssignStoryToPhaseOutputSchema, ht as UpdatePrdSectionOutputSchema, i as AddAttachmentInputSchema, it as ResolveOpenQuestionOutputSchema, j as ExportPrdMarkdownOutputSchema, k as DeleteUserStoryOutputSchema, l as AddGlossaryTermOutputSchema, m as AssignStoryToPhaseInputSchema, mt as UpdatePrdSectionInputSchema, n as reviewStoryPrompt, nt as ReorderPhasesInputSchema, o as AddDecisionInputSchema, p as AddUserStoryOutputSchema, pt as UpdatePhaseInputSchema, q as ListTemplatesOutputSchema, r as shapePrdPrompt, rt as ResolveOpenQuestionInputSchema, s as AddDecisionOutputSchema, t as implementStoryPrompt, tt as RemoveAttachmentOutputSchema, u as AddStoryLogInputSchema, v as CreateCustomPhaseInputSchema, vt as UpdateUserStoryInputSchema, w as DecideEdgeCaseOutputSchema, x as CreatePrdOutputSchema, xt as TEMPLATE_IDS, y as CreateCustomPhaseOutputSchema, yt as UpdateUserStoryOutputSchema, z as GetPrdOutputSchema } from "./prompts-Bber0S1Z.mjs";
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";
2
2
  import { z } from "zod/v3";
3
3
  //#region src/mcp/tool-response.ts
4
4
  /**
@@ -121,7 +121,7 @@ function registerPRDTools(server, service) {
121
121
  });
122
122
  server.registerTool("add_user_story", {
123
123
  title: "Add a user story",
124
- description: "Append a user story with acceptance criteria to a PRD.",
124
+ description: "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.",
125
125
  inputSchema: AddUserStoryInputSchema,
126
126
  outputSchema: AddUserStoryOutputSchema,
127
127
  annotations: MUTATING_TOOL
@@ -486,15 +486,25 @@ function registerPRDTools(server, service) {
486
486
  title: "Shape a PRD",
487
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.",
488
488
  argsSchema: {
489
- idea: z.string().optional().describe("What to build, in a sentence or two"),
490
- filename: z.string().optional().describe("Existing PRD to keep shaping, inside .prds"),
491
- template: z.enum(TEMPLATE_IDS).optional().describe("Kind of work, see list_templates")
489
+ 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")
492
491
  }
493
- }, ({ idea, filename, template }) => ({ messages: [{
492
+ }, ({ overview, filename }) => ({ messages: [{
494
493
  role: "user",
495
494
  content: {
496
495
  type: "text",
497
- text: shapePrdPrompt(idea, filename, template)
496
+ text: shapePrdPrompt(overview, filename)
497
+ }
498
+ }] }));
499
+ server.registerPrompt("architect_prd", {
500
+ title: "Architect a PRD",
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") }
503
+ }, ({ filename }) => ({ messages: [{
504
+ role: "user",
505
+ content: {
506
+ type: "text",
507
+ text: architectPrdPrompt(filename)
498
508
  }
499
509
  }] }));
500
510
  server.registerPrompt("review_story", {
package/node.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { t as PrdDeps } from "./prd.service-DSBp8sMl.js";
1
+ import { t as PrdDeps } from "./prd.service-x5EpOoMv.js";
2
2
  //#region src/node.d.ts
3
3
  export interface NodePrdDepsOptions {
4
4
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@makerkit/prd",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "description": "Structured PRDs as JSON files: the format, a service to manage them, and MCP tools so coding agents can read and update them.",
5
5
  "keywords": [
6
6
  "ai-agents",
@@ -35,7 +35,7 @@
35
35
  }
36
36
  },
37
37
  "dependencies": {
38
- "@makerkit/repo-checks": "^0.0.1",
38
+ "@makerkit/repo-checks": "^0.0.2",
39
39
  "zod": "^3.25.0 || ^4.0.0"
40
40
  },
41
41
  "peerDependencies": {
@@ -2138,16 +2138,19 @@ declare const ListTemplatesOutputSchema: z.ZodObject<{
2138
2138
  name: z.ZodString;
2139
2139
  description: z.ZodString;
2140
2140
  when_to_use: z.ZodString;
2141
+ interview_focus: z.ZodArray<z.ZodString, "many">;
2141
2142
  }, "strip", z.ZodTypeAny, {
2142
2143
  name: string;
2143
2144
  description: string;
2144
2145
  id: string;
2145
2146
  when_to_use: string;
2147
+ interview_focus: string[];
2146
2148
  }, {
2147
2149
  name: string;
2148
2150
  description: string;
2149
2151
  id: string;
2150
2152
  when_to_use: string;
2153
+ interview_focus: string[];
2151
2154
  }>, "many">;
2152
2155
  }, "strip", z.ZodTypeAny, {
2153
2156
  templates: {
@@ -2155,6 +2158,7 @@ declare const ListTemplatesOutputSchema: z.ZodObject<{
2155
2158
  description: string;
2156
2159
  id: string;
2157
2160
  when_to_use: string;
2161
+ interview_focus: string[];
2158
2162
  }[];
2159
2163
  }, {
2160
2164
  templates: {
@@ -2162,6 +2166,7 @@ declare const ListTemplatesOutputSchema: z.ZodObject<{
2162
2166
  description: string;
2163
2167
  id: string;
2164
2168
  when_to_use: string;
2169
+ interview_focus: string[];
2165
2170
  }[];
2166
2171
  }>;
2167
2172
  type ListTemplatesOutput = z.infer<typeof ListTemplatesOutputSchema>;
@@ -1,4 +1,82 @@
1
1
  import { z } from "zod/v3";
2
+ //#region src/safe-file-name.ts
3
+ /**
4
+ * Accept only a bare file name. Anything that could escape the intended
5
+ * directory (path separators, parent references, hidden files) is rejected
6
+ * before the filesystem is touched.
7
+ */
8
+ function assertSafeFileName(value, label = "file name") {
9
+ const name = value.trim();
10
+ if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
11
+ return name;
12
+ }
13
+ /**
14
+ * Accept only a relative path that stays inside the directory it is joined
15
+ * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
16
+ * This is a check on the text only; code that serves the file must still
17
+ * resolve symlinks before reading it.
18
+ */
19
+ function assertSafeRelativePath(value, label = "path") {
20
+ const path = value.trim();
21
+ const segments = path.split("/");
22
+ if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
23
+ return path;
24
+ }
25
+ //#endregion
26
+ //#region src/attachment-paths.ts
27
+ /**
28
+ * The folder for a PRD's files, relative to `.prds`: the PRD file name
29
+ * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
30
+ */
31
+ function attachmentsFolder(filename) {
32
+ return filename.replace(/\.json$/, "");
33
+ }
34
+ /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
35
+ function attachmentProjectPath(filename, path) {
36
+ return `.prds/${attachmentsFolder(filename)}/${path}`;
37
+ }
38
+ /** Attachments as an agent needs them: file paths from the project root. */
39
+ function resolveAttachments(filename, attachments) {
40
+ return attachments.map(({ path, ...attachment }) => ({
41
+ ...attachment,
42
+ ...path ? { path: attachmentProjectPath(filename, path) } : {}
43
+ }));
44
+ }
45
+ /**
46
+ * Attachments as stored, with hand-edited entries that would break readers
47
+ * or point outside the PRD folder dropped: each needs a string id and title
48
+ * and either a safe relative path or an http(s) url.
49
+ */
50
+ function normalizeAttachments(value) {
51
+ if (!Array.isArray(value)) return [];
52
+ return value.flatMap((entry) => {
53
+ if (typeof entry !== "object" || entry === null) return [];
54
+ const { id, title, path, url, note } = entry;
55
+ if (typeof id !== "string" || typeof title !== "string") return [];
56
+ const base = {
57
+ id,
58
+ title,
59
+ ...typeof note === "string" && note ? { note } : {}
60
+ };
61
+ if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
62
+ ...base,
63
+ path
64
+ }];
65
+ if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
66
+ ...base,
67
+ url
68
+ }];
69
+ return [];
70
+ });
71
+ }
72
+ function isSafePath(path) {
73
+ try {
74
+ return assertSafeRelativePath(path) === path;
75
+ } catch {
76
+ return false;
77
+ }
78
+ }
79
+ //#endregion
2
80
  //#region src/templates.ts
3
81
  const TEMPLATE_IDS = [
4
82
  "saas-feature",
@@ -689,7 +767,8 @@ const ListTemplatesOutputSchema = z.object({ templates: z.array(z.object({
689
767
  id: z.string(),
690
768
  name: z.string(),
691
769
  description: z.string(),
692
- when_to_use: z.string()
770
+ when_to_use: z.string(),
771
+ interview_focus: z.array(z.string())
693
772
  })) });
694
773
  //#endregion
695
774
  //#region src/prompts.ts
@@ -697,10 +776,9 @@ const ListTemplatesOutputSchema = z.object({ templates: z.array(z.object({
697
776
  * The instructions behind the MCP prompts, exported so other tools (e.g. a
698
777
  * UI that shows what to ask the agent) give exactly the same text.
699
778
  */
700
- function shapePrdPrompt(idea, filename, templateId) {
701
- const template = templateId ? getTemplate(templateId) : null;
779
+ function shapePrdPrompt(overview, filename) {
702
780
  return [
703
- `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.` : idea ? `The idea: ${idea}` : "Start by asking what we are building, in a sentence or two."}`,
781
+ `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.` : overview ? `What the user wants to build:\n\n${overview}\n\nTreat this as the starting point: do not ask again what it already answers.` : "Start by asking the user to describe what they want to build, in their own words: what it is, who it is for and what it should do."}`,
704
782
  "",
705
783
  "How to run the interview:",
706
784
  "- Think of the plan as a tree of decisions. In each round, ask only the questions that can be answered now, i.e. whose prerequisites are already decided. Number them.",
@@ -711,7 +789,7 @@ function shapePrdPrompt(idea, filename, templateId) {
711
789
  "- After each round, record what was decided before asking the next round.",
712
790
  "- Stop when no undecided questions remain, and confirm with the user before slicing the work.",
713
791
  "",
714
- template ? `This is a "${template.name}" (${template.description}) Create the PRD with template "${template.id}", and make sure the interview covers: ${template.interviewFocus.join(" ")}` : "If you are unsure what kind of work this is, call list_templates and suggest one.",
792
+ "Pick the template yourself instead of asking the user: call list_templates, choose the one whose when_to_use fits what they described, pass it to create_prd and cover its interview_focus questions in the rounds. If none fits, create the PRD without one.",
715
793
  "",
716
794
  "Order of the rounds, broad to detailed:",
717
795
  "1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).",
@@ -728,11 +806,33 @@ function shapePrdPrompt(idea, filename, templateId) {
728
806
  "12. If a part genuinely does not apply (no outside services; no rollout plan for an internal tool), mark it with mark_not_applicable and a reason instead of leaving it empty. Never mark security or edge cases as not applicable for a feature that takes input from people or stores their data.",
729
807
  "",
730
808
  "Then slice the work:",
731
- "- Each story is a thin slice through every layer that a person can try once it is done, and that fits in one agent session. Put refactoring needed by later stories in its own earlier story.",
809
+ "- Each story is one commit: a small, self-contained change that leaves the build passing and is tested, and that a reviewer can read in a few minutes. Aim for one behaviour per story, usually a handful of files and one or two test seams. A story does not have to be something a person can try on its own; the phase is.",
810
+ "- Size stories small. Split one that has more than three or four acceptance criteria, covers several screens, endpoints or roles, or needs \"and\" in its title. More small stories are better than a few broad ones. Still slice vertically where you can (one field end to end, not every field in one layer), and put refactoring needed by later stories in its own earlier story.",
811
+ "- But not smaller than one behaviour. A story must change what the system does in a way a test can check through a seam: \"a member can archive a project and it disappears from the list\", not \"add an archive button\". A button, field, route, migration or config change on its own is a task, not a story: fold it into the story whose behaviour needs it. Merge stories whose acceptance criteria only describe what is on the screen, or that cannot be tested without the next story.",
732
812
  "- Create the phases first (create_custom_phase), in the order they should be built. Each phase should end with something a person can try (a page in the app, an API call, a command); say what in its description.",
733
813
  "- Add each story with add_user_story in one call: testSeams (the public entry points the tests will exercise), dependencies (stories that must be completed first) and phaseId. Add designNotes when the story has a screen or states the PRD design guidance does not settle, and securityNotes for each way this story in particular could be abused (whose ids it accepts, what input it trusts, what it costs to repeat) with the defence. Do not repeat the PRD-wide guidance or considerations there.",
734
814
  "- When the user shares mockups, screenshots or reference docs, save each file in the PRD folder (.prds/<prd file name without .json>/) and record it with add_attachment, linking the stories that use it. Record links to outside docs with a url instead.",
735
- "- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase."
815
+ "- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase.",
816
+ "- When the breakdown is confirmed, tell the user the next step is the architect_prd prompt, which designs the shape all the stories share before any of them is built."
817
+ ].join("\n");
818
+ }
819
+ function architectPrdPrompt(filename) {
820
+ const designPath = attachmentProjectPath(filename, "architecture.md");
821
+ return [
822
+ `Design how the PRD "${filename}" gets built, before any story is coded: the data model, the modules and who owns which rule, the entry points and the test seams all stories share. Without it, each story's agent invents its own shape.`,
823
+ "",
824
+ "1. Call get_prd and check_plan. If check_plan returns a required item, an edge case is still open, or an open question blocks a story, stop: tell the user what is missing and that shape_prd continues from there. A design built around an undecided behaviour bakes in a guess.",
825
+ "2. If an \"Architecture\" attachment already exists, this is a redesign. Read it, and call get_story on the completed stories to read their logs. The same kind of deviation in two or more stories means the shape is wrong; one deviation is information. If the shape still holds, say so and stop.",
826
+ `3. Design. If the project provides an architect skill (for example /architect), run it now. Give it the PRD's content itself (stories, acceptance criteria, edge cases, data models, permissions, security considerations, integrations, decisions), not just the file name, and ${designPath} as the output path. Ask it to key the work and test seams by story id. For a redesign, also give it the previous design and the deviations found in step 2, and say it is a redesign. Otherwise design it yourself: learn how the nearest existing feature works end to end; sketch two structurally different designs (where state lives, who owns which rule), each starting from the code that will call it, then the data model, then the interfaces and the test seams per story; drop shapes with shallow interfaces, logic split across owners, or two ways to do one thing; choose one, and write it to ${designPath} with what was rejected and why. Do not write production code or migrations.`,
827
+ "",
828
+ "Then record the design in the PRD, where story agents will find it. get_story does not return technicalContracts.apis or architecture decisions, so the attachment is how the design reaches them:",
829
+ "4. add_attachment with title \"Architecture\", path \"architecture.md\", a note (\"The contract for the data model, modules and test seams; record departures as deviations\"), and storyIds for every story it covers. If the attachment already exists, use update_attachment instead.",
830
+ "5. update_prd_section, section \"technicalContracts\", value { apis, dataModels }. Only the keys given change, but each list replaces the previous one, so pass every item. apis: one line per action, route, endpoint or function. dataModels: refine the existing descriptions with the real tables or entities, keeping their plain-language wording.",
831
+ "6. add_decision with topic \"architecture\": the chosen shape in one sentence, with a rationale that names the rejected alternative and why it lost. For a redesign, set supersedes to the previous architecture decision. Add a separate decision for each other hard-to-reverse choice.",
832
+ "7. For each story, update_user_story with its testSeams, and with dependencies when the design reveals an order the slicing missed.",
833
+ "8. If several stories need shared groundwork (the core schema, a module skeleton), add it as its own story with add_user_story in the earliest phase, and make the stories that need it depend on it. For a redesign, add stories that move the built parts to the new shape.",
834
+ "9. Open questions the design raised go to update_prd_section \"openQuestions\" with the stories they block (keep the ids of existing questions; the list replaces the previous one), or ask the user now and record the answer with add_decision. Never leave a question only in the design file: get_story and check_plan do not read it.",
835
+ "10. Do not change story statuses. Report the chosen shape, the rejected alternative, the decisions recorded, any new stories, and that implement_story is the next step."
736
836
  ].join("\n");
737
837
  }
738
838
  function reviewStoryPrompt(filename, storyId, base) {
@@ -763,7 +863,7 @@ function implementStoryPrompt(filename, storyId) {
763
863
  return [
764
864
  `You are implementing a story from the PRD "${filename}". ${storyId ? `Work on story ${storyId}.` : "Call get_next_story. If a story is already in progress (for example one sent back from review), finish that one first; otherwise take the story it returns. If none is ready, report why and stop."}`,
765
865
  "",
766
- "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. Build only what this story asks for.",
866
+ "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. An \"Architecture\" attachment is the contract for the data model, modules and test seams: build against it, and list every departure from it in deviations. Build only what this story asks for.",
767
867
  " Its edge_cases are part of the spec: implement and test each decided case as stated. If a case is still open, ask the user what should happen before building that part; never pick a behaviour yourself. Follow the design guidance, design decisions and the story's own design.story_notes for anything a person sees.",
768
868
  " If open_questions lists questions that block this story, ask the user, record the answer with resolve_open_question, and only then build the part it affects.",
769
869
  " The security rules are binding, including the story's own security.story_notes: enforce the permissions on the server for every read and write, never trust input from the browser, and keep secrets out of the client and logs. Before finishing, attack your own change: try another user's ids, a lower role, hostile input and repeated requests, and add tests for what you find. Parts listed in not_applicable do not apply: do not build them.",
@@ -775,4 +875,4 @@ function implementStoryPrompt(filename, storyId) {
775
875
  ].join("\n");
776
876
  }
777
877
  //#endregion
778
- export { PrdSummarySchema as $, ExportPrdMarkdownInputSchema as A, GetProjectStatusInputSchema as B, DecideEdgeCaseInputSchema as C, DeletePrdOutputSchema as D, DeletePrdInputSchema as E, GetImprovementSuggestionsOutputSchema as F, ListPrdsOutputSchema as G, GetStoryInputSchema as H, GetNextStoryInputSchema as I, MarkNotApplicableInputSchema as J, ListTemplatesInputSchema as K, GetNextStoryOutputSchema as L, GetImplementationPromptsInputSchema as M, GetImplementationPromptsOutputSchema as N, DeleteUserStoryInputSchema as O, GetImprovementSuggestionsInputSchema as P, PrdSectionValueSchemas as Q, GetPrdInputSchema as R, CustomPhaseSchema as S, getTemplate as St, DeletePhaseInputSchema as T, GetStoryOutputSchema as U, GetProjectStatusOutputSchema as V, ListPrdsInputSchema as W, NotApplicableTopicSchema as X, MarkNotApplicableOutputSchema as Y, PhasesOutputSchema as Z, CheckPlanOutputSchema as _, UpdateStoryStatusOutputSchema as _t, AddAttachmentOutputSchema as a, StoryAttachmentSchema as at, CreatePrdInputSchema as b, PRD_TEMPLATES as bt, AddGlossaryTermInputSchema as c, StoryPrioritySchema as ct, AddStoryLogOutputSchema as d, UpdateAttachmentInputSchema as dt, RemoveAttachmentInputSchema as et, AddUserStoryInputSchema as f, UpdateAttachmentOutputSchema as ft, CheckPlanInputSchema as g, UpdateStoryStatusInputSchema as gt, AssignStoryToPhaseOutputSchema as h, UpdatePrdSectionOutputSchema as ht, AddAttachmentInputSchema as i, ResolveOpenQuestionOutputSchema as it, ExportPrdMarkdownOutputSchema as j, DeleteUserStoryOutputSchema as k, AddGlossaryTermOutputSchema as l, StoryStatusSchema as lt, AssignStoryToPhaseInputSchema as m, UpdatePrdSectionInputSchema as mt, reviewStoryPrompt as n, ReorderPhasesInputSchema as nt, AddDecisionInputSchema as o, StoryComplexitySchema as ot, AddUserStoryOutputSchema as p, UpdatePhaseInputSchema as pt, ListTemplatesOutputSchema as q, shapePrdPrompt as r, ResolveOpenQuestionInputSchema as rt, AddDecisionOutputSchema as s, StoryLogEntrySchema as st, implementStoryPrompt as t, RemoveAttachmentOutputSchema as tt, AddStoryLogInputSchema as u, StoryVerificationSchema as ut, CreateCustomPhaseInputSchema as v, UpdateUserStoryInputSchema as vt, DecideEdgeCaseOutputSchema as w, CreatePrdOutputSchema as x, TEMPLATE_IDS as xt, CreateCustomPhaseOutputSchema as y, UpdateUserStoryOutputSchema as yt, GetPrdOutputSchema as z };
878
+ export { PrdSectionValueSchemas as $, DeleteUserStoryOutputSchema as A, GetPrdOutputSchema as B, CustomPhaseSchema as C, getTemplate as Ct, DeletePrdInputSchema as D, resolveAttachments as Dt, DeletePhaseInputSchema as E, normalizeAttachments as Et, GetImprovementSuggestionsInputSchema as F, ListPrdsInputSchema as G, GetProjectStatusOutputSchema as H, GetImprovementSuggestionsOutputSchema as I, ListTemplatesOutputSchema as J, ListPrdsOutputSchema as K, GetNextStoryInputSchema as L, ExportPrdMarkdownOutputSchema as M, GetImplementationPromptsInputSchema as N, DeletePrdOutputSchema as O, assertSafeFileName as Ot, GetImplementationPromptsOutputSchema as P, PhasesOutputSchema as Q, GetNextStoryOutputSchema as R, CreatePrdOutputSchema as S, TEMPLATE_IDS as St, DecideEdgeCaseOutputSchema as T, attachmentsFolder as Tt, GetStoryInputSchema as U, GetProjectStatusInputSchema as V, GetStoryOutputSchema as W, MarkNotApplicableOutputSchema as X, MarkNotApplicableInputSchema as Y, NotApplicableTopicSchema as Z, CheckPlanInputSchema as _, UpdateStoryStatusInputSchema as _t, AddAttachmentInputSchema as a, ResolveOpenQuestionOutputSchema as at, CreateCustomPhaseOutputSchema as b, UpdateUserStoryOutputSchema as bt, AddDecisionOutputSchema as c, StoryLogEntrySchema as ct, AddStoryLogInputSchema as d, StoryVerificationSchema as dt, PrdSummarySchema as et, AddStoryLogOutputSchema as f, UpdateAttachmentInputSchema as ft, AssignStoryToPhaseOutputSchema as g, UpdatePrdSectionOutputSchema as gt, AssignStoryToPhaseInputSchema as h, UpdatePrdSectionInputSchema as ht, shapePrdPrompt as i, ResolveOpenQuestionInputSchema as it, ExportPrdMarkdownInputSchema as j, DeleteUserStoryInputSchema as k, assertSafeRelativePath as kt, AddGlossaryTermInputSchema as l, StoryPrioritySchema as lt, AddUserStoryOutputSchema as m, UpdatePhaseInputSchema as mt, implementStoryPrompt as n, RemoveAttachmentOutputSchema as nt, AddAttachmentOutputSchema as o, StoryAttachmentSchema as ot, AddUserStoryInputSchema as p, UpdateAttachmentOutputSchema as pt, ListTemplatesInputSchema as q, reviewStoryPrompt as r, ReorderPhasesInputSchema as rt, AddDecisionInputSchema as s, StoryComplexitySchema as st, architectPrdPrompt as t, RemoveAttachmentInputSchema as tt, AddGlossaryTermOutputSchema as u, StoryStatusSchema as ut, CheckPlanOutputSchema as v, UpdateStoryStatusOutputSchema as vt, DecideEdgeCaseInputSchema as w, attachmentProjectPath as wt, CreatePrdInputSchema as x, PRD_TEMPLATES as xt, CreateCustomPhaseInputSchema as y, UpdateUserStoryInputSchema as yt, GetPrdInputSchema as z };
@@ -1,4 +1,82 @@
1
1
  let zod_v3 = require("zod/v3");
2
+ //#region src/safe-file-name.ts
3
+ /**
4
+ * Accept only a bare file name. Anything that could escape the intended
5
+ * directory (path separators, parent references, hidden files) is rejected
6
+ * before the filesystem is touched.
7
+ */
8
+ function assertSafeFileName(value, label = "file name") {
9
+ const name = value.trim();
10
+ if (name.length === 0 || name.includes("..") || name.includes("/") || name.includes("\\") || name.startsWith(".")) throw new Error(`Invalid ${label} "${value}"`);
11
+ return name;
12
+ }
13
+ /**
14
+ * Accept only a relative path that stays inside the directory it is joined
15
+ * to: no absolute paths, no `..`, no backslashes, no empty or hidden segments.
16
+ * This is a check on the text only; code that serves the file must still
17
+ * resolve symlinks before reading it.
18
+ */
19
+ function assertSafeRelativePath(value, label = "path") {
20
+ const path = value.trim();
21
+ const segments = path.split("/");
22
+ if (path.length === 0 || path.includes("\\") || /^[a-zA-Z]:/.test(path) || segments.some((segment) => segment.length === 0 || segment.startsWith("."))) throw new Error(`Invalid ${label} "${value}"`);
23
+ return path;
24
+ }
25
+ //#endregion
26
+ //#region src/attachment-paths.ts
27
+ /**
28
+ * The folder for a PRD's files, relative to `.prds`: the PRD file name
29
+ * without `.json`, so `notes.json` keeps its files in `.prds/notes/`.
30
+ */
31
+ function attachmentsFolder(filename) {
32
+ return filename.replace(/\.json$/, "");
33
+ }
34
+ /** An attachment's file relative to the project root, e.g. `.prds/notes/a.png`. */
35
+ function attachmentProjectPath(filename, path) {
36
+ return `.prds/${attachmentsFolder(filename)}/${path}`;
37
+ }
38
+ /** Attachments as an agent needs them: file paths from the project root. */
39
+ function resolveAttachments(filename, attachments) {
40
+ return attachments.map(({ path, ...attachment }) => ({
41
+ ...attachment,
42
+ ...path ? { path: attachmentProjectPath(filename, path) } : {}
43
+ }));
44
+ }
45
+ /**
46
+ * Attachments as stored, with hand-edited entries that would break readers
47
+ * or point outside the PRD folder dropped: each needs a string id and title
48
+ * and either a safe relative path or an http(s) url.
49
+ */
50
+ function normalizeAttachments(value) {
51
+ if (!Array.isArray(value)) return [];
52
+ return value.flatMap((entry) => {
53
+ if (typeof entry !== "object" || entry === null) return [];
54
+ const { id, title, path, url, note } = entry;
55
+ if (typeof id !== "string" || typeof title !== "string") return [];
56
+ const base = {
57
+ id,
58
+ title,
59
+ ...typeof note === "string" && note ? { note } : {}
60
+ };
61
+ if (typeof path === "string" && url === void 0 && isSafePath(path)) return [{
62
+ ...base,
63
+ path
64
+ }];
65
+ if (typeof url === "string" && path === void 0 && /^https?:\/\//i.test(url)) return [{
66
+ ...base,
67
+ url
68
+ }];
69
+ return [];
70
+ });
71
+ }
72
+ function isSafePath(path) {
73
+ try {
74
+ return assertSafeRelativePath(path) === path;
75
+ } catch {
76
+ return false;
77
+ }
78
+ }
79
+ //#endregion
2
80
  //#region src/templates.ts
3
81
  const TEMPLATE_IDS = [
4
82
  "saas-feature",
@@ -689,7 +767,8 @@ const ListTemplatesOutputSchema = zod_v3.z.object({ templates: zod_v3.z.array(zo
689
767
  id: zod_v3.z.string(),
690
768
  name: zod_v3.z.string(),
691
769
  description: zod_v3.z.string(),
692
- when_to_use: zod_v3.z.string()
770
+ when_to_use: zod_v3.z.string(),
771
+ interview_focus: zod_v3.z.array(zod_v3.z.string())
693
772
  })) });
694
773
  //#endregion
695
774
  //#region src/prompts.ts
@@ -697,10 +776,9 @@ const ListTemplatesOutputSchema = zod_v3.z.object({ templates: zod_v3.z.array(zo
697
776
  * The instructions behind the MCP prompts, exported so other tools (e.g. a
698
777
  * UI that shows what to ask the agent) give exactly the same text.
699
778
  */
700
- function shapePrdPrompt(idea, filename, templateId) {
701
- const template = templateId ? getTemplate(templateId) : null;
779
+ function shapePrdPrompt(overview, filename) {
702
780
  return [
703
- `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.` : idea ? `The idea: ${idea}` : "Start by asking what we are building, in a sentence or two."}`,
781
+ `We are shaping a product requirements document before any code is written. ${filename ? `Keep shaping the PRD "${filename}". Read it with get_prd first and continue from its open questions.` : overview ? `What the user wants to build:\n\n${overview}\n\nTreat this as the starting point: do not ask again what it already answers.` : "Start by asking the user to describe what they want to build, in their own words: what it is, who it is for and what it should do."}`,
704
782
  "",
705
783
  "How to run the interview:",
706
784
  "- Think of the plan as a tree of decisions. In each round, ask only the questions that can be answered now, i.e. whose prerequisites are already decided. Number them.",
@@ -711,7 +789,7 @@ function shapePrdPrompt(idea, filename, templateId) {
711
789
  "- After each round, record what was decided before asking the next round.",
712
790
  "- Stop when no undecided questions remain, and confirm with the user before slicing the work.",
713
791
  "",
714
- template ? `This is a "${template.name}" (${template.description}) Create the PRD with template "${template.id}", and make sure the interview covers: ${template.interviewFocus.join(" ")}` : "If you are unsure what kind of work this is, call list_templates and suggest one.",
792
+ "Pick the template yourself instead of asking the user: call list_templates, choose the one whose when_to_use fits what they described, pass it to create_prd and cover its interview_focus questions in the rounds. If none fits, create the PRD without one.",
715
793
  "",
716
794
  "Order of the rounds, broad to detailed:",
717
795
  "1. What we are building and for whom (create_prd once this is clear, if there is no PRD yet).",
@@ -728,11 +806,33 @@ function shapePrdPrompt(idea, filename, templateId) {
728
806
  "12. If a part genuinely does not apply (no outside services; no rollout plan for an internal tool), mark it with mark_not_applicable and a reason instead of leaving it empty. Never mark security or edge cases as not applicable for a feature that takes input from people or stores their data.",
729
807
  "",
730
808
  "Then slice the work:",
731
- "- Each story is a thin slice through every layer that a person can try once it is done, and that fits in one agent session. Put refactoring needed by later stories in its own earlier story.",
809
+ "- Each story is one commit: a small, self-contained change that leaves the build passing and is tested, and that a reviewer can read in a few minutes. Aim for one behaviour per story, usually a handful of files and one or two test seams. A story does not have to be something a person can try on its own; the phase is.",
810
+ "- Size stories small. Split one that has more than three or four acceptance criteria, covers several screens, endpoints or roles, or needs \"and\" in its title. More small stories are better than a few broad ones. Still slice vertically where you can (one field end to end, not every field in one layer), and put refactoring needed by later stories in its own earlier story.",
811
+ "- But not smaller than one behaviour. A story must change what the system does in a way a test can check through a seam: \"a member can archive a project and it disappears from the list\", not \"add an archive button\". A button, field, route, migration or config change on its own is a task, not a story: fold it into the story whose behaviour needs it. Merge stories whose acceptance criteria only describe what is on the screen, or that cannot be tested without the next story.",
732
812
  "- Create the phases first (create_custom_phase), in the order they should be built. Each phase should end with something a person can try (a page in the app, an API call, a command); say what in its description.",
733
813
  "- Add each story with add_user_story in one call: testSeams (the public entry points the tests will exercise), dependencies (stories that must be completed first) and phaseId. Add designNotes when the story has a screen or states the PRD design guidance does not settle, and securityNotes for each way this story in particular could be abused (whose ids it accepts, what input it trusts, what it costs to repeat) with the defence. Do not repeat the PRD-wide guidance or considerations there.",
734
814
  "- When the user shares mockups, screenshots or reference docs, save each file in the PRD folder (.prds/<prd file name without .json>/) and record it with add_attachment, linking the stories that use it. Record links to outside docs with a url instead.",
735
- "- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase."
815
+ "- Confirm the breakdown with the user, then fix anything with update_user_story or assign_story_to_phase.",
816
+ "- When the breakdown is confirmed, tell the user the next step is the architect_prd prompt, which designs the shape all the stories share before any of them is built."
817
+ ].join("\n");
818
+ }
819
+ function architectPrdPrompt(filename) {
820
+ const designPath = attachmentProjectPath(filename, "architecture.md");
821
+ return [
822
+ `Design how the PRD "${filename}" gets built, before any story is coded: the data model, the modules and who owns which rule, the entry points and the test seams all stories share. Without it, each story's agent invents its own shape.`,
823
+ "",
824
+ "1. Call get_prd and check_plan. If check_plan returns a required item, an edge case is still open, or an open question blocks a story, stop: tell the user what is missing and that shape_prd continues from there. A design built around an undecided behaviour bakes in a guess.",
825
+ "2. If an \"Architecture\" attachment already exists, this is a redesign. Read it, and call get_story on the completed stories to read their logs. The same kind of deviation in two or more stories means the shape is wrong; one deviation is information. If the shape still holds, say so and stop.",
826
+ `3. Design. If the project provides an architect skill (for example /architect), run it now. Give it the PRD's content itself (stories, acceptance criteria, edge cases, data models, permissions, security considerations, integrations, decisions), not just the file name, and ${designPath} as the output path. Ask it to key the work and test seams by story id. For a redesign, also give it the previous design and the deviations found in step 2, and say it is a redesign. Otherwise design it yourself: learn how the nearest existing feature works end to end; sketch two structurally different designs (where state lives, who owns which rule), each starting from the code that will call it, then the data model, then the interfaces and the test seams per story; drop shapes with shallow interfaces, logic split across owners, or two ways to do one thing; choose one, and write it to ${designPath} with what was rejected and why. Do not write production code or migrations.`,
827
+ "",
828
+ "Then record the design in the PRD, where story agents will find it. get_story does not return technicalContracts.apis or architecture decisions, so the attachment is how the design reaches them:",
829
+ "4. add_attachment with title \"Architecture\", path \"architecture.md\", a note (\"The contract for the data model, modules and test seams; record departures as deviations\"), and storyIds for every story it covers. If the attachment already exists, use update_attachment instead.",
830
+ "5. update_prd_section, section \"technicalContracts\", value { apis, dataModels }. Only the keys given change, but each list replaces the previous one, so pass every item. apis: one line per action, route, endpoint or function. dataModels: refine the existing descriptions with the real tables or entities, keeping their plain-language wording.",
831
+ "6. add_decision with topic \"architecture\": the chosen shape in one sentence, with a rationale that names the rejected alternative and why it lost. For a redesign, set supersedes to the previous architecture decision. Add a separate decision for each other hard-to-reverse choice.",
832
+ "7. For each story, update_user_story with its testSeams, and with dependencies when the design reveals an order the slicing missed.",
833
+ "8. If several stories need shared groundwork (the core schema, a module skeleton), add it as its own story with add_user_story in the earliest phase, and make the stories that need it depend on it. For a redesign, add stories that move the built parts to the new shape.",
834
+ "9. Open questions the design raised go to update_prd_section \"openQuestions\" with the stories they block (keep the ids of existing questions; the list replaces the previous one), or ask the user now and record the answer with add_decision. Never leave a question only in the design file: get_story and check_plan do not read it.",
835
+ "10. Do not change story statuses. Report the chosen shape, the rejected alternative, the decisions recorded, any new stories, and that implement_story is the next step."
736
836
  ].join("\n");
737
837
  }
738
838
  function reviewStoryPrompt(filename, storyId, base) {
@@ -763,7 +863,7 @@ function implementStoryPrompt(filename, storyId) {
763
863
  return [
764
864
  `You are implementing a story from the PRD "${filename}". ${storyId ? `Work on story ${storyId}.` : "Call get_next_story. If a story is already in progress (for example one sent back from review), finish that one first; otherwise take the story it returns. If none is ready, report why and stop."}`,
765
865
  "",
766
- "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. Build only what this story asks for.",
866
+ "1. Call get_story. If the story has notes, read them first: a story sent back from review carries the reviewer's feedback there, and addressing it comes before anything else. Read the acceptance criteria, the non-goals and out-of-scope items, and the logs of its dependencies and of the previous story. Open the files and links in its attachments (mockups, reference docs); they show what is meant, but the acceptance criteria decide what is done. An \"Architecture\" attachment is the contract for the data model, modules and test seams: build against it, and list every departure from it in deviations. Build only what this story asks for.",
767
867
  " Its edge_cases are part of the spec: implement and test each decided case as stated. If a case is still open, ask the user what should happen before building that part; never pick a behaviour yourself. Follow the design guidance, design decisions and the story's own design.story_notes for anything a person sees.",
768
868
  " If open_questions lists questions that block this story, ask the user, record the answer with resolve_open_question, and only then build the part it affects.",
769
869
  " The security rules are binding, including the story's own security.story_notes: enforce the permissions on the server for every read and write, never trust input from the browser, and keep secrets out of the client and logs. Before finishing, attack your own change: try another user's ids, a lower role, hostile input and repeated requests, and add tests for what you find. Parts listed in not_applicable do not apply: do not build them.",
@@ -1207,6 +1307,36 @@ Object.defineProperty(exports, "UpdateUserStoryOutputSchema", {
1207
1307
  return UpdateUserStoryOutputSchema;
1208
1308
  }
1209
1309
  });
1310
+ Object.defineProperty(exports, "architectPrdPrompt", {
1311
+ enumerable: true,
1312
+ get: function() {
1313
+ return architectPrdPrompt;
1314
+ }
1315
+ });
1316
+ Object.defineProperty(exports, "assertSafeFileName", {
1317
+ enumerable: true,
1318
+ get: function() {
1319
+ return assertSafeFileName;
1320
+ }
1321
+ });
1322
+ Object.defineProperty(exports, "assertSafeRelativePath", {
1323
+ enumerable: true,
1324
+ get: function() {
1325
+ return assertSafeRelativePath;
1326
+ }
1327
+ });
1328
+ Object.defineProperty(exports, "attachmentProjectPath", {
1329
+ enumerable: true,
1330
+ get: function() {
1331
+ return attachmentProjectPath;
1332
+ }
1333
+ });
1334
+ Object.defineProperty(exports, "attachmentsFolder", {
1335
+ enumerable: true,
1336
+ get: function() {
1337
+ return attachmentsFolder;
1338
+ }
1339
+ });
1210
1340
  Object.defineProperty(exports, "getTemplate", {
1211
1341
  enumerable: true,
1212
1342
  get: function() {
@@ -1219,6 +1349,18 @@ Object.defineProperty(exports, "implementStoryPrompt", {
1219
1349
  return implementStoryPrompt;
1220
1350
  }
1221
1351
  });
1352
+ Object.defineProperty(exports, "normalizeAttachments", {
1353
+ enumerable: true,
1354
+ get: function() {
1355
+ return normalizeAttachments;
1356
+ }
1357
+ });
1358
+ Object.defineProperty(exports, "resolveAttachments", {
1359
+ enumerable: true,
1360
+ get: function() {
1361
+ return resolveAttachments;
1362
+ }
1363
+ });
1222
1364
  Object.defineProperty(exports, "reviewStoryPrompt", {
1223
1365
  enumerable: true,
1224
1366
  get: function() {