How the agent-instruction-compose System Generates Dynamic Agent Prompts in OpenWork

The agent-instruction-compose system dynamically assembles AI agent prompts by loading instruction fragments from disk, filtering them by capability matching, substituting context variables, and concatenating them into a final prompt string.

The agent-instruction-compose subsystem in the different-ai/openwork repository generates context-aware prompts that guide AI agents at runtime. Located within the server's opencode-plugins directory, this module transforms static instruction files into dynamic prompts tailored to specific user requests and agent capabilities without requiring code changes.

Architecture of the Prompt Composition Pipeline

The system processes declarative instruction fragments through a four-stage pipeline to produce executable prompt strings.

Loading Instruction Fragments

The loader reads all files stored in apps/server/src/opencode-plugins/instructions/. These fragments use .md or .txt extensions and may include optional front-matter metadata such as applyTo: '**' to specify targeting patterns. The loader parses each file's raw text together with its associated metadata, creating an in-memory registry of available instruction components.

Capability-Based Filtering

Once loaded, the system filters fragments based on the capabilities requested by the caller. Each fragment declares an applyTo glob pattern; only fragments matching the current agent's capability set—such as search_files—are retained for composition. This ensures agents receive strictly relevant instructions for their assigned tasks.

Variable Substitution

The substituteVariables helper processes the filtered fragments, replacing placeholders like {{userMessage}}, {{workspaceId}}, and {{model}} with values from the request payload. The substitution performs a single-pass replacement, leaving undefined variables untouched to preserve template integrity for debugging purposes.

Prompt Assembly

The selected fragments are concatenated in deterministic order—by default following their disk ordering unless a fragment explicitly specifies an order metadata value. Blank lines are trimmed and a final newline is appended, producing a clean prompt string ready for transmission to the LLM.

Core Implementation in the OpenWork Source Code

The composition logic resides in apps/server/src/opencode-plugins/agent-instruction-compose.ts, which exports the primary composeAgentPrompt function. This function orchestrates the loading, filtering, substitution, and assembly phases described above.

The accompanying test file, apps/server/src/opencode-plugins/agent-instruction-compose.test.ts, validates the entire pipeline using mock instruction files and synthetic request payloads. These tests verify that the composition correctly filters by capability and substitutes variables, serving as executable documentation for the module's public API.

When the server receives a request at the execute_capability endpoint, it invokes composeAgentPrompt(request) to generate the final prompt. The composed string is then passed directly to the configured language model provider, whether Anthropic, OpenAI, or another backend.

Practical Example: Composing a Prompt for File Search

Consider a client requesting a file search capability:

import { composeAgentPrompt } from '@/opencode-plugins/agent-instruction-compose';

const request = {
  capability: 'search_files',
  userMessage: 'Find all TODOs in the repo.',
  workspaceId: 'ws_12345',
  model: 'claude-3-opus'
};

const prompt = await composeAgentPrompt(request);
console.log(prompt);

The system loads fragments from the instructions directory, selects those with applyTo patterns matching search_files, and substitutes the variables:

You are an expert developer assistant. Your task is to search files in the workspace.
Workspace ID: ws_12345
User request: Find all TODOs in the repo.
Model: claude-3-opus

This data-driven approach means adding new capabilities requires only creating new instruction files—no changes to the core composition logic are necessary.

Summary

• The agent-instruction-compose system lives in apps/server/src/opencode-plugins/agent-instruction-compose.ts and generates prompts via the composeAgentPrompt function.
• Instruction fragments are stored in apps/server/src/opencode-plugins/instructions/ as .md or .txt files with optional front-matter metadata.
• The capability-based filtering mechanism uses applyTo glob patterns to ensure agents receive only relevant instructions.
• Variable substitution replaces placeholders like {{userMessage}} and {{workspaceId}} with runtime values from the request payload.
• The architecture enables purely declarative prompt management, allowing new capabilities to be added by creating instruction files without modifying source code.

Frequently Asked Questions

What is the agent-instruction-compose system in OpenWork?

The agent-instruction-compose system is a prompt generation engine within the different-ai/openwork repository that dynamically assembles AI agent instructions. It combines static text fragments with runtime context to create tailored prompts for specific capabilities and user requests.

How does the system handle capability-specific instructions?

The system reads the applyTo metadata field from each instruction fragment, which contains glob patterns matching specific capability names. Only fragments whose patterns match the requested capability are included in the final prompt, ensuring agents receive contextually appropriate instructions.

What variable placeholders are supported in instruction fragments?

Instruction fragments can use placeholders such as {{userMessage}}, {{workspaceId}}, and {{model}}. The substituteVariables function replaces these with actual values from the request payload, leaving unmatched placeholders intact for debugging purposes.

Where are the instruction fragment files stored?

All instruction fragments reside in the apps/server/src/opencode-plugins/instructions/ directory. The loader recursively reads .md and .txt files from this location, parsing their content and front-matter during the composition process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}