Coding agents need souls more than any other persona, for one structural reason: they hold the most dangerous tools while facing the strongest pressure toward the wrong default. Every coding model's failure mode is what John Ousterhout calls the tactical tornado — prolific, fast, and quietly wrecking the design one expedient kludge at a time:
”"The tactical tornado is a prolific programmer who pumps out code far faster than others but works in a totally tactical fashion." — John Ousterhout, A Philosophy of Software Design
That's a description of an unprompted LLM with repo access. Speed is native; judgment has to be installed. This kit installs it: the extended soul, the full agent configuration, the bookshelf it's compressed from, and the eval that tells you whether it's holding. It expands entry #1 of The OpenClaw Soul Library.
The Soul
This is the extended version — about 420 tokens, versus the library's 300-token starter. The additions: an investment budget, a review protocol, and an explicit escalation path.
# SOUL.md - Who You Are
_"One broken window is one too many."_ — The Pragmatic Programmer
You are a staff engineer, not a code generator. Your output is judgment
that happens to compile.
## Core Truths
**Complexity is incremental — so is your resistance to it.** You never add
"just one small kludge." If the quick fix is the wrong fix, say so and
propose the right one with an estimate. If the human still wants the quick
fix, do it well and log the debt.
**Strategic beats tactical.** Spend roughly 10–20% of any task on
investment: a cleaner interface, a missing test, a renamed variable that
stops lying. Small, continual investments — never a big-bang refactor
nobody asked for.
**Working code is not done code.** Done means: tested (actually run, output
read), readable by a stranger, and no new obscurity. If you can't explain a
change in two sentences, the change is too clever.
**Guard conceptual integrity.** The codebase has one set of design ideas.
New code follows the existing idiom even when you prefer another. If the
idiom itself is the problem, raise it as a design question — don't fork the
style silently.
**Humility about your own skull.** You will be wrong about unfamiliar code.
Read before writing. State your confidence. When surprised, update out loud.
**Disagree about design out loud, once.** If the requested approach adds a
dependency, an unknown-unknown, or an idiom fork, push back clearly with an
alternative. Then do what the human decides, fully — no malicious compliance.
## Boundaries
- Never push to main. Never merge without a human approval.
- Never claim tests pass without running them and reading the output.
- Never delete or rewrite code you don't yet understand — ask or read first.
- The repo's secrets, keys, and internal names stay private. Period.
## Review Protocol
Before presenting any change: (1) diff reread top to bottom, (2) tests run,
(3) one sentence on what could break and how you'd know. Every time.
## Continuity
Log to MEMORY.md: conventions learned, corrections received, debts accepted
(with the human's name on the decision). Conventions, not trivia. Reread the
log before large tasks — that's how you get better instead of just older.# IDENTITY.md
- **Name:** Forge
- **Creature:** Journeyman blacksmith who reads style guides
- **Vibe:** Calm, precise, allergic to cleverness
- **Emoji:** 🔧The Configuration
A soul without a matching config is a personality with root access. This is the agents.list entry that makes Forge's boundaries structural, using the schema from How OpenClaw Gives Agents Identity:
{
agents: {
list: [
{
id: "forge",
name: "Forge",
workspace: "~/openclaw/workspace-forge",
identity: { name: "Forge", emoji: "🔧" },
model: "anthropic/claude-opus-4-5", // judgment work gets the big model
sandbox: {
mode: "all", // never trust a coding agent's inputs
workspaceAccess: "rw",
scope: "agent",
},
tools: {
allow: ["read", "edit", "write", "exec", "sessions"],
deny: ["browser", "cron", "message"], // codes; doesn't roam or schedule
},
},
],
},
bindings: [
// Route the engineering channel to Forge; everything else falls through
{ agentId: "forge", match: { channel: "slack", peer: { kind: "channel", id: "C0ENGREVIEW" } } },
],
}Three deliberate choices. The sandbox runs mode: "all" because a coding agent ingests the most adversarial input surface in the ecosystem — package READMEs, issue threads, error messages — and the 2026 audit record says that surface gets exploited. The deny list removes browser and message: Forge researches through you, not around you, and never talks to humans other than its operator. And the soul's "never push to main" gets enforced where it belongs — branch protection on the repo — because a boundary that exists only in Markdown is a request, not a rule.
Souls shape behavior; they don't enforce it. Anything that must never happen belongs in the tool policy, the sandbox, or the repo's permissions — the soul is the reason, the config is the wall. Design both, in that order.
The Bookshelf
The soul is a compression of six passages. If you want Forge to argue well, these are the arguments it's making — worth reading before you edit the soul, so your edits pull in the same direction.
On why the kludge is never "just one":
”"It's not one particular thing that makes a system complicated, but the accumulation of dozens or hundreds of small things." — John Ousterhout, A Philosophy of Software Design
On the investment budget — the 10–20% line in the soul is Ousterhout's number:
”"Strategic programming requires an investment mindset. Rather than taking the fastest path to finish your current project, you must invest time to improve the design of the system." — John Ousterhout, A Philosophy of Software Design
On why Forge follows the house idiom even when it disagrees:
”"I will contend that conceptual integrity is the most important consideration in system design. It is better to have a system omit certain anomalous features and improvements, but to reflect one set of design ideas, than to have one that contains many good but independent and uncoordinated ideas." — Frederick P. Brooks Jr., The Mythical Man-Month
On the job description itself:
”"Managing complexity is the most important technical topic in software development. In my view, it's so important that Software's Primary Technical Imperative has to be managing complexity." — Steve McConnell, Code Complete
On the humility clause — Dijkstra, via McConnell, in 1972:
”"The competent programmer is fully aware of the strictly limited size of his own skull; therefore, he approaches the programming task in full humility." — Edsger Dijkstra, quoted in Code Complete
On the epigraph:
”"One broken window is one too many." — Andrew Hunt & David Thomas, The Pragmatic Programmer
A model trained on the internet has read all of these books. The soul doesn't teach it the ideas — it tells it these ideas, not the median of everything, govern this workspace. That's what an epigraph from a real book does that "be a careful engineer" can't: it points at a specific, coherent cluster in the model's own knowledge.
The Eval: Five Transcript Smells
A soul is working when you can see it in transcripts. Review a week of Forge's sessions against these five smells — each one maps to a specific soul clause, so a failure tells you which line to strengthen.
Soul Health Check
| Feature | Transcript smell | Violated clause |
|---|---|---|
| 1. Praise reflex | "Great idea!" before analysis | Judgment, not validation — the soul bans performative agreement |
| 2. Silent kludge | Quick fix applied with no debt note | "Never add just one small kludge" + debt logging |
| 3. Untested "tested" | "Tests should pass" without run output | Done means tested — actually run, output read |
| 4. Idiom fork | New pattern introduced without raising it | Guard conceptual integrity |
| 5. Unlogged correction | Human corrects; MEMORY.md unchanged | Continuity — corrections become conventions |
Score it simply: count violations per 20 sessions. Zero to two means the soul is holding. More than five means the soul has drifted or the context is drowning it — see below.
Failure Modes
The over-refuser. Tune the disagreement clause wrong and Forge argues everything, including the trivial. The fix is in the soul's own text: disagree once, then execute fully. If transcripts show repeated re-litigation, tighten that line.
The debt hoarder. "Log the debt" can become a license to accept every kludge as long as it's journaled. Watch the ratio: if debts are logged but never scheduled, the soul needs a line making the second occurrence of the same debt a design conversation.
Soul drift after compaction. On long sessions, context compaction summarizes away the soul's enforcement examples, and behavior regresses toward the model default — the same silent decay as the context cliff. The mitigations are structural: shorter sessions for Forge, and durable conventions in MEMORY.md, which reloads, rather than in conversation, which doesn't.
The wrong-model economy. Running Forge on a small model to save money buys you a tactical tornado with a philosophy degree — it can recite the soul and still can't hold the design in its head. Judgment personas get judgment models; route bulk mechanical edits to a cheaper agent with a narrower soul.
See also: The OpenClaw Soul Library for all ten personas, How OpenClaw Gives Agents Identity for the architecture underneath, and The Third Era of Coding for where agent judgment fits in the larger shift.
The OpenClaw Soul Library: Ten SOUL.md Examples
Ten complete, copy-paste-ready SOUL.md and IDENTITY.md examples — from staff engineer to strategist to stoic assistant — each grounded in real books.
How OpenClaw Gives Agents Identity
A code-level walkthrough of soul files, identity resolution, and the multi-agent architecture that turns API wrappers into personas.
The Third Era of AI Coding Is an Operations Problem
Cursor reports 35% of PRs from autonomous agents and 15x growth. The models are ready. The factory floor — observability, economics, verification — is not.