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

> Discover how the agent-instruction-compose system dynamically generates AI agent prompts by loading, filtering, and assembling instruction fragments with context variables in OpenWork.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: internals
- Published: 2026-08-22

---

**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](https://github.com/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```typescript
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`](https://github.com/different-ai/openwork/blob/main/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.