Prompt System

Prompt System

M31 Autonomous (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. Prompts can be overridden at multiple levels.

Source: internal/engine/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 Override System

M31A supports a 4-level prompt priority chain:

Priority	Source	Description
1 (highest)	Config override	prompts.overrides[name] in TOML
2	Project override	.m31a/prompts/<name>.md in project root
3	Global override	~/.m31a/prompts/<name>.md
4 (lowest)	Embedded default	prompts/<name>.md from go:embed

Configuration

[prompts]
# Path to custom system prompt (replaces base.md)
system_prompt_file = ""

# Project-level prompt overrides directory
project_prompt_dir = ""

# Global prompt overrides directory
global_prompt_dir = ""

# Per-prompt overrides
[prompts.overrides]
"execute-task" = "/path/to/custom-execute.md"
"plan-phase" = "/path/to/custom-plan.md"

# Per-model template overrides
[prompts.model_template_overrides]
"mistral" = "/path/to/mistral.txt"
"deepseek" = "/path/to/deepseek.txt"

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
    Research         string  // prompts/research.md
    PlanCheck        string  // prompts/plan-check.md
    PlanRevise       string  // prompts/plan-revise.md
    PlanOutline      string  // prompts/plan-outline.md
    DiscussFollowup  string  // prompts/discuss-followup.md
    IntentClassify   string  // prompts/intent-classify.md
    WebsiteBuild     string  // prompts/website-build.md
}

Loaded once at engine creation via LoadPrompts() with the 4-level override chain. 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

research.md

Pre-plan research step instructions for gathering context before plan generation.

plan-check.md

Plan quality checking instructions for validating plan completeness and correctness.

plan-revise.md

Plan revision instructions for improving plans based on review feedback.

plan-outline.md

Outline generation for chunked planning when plans exceed the task threshold.

discuss-followup.md

Follow-up question generation for deeper exploration during the Discuss phase.

intent-classify.md

LLM intent classification for routing REPL input to appropriate workflow phases.

website-build.md

Website build instructions for the website generation feature.

Plan Parsing

The plan markdown is parsed into structured data by internal/engine/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