MobilityOps/CLAUDE.md

Binding instructions for Claude

Operating mode

Work autonomously. Do not ask the user product, architecture, naming, UI, scope or implementation questions already answered in this repository. Record a reasonable assumption in an ADR only when a genuine gap blocks implementation.

Use normal or medium reasoning for routine work. Reserve high reasoning for an actual cross-service design conflict or a persistent failure after evidence-driven debugging.

Continue from milestone to milestone until every acceptance criterion is satisfied. Do not stop merely because one milestone is complete.

Token and tool efficiency

1. Read START_HERE.md, this file, PROJECT_STATE.md and docs/15-build-plan.md first.
2. Read only the milestone-specific documents named in the build plan.
3. Do not repeatedly reread all documentation.
4. Keep explanations terse; spend effort on implementation and validation.
5. Update PROJECT_STATE.md after each milestone with decisions, commands, evidence and the exact next action.
6. Prefer focused file inspection and targeted tests over broad repository scans.
7. Do not generate large speculative documents after implementation starts.

Scope discipline

• Build the locked PoC only.
• Do not add accounting, payments, public reservations, a generic CRM, inventory, HR, a second RAG stack, a separate MCP server or autonomous write actions.
• Do not modify the RAGcore or ITWorx MCP Hub repositories. Integrate only through documented contracts and configurable adapters.
• Keep critical business rules in MobilityOps code, not in n8n or prompts.
• No direct MCP Hub or RAGcore access to the MobilityOps database.

Product quality

• No dead buttons, empty routes, unexplained placeholders or hardcoded dashboard metrics.
• Every visible number must derive from persisted data.
• All important state changes must be audited.
• AI must never invent an answer when RAGcore is unavailable or returns insufficient evidence.
• Vehicle returns must commit locally even when n8n is unavailable; orchestration becomes pending and retryable.
• External dependencies require timeouts, bounded retries, health state and graceful degradation.
• Demo data must be clearly labelled synthetic.

Engineering rules

• Backend: Python, FastAPI, SQLAlchemy 2, Alembic, PostgreSQL.
• Frontend: React, TypeScript, Vite, accessible responsive UI.
• Validation: Pydantic at API boundaries and database constraints for invariants.
• Use UUID primary keys internally and stable human-readable public references.
• Store UTC timestamps; render Europe/Brussels in the UI.
• API paths start with /api/v1.
• Use an outbox record for reliable post-commit n8n delivery.
• Tests must cover domain rules, API contracts and the five-minute Playwright demo.
• Generate and commit dependency lockfiles.

Git workflow

Create one coherent commit per milestone after its validation passes. Suggested message format:

M1: implement operational core

Never rewrite already accepted milestone history unless necessary to fix a regression.

Definition of done

The project is done only when docs/14-testing-and-acceptance.md passes from a clean checkout and PROJECT_STATE.md contains the final evidence summary.