Why Composable Prompts

The monolithic prompt problem

Your agent config file is 400 lines. Half is voice and tone. A quarter is project rules. The rest is workflow instructions. It all lives in one file.

This works until it doesn’t. Three things break:

No reuse. You copy the file between projects. You tweak it for each one. The copies drift. Six months later you have five versions and no source of truth.

No switching. You want the agent to do code review instead of writing code. You rewrite the file, or you maintain two files by hand and swap them. Neither scales.

No sharing. A teammate asks how you set up your agent. You paste a blob into Slack. They paste it into their config. No structure, no versioning, no way to push an update.

The monolithic file is a dead end. It conflates identity, workflow, and constraints into one unstructured blob. Every change is a full-file edit. Every variant is a fork.

How production agents are built

The most advanced AI agent systems don’t use monolithic prompts. They assemble prompts from modular, composable sections at runtime:

• Cached identity sections — who the agent is, how it sounds. Stable across sessions. Loaded once and reused.
• Role and method sections — the role the agent is playing right now and the playbook it’s following. Swappable per task.
• Dynamic task sections — current context, active tools, user-specific state. Changes every turn or every session.
• Behavioral constraints — guardrails applied conditionally based on context, project, or task type.

This isn’t a niche pattern. Production coding agents, research assistants, and autonomous workflows all converge on the same structure. The prompt is not a single document — it’s an assembly of layers, each with its own lifecycle and ownership.

Why does this work? Because each section has a different rate of change. Identity is nearly static. Task context changes every request. Constraints change per project or deployment. Bundling them together means reprocessing stable content every time dynamic content changes. Separating them lets each layer be cached, tested, and updated independently.

The industry is converging on composable prompt architectures. The question is whether you manage that composition by hand or with tooling.

Separation of concerns

Software engineers already know this principle: separate things that change for different reasons. The same logic applies to prompt configuration.

Four natural seams emerge:

Layer	Maps to	Changes when
Soul	Identity — voice, character, standards	Rarely. Reflects who the agent is.
Persona	Role — disposition, methodology	Per task. Reflects what the agent is doing.
Procedure	Method — step-by-step playbook for a workflow	Per workflow. Reflects how the work gets done.
Rules	Constraints — guardrails, policies	Per project or context. Reflects what the agent must not do.

These aren’t arbitrary divisions. They map to how behavior naturally decomposes:

• Who you are doesn’t change when you switch tasks.
• What you’re doing doesn’t change your core character.
• How you carry it out can be swapped without changing role — a CTO running a delivery loop and a CTO triaging an incident share the same persona but follow different procedures.
• What you must not do depends on the project, not the persona or the playbook.

A monolithic file manages all of these in one blob. When you change the voice, you risk breaking a guardrail. When you add a project rule, you’re editing the same file that defines workflow. When you want to share just the guardrails with a teammate, you can’t — they’re tangled into everything else.

Composable layers let you change one concern without touching the others. Update the voice across every project by editing one soul. Swap the workflow by switching one procedure. Add a security constraint without reading 400 lines of unrelated config.

What this enables

Instant context switching. One command spawns an agent with the full composed configuration:

brainjar shell --brain review

No file editing. No copy-paste. The agent is now a reviewer with the right persona, voice, and rules. Use brainjar compose review instead when you want the prompt as text (for MCP, orchestration, or piping into another tool). See Brains.

Team alignment. Export the workspace as a pack. Teammates import it. The entire team runs the same agent behavior for the same workflow:

brainjar pack export -o review.json
brainjar pack import -i review.json

One JSON bundle, version-controlled, shareable. See Packs.

Subagent orchestration. Compose a full prompt from named layers and dispatch it to a subagent. The lead agent doesn’t paste raw text — it calls the MCP tool with a structured source:

mcp__brainjar__compose({
  source: { kind: "brain", brain_slug: "review" },
  task:   "Review changes in src/sync.ts"
})

The returned prompt is passed to Claude Code’s Agent tool to spawn the subagent. Each worker gets exactly the identity, role, procedure, and constraints it needs — with worktree isolation available for parallel dispatch. See Subagent Orchestration.

Reproducibility. Save a configuration, restore it anywhere. Same layers in, same behavior out. No drift, no “works on my machine” for agent setups. Debug a misbehaving agent by inspecting each layer independently — you can see exactly which layer introduced a behavior.

brainjar’s approach

brainjar treats prompt configuration as a first-class engineering artifact. Souls, personas, procedures, and rules are version-controlled markdown documents stored in a local SQLite database (or a brainjar serve instance, if you want a shared one). They compose into brains. Brains compose into full prompts on demand — written into your platform’s config file with sync, spawned in-memory with shell, or returned as text from compose for orchestration.

The result: agent behavior that’s modular, shareable, and reproducible — managed with the same rigor you’d apply to code.

Start with Getting Started or learn about the core concepts.