Fable Soul provides a set of judgment rules and tooling to make AI coding agents think, verify, and communicate like senior engineers, based on real agent failures and tested behavior changes.

Stars

106

7-day growth

No data

Forks

26

Open issues

0

License

MIT

Last updated

2026-07-08

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

It packages executable discipline—not just advice—as loadable rules with RED-GREEN verification, a rationalization table to counter model excuses, and sync/drift tooling for consistent enforcement across sessions and machines.

Who it is for

  • AI coding agent users (e.g., Claude Code, Codex)
  • Software engineers who rely on AI assistants for development
  • Teams seeking to standardize AI behavior and reduce costly errors
  • Developers building custom instruction layers for AI agents

Use cases

  • Preventing an AI agent from claiming 'done' without running tests
  • Forcing root‑cause analysis before accepting a bug fix
  • Distilling a stronger model's judgment into rules for a cheaper model
  • Continuously capturing and fixing an agent's recurring failure patterns

Strengths

  • Rules are captured from real agent failures and tested via RED‑GREEN runs (evals.md shows recorded scenarios)
  • Lightweight: pure Markdown + two small Python scripts, no dependencies, works with multiple runners
  • Includes a rationalization table that counters common model excuses, making rules harder to bypass
  • Modular design with sync tooling ensures single source of truth and drift detection across install locations

Considerations

  • Requires manual setup and periodic maintenance (e.g., running sync scripts, growing rules via capture loop)
  • Effectiveness depends on the quality of the user's own failure capture and rule refinement
  • May increase session token usage when installed as always‑on global instructions, though a compact variant is provided

README quick start

Fable Soul

English | 繁體中文

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 doesWhat a senior engineer does
Edits a file, says "Done! Fixed the bug." — never ran anythingRuns the test, pastes the output, then says done
Bumps the timeout because you asked, knowing it won't helpTells 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 awayStates 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 tidyStops and digs — surprise is where the real bug lives
Answers a one-line question with a 5-section reportAnswers 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 procedure, failure-capture loop
│   ├── transfer-prompts.md         # 6 prompt templates for turning experience into skills
│   ├── evals.md                    # Behavioral eval scenarios + recorded RED-GREEN runs
│   └── worked-examples.md          # Captured failures with before/after receipts
├── examples/
│   └── hooks.json                  # Optional Stop-hook enforcement for Claude Code
└── scri

Description

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

Related repositories

Similar projects matched by category, topics, and programming language.

lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390
slvDev
Featured
slvDev GitHub avatar

esp32-ai

A 28.9 million parameter language model runs on an $8 ESP32-S3 microcontroller entirely on-device, generating simple stories at about 9.5 tokens per second.

AI & Machine LearningLarge Language Models
1,960
littledivy
Featured
littledivy GitHub avatar

mimic

mimic captures traffic from any iOS or web app and automatically generates a Python client library that lets you call the app's API like a regular library.

AI & Machine Learning
1,482