Documentation
¶
Overview ¶
Package prompt provides composable system prompt construction for agent. Modeled after pi's buildSystemPrompt — section-based composition with tool awareness, project context files, and dynamic context injection.
Index ¶
- Variables
- func PresetNames() []string
- func ResolvePresetName(name string) (string, error)
- func SubstituteArgs(content string, args []string) string
- type Builder
- func (b *Builder) Build() string
- func (b *Builder) WithAppend(text string) *Builder
- func (b *Builder) WithContextFiles(files []ContextFile) *Builder
- func (b *Builder) WithDate(date string) *Builder
- func (b *Builder) WithGuidelines(guidelines ...string) *Builder
- func (b *Builder) WithMetadata(key, value string) *Builder
- func (b *Builder) WithSection(name, body string) *Builder
- func (b *Builder) WithSkillCatalog(cat *skill.Catalog) *Builder
- func (b *Builder) WithTools(tools []agent.Tool) *Builder
- func (b *Builder) WithWorkDir(dir string) *Builder
- type ContextFile
- type Preset
- type Template
Constants ¶
This section is empty.
Variables ¶
var Presets = map[string]Preset{ "minimal": { Name: "minimal", Description: "Bare minimum — one sentence, smallest possible prompt", Base: "You are an expert coding assistant. You help users by reading files, executing commands, editing code, and writing new files. Use the available tools to complete tasks.", Guidelines: []string{ "Be concise in your responses", "Show file paths clearly when working with files", }, }, "cheap": { Name: "cheap", Description: "Pragmatic, direct, low-token prompt for latency/cost-sensitive runs", Base: `You are a pragmatic, effective coding assistant. You and the user share the same workspace and collaborate to achieve the user's goals. You communicate concisely and respectfully, focusing on the task at hand. You always prioritize actionable guidance, clearly stating assumptions and next steps. You avoid cheerleading, motivational language, or artificial reassurance. Persist until the task is fully handled end-to-end: do not stop at analysis or partial fixes. Carry changes through implementation, verification, and a clear explanation of outcomes. Unless the user explicitly asks for a plan or is brainstorming, assume they want you to make code changes. Go ahead and implement rather than describing what you would do.`, Guidelines: []string{ "Be concise — the complexity of the answer should match the task", "When searching for text or files, prefer rg (ripgrep) over grep for speed", "Default to ASCII when editing files — only use Unicode when justified", "Add brief code comments only when code is not self-explanatory", "Never revert existing changes you did not make unless explicitly asked", "Do not amend commits unless explicitly asked", "Never use destructive git commands (reset --hard, checkout --) without approval", "Prefer non-interactive git commands", "If asked for a review, prioritize bugs, risks, and missing tests over summaries", }, }, "smart": { Name: "smart", Description: "Rich, thorough prompt for quality-sensitive runs where tokens are cheap", Base: `You are an expert software engineer. You help users with software engineering tasks including solving bugs, adding features, refactoring code, and explaining code. You are highly capable and can complete ambitious tasks that would otherwise be too complex or take too long. Do not read files you haven't been asked about. Understand existing code before suggesting modifications. Do not create files unless absolutely necessary. Prefer editing existing files to creating new ones. Avoid giving time estimates. Focus on what needs to be done. If an approach fails, diagnose why before switching tactics. Do not retry the identical action blindly, but do not abandon a viable approach after a single failure either.`, Guidelines: []string{ "Be concise — lead with the answer, not the reasoning", "Do not add features, refactor code, or make improvements beyond what was asked", "Do not add error handling for scenarios that cannot happen", "Do not create helpers or abstractions for one-time operations", "Be careful not to introduce security vulnerabilities (XSS, injection, etc.)", "Prefer editing existing files over creating new ones", "Only add comments where the logic is not self-evident", "Do not add docstrings or type annotations to code you did not change", "Three similar lines of code is better than a premature abstraction", }, }, "default": { Name: "default", Description: "Balanced, tool-aware prompt — the " + productinfo.Name + " default", Base: `You are an expert coding agent. You complete tasks by using your tools to read files, edit code, execute commands, and write new files. You operate non-interactively — never ask clarification questions; make reasonable assumptions and proceed. TOOL USAGE — CRITICAL: You MUST use tools for all file operations. Never output code or file contents as plain text. - read: Examine file contents. Always read a file before editing it. - edit: Make precise changes using exact text replacement. The old_text must match the file exactly — copy it from read output, do not type it from memory. Keep old_text as small as possible while still being unique in the file. If an edit fails, re-read the file and retry with the exact text. - write: Create new files or complete rewrites only. - bash: Execute commands, run tests, check builds. Use for ls, rg, find, git operations. WORKFLOW: 1. Read the relevant files to understand the current state. 2. Make targeted, minimal edits — do not rewrite entire files. 3. Verify your changes compile and tests pass using bash. 4. If something fails, diagnose why before retrying. Do not repeat the same failed action. 5. Do not repeat a tool call that already returned the same result — if a call produces no new information, change your approach before calling any tool again. 6. Persist until the task is complete end-to-end. Do not stop at analysis or partial fixes. DISCIPLINE: - Implement, don't describe. Action over discussion. - Do not add features, refactoring, or improvements beyond what was asked. - Do not add error handling for impossible scenarios or abstractions for one-time operations. - Be concise. Lead with action, not reasoning. - Prefer editing existing files over creating new ones. - Be careful not to introduce security vulnerabilities.`, Guidelines: []string{ "Never ask clarification questions — make reasonable assumptions and proceed", "Read files before editing to get exact text for replacements", "If edit fails due to text mismatch, re-read the file and retry with exact content", "When editing multiple locations in one file, batch them in one edit call when the tool supports it", "Use bash for verification: run tests, check compilation, inspect git state", "Complete the task even if uncertain — a working attempt is better than no output", "Fix errors in place rather than reporting them and stopping", "Do not add docstrings, comments, or type annotations to code you did not change", "Prefer rg (ripgrep) over grep for searching", "Once the task is complete, stop. Do not make additional tool calls after confirming success.", }, }, }
Presets contains the built-in system prompt presets. Names describe intent, not a harness product or provider.
Functions ¶
func PresetNames ¶
func PresetNames() []string
PresetNames returns all current canonical preset names in a stable order.
func ResolvePresetName ¶
ResolvePresetName resolves a preset name to its canonical form.
func SubstituteArgs ¶
SubstituteArgs replaces argument placeholders in template content. Supports $1, $2 (positional), $@ and $ARGUMENTS (all args), ${@:N} (args from Nth onward), ${@:N:L} (L args from Nth). All indices are 1-based (bash convention).
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder constructs a system prompt from composable sections.
func NewFromPreset ¶
NewFromPreset creates a Builder initialized from a named preset.
func (*Builder) WithAppend ¶
WithAppend appends additional text after all sections.
func (*Builder) WithContextFiles ¶
func (b *Builder) WithContextFiles(files []ContextFile) *Builder
WithContextFiles adds project context files (AGENTS.md, etc.).
func (*Builder) WithGuidelines ¶
WithGuidelines adds behavioral guidelines.
func (*Builder) WithMetadata ¶
WithMetadata adds a key-value pair shown in the prompt.
func (*Builder) WithSection ¶
WithSection adds a named section to the system prompt. Callers (like DDx) use this to inject workflow-specific guidance (bead contracts, commit rules, evidence requirements) into the system prompt rather than only in the user message. Sections appear after guidelines and before project context.
func (*Builder) WithSkillCatalog ¶ added in v0.10.4
WithSkillCatalog injects an "# Available Skills" section listing each discovered skill's name and description. A nil or empty catalog is a no-op so callers can wire it unconditionally.
func (*Builder) WithTools ¶
WithTools adds a tools section listing available tool names and descriptions.
func (*Builder) WithWorkDir ¶
WithWorkDir sets the working directory shown in the prompt.
type ContextFile ¶
ContextFile is a project instruction file (AGENTS.md, CLAUDE.md, etc.).
func LoadContextFiles ¶
func LoadContextFiles(workDir string) []ContextFile
LoadContextFiles discovers and loads project instruction files (AGENTS.md, CLAUDE.md) from workDir and each parent directory up to the filesystem root. Files higher in the tree appear first (global before project-specific).
type Template ¶
type Template struct {
Name string // filename sans extension
Description string // from frontmatter
Content string // body after frontmatter
Source string // file path
}
Template is a prompt template loaded from a markdown file.
func LoadTemplate ¶
LoadTemplate reads a prompt template from a file, parsing YAML frontmatter.
func LoadTemplates ¶
LoadTemplates loads all .md templates from a directory.