Fable Soul

Fable Soul

English | [繁體中文](README.zh-TW.md)

**A judgment layer for AI coding agents — make your AI think, verify, and communicate like a senior engineer.**

MIT licensed · Works with Claude Code & Codex · Pure Markdown + two small Python scripts, no dependencies

---

The problem

Most AI agent failures are not knowledge failures. The model knows how to write the code. What it lacks is *judgment* — the operating discipline a senior engineer applies without thinking:

What the agent does	What a senior engineer does
Edits a file, says "Done! Fixed the bug." — never ran anything	Runs the test, pastes the output, then says done
Bumps the timeout because you asked, knowing it won't help	Tells you the timeout isn't the cause, finds what is
"This should be much faster now"	"3.4s → 0.06s, measured"
Patches the symptom so the error message goes away	States the mechanism in one sentence, fixes that
Diagnoses the real bug, then asks "want me to fix it?"	Fixes it — it's in scope and reversible
Explains away a surprising test result to keep its story tidy	Stops and digs — surprise is where the real bug lives
Answers a one-line question with a 5-section report	Answers in a sentence

Fable Soul packages the right-hand column as loadable rules. Every rule was captured from a **real agent failure**, written to prevent that specific failure, and tested to confirm it actually changes behavior. It is not a collection of "best practices" prose — it is operating infrastructure.

What's inside

fable-soul/
├── SKILL.md                        # Skill entry point (3 modes: Embody / Maintain / Transfer)
├── references/
│   ├── soul.md                     # The judgment rules — the core of this project
│   ├── soul-compact.md             # Token-lean rendering installed into global files (~40% smaller)
│   ├── maintenance.md              # Mirror map, sync proc