Skip to content

How Glueprint composes prompts

The four prompt layers behind every assistant wake, and how each harness handles them differently.

Available on
  • Desktop
  • Web Portal

The Prompting settings page is the quick reference for the Prompts tab. This page is the longer story: why Glueprint splits the prompt into layers instead of concatenating one big string, what each layer holds, and how Claude Code, Codex, Gemini CLI, and other ACP agents deliver those layers very differently.

If you’ve never opened the Prompts tab, you don’t need this page. If you’re tuning behavior and want to know what each toggle actually changes, read on.

Why a layered model

A naive “one big prompt” approach has three problems Glueprint avoids:

  • Stability vs. freshness. Some content — who the assistant is, what rules it follows — is stable for days or weeks. Some content — today’s tasks, recent messages, what time it is — changes on every wake. Mixing them means stable context gets re-serialized constantly and freshness gets buried in old context.
  • Harness portability. Different coding agents accept prompts in different ways. Claude Code reads files from the working directory and accepts a --append-system-prompt-file flag. Codex has no system-prompt flag at all. ACP-protocol agents (including Gemini) take a system prompt as a field in the protocol message. A single monolithic prompt would be impossible to deliver uniformly.
  • Cache efficiency. Claude Code and ACP agents support prompt caching. Splitting stable context from dynamic context means the cacheable parts can actually be cached, while volatile parts stay small.

The Prompts tab in the UI mirrors this split. Every checkbox is doing one of three things: changing what’s in a stable layer, changing what’s in a dynamic layer, or changing how the harness receives them.

Layer 1: Stable context (AGENTS.md / CLAUDE.md)

Glueprint writes a Markdown file to each assistant’s working folder called AGENTS.md, plus a byte-identical copy called CLAUDE.md. The content includes, in this order:

  1. Title and identity — the assistant’s name and root directory.
  2. Authority order (optional, toggled by the Authority order block checkbox) — the explainer that ranks org rules > per-assistant rules > persona > user notes > memory > recent conversation.
  3. Custom preamble (optional) — the free-form text from the Stable context textarea.
  4. Organization rules — the org-wide constitution.
  5. Personal rules — the per-assistant constitution.
  6. Team rules — if the assistant is on a team, the team’s constitution.
  7. Persona — the persona document.
  8. User notes — a user-editable section that survives regeneration because Glueprint reads it back out before rewriting the rest of the file.

This file is regenerated whenever the persona, the constitution, or the relevant config changes. The User notes section is preserved across regenerations.

Coverage by harness:

AGENTS.md (plural) is the cross-tool convention published at agents.md. Glueprint writes the plural form, plus a byte-identical CLAUDE.md, into the assistant’s working directory and spawns every agent with that directory as cwd — both at the OS level (current_dir) and as the ACP-protocol cwd field for ACP agents. Whether a given agent picks up Layer 1 from disk then depends on that agent’s own behavior.

  • Claude Code auto-discovers CLAUDE.md reliably (and AGENTS.md where supported). The byte-identical pair covers both filenames.
  • Codex CLI follows the AGENTS.md convention and reads the file at session start.
  • Other agents that follow agents.md — Kiro, GitHub Copilot, Cursor, Cline, Aider, and a growing list of others all pick up AGENTS.md when they find it in cwd. As long as the agent honors the convention, Glueprint’s file just works.
  • Agents that don’t read files from disk still get the same content through Layer 2 (the overlay carried in their system prompt) and Layer 3 (the per-wake user message). No agent goes without stable context, regardless of its file-discovery behavior.

The short version: Glueprint puts AGENTS.md where the convention says it should be. Any agent that follows the convention will load it.

Layer 2: Glueprint overlay (system prompt)

The Glueprint overlay is the bundle of instructions that turn a bare coding agent into a Glueprint-aware one: the rule that user-visible output must go through the channel-message tool, the framing for memory and journals, the orchestration model for sub-sessions, the safety guardrails. Each block can be toggled independently from the Glueprint system prompt section of the Prompts tab.

Glueprint writes the overlay to a local file per assistant and stamps it with a version. When the version baked into the engine changes (because a Glueprint release shipped new overlay wording), every assistant’s cached harness session is invalidated on next boot so the new overlay is picked up cleanly.

Coverage by harness:

  • Claude Code receives the overlay through --append-system-prompt-file <path>. The file is written to disk and Claude reads it. Replace mode swaps the overlay for a custom prompt; Append mode (default) layers it on top of Claude’s own system prompt.
  • Codex CLI has no system-prompt flag. Glueprint stages the overlay as a “pending” overlay at spawn time, then inlines it at the top of the first user message with a --- divider before the actual message. Subsequent turns do not re-inline the overlay — it’s a one-shot delivery on turn one. Because of this, Replace mode is disabled in the UI for Codex: replacing isn’t truly possible. The system-prompt-mode picker on the Prompts tab silently degrades to Append for Codex.
  • ACP agents (including Gemini) receive the overlay in-protocol as the systemPrompt field of the session-new (or session-load) message. No file is written; the overlay is ephemeral to the session.

Layer 3: Per-wake user message

Every time the assistant wakes, Glueprint composes a fresh user message containing only what’s needed for this wake. The composer is what the Wake message defaults section controls. From top to bottom, the message contains:

  1. Runtime — assistant id, harness, model, host, OS, paths to the assistant’s root and current working directory, the current time.
  2. Who triggered this wake — when a human triggered it, that user’s identity is included so the assistant knows whom to address.
  3. Memory (toggle) — the index of long-term memory plus today’s and yesterday’s journal entries.
  4. Dream journals (dream trigger only) — recent journal entries for reflection.
  5. Tasks (toggle) — the assistant’s open task list with status and priority.
  6. Team (toggle) — if the assistant is on a team, the team’s constitution and the team’s board summary.
  7. Due instructions (toggle) — any routines that have fired and are ready to run.
  8. Coordination block — when a child session finished, a routine fired, or a delegation update came in, this block names the active children and tells the assistant whether to supervise or spawn.
  9. Recent conversation (toggle) — recent channel messages. This block is stripped on a warm-resume, because the underlying agent already has it as part of its conversation history.
  10. Supervised sessions (toggle) — the tree of active children, or a legacy list of rules-based supervised sessions.
  11. Trigger guidance and “why you were woken” — the framing copy explaining why this wake is happening (see Layer 4).
  12. Pending chats — any chat messages that came in while the wake was being composed, rendered last so they have freshest precedence.

The list is composed cold every wake. Anything you didn’t toggle on doesn’t appear.

Layer 4: Per-trigger framing

Glueprint has six trigger types: chat, heartbeat, routine, task, mention, and dream. Each one composes a slightly different “why you were woken” framing at the end of the per-wake message. Defaults:

  • Chat message — “Respond via the channel-message tool. Save durable preferences and corrections to memory.”
  • Heartbeat — “Check tasks, supervised sessions, team board, due instructions. If nothing needs attention, reply HEARTBEAT_OK to short-circuit.”
  • Scheduled routine — “Follow the instruction file. Report results in the channel and journal a summary.”
  • Task dependency — “Task unblocked, proceed with work, report via channel, journal on completion.”
  • Mention — “Respond in the team channel if appropriate.”
  • Dream — adaptive framing based on whether memory and journals are present; consolidate via the memory and journal tools.

The Prompts tab lets you override section gating, the framing copy, and add custom additions per trigger. A heartbeat wake can be much leaner than a chat wake; a routine wake can include extra context that’s irrelevant elsewhere.

Session continuity

Some wakes start a fresh agent process; some pick up where the last wake left off.

  • Claude Code supports warm session resume. Glueprint stores the prior conversation id on disk and passes it via --resume <id> on the next spawn. The recent-conversation block in the per-wake message is stripped on warm-resume, because Claude already has the transcript. The session id is dropped (forcing a cold start) whenever persona or constitution changes, so the agent picks up the refreshed stable context cleanly.
  • Codex CLI supports warm session resume too, through the thread/resume JSON-RPC method. Glueprint stores the prior thread id and passes it back on the next wake. Like Claude, the recent-conversation block is stripped on warm-resume.
  • ACP agents (including Gemini) support warm session resume through the protocol’s session-load message. Glueprint stores the session identifier returned by session-new and passes it to session-load on the next wake.

If continuity isn’t available for whatever reason — new assistant, persona changed, harness doesn’t support it — every wake cold-starts. The stable context (AGENTS.md), the overlay, the per-wake message, and the trigger framing all still flow in normally; the agent just doesn’t carry forward conversational state from the previous wake.

Mid-turn steering (Codex only)

Codex CLI exposes a JSON-RPC method (turn/steer) that lets Glueprint inject a message into the middle of an active turn, without waiting for the turn to finish. This is wired up but used sparingly — only when a human types a chat message into the channel while Codex is mid-turn. Glueprint tracks the active turn id, sends the steer, and waits up to two seconds for an ack; if the steer times out, the message is queued normally and delivered on the next turn boundary.

This is Codex-only today. Claude Code and ACP agents don’t have an equivalent mid-turn interrupt protocol.

Putting it together

When an assistant wakes, the harness sees:

  1. The stable context (Claude reads it from disk; Codex doesn’t see it directly; ACP gets it carried in-protocol).
  2. The overlay (Claude as --append-system-prompt-file; Codex inlined into the first user message with a divider; ACP as the protocol’s system prompt field).
  3. The per-wake user message (carried as the actual user prompt in all three).
  4. The per-trigger framing (the closing section of the per-wake user message).

The cached wisdom of the codebase is that most of the prompt does not move. AGENTS.md sits on disk for days. The overlay is regenerated only when its version bumps or you change its config. Only the per-wake user message is genuinely composed from scratch every wake. If your assistant feels slow or expensive, the right knobs to tune are in the per-wake message section — not in the stable context.

PreviousPrompting settings
NextMemory