Cross-tool guidance for AI coding assistants working on the Wheels
framework repository itself (maintainers). Claude Code also auto-loads
the more detailed CLAUDE.md next to this file.
The wheels repo IS the Wheels CFML framework: vendor/wheels/ is the
framework source (not a dependency), vendor/wheels/tests/specs/ is the
suite CI runs across every engine × database, cli/lucli/ is the wheels
CLI, and app/ is a demo app for hand-testing.
- Read
CLAUDE.mdfirst — the Cross-Engine Invariants and Anti-Patterns there cause more failures than anything else. Every change tovendor/wheels/**must keep the framework green on Lucee, Adobe CF, BoxLang (and best-effort RustCFML). - Two-tier docs. AI docs for APPLICATION developers live in
docs/consumer-ai/and ship in every distribution (ForgeBox core, starter app,wheels newscaffolds). Maintainer docs (this file,CLAUDE.md,.ai/) never ship. If you change a user-facing quick reference, update the consumer copy too —tools/build/scripts/ship-consumer-docs.sh checkenforces the split in CI. - Test before reporting done —
bash tools/test-local.sh [area]for framework changes; see the "Before Reporting a Change Complete" table inCLAUDE.md. - Commit conventions — conventional commits with DCO sign-off
(
git commit -s); user-facing changes add achangelog.d/fragment.
CLAUDE.md— invariants, anti-patterns, test/verification workflow (read first).ai/— deep reference docs (maintainer runbooks and Wheels internals), searched on demanddocs/releases/wheels-5-roadmap.md— the committed 5.0 directiondocs/releases/wheels-4.x-backlog.md— candidate items for the current 4.x line.claude/commands/— wheels-bot prompts run by the bot-*.yml workflowsdocs/consumer-ai/— the consumer AI doc tier (ships in artifacts)