Eugene Kravets
0da933fdee
## Summary This fixes a gap in instruction loading: `instructionFiles` could be enabled globally, but the loader still only looked in the repo root. This change: - loads enabled instruction sources from both the project directory and the user's home directory - keeps both project and global instructions in the prompt and makes global precedence explicit when both exist - adds targeted loader tests and updates the docs for prompt assembly, config, and headless behavior ## Testing - `bun test tests/instructions-loader.test.ts tests/shiki-marked.test.ts tests/prompt-builder.test.ts` - `bunx biome check src/core/instructions.ts tests/instructions-loader.test.ts`
2.9 KiB
Prompt System
SoulForge uses a modular, per-family prompt architecture. Each model family (Claude, OpenAI, Gemini) gets a tailored system prompt optimized for its strengths, with shared rules and tool guidance appended automatically.
Family Detection
SoulForge detects the model family from the model ID:
| Model ID Pattern | Family | Prompt style |
|---|---|---|
anthropic/*, claude-* |
claude |
Concise, imperative, zero-filler |
openai/*, xai/*, gpt-*, o1*, o3* |
openai |
Agent framing, structured guidelines |
google/*, gemini-* |
google |
Core mandates, enumerated workflows |
| Everything else | other |
Generic, 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
The system prompt is assembled from these sections:
- Family base prompt — identity, tone, style, workflow (per-model)
- Shared rules — tool policy, conventions, commit restrictions (same for all)
- Tool guidance — priority list, editing rules, dispatch rules
- Project context — cwd, toolchain, project instructions (project-local plus home-scoped instruction files such as
SOULFORGE.md,~/.soulforge/instructions.md,AGENTS.md, etc.) - Forbidden files — security patterns
- Editor context — open file, cursor position, visual selection
- Git context — branch, status, conflicts
- Memory — persistent memory index
- Mode overlay — architect, plan, auto, etc. (if active)
- Skills reference — loaded skill instructions
Cache Strategy
The system prompt is structured for Anthropic prompt caching efficiency:
- System prompt (all sections above) — stable across steps, cached after the first turn
- Soul Map — injected as a separate message pair (updates after edits without invalidating the cached system prompt)
- Skills — injected as a separate message pair
Mode Overlays
Modes append additional instructions to the base prompt:
| Mode | Behavior |
|---|---|
default |
No overlay — full agent |
architect |
Read-only, produces structured architecture analysis |
socratic |
Investigates first, asks targeted questions |
challenge |
Adversarial review with evidence from soul tools |
plan |
Research → structured plan → user confirms → execute |
auto |
Autonomous 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 message pair prepended to the conversation, showing the ranked file/symbol view of the codebase. This keeps structural context visible to the model without bloating the cached system prompt.