Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Static prompt fragments used to compose AI system prompts.
//!
//! Each module holds one prompt section as static strings and exports a
//! `PROMPT` static — a [`StaticPrompt`] borrowing string data with `'static`
//! lifetime. Prompts chain together via [`StaticPrompt::compose`].
#![deny(missing_docs)]
pub mod about_macro;
pub mod agent_identity;
pub mod agent_session;
pub mod channel_mention;
pub mod citations;
pub mod code_mode;
pub mod coding_agents;
pub mod connected_toolsets;
pub mod databases;
pub mod deferred_tools;
pub mod do_not;
pub mod math;
pub mod mcp_item_links;
pub mod mentions;
pub mod privacy;
pub mod pull_requests;
pub mod skills;
pub mod tone;
mod types;
pub mod user_tools;
pub use types::{ComposedPrompt, Section, StaticPrompt};
/// The base prompt: tone, math, citations, mentions, do-not rules, and Macro
/// terms. Contains no tool use instructions.
pub static BASE_PROMPT: ComposedPrompt = tone::PROMPT
.compose(&math::PROMPT)
.compose(&citations::PROMPT)
.compose(&mentions::PROMPT)
.compose(&do_not::PROMPT)
.compose(&about_macro::PROMPT);
/// [`BASE_PROMPT`] without its tone section, for agent sessions, whose
/// preamble ([`agent_session`]) sets their own tone.
static SESSION_BASE_PROMPT: ComposedPrompt = math::PROMPT
.compose(&citations::PROMPT)
.compose(&mentions::PROMPT)
.compose(&do_not::PROMPT)
.compose(&about_macro::PROMPT);
/// The tool-enabled prompt for hosts whose tools all execute directly in the
/// agent loop (the channel-mention bot, the MCP server): [`BASE_PROMPT`] with
/// the skill-following rules appended. How each area of Macro works is the
/// SDK's `@agent` guidance, which `ai_tools` composes after this. Says nothing about
/// composer-confirmed user tools — those hosts' toolsets execute
/// `CreateCalendarEvent` directly and have no `SendEmail` at all.
pub static DIRECT_TOOL_USE_PROMPT: ComposedPrompt = BASE_PROMPT.compose(&skills::PROMPT);
/// The chat tool-enabled prompt: [`DIRECT_TOOL_USE_PROMPT`] plus the rules
/// for composer-confirmed user tools (`SendEmail`, deferred execution), which
/// only apply on surfaces that can render the composer card.
pub static TOOL_USE_PROMPT: ComposedPrompt = BASE_PROMPT
.compose(&user_tools::PROMPT)
.compose(&skills::PROMPT);
/// The agent-session tool-enabled prompt: [`TOOL_USE_PROMPT`] on
/// [`SESSION_BASE_PROMPT`], with the user tool rules restated for a host that
/// reviews those calls in the turn - a review card the user answers while the
/// agent waits, not a composer left pending after it.
pub static SESSION_TOOL_USE_PROMPT: ComposedPrompt = SESSION_BASE_PROMPT
.compose(&user_tools::SESSION_PROMPT)
.compose(&skills::PROMPT);
/// Agent-session instructions in code mode: [`SESSION_TOOL_USE_PROMPT`] with
/// the [`code_mode`] section and nonblocking saved reviews.
pub static CODE_MODE_SESSION_TOOL_USE_PROMPT: ComposedPrompt = SESSION_BASE_PROMPT
.compose(&code_mode::PROMPT)
.compose(&user_tools::CODE_MODE_SESSION_PROMPT)
.compose(&skills::PROMPT);
/// Database question instructions for hosts that only discover and read data.
pub static DATABASE_READ_ONLY_TOOL_USE_PROMPT: ComposedPrompt =
BASE_PROMPT.compose(&databases::READ_ONLY_PROMPT);
/// Citation, do-not, Macro-terms and pull-request rules surfaced
/// to external MCP clients, composed together. These are static; the
/// item-linking rules for the model's own replies are not, because they
/// depend on the runtime app base URL — see [`mcp_instructions`].
///
/// Deliberately omits the in-app [`mentions`] section (MCP clients cannot render
/// `<m-document-mention>` tags in a chat reply) as well as chat tone/style and
/// general tool-use instructions, which belong to the host client, not to Macro.
/// The areas MCP clients write into (databases, CRM, document content) are the
/// SDK's `@agent` guidance, which the MCP server appends.
static MCP_STATIC_INSTRUCTIONS: ComposedPrompt = citations::PROMPT
.compose(&do_not::PROMPT)
.compose(&about_macro::PROMPT)
.compose(&pull_requests::PROMPT);
/// Builds the instructions surfaced to external MCP clients via the server
/// `instructions` field.
///
/// Carries the formatting/correctness rules Macro features depend on so that AI
/// used through MCP produces valid output. Item links in the model's own chat
/// replies are rendered as plain Markdown URLs (built from `base_url`, the
/// runtime `APP_BASE_URL` value) and lists of items as Markdown tables — NOT
/// the in-app `<m-document-mention>` markup, which MCP clients cannot render.
/// Content the model writes *into* a Macro document via `CreateDocument` or
/// `EditDocument` is the opposite: it must still use `<m-document-mention>`
/// tags (`DocumentNamespace`'s `@agent` guidance, which the MCP server
/// appends), since the Macro app renders that
/// content regardless of which surface created it. `base_url` should already
/// have any trailing slash trimmed.
pub fn mcp_instructions(base_url: &str) -> String {
format!(
"{}\n{MCP_STATIC_INSTRUCTIONS}",
mcp_item_links::render(base_url)
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn mcp_instructions_link_items_as_urls_built_from_base_url() {
let instructions = mcp_instructions("https://macro.com");
// Item links are plain URLs built from the base url, including a
// worked example for a document.
assert!(instructions.contains("https://macro.com/app/<type>/<id>"));
assert!(instructions.contains("[Name](https://macro.com/app/md/<id>)"));
assert!(instructions.contains("[Name](https://macro.com/app/routines/<id>)"));
}
#[test]
fn mcp_instructions_forbid_mention_tags_but_in_app_prompt_keeps_them() {
let instructions = mcp_instructions("https://macro.com");
// MCP responses must steer away from the in-app mention markup...
assert!(instructions.contains("Do NOT emit `<m-document-mention>`"));
// ...while the in-app base prompt still instructs the model to use it.
let in_app = BASE_PROMPT.to_string();
assert!(in_app.contains("<m-document-mention>"));
assert!(in_app.contains("use XML mention tags"));
}
#[test]
fn mcp_instructions_describe_item_table_columns() {
let instructions = mcp_instructions("https://macro.com");
for column in ["number", "name", "link"] {
assert!(
instructions.contains(column),
"instructions should describe the {column} table column"
);
}
}
#[test]
fn direct_tool_use_prompt_omits_composer_confirmed_user_tool_rules() {
// Hosts on the direct prompt (channel bot, MCP) have no composer and
// no SendEmail tool; describing deferred user tools there would tell
// the model the opposite of what its tools actually do.
let direct = DIRECT_TOOL_USE_PROMPT.to_string();
assert!(!direct.contains("PendingUserExecution"));
assert!(!direct.contains("MUST use the `SendEmail` tool"));
// The chat prompt keeps both rules.
let chat = TOOL_USE_PROMPT.to_string();
assert!(chat.contains("PendingUserExecution"));
assert!(chat.contains("MUST use the `SendEmail` tool"));
}
#[test]
fn session_tool_use_prompt_describes_a_review_in_the_turn_not_a_pending_composer() {
// An agent session finishes user tools in the turn: the model never
// sees "PendingUserExecution" there, and telling it about a composer
// to confirm in later would have it say so to the user.
let session = SESSION_TOOL_USE_PROMPT.to_string();
assert!(!session.contains("PendingUserExecution"));
assert!(session.contains("review card"));
assert!(session.contains("MUST use the `SendEmail` tool"));
assert!(session.contains("do not ask for confirmation in prose"));
}
#[test]
fn code_mode_presents_views_unasked_and_mentions_leave_what_they_show_unmentioned() {
let code_mode = CODE_MODE_SESSION_TOOL_USE_PROMPT.to_string();
assert!(
code_mode.contains("present them with `execution.views.present` without being asked")
);
assert!(
!SESSION_TOOL_USE_PROMPT
.to_string()
.contains("execution.views.present` without")
);
// The mention rule is the base prompt's; a view's items are its one
// exception, or the agent names them again under the view.
assert!(
BASE_PROMPT
.to_string()
.contains("the view already opens them")
);
}
#[test]
fn session_tool_use_prompt_routes_thread_prompts_to_prose_and_the_confirmed_send() {
// A prompt read out of a channel or document thread has no review
// card anyone is watching: the model asks in the thread, then sends
// on the user's reply through SendConfirmedEmail, quoting it.
let session = SESSION_TOOL_USE_PROMPT.to_string();
assert!(session.contains("channel or document thread"));
assert!(session.contains("context block names a conversation parent"));
assert!(session.contains("`SendConfirmedEmail`"));
assert!(session.contains("quoted verbatim"));
assert!(session.contains("`userConfirmation`"));
assert!(session.contains("`AskUser`"));
assert!(session.contains(
"`SendConfirmedEmail` and `CreateConfirmedCalendarEvent` are never right here"
));
// The thread rule is to restate what the tool would have done, whole,
// so the user can approve it without opening the session - and it
// covers every user tool, not just email: an approved event goes
// through the calendar twin of the confirmed send.
assert!(session.contains("written out verbatim"));
assert!(session.contains("the whole calendar event"));
assert!(session.contains("`CreateConfirmedCalendarEvent` for the event"));
// Which prompt is being answered decides it, not the session.
assert!(session.contains("decided per"));
}
#[test]
fn session_tool_use_prompt_treats_a_private_conversation_like_the_session_view() {
// A DM with the agent is read live: its questions and review cards
// appear there, so the thread rule does not apply to it.
let session = SESSION_TOOL_USE_PROMPT.to_string();
assert!(session.contains("private conversation with the user is the exception"));
assert!(session.contains("like one typed in the agent session view"));
}
#[test]
fn session_tool_use_prompt_keeps_the_thread_mechanics_away_from_the_user() {
// The thread rule explains review cards and the session view so the
// model knows why it writes the draft out. None of that is for the
// user, who asked for an email or an event and should just get the
// draft and a question - not a note about where their prompt came from.
let session = SESSION_TOOL_USE_PROMPT.to_string();
assert!(session.contains("The rule above is for you, not the user"));
assert!(session.contains("Never explain why you are writing the draft out"));
assert!(session.contains("not mention the agent session view, review cards"));
assert!(session.contains("does not know or care"));
assert!(session.contains("with no preamble about"));
}
#[test]
fn chat_prompt_names_the_confirmed_tools_only_to_rule_them_out() {
// The chat host has the same toolset and a composer, so the direct
// tools are visible there and must be steered away from; the direct
// prompt's hosts do not register them and say nothing about them.
let chat = TOOL_USE_PROMPT.to_string();
assert!(chat.contains("`SendConfirmedEmail`"));
assert!(chat.contains("`CreateConfirmedCalendarEvent`"));
assert!(chat.contains("never use them here"));
let direct = DIRECT_TOOL_USE_PROMPT.to_string();
assert!(!direct.contains("SendConfirmedEmail"));
assert!(!direct.contains("CreateConfirmedCalendarEvent"));
}
#[test]
fn agent_session_preamble_tells_the_model_to_emit_mention_tags() {
let preamble = agent_session::PROMPT.to_string();
assert!(preamble.contains("XML mention tag"));
assert!(preamble.contains("clickable chips"));
assert!(preamble.contains("agent session"));
assert!(preamble.contains("date/time"));
}
#[test]
fn mentions_prompt_says_a_shared_calendar_event_previews_for_channel_members() {
let instructions = mentions::PROMPT.instructions.as_ref();
assert!(instructions.contains("read-only preview"));
assert!(instructions.contains("Private and confidential events are never shared"));
}
#[test]
fn mentions_prompt_writes_whole_days_as_local_dates_from_the_current_time() {
let instructions = mentions::PROMPT.instructions.as_ref();
assert!(instructions.contains("bare local calendar date (`2025-12-01`)"));
assert!(instructions.contains("never midnight UTC"));
assert!(instructions.contains("`<current_time>`"));
}
#[test]
fn mentions_prompt_covers_date_and_agent_session_chips() {
let instructions = mentions::PROMPT.instructions.as_ref();
assert!(instructions.contains("<m-date-mention>"));
assert!(instructions.contains("<m-agent-session-mention>"));
assert!(instructions.contains("<m-user-mention>"));
assert!(instructions.contains("\"expanded\":true"));
assert!(instructions.contains("\"blockName\":\"skill\""));
assert!(instructions.contains("\"blockName\":\"initiative\""));
assert!(instructions.contains("\"blockName\":\"pipeline\""));
assert!(instructions.contains("\"blockName\":\"routine\""));
}
#[test]
fn mcp_and_coding_agents_open_ready_pull_requests_with_ci_passing() {
assert!(mcp_instructions("https://macro.com").contains(pull_requests::READY_PULL_REQUEST));
let coding = coding_agents::PROMPT.to_string();
assert!(coding.contains("ready for review, not a draft"));
assert!(coding.contains("CI passing"));
}
#[test]
fn agent_identity_names_the_agent_before_the_session_preamble() {
let identity = agent_identity::render("Grunk", "grunk");
assert!(identity.starts_with("# Identity\n"));
assert!(identity.contains("You are Grunk (@grunk)."));
}
#[test]
fn markdown_surface_scope_names_every_surface_but_the_reply_tone_exception() {
// The mention rule must name every Markdown-authoring surface and the
// non-Markdown-document exception, and the tool-use tone rule must not
// silently bleed into tool-authored content.
let in_app = TOOL_USE_PROMPT.to_string();
for surface in [
"SendChannelMessage",
"SendEmail",
"CreateDocument",
"agent session",
] {
assert!(
in_app.contains(surface),
"markdown surface scope should name {surface}"
);
}
assert!(in_app.contains("non-Markdown documents"));
assert!(in_app.contains("apply to your own conversational replies only"));
}
}
/// Compose runtime sections in their supplied order without retaining their data.
pub fn compose(sections: &[&dyn std::fmt::Display]) -> String {
sections
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>()
.join("\n")
}