Skip to main content
Each model family (Claude, OpenAI, Gemini) gets a tailored system prompt, with shared rules and tool guidance appended automatically.

​
Family detection

detectModelFamily(modelId) determines which prompt to use:
Model ID PatternFamilyPrompt style
anthropic/*, claude-*claudeConcise, imperative, zero-filler
openai/*, xai/*, gpt-*, o1*, o3*openaiAgent framing, structured guidelines
google/*, gemini-*googleCore mandates, enumerated workflows
Everything elseotherGeneric, works with any model
Gateway providers (OpenRouter, LLM Gateway, Vercel AI Gateway, Proxy) are detected by inspecting the model name portion of the ID. For example, llmgateway/claude-sonnet-4 matches claude family.

​
Prompt assembly

buildSystemPrompt() assembles the final prompt from these sections:
1

Family base prompt

Identity, tone, style, workflow (per-model family).
2

Shared rules

Tool policy, conventions, commit restrictions (same for all families).
3

Tool guidance

Priority list, editing rules, dispatch rules (with/without Soul Map).
4

Project context

cwd, toolchain, project instructions (SOULFORGE.md, CLAUDE.md, etc.).
5

Forbidden files

Security patterns.
6

Editor context

Open file, cursor position, visual selection.
7

Git context

Branch, status, conflicts.
8

Memory

Persistent memory index.
9

Mode overlay

Architect, plan, auto, etc. (if active).
10

Skills reference

Static reference line.

​
Cache strategy

The system prompt is split for Anthropic prompt caching efficiency:
  • System prompt (steps 1-10) —marked with EPHEMERAL_CACHE, stable across steps
  • Soul Map —injected as a user/assistant message pair (updates after edits without invalidating the cached system prompt)
  • Skills —injected as a separate user/assistant message pair
The ~12k token system prompt + tool schemas are cached on the first turn and reused on subsequent turns.

​
Mode overlays

Modes append additional instructions to the base prompt:
ModeBehavior
defaultNo overlay —full agent
architectRead-only, produces structured architecture analysis
socraticInvestigates first, asks targeted questions
challengeAdversarial review with evidence from soul tools
planResearch, structured plan, user confirms, execute
autoAutonomous execution, minimal interruptions
Plan mode has two variants: full (high context —includes code snippets and diffs) and light (low context —just steps and descriptions).

​
Soul Map injection

The Soul Map is injected as a user/assistant message pair prepended to the conversation: 
<soul_map>
  <description>...</description>
  <how_to_use>...</how_to_use>
  <directory_tree>
    +-- src/
    |   +-- core/
    |   +-- components/
    |   +-- hooks/
    +-- tests/
  </directory_tree>
  <data>
    src/types/index.ts: (->86)
      +TaskRouter -- [types] interface: task router
      ...
  </data>
</soul_map>
This pattern (inspired by Aider’s repo map) keeps the structural context visible to the model without bloating the cached system prompt.

​
Adding a new family

  1. Create src/core/prompts/families/yourfamily.ts: 
    import { SHARED_RULES } from "./shared-rules.js";
export const YOUR_PROMPT = `You are Forge -- ...
${SHARED_RULES}`;
  2. Add to FAMILY_PROMPTS in builder.ts
  3. Add detection in provider-options.ts detectModelFamily()

​
File layout

src/core/prompts/
+-- builder.ts              # Assembles system prompt
+-- index.ts                # Module entry
+-- families/
|   +-- shared-rules.ts     # Tool policy, conventions (shared)
|   +-- claude.ts           # Claude family
|   +-- openai.ts           # OpenAI family
|   +-- google.ts           # Gemini family
|   +-- default.ts          # Fallback
+-- shared/
|   +-- tool-guidance.ts    # Tool priority list
|   +-- soul-map.ts         # Soul Map builder + directory tree
+-- modes/
    +-- index.ts            # Mode overlays