Prompt System

Prompt System

M31A uses embedded markdown prompt templates that are compiled into the binary at build time. These prompts instruct the LLM on how to behave during each workflow phase.

Source: internal/workflow/prompts/

Embedding

Prompts are embedded via Go's //go:embed directive:

//go:embed prompts/*.md
var promptFS embed.FS

This eliminates runtime file dependencies -- the binary is fully self-contained.

Prompt Registry

type PromptRegistry struct {
    Base             string  // prompts/base.md
    ToolUse          string  // prompts/tool-use.md
    PlanFormat       string  // prompts/plan-format.md
    ExecuteTask      string  // prompts/execute-task.md
    Discuss          string  // prompts/discuss-questions.md
    SelfHeal         string  // prompts/self-heal.md
    Demonstration    string  // prompts/demonstration-format.md
    Autonomous       string  // prompts/autonomous.md
    ContextAwareness string  // prompts/context-awareness.md
    CodeQuality      string  // prompts/code-quality.md
    CodeIntelligence string  // prompts/code-intelligence.md
}

Loaded once at engine creation via LoadPrompts(). The base prompt is cached for the session lifetime using sync.Once.

Prompt Composition

The system prompt is built by buildSystemPrompt():

func (e *Engine) buildSystemPrompt(extra ...string) string {
    parts := []string{e.cachedBasePrompt}  // base.md (cached)
    for _, p := range extra {
        if p != "" {
            parts = append(parts, p)
        }
    }
    return strings.Join(parts, "\n\n---\n\n")
}

Each phase appends relevant prompts:

Phase	Extra Prompts
Discuss	Discuss, ContextAwareness
Plan	PlanFormat, ContextAwareness, CodeIntelligence, CodeQuality
Execute	ExecuteTask, ToolUse, CodeQuality, CodeIntelligence
Verify	(uses base + tool definitions)
Ship	Autonomous

Prompt Templates

base.md

The foundational system prompt. Defines the agent's identity, capabilities, and general behavior guidelines. Cached via sync.Once since it never changes during a session.

tool-use.md

Instructions for how the LLM should invoke tools. Includes:

• Available tool names and descriptions
• Parameter format (JSON Schema when SchemaProvider is implemented)
• How to interpret tool results
• Error handling guidance

plan-format.md

Defines the expected markdown structure for implementation plans:

• # Title -- Plan title
• ## Summary -- High-level overview
• ## User Review Required -- Admonition blocks ([!IMPORTANT], [!WARNING])
• ## Open Questions -- Numbered questions with optional suggestions
• ## Proposed Changes -- Category groups with [NEW]/[MODIFY] file entries
• ## Task List -- JSON task array for machine parsing
• ## Verification Plan -- Automated and manual verification steps

execute-task.md

Instructions for task execution:

• How to read and interpret the task description
• File prediction and modification strategy
• Acceptance criteria validation
• When to commit changes

discuss-questions.md

Format for generating clarifying questions during the Discuss phase.

self-heal.md

Instructions for self-healing failed tasks:

• How to analyze error output
• Strategies for fixing common failures
• When to give up (max heal attempts)

demonstration-format.md

Format for generating demonstration outputs.

autonomous.md

Instructions for fully autonomous operation mode.

context-awareness.md

Guidance for using codebase context:

• How to reference relevant files
• How to use import graph information
• Package-level awareness

code-quality.md

Code quality standards the LLM should follow:

• Language-specific best practices
• Error handling patterns
• Testing conventions

code-intelligence.md

Instructions for using the code intelligence layer:

• How to interpret relevance scores
• How to use symbol definitions
• Import graph navigation guidance

Plan Parsing

The plan markdown is parsed into structured data by internal/workflow/plan_parser.go:

Section	Parser Function	Output
Title	extractTitle()	First H1 heading
Summary	extractSection("Summary")	Text between H2 headers
Review Notes	extractReviewNotes()	[!IMPORTANT]/[!WARNING] admonitions
Open Questions	extractOpenQuestions()	Numbered questions with suggestions
Proposed Changes	extractProposedChanges()	Category groups with file actions
Verification	extractVerificationPlan()	Automated + manual steps
Task List	extractTasksFromPlan()	JSON array parsed into []Task

Regex patterns are pre-compiled and cached in sync.Map to avoid recompilation.

Caching Strategy

Item	Cache Method	Lifetime
Base prompt	sync.Once	Session (engine instance)
Tool definitions	sync.Once	Session
Regex patterns	sync.Map	Process lifetime
Code intelligence	sync.Once	Session