feat: project-level prompts for metadata generation (#836)

* feat(server): project-level prompts for metadata generation

Add `metadataGeneration` config to `paseo.json` so projects can customize the
four LLM-generated metadata strings — agent title, worktree branch name, commit
message, and pull request title+body. Each entry takes an `instructions` string
that gets injected as a `<user-instructions>` block between the default rules
and the load-bearing JSON format contract, with wrapper text saying user
instructions override defaults. Missing/empty/invalid config keeps every prompt
byte-identical to today.

* refactor(server): centralize project metadata prompt building

Three near-identical readers and four gate-then-wrap blocks collapsed
into one buildMetadataPrompt helper. wrapWithUserInstructions tightened
to require a non-empty string; its misleading empty fallback is gone.

* feat(app): edit metadata generation prompts in project settings

Adds four textareas (agent title, branch name, commit message, pull
request) under project settings, modeled on the existing setup/teardown
pattern. Round-trips through paseo.json preserving unknown sibling
fields at both the metadataGeneration and entry level.

packages/server/src/utils/build-metadata-prompt.ts

@@ -0,0 +1,46 @@
+import { readPaseoConfigJson } from "./paseo-config-file.js";
+import { PaseoConfigSchema } from "./paseo-config-schema.js";
+import { wrapWithUserInstructions } from "./wrap-user-instructions.js";
+
+export type MetadataConfigKey = "agentTitle" | "branchName" | "commitMessage" | "pullRequest";
+
+export interface RepoRootResolver {
+  resolveRepoRoot: (cwd: string) => Promise<string>;
+}
+
+export interface BuildMetadataPromptOptions {
+  cwd: string;
+  configKey: MetadataConfigKey;
+  before: string;
+  after: string;
+  trailing?: string;
+  workspaceGitService?: RepoRootResolver;
+}
+
+export async function buildMetadataPrompt(options: BuildMetadataPromptOptions): Promise<string> {
+  const instructions = await readProjectMetadataInstructions(options);
+  const head = isNonEmptyString(instructions)
+    ? wrapWithUserInstructions(options.before, instructions, options.after)
+    : `${options.before}\n${options.after}`;
+  return options.trailing ? `${head}\n\n${options.trailing}` : head;
+}
+
+async function readProjectMetadataInstructions(
+  options: Pick<BuildMetadataPromptOptions, "cwd" | "configKey" | "workspaceGitService">,
+): Promise<string | undefined> {
+  if (!options.workspaceGitService) {
+    return undefined;
+  }
+  try {
+    const repoRoot = await options.workspaceGitService.resolveRepoRoot(options.cwd);
+    const json = readPaseoConfigJson(repoRoot);
+    const config = PaseoConfigSchema.parse(json);
+    return config.metadataGeneration?.[options.configKey]?.instructions;
+  } catch {
+    return undefined;
+  }
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}

packages/server/src/utils/paseo-config-schema.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from "vitest";
+import { PaseoConfigRawSchema, PaseoConfigSchema } from "./paseo-config-schema.js";
+
+describe("paseo config schema", () => {
+  it("parses an empty config without metadata generation", () => {
+    const parsed = PaseoConfigSchema.parse({});
+
+    expect(parsed).toEqual({});
+    expect(parsed.metadataGeneration).toBeUndefined();
+  });
+
+  it("parses old-style worktree and scripts config unchanged", () => {
+    const config = {
+      worktree: {
+        setup: "npm install",
+        teardown: ["npm run clean"],
+      },
+      scripts: {
+        dev: {
+          type: "service",
+          command: "npm run dev",
+          port: 5173,
+        },
+      },
+    };
+
+    expect(PaseoConfigSchema.parse(config)).toEqual({
+      worktree: {
+        setup: ["npm install"],
+        teardown: ["npm run clean"],
+      },
+      scripts: config.scripts,
+    });
+  });
+
+  it("parses all metadata generation instruction entries", () => {
+    expect(
+      PaseoConfigSchema.parse({
+        metadataGeneration: {
+          agentTitle: { instructions: "Use concise titles." },
+          branchName: { instructions: "Prefix branches with feat/." },
+          commitMessage: { instructions: "Use imperative mood." },
+          pullRequest: { instructions: "Include risk notes." },
+        },
+      }),
+    ).toEqual({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use concise titles." },
+        branchName: { instructions: "Prefix branches with feat/." },
+        commitMessage: { instructions: "Use imperative mood." },
+        pullRequest: { instructions: "Include risk notes." },
+      },
+    });
+  });
+
+  it("parses partial metadata generation instructions with missing entries undefined", () => {
+    const parsed = PaseoConfigSchema.parse({
+      metadataGeneration: {
+        agentTitle: { instructions: "Keep it short." },
+      },
+    });
+
+    expect(parsed.metadataGeneration).toEqual({
+      agentTitle: { instructions: "Keep it short." },
+    });
+    expect(parsed.metadataGeneration?.branchName).toBeUndefined();
+    expect(parsed.metadataGeneration?.commitMessage).toBeUndefined();
+    expect(parsed.metadataGeneration?.pullRequest).toBeUndefined();
+  });
+
+  it("passes through unknown metadata generation fields", () => {
+    expect(
+      PaseoConfigSchema.parse({
+        metadataGeneration: {
+          agentTitle: { instructions: "Use concise titles." },
+          futureField: 42,
+        },
+      }),
+    ).toEqual({
+      metadataGeneration: {
+        agentTitle: { instructions: "Use concise titles." },
+        futureField: 42,
+      },
+    });
+  });
+
+  it("passes through unknown metadata generator entry fields", () => {
+    expect(
+      PaseoConfigSchema.parse({
+        metadataGeneration: {
+          agentTitle: {
+            instructions: "Use concise titles.",
+            model: "haiku",
+          },
+        },
+      }),
+    ).toEqual({
+      metadataGeneration: {
+        agentTitle: {
+          instructions: "Use concise titles.",
+          model: "haiku",
+        },
+      },
+    });
+  });
+
+  it("falls back to an empty metadata generator entry when instructions has an invalid type", () => {
+    expect(
+      PaseoConfigSchema.parse({
+        metadataGeneration: {
+          agentTitle: { instructions: 42 },
+        },
+      }),
+    ).toEqual({
+      metadataGeneration: {
+        agentTitle: {},
+      },
+    });
+  });
+
+  it("raw schema preserves old-style config while accepting metadata generation", () => {
+    const config = {
+      worktree: {
+        setup: "npm install",
+        teardown: ["npm run clean"],
+      },
+      scripts: {
+        dev: {
+          type: "service",
+          command: "npm run dev",
+        },
+      },
+      metadataGeneration: {
+        agentTitle: { instructions: "Use concise titles." },
+      },
+    };
+
+    expect(PaseoConfigRawSchema.parse(config)).toEqual(config);
+  });
+
+  it("raw schema falls back to an empty metadata generator entry when instructions has an invalid type", () => {
+    expect(
+      PaseoConfigRawSchema.parse({
+        metadataGeneration: {
+          agentTitle: { instructions: 42 },
+        },
+      }),
+    ).toEqual({
+      metadataGeneration: {
+        agentTitle: {},
+      },
+    });
+  });
+});

packages/server/src/utils/paseo-config-schema.ts

@@ -30,10 +30,28 @@ export const PaseoWorktreeConfigRawSchema = z
   })
   .passthrough();
 
+export const PaseoMetadataGenerationEntrySchema = z
+  .object({
+    instructions: z.string().optional(),
+  })
+  .passthrough()
+  .catch({});
+
+export const PaseoMetadataGenerationSchema = z
+  .object({
+    agentTitle: PaseoMetadataGenerationEntrySchema.optional(),
+    branchName: PaseoMetadataGenerationEntrySchema.optional(),
+    commitMessage: PaseoMetadataGenerationEntrySchema.optional(),
+    pullRequest: PaseoMetadataGenerationEntrySchema.optional(),
+  })
+  .passthrough()
+  .catch({});
+
 export const PaseoConfigRawSchema = z
   .object({
     worktree: PaseoWorktreeConfigRawSchema.optional(),
     scripts: z.record(z.string(), PaseoScriptEntryRawSchema).optional(),
+    metadataGeneration: PaseoMetadataGenerationSchema.optional(),
   })
   .passthrough();
 
@@ -49,6 +67,7 @@ export const ScriptEntrySchema = PaseoScriptEntryRawSchema.catch({});
 export const PaseoConfigSchema = PaseoConfigRawSchema.extend({
   worktree: WorktreeConfigSchema.optional(),
   scripts: z.record(z.string(), ScriptEntrySchema).optional().catch({}),
+  metadataGeneration: PaseoMetadataGenerationSchema.optional(),
 })
   .passthrough()
   .catch({});
@@ -69,6 +88,8 @@ export const ProjectConfigRpcErrorSchema = z.discriminatedUnion("code", [
 ]);
 
 export type PaseoScriptEntryRaw = z.infer<typeof PaseoScriptEntryRawSchema>;
+export type PaseoMetadataGenerationEntry = z.infer<typeof PaseoMetadataGenerationEntrySchema>;
+export type PaseoMetadataGeneration = z.infer<typeof PaseoMetadataGenerationSchema>;
 export type PaseoConfigRaw = z.infer<typeof PaseoConfigRawSchema>;
 export type PaseoConfig = z.infer<typeof PaseoConfigSchema>;
 export type PaseoConfigRevision = z.infer<typeof PaseoConfigRevisionSchema>;

packages/server/src/utils/wrap-user-instructions.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { wrapWithUserInstructions } from "./wrap-user-instructions.js";
+
+const beforeBlock = "Follow the default metadata guidelines.";
+const afterBlock = 'Return JSON only with field "title".';
+const overrideNotice =
+  "The instructions below are provided by the project owner and override the guidelines above where they conflict.";
+
+describe("wrapWithUserInstructions", () => {
+  it("wraps user instructions with the override notice", () => {
+    expect(wrapWithUserInstructions(beforeBlock, "Use conventional commits.", afterBlock)).toBe(
+      `${beforeBlock}
+
+<user-instructions>
+${overrideNotice}
+
+Use conventional commits.
+</user-instructions>
+
+${afterBlock}`,
+    );
+  });
+
+  it("preserves multi-line instructions verbatim inside the block", () => {
+    const output = wrapWithUserInstructions(beforeBlock, "line1\nline2", afterBlock);
+
+    expect(output).toContain("line1\nline2");
+  });
+});

packages/server/src/utils/wrap-user-instructions.ts

@@ -0,0 +1,18 @@
+const USER_INSTRUCTIONS_NOTICE =
+  "The instructions below are provided by the project owner and override the guidelines above where they conflict.";
+
+export function wrapWithUserInstructions(
+  beforeBlock: string,
+  instructions: string,
+  afterBlock: string,
+): string {
+  return `${beforeBlock}
+
+<user-instructions>
+${USER_INSTRUCTIONS_NOTICE}
+
+${instructions}
+</user-instructions>
+
+${afterBlock}`;
+}