Home

Cadillac Wiki

Companion documentation to the README. The README is the elevator pitch and quick start. The wiki is where the depth lives — design rationale, full reference material, and the why behind every choice.

🚀 Start here

• 👋 New to the project? Read the README first
• 🛠 Already building? Skip to Tool API or CLI Reference
• 🤔 Wondering why some choice was made? See the FAQ

📖 Contents

Concepts

• 🏗 Architecture — the phase loop, state machine, flat vs modular pipelines, inspector, contracts, wiring, retry semantics
• ✅ Validation Pipeline — every one of the 12 checks, what each catches, how false positives are guarded
• 🛡 Resilience Stack — SPEC, CRITIC, RUNTIME, surgical mode, progressive tiers — the five layers between BUILD and PACKAGE
• 🧠 Memory System — Lesson schema, recall scoring, dedup, cross-task decay, the improve-cycle meta-lessons
• 🔁 Improve Cycle — closed-loop self-improvement, the curated matrix, audit → correlate → propose → apply → verify
• 🗂 Workspace Anatomy — what's in a workspace directory, .cadillac/ subdir, persisted artifacts

Reference

• 🛠 Tool API — every tool the LLM can call, with signature + when allowed
• 💻 CLI Reference — every subcommand, every flag, env vars, the interactive shell
• 🌐 Languages — Python / TypeScript / React / Vue / Angular / Electron / Go / Rust / WordPress / browser-ext / PyTorch

Help

• 🚑 Troubleshooting — common issues and resolutions
• ❓ FAQ — design rationale, comparisons to other coding agents
• 📖 Glossary — terms used throughout the docs and source

🔗 Quick links into the codebase

Subsystem	Source	What it does
Phase loop	cadillac/engine.py:run()	The while True over phases — every iteration is one round
Phase state	cadillac/phases.py	Phase enum, budgets, retry counters, tier state
Validation	cadillac/validate.py	The 12-check gate; WIRING dynamic probe; contract alignment
Operational gates	cadillac/operational.py	Schema integrity, missing-env, SIGTERM probes
SPEC	cadillac/spec.py	Task → user stories (must/should/could)
CRITIC	cadillac/critic.py	Completeness audit (static prefilter + LLM second opinion)
RUNTIME	cadillac/runtime/	HTTP / CLI / library strategy dispatch + runners
Surgical mode	cadillac/surgical.py	Stuck-loop targeted fix with cross-module hints
Memory	cadillac/memory.py	Lessons + tag-aware recall + cross-task decay
Improve cycle	cadillac/improve/	Self-improvement against a curated matrix
Tools	cadillac/tools.py	Sandboxed I/O — read_file, write_file, edit_file, run_command, ...
Languages	cadillac/languages.py	Per-language toolchain config
Dashboard	cadillac/dash.py	Zero-service TUI for browsing past + live builds

📝 Contributing to the wiki

The wiki is itself a git repo:

git clone https://github.com/mtecnic/cadillac.wiki.git
# edit pages as Markdown
git push origin master

Pages use GitHub Wiki conventions:

• Each .md file becomes a page; filename = page slug
• Spaces in filenames become hyphens in URLs (Tool-API.md → /wiki/Tool-API)
• Internal links use [Link Text](Page-Name) syntax (no .md extension)