Agent Instructions

Author or refine agent instructions: $ARGUMENTS

Before Starting

1. Search OpenAI docs for prompt engineering guidance:
   • Use mcp__openai-docs__search_openai_docs with query "system instructions best practices" for latest recommendations
   • Use mcp__openai-docs__search_openai_docs with query "agent instructions" for agents-specific patterns
2. Read the existing instruction architecture to understand the composable pattern:
   • /Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/core.ts — identity + voice markers + failure modes
   • /Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/themes.ts — theme-specific layers (metanoia, movemental, mdna)
   • /Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/modes.ts — pedagogical modes (teacher, coach, reflection, mentor, companion)
   • /Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/styles.ts — interaction styles (conversation, challenge, socratic, evaluative, explainer)
   • /Users/joshuashepherd/Desktop/dev/repos/ai-lab-agent/src/agents/ai-lab/instructions/context.ts — dynamic user context per run
3. Read the writing assistant instruction pattern:
   • /Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions.ts — buildWritingAssistantPrompt() with pluggable content sources
   • /Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/identity.ts — voice identity template
   • /Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/content-forms.ts — content form templates
   • /Users/joshuashepherd/Desktop/dev/repos/movemental-dashboard/src/agents/writing-assistant/instructions/examples.ts — voice calibration examples

Instruction Architecture

Instructions are composed from layers that are concatenated at runtime:

┌─────────────────────────────────┐
│  STATIC (cached by dimension key)│
│  ┌───────────────────────────┐  │
│  │  Core Identity            │  │  — who the agent IS, voice markers, failure modes
│  │  + Theme Layer            │  │  — theological/framework lens
│  │  + Mode Layer             │  │  — pedagogical approach
│  │  + Style Layer            │  │  — interaction pattern
│  └───────────────────────────┘  │
├─────────────────────────────────┤
│  DYNAMIC (fresh per run)        │
│  ┌───────────────────────────┐  │
│  │  User Context             │  │  — name, role, language, kairos, engagement
│  │  + Conversation History   │  │  — continuity from prior turns
│  │  + Page/Content Context   │  │  — what the user is currently viewing
│  └───────────────────────────┘  │
└─────────────────────────────────┘

Static sections are cached by key {theme}-{mode}-{style} (max 100 entries) for performance.

Dynamic sections are NEVER cached — they change per run.

Writing Instructions

Core Identity Section

Define who the agent is. Include:

• Role statement: "You are [name], a [role] who [purpose]."
• Voice markers: 3-5 dimensions that define the voice (e.g., Christocentric Anchoring, Pastoral Warmth, Narrative Imagery, Theological Depth, Prophetic Intensity)
• Signature elements: Recurring phrases, metaphors, or framing devices the voice uses
• Failure modes: What the agent must NOT do (e.g., "Never simplify theological terms", "Never invent citations")

Theme/Mode/Style Layers

Each adds a focused paragraph or two. Keep them modular — they should make sense in any combination.

Dynamic Context Section

Built from RunContext at runtime. Use the DynamicInstructionsGenerator pattern:

export const myDynamicInstructions: DynamicInstructionsGenerator = async (
  baseInstructions: string,
  context: Record<string, unknown>
) => {
  const sections: string[] = [baseInstructions];

  if (context.userName) {
    sections.push(`## User Context\nYou are speaking with ${context.userName}.`);
  }

  return sections.join('\n\n');
};

For Writing Assistant Instructions

Use the pluggable content source pattern from movemental-dashboard:

export function buildWritingAssistantPrompt(content: AgentPromptContent): string {
  return [
    content.headerTemplate,        // from voice_identities table
    content.coreIdentity,          // from voice_identities table
    content.platformContext,       // from voice_identities table
    buildContentFormSection(content.contentForms),  // from content_form_templates table
    buildExamplesSection(content.examples),          // from writing_examples table
  ].filter(Boolean).join('\n\n');
}

This allows org-specific voice swapping without code changes.

Rules

• Never hardcode tenant-specific names, content, or theological positions — use tenantConfig or DB-backed content
• Keep total instruction length under 10,000 tokens (static + dynamic combined)
• Voice markers should be descriptive enough for the LLM to calibrate tone
• Failure modes are as important as positive instructions — always include them
• Test instruction changes by running the agent and checking voice fidelity
• For book-related agents, include mandatory retrieval instructions ("Always use file_search before answering questions about specific books")
• Use markdown formatting in instructions — LLMs parse it well
• Check OpenAI docs MCP for any changes to instruction handling or token limits