Merge pull request #501 from AutoMaker-Org/feature/v0.11.0rc-1768426435282-1ogl

feat: centralize prompts and add customization UI for App Spec, Context, Suggestions, Tasks

apps/server/src/routes/app-spec/generate-features-from-spec.ts

@@ -14,7 +14,7 @@ import { streamingQuery } from '../../providers/simple-query-service.js';
 import { parseAndCreateFeatures } from './parse-and-create-features.js';
 import { getAppSpecPath } from '@automaker/platform';
 import type { SettingsService } from '../../services/settings-service.js';
-import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
+import { getAutoLoadClaudeMdSetting, getPromptCustomization } from '../../lib/settings-helpers.js';
 
 const logger = createLogger('SpecRegeneration');
 
@@ -53,38 +53,16 @@ export async function generateFeaturesFromSpec(
     return;
   }
 
+  // Get customized prompts from settings
+  const prompts = await getPromptCustomization(settingsService, '[FeatureGeneration]');
+
   const prompt = `Based on this project specification:
 
 ${spec}
 
-Generate a prioritized list of implementable features. For each feature provide:
+${prompts.appSpec.generateFeaturesFromSpecPrompt}
 
-1. **id**: A unique lowercase-hyphenated identifier
-2. **category**: Functional category (e.g., "Core", "UI", "API", "Authentication", "Database")
-3. **title**: Short descriptive title
-4. **description**: What this feature does (2-3 sentences)
-5. **priority**: 1 (high), 2 (medium), or 3 (low)
-6. **complexity**: "simple", "moderate", or "complex"
-7. **dependencies**: Array of feature IDs this depends on (can be empty)
-
-Format as JSON:
-{
-  "features": [
-    {
-      "id": "feature-id",
-      "category": "Feature Category",
-      "title": "Feature Title",
-      "description": "What it does",
-      "priority": 1,
-      "complexity": "moderate",
-      "dependencies": []
-    }
-  ]
-}
-
-Generate ${featureCount} features that build on each other logically.
-
-IMPORTANT: Do not ask for clarification. The specification is provided above. Generate the JSON immediately.`;
+Generate ${featureCount} features that build on each other logically.`;
 
   logger.info('========== PROMPT BEING SENT ==========');
   logger.info(`Prompt length: ${prompt.length} chars`);

apps/server/src/routes/app-spec/generate-spec.ts

@@ -7,12 +7,7 @@
 
 import * as secureFs from '../../lib/secure-fs.js';
 import type { EventEmitter } from '../../lib/events.js';
-import {
-  specOutputSchema,
-  specToXml,
-  getStructuredSpecPromptInstruction,
-  type SpecOutput,
-} from '../../lib/app-spec-format.js';
+import { specOutputSchema, specToXml, type SpecOutput } from '../../lib/app-spec-format.js';
 import { createLogger } from '@automaker/utils';
 import { DEFAULT_PHASE_MODELS, isCursorModel } from '@automaker/types';
 import { resolvePhaseModel } from '@automaker/model-resolver';
@@ -21,7 +16,7 @@ import { streamingQuery } from '../../providers/simple-query-service.js';
 import { generateFeaturesFromSpec } from './generate-features-from-spec.js';
 import { ensureAutomakerDir, getAppSpecPath } from '@automaker/platform';
 import type { SettingsService } from '../../services/settings-service.js';
-import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
+import { getAutoLoadClaudeMdSetting, getPromptCustomization } from '../../lib/settings-helpers.js';
 
 const logger = createLogger('SpecRegeneration');
 
@@ -43,6 +38,9 @@ export async function generateSpec(
   logger.info('analyzeProject:', analyzeProject);
   logger.info('maxFeatures:', maxFeatures);
 
+  // Get customized prompts from settings
+  const prompts = await getPromptCustomization(settingsService, '[SpecRegeneration]');
+
   // Build the prompt based on whether we should analyze the project
   let analysisInstructions = '';
   let techStackDefaults = '';
@@ -66,9 +64,7 @@ export async function generateSpec(
 Use these technologies as the foundation for the specification.`;
   }
 
-  const prompt = `You are helping to define a software project specification.
-
-IMPORTANT: Never ask for clarification or additional information. Use the information provided and make reasonable assumptions to create the best possible specification. If details are missing, infer them based on common patterns and best practices.
+  const prompt = `${prompts.appSpec.generateSpecSystemPrompt}
 
 Project Overview:
 ${projectOverview}
@@ -77,7 +73,7 @@ ${techStackDefaults}
 
 ${analysisInstructions}
 
-${getStructuredSpecPromptInstruction()}`;
+${prompts.appSpec.structuredSpecInstructions}`;
 
   logger.info('========== PROMPT BEING SENT ==========');
   logger.info(`Prompt length: ${prompt.length} chars`);

apps/server/src/routes/context/routes/describe-file.ts

@@ -19,7 +19,10 @@ import { simpleQuery } from '../../../providers/simple-query-service.js';
 import * as secureFs from '../../../lib/secure-fs.js';
 import * as path from 'path';
 import type { SettingsService } from '../../../services/settings-service.js';
-import { getAutoLoadClaudeMdSetting } from '../../../lib/settings-helpers.js';
+import {
+  getAutoLoadClaudeMdSetting,
+  getPromptCustomization,
+} from '../../../lib/settings-helpers.js';
 
 const logger = createLogger('DescribeFile');
 
@@ -130,11 +133,12 @@ export function createDescribeFileHandler(
       // Get the filename for context
       const fileName = path.basename(resolvedPath);
 
+      // Get customized prompts from settings
+      const prompts = await getPromptCustomization(settingsService, '[DescribeFile]');
+
       // Build prompt with file content passed as structured data
       // The file content is included directly, not via tool invocation
-      const prompt = `Analyze the following file and provide a 1-2 sentence description suitable for use as context in an AI coding assistant. Focus on what the file contains, its purpose, and why an AI agent might want to use this context in the future (e.g., "API documentation for the authentication endpoints", "Configuration file for database connections", "Coding style guidelines for the project").
-
-Respond with ONLY the description text, no additional formatting, preamble, or explanation.
+      const prompt = `${prompts.contextDescription.describeFilePrompt}
 
 File: ${fileName}${truncated ? ' (truncated)' : ''}
 

apps/server/src/routes/context/routes/describe-image.ts

@@ -19,7 +19,10 @@ import { simpleQuery } from '../../../providers/simple-query-service.js';
 import * as secureFs from '../../../lib/secure-fs.js';
 import * as path from 'path';
 import type { SettingsService } from '../../../services/settings-service.js';
-import { getAutoLoadClaudeMdSetting } from '../../../lib/settings-helpers.js';
+import {
+  getAutoLoadClaudeMdSetting,
+  getPromptCustomization,
+} from '../../../lib/settings-helpers.js';
 
 const logger = createLogger('DescribeImage');
 
@@ -278,12 +281,11 @@ export function createDescribeImageHandler(
 
       logger.info(`[${requestId}] Using model: ${model}`);
 
-      // Build the instruction text
-      const instructionText =
-        `Describe this image in 1-2 sentences suitable for use as context in an AI coding assistant. ` +
-        `Focus on what the image shows and its purpose (e.g., "UI mockup showing login form with email/password fields", ` +
-        `"Architecture diagram of microservices", "Screenshot of error message in terminal").\n\n` +
-        `Respond with ONLY the description text, no additional formatting, preamble, or explanation.`;
+      // Get customized prompts from settings
+      const prompts = await getPromptCustomization(settingsService, '[DescribeImage]');
+
+      // Build the instruction text from centralized prompts
+      const instructionText = prompts.contextDescription.describeImagePrompt;
 
       // Build prompt based on provider capability
       // Some providers (like Cursor) may not support image content blocks

apps/server/src/routes/features/index.ts

@@ -4,6 +4,7 @@
 
 import { Router } from 'express';
 import { FeatureLoader } from '../../services/feature-loader.js';
+import type { SettingsService } from '../../services/settings-service.js';
 import { validatePathParams } from '../../middleware/validate-paths.js';
 import { createListHandler } from './routes/list.js';
 import { createGetHandler } from './routes/get.js';
@@ -15,7 +16,10 @@ import { createDeleteHandler } from './routes/delete.js';
 import { createAgentOutputHandler, createRawOutputHandler } from './routes/agent-output.js';
 import { createGenerateTitleHandler } from './routes/generate-title.js';
 
-export function createFeaturesRoutes(featureLoader: FeatureLoader): Router {
+export function createFeaturesRoutes(
+  featureLoader: FeatureLoader,
+  settingsService?: SettingsService
+): Router {
   const router = Router();
 
   router.post('/list', validatePathParams('projectPath'), createListHandler(featureLoader));
@@ -35,7 +39,7 @@ export function createFeaturesRoutes(featureLoader: FeatureLoader): Router {
   router.post('/delete', validatePathParams('projectPath'), createDeleteHandler(featureLoader));
   router.post('/agent-output', createAgentOutputHandler(featureLoader));
   router.post('/raw-output', createRawOutputHandler(featureLoader));
-  router.post('/generate-title', createGenerateTitleHandler());
+  router.post('/generate-title', createGenerateTitleHandler(settingsService));
 
   return router;
 }

apps/server/src/routes/features/routes/generate-title.ts

@@ -9,6 +9,8 @@ import type { Request, Response } from 'express';
 import { createLogger } from '@automaker/utils';
 import { CLAUDE_MODEL_MAP } from '@automaker/model-resolver';
 import { simpleQuery } from '../../../providers/simple-query-service.js';
+import type { SettingsService } from '../../../services/settings-service.js';
+import { getPromptCustomization } from '../../../lib/settings-helpers.js';
 
 const logger = createLogger('GenerateTitle');
 
@@ -26,16 +28,9 @@ interface GenerateTitleErrorResponse {
   error: string;
 }
 
-const SYSTEM_PROMPT = `You are a title generator. Your task is to create a concise, descriptive title (5-10 words max) for a software feature based on its description.
-
-Rules:
-- Output ONLY the title, nothing else
-- Keep it short and action-oriented (e.g., "Add dark mode toggle", "Fix login validation")
-- Start with a verb when possible (Add, Fix, Update, Implement, Create, etc.)
-- No quotes, periods, or extra formatting
-- Capture the essence of the feature in a scannable way`;
-
-export function createGenerateTitleHandler(): (req: Request, res: Response) => Promise<void> {
+export function createGenerateTitleHandler(
+  settingsService?: SettingsService
+): (req: Request, res: Response) => Promise<void> {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { description } = req.body as GenerateTitleRequestBody;
@@ -61,11 +56,15 @@ export function createGenerateTitleHandler(): (req: Request, res: Response) => P
 
       logger.info(`Generating title for description: ${trimmedDescription.substring(0, 50)}...`);
 
+      // Get customized prompts from settings
+      const prompts = await getPromptCustomization(settingsService, '[GenerateTitle]');
+      const systemPrompt = prompts.titleGeneration.systemPrompt;
+
       const userPrompt = `Generate a concise title for this feature:\n\n${trimmedDescription}`;
 
       // Use simpleQuery - provider abstraction handles all the streaming/extraction
       const result = await simpleQuery({
-        prompt: `${SYSTEM_PROMPT}\n\n${userPrompt}`,
+        prompt: `${systemPrompt}\n\n${userPrompt}`,
         model: CLAUDE_MODEL_MAP.haiku,
         cwd: process.cwd(),
         maxTurns: 1,

apps/server/src/routes/github/routes/validate-issue.ts

@@ -30,11 +30,11 @@ import { writeValidation } from '../../../lib/validation-storage.js';
 import { streamingQuery } from '../../../providers/simple-query-service.js';
 import {
   issueValidationSchema,
-  ISSUE_VALIDATION_SYSTEM_PROMPT,
   buildValidationPrompt,
   ValidationComment,
   ValidationLinkedPR,
 } from './validation-schema.js';
+import { getPromptCustomization } from '../../../lib/settings-helpers.js';
 import {
   trySetValidationRunning,
   clearValidationStatus,
@@ -117,13 +117,17 @@ async function runValidation(
 
     let responseText = '';
 
+    // Get customized prompts from settings
+    const prompts = await getPromptCustomization(settingsService, '[ValidateIssue]');
+    const issueValidationSystemPrompt = prompts.issueValidation.systemPrompt;
+
     // Determine if we should use structured output (Claude/Codex support it, Cursor/OpenCode don't)
     const useStructuredOutput = isClaudeModel(model) || isCodexModel(model);
 
     // Build the final prompt - for Cursor, include system prompt and JSON schema instructions
     let finalPrompt = basePrompt;
     if (!useStructuredOutput) {
-      finalPrompt = `${ISSUE_VALIDATION_SYSTEM_PROMPT}
+      finalPrompt = `${issueValidationSystemPrompt}
 
 CRITICAL INSTRUCTIONS:
 1. DO NOT write any files. Return the JSON in your response only.
@@ -167,7 +171,7 @@ ${basePrompt}`;
       prompt: finalPrompt,
       model: model as string,
       cwd: projectPath,
-      systemPrompt: useStructuredOutput ? ISSUE_VALIDATION_SYSTEM_PROMPT : undefined,
+      systemPrompt: useStructuredOutput ? issueValidationSystemPrompt : undefined,
       abortController,
       thinkingLevel: effectiveThinkingLevel,
       reasoningEffort: effectiveReasoningEffort,

apps/server/src/routes/github/routes/validation-schema.ts

@@ -1,8 +1,11 @@
 /**
- * Issue Validation Schema and System Prompt
+ * Issue Validation Schema and Prompt Building
  *
  * Defines the JSON schema for Claude's structured output and
- * the system prompt that guides the validation process.
+ * helper functions for building validation prompts.
+ *
+ * Note: The system prompt is now centralized in @automaker/prompts
+ * and accessed via getPromptCustomization() in validate-issue.ts
  */
 
 /**
@@ -82,76 +85,6 @@ export const issueValidationSchema = {
   additionalProperties: false,
 } as const;
 
-/**
- * System prompt that guides Claude in validating GitHub issues.
- * Instructs the model to use read-only tools to analyze the codebase.
- */
-export const ISSUE_VALIDATION_SYSTEM_PROMPT = `You are an expert code analyst validating GitHub issues against a codebase.
-
-Your task is to analyze a GitHub issue and determine if it's valid by scanning the codebase.
-
-## Validation Process
-
-1. **Read the issue carefully** - Understand what is being reported or requested
-2. **Search the codebase** - Use Glob to find relevant files by pattern, Grep to search for keywords
-3. **Examine the code** - Use Read to look at the actual implementation in relevant files
-4. **Check linked PRs** - If there are linked pull requests, use \`gh pr diff <PR_NUMBER>\` to review the changes
-5. **Form your verdict** - Based on your analysis, determine if the issue is valid
-
-## Verdicts
-
-- **valid**: The issue describes a real problem that exists in the codebase, or a clear feature request that can be implemented. The referenced files/components exist and the issue is actionable.
-
-- **invalid**: The issue describes behavior that doesn't exist, references non-existent files or components, is based on a misunderstanding of the code, or the described "bug" is actually expected behavior.
-
-- **needs_clarification**: The issue lacks sufficient detail to verify. Specify what additional information is needed in the missingInfo field.
-
-## For Bug Reports, Check:
-- Do the referenced files/components exist?
-- Does the code match what the issue describes?
-- Is the described behavior actually a bug or expected?
-- Can you locate the code that would cause the reported issue?
-
-## For Feature Requests, Check:
-- Does the feature already exist?
-- Is the implementation location clear?
-- Is the request technically feasible given the codebase structure?
-
-## Analyzing Linked Pull Requests
-
-When an issue has linked PRs (especially open ones), you MUST analyze them:
-
-1. **Run \`gh pr diff <PR_NUMBER>\`** to see what changes the PR makes
-2. **Run \`gh pr view <PR_NUMBER>\`** to see PR description and status
-3. **Evaluate if the PR fixes the issue** - Does the diff address the reported problem?
-4. **Provide a recommendation**:
-   - \`wait_for_merge\`: The PR appears to fix the issue correctly. No additional work needed - just wait for it to be merged.
-   - \`pr_needs_work\`: The PR attempts to fix the issue but is incomplete or has problems.
-   - \`no_pr\`: No relevant PR exists for this issue.
-
-5. **Include prAnalysis in your response** with:
-   - hasOpenPR: true/false
-   - prFixesIssue: true/false (based on diff analysis)
-   - prNumber: the PR number you analyzed
-   - prSummary: brief description of what the PR changes
-   - recommendation: one of the above values
-
-## Response Guidelines
-
-- **Always include relatedFiles** when you find relevant code
-- **Set bugConfirmed to true** only if you can definitively confirm a bug exists in the code
-- **Provide a suggestedFix** when you have a clear idea of how to address the issue
-- **Use missingInfo** when the verdict is needs_clarification to list what's needed
-- **Include prAnalysis** when there are linked PRs - this is critical for avoiding duplicate work
-- **Set estimatedComplexity** to help prioritize:
-  - trivial: Simple text changes, one-line fixes
-  - simple: Small changes to one file
-  - moderate: Changes to multiple files or moderate logic changes
-  - complex: Significant refactoring or new feature implementation
-  - very_complex: Major architectural changes or cross-cutting concerns
-
-Be thorough in your analysis but focus on files that are directly relevant to the issue.`;
-
 /**
  * Comment data structure for validation prompt
  */

apps/server/src/routes/suggestions/generate-suggestions.ts

@@ -15,7 +15,7 @@ import { FeatureLoader } from '../../services/feature-loader.js';
 import { getAppSpecPath } from '@automaker/platform';
 import * as secureFs from '../../lib/secure-fs.js';
 import type { SettingsService } from '../../services/settings-service.js';
-import { getAutoLoadClaudeMdSetting } from '../../lib/settings-helpers.js';
+import { getAutoLoadClaudeMdSetting, getPromptCustomization } from '../../lib/settings-helpers.js';
 
 const logger = createLogger('Suggestions');
 
@@ -137,11 +137,15 @@ export async function generateSuggestions(
   modelOverride?: string,
   thinkingLevelOverride?: ThinkingLevel
 ): Promise<void> {
+  // Get customized prompts from settings
+  const prompts = await getPromptCustomization(settingsService, '[Suggestions]');
+
+  // Map suggestion types to their prompts
   const typePrompts: Record<string, string> = {
-    features: 'Analyze this project and suggest new features that would add value.',
-    refactoring: 'Analyze this project and identify refactoring opportunities.',
-    security: 'Analyze this project for security vulnerabilities and suggest fixes.',
-    performance: 'Analyze this project for performance issues and suggest optimizations.',
+    features: prompts.suggestions.featuresPrompt,
+    refactoring: prompts.suggestions.refactoringPrompt,
+    security: prompts.suggestions.securityPrompt,
+    performance: prompts.suggestions.performancePrompt,
   };
 
   // Load existing context to avoid duplicates
@@ -151,15 +155,7 @@ export async function generateSuggestions(
 ${existingContext}
 
 ${existingContext ? '\nIMPORTANT: Do NOT suggest features that are already implemented or already in the backlog above. Focus on NEW ideas that complement what already exists.\n' : ''}
-Look at the codebase and provide 3-5 concrete suggestions.
-
-For each suggestion, provide:
-1. A category (e.g., "User Experience", "Security", "Performance")
-2. A clear description of what to implement
-3. Priority (1=high, 2=medium, 3=low)
-4. Brief reasoning for why this would help
-
-The response will be automatically formatted as structured JSON.`;
+${prompts.suggestions.baseTemplate}`;
 
   // Don't send initial message - let the agent output speak for itself
   // The first agent message will be captured as an info entry