src — prompts

Module: src-prompts Cohesion: 0.80 Members: 0

src — prompts

The src/prompts module is the central hub for managing, composing, and delivering system prompts to Code Buddy's underlying Large Language Models (LLMs). It ensures that the AI agent receives precise instructions, context, and safety guidelines tailored to the current task, operational mode, and even the specific model being used.

This module is critical for defining Code Buddy's identity, capabilities, and behavioral guardrails. It supports dynamic prompt construction, external customization, and adaptive prompt selection based on model characteristics.

Core Concepts

  1. System Prompts: These are the foundational instructions given to the LLM, defining its role (), rules (, ), available tools (), and expected response style ().
  2. Dynamic Composition: Prompts are not static strings. They are built dynamically from various sections (base prompt, context, tools, project info, user instructions, workflow rules) which are assembled based on configuration and runtime data.
  3. External Prompts: Inspired by systems like mistral-vibe, Code Buddy allows users to define and customize system prompts using Markdown files (.md) stored in ~/.codebuddy/prompts/. This enables flexible customization without modifying the core codebase.
  4. Model Alignment: Different LLMs have varying levels of inherent safety and instruction following capabilities. This module can detect model types (e.g., "well-aligned" vs. "needs extra security") and automatically select a suitable prompt complexity.
  5. Prompt Variation: To prevent LLMs from developing brittle, memorized response patterns, a "variation injector" subtly shuffles and rephrases non-critical sections of the prompt on each session.

Module Components

The prompts module is composed of several key files, each with a distinct responsibility:

src/prompts/prompt-manager.ts

This file contains the PromptManager class, which is the primary orchestrator for loading, caching, and building system prompts. It handles the logic for finding prompts in user-defined directories, falling back to built-in files, and finally to inline defaults.

Key Responsibilities:

Key Classes & Functions:

src/prompts/system-base.ts

This file defines the core, hardcoded system prompts and their modular additions. These serve as the default content that PromptManager can load or extend.

Key Responsibilities:

Key Functions & Constants:

src/prompts/variation-injector.ts

This module implements the "Prompt Variation Injector" pattern, inspired by Manus AI. Its purpose is to introduce subtle, randomized structural variations into the system prompt to prevent LLMs from falling into brittle, repetitive patterns due to memorized few-shot examples.

Key Responsibilities:

Key Functions & Types:

src/prompts/workflow-rules.ts

This file provides a block of concrete, measurable workflow rules designed to guide the AI agent through complex tasks. These rules are intended to be injected into the system prompt to improve planning, auto-correction, and verification behaviors.

Key Responsibilities:

Key Functions:

How Prompts Are Constructed

The prompts module works in concert with src/services/prompt-builder.ts (an external consumer) to construct the final system prompt. The general flow is as follows: 

sequenceDiagram
    participant PB as PromptBuilder (src/services)
    participant PM as PromptManager (src/prompts)
    participant SB as SystemBase (src/prompts)
    participant WR as WorkflowRules (src/prompts)
    participant VI as VariationInjector (src/prompts)
    participant GC as GitContext (src/context)

    PB->>PM: getPromptManager()
    PB->>PM: buildSystemPrompt(config)
    PM->>PM: loadPrompt(config.promptId)
    alt Prompt file not found
        PM->>SB: getInlinePrompt(config.promptId)
    end
    PM->>PM: parseFrontmatter(rawPrompt)
    PM->>PM: buildToolSection(config.tools)
    PM->>PM: buildProjectContext(config.cwd)
    PM->>GC: getGitState(config.cwd)
    PM->>GC: formatGitState(gitState)
    PM-->>PB: basePromptWithContext
    PB->>WR: getWorkflowRulesBlock()
    PB->>PB: Append Workflow Rules
    PB->>VI: varySystemPrompt(finalPrompt, options)
    VI->>VI: extractBlocks(prompt)
    VI->>VI: applyVariation(blocks, options)
    VI-->>PB: finalVariedPrompt

  1. Initialization: The PromptBuilder (or other consumers) obtains an instance of PromptManager via getPromptManager().
  2. Base Prompt Assembly: PromptManager.buildSystemPrompt() is called with a PromptConfig object.

  1. Workflow Rules Injection: The PromptBuilder then appends the concrete workflow rules obtained from getWorkflowRulesBlock() to the prompt.
  2. Prompt Variation: Finally, the PromptBuilder passes the fully assembled prompt to varySystemPrompt() from src/prompts/variation-injector.ts to introduce subtle, randomized changes before sending it to the LLM.

Integration and Usage

Developer Notes