pr-narrator-mcp: Instructions file for GitHub Copilot

Zod Schema Review Rules

Field Descriptors

• Every schema field must have .describe() with a clear, user-facing description
• Descriptions should explain purpose, not just repeat the field name

// Avoid: no description or useless description
z.string().optional()
z.string().optional().describe("repoPath")

// Prefer: meaningful description
z.string().optional().describe("Path to the git repository. Uses cwd if not provided.")

Defaults and Optionality

• Use .default() for all fields that have sensible defaults
• Use .optional() for truly optional fields where no default makes sense
• Every field in configSchema that affects behavior must have a default

// Config field with a sensible default
includeStats: z.boolean().default(true).describe("Whether to include file/line stats in summaries"),

// Truly optional — no sensible default
ticketPattern: z.string().optional().describe("Regex pattern to extract ticket numbers from branch names"),

Schema Structure

• Nested schemas must be extracted as named constants for reuse and readability
• Use descriptive names with Schema suffix for standalone schemas

// Prefer: extracted named schemas
const prefixSchema = z.object({
  enabled: z.boolean().default(true).describe("Whether to add prefix to messages"),
  style: z.enum(["capitalized", "bracketed"]).default("capitalized").describe("Prefix format style"),
  branchFallback: z.boolean().default(true).describe("Use branch prefix when no ticket found"),
}).default({});

const commitSchema = z.object({
  prefix: prefixSchema,
  maxTitleLength: z.number().default(100).describe("Maximum commit title length"),
  // ...
}).default({});

// Avoid: deeply nested inline schemas
const configSchema = z.object({
  commit: z.object({
    prefix: z.object({
      enabled: z.boolean().default(true),
      // ...
    }).default({}),
  }).default({}),
});

Type Derivation

• Derive TypeScript types from Zod schemas using z.infer<typeof schema>
• Never manually duplicate a Zod schema as a TypeScript interface