motovaultpro/.claude/CLAUDE.md

.claude/

Subdirectories

Directory	What	When to read
agents/	Role subagent definitions with pinned models (see Agents table below)	Delegating work to a subagent; changing a model pin
skills/	16 mvp-* reusable knowledge skills, one directory each (see Skills table below)	Loading project-specific knowledge before a task
output-styles/	Output formatting templates (direct.md)	Customizing response style
tdd-guard/	TDD-guard tool state (test/modification tracking data)	Debugging TDD-guard behavior

Agents (agents/)

Each agent is agents/{name}.md; frontmatter pins its model. Agents are role executors - each one's prompt directs it to read the relevant skills/ SKILL.md files before acting, so skills stay the single source of domain knowledge.

Agent	Model	Role	Primary skills read
developer	sonnet	Implement scoped code changes, self-gate lint/type-check/tests	mvp-architecture-contract, mvp-change-control
debugger	sonnet	Root-cause a symptom with evidence; no fixes unless asked	mvp-debugging-playbook, mvp-failure-archaeology
quality-reviewer	opus	RULE 0/1/2 merge-gate review; read-only toolset	mvp-change-control, mvp-validation-and-qa
operator	sonnet	Deploys, rollbacks, backups, CI workflow changes	mvp-run-and-operate, mvp-deploy-safety-campaign
tech-writer	sonnet	Doc-sync and new docs under house style	mvp-docs-and-writing, mvp-launch-readiness

Skills (skills/)

Each skill is skills/{name}/SKILL.md; its frontmatter description states exactly when to load it — this table is a condensed pointer, not a substitute for reading it.

Skill	What	When to read
mvp-architecture-contract/	Load-bearing architecture decisions, invariants, and known weak points	Designing, extending, or reviewing a feature or refactor
mvp-build-and-env/	Fresh-checkout setup and build/test/install failure triage	Any local build, install, or test command fails
mvp-change-control/	Issue/branch/PR workflow, RULE 0/1/2 quality-review taxonomy, label discipline	Making any repo change, reviewing code, asking "is this safe to merge"
mvp-config-and-secrets/	Env vars, config fields, Docker secrets, feature flags, tier gates	Adding/changing config or secrets; startup config errors
mvp-debugging-playbook/	Symptom-to-root-cause triage index	Diagnosing a live bug from its symptom
mvp-deploy-safety-campaign/	CI/CD safety gaps (no tests/lint/security gate, :latest tag hazard) and the plan to close them	Working on CI/CD pipeline safety
mvp-diagnostics-and-logging/	Grafana/Loki/LogQL, health checks, redis-cli, shipped diagnostic scripts	Observing or measuring the running system instead of guessing
mvp-docs-and-writing/	Doc trust map, house style, doc-sync discipline, temporal-contamination rule	Reading or writing any documentation, including CLAUDE.md files
mvp-failure-archaeology/	Chronicle of past incidents, dead ends, and reverts with root cause and evidence	Before re-investigating a familiar-smelling bug or deleting old-looking code
mvp-launch-readiness/	Pre-launch blockers and guardrails for external/user-facing claims	Assessing launch readiness or writing a public claim about the product
mvp-ocr-gemini-pipeline/	OCR engine stack, Gemini semantic extraction, VIN decode, WIF auth chain	Working on OCR, VIN decode, or email-ingestion features
mvp-proof-and-analysis-toolkit/	Prove-it methods for high-stakes decisions and stuck bugs	Before committing to an architectural/design decision, or after a failed fix attempt
mvp-research-frontier/	Open problems and methodology for proposing/validating new work	Seeding the next piece of work; the issue tracker is empty
mvp-run-and-operate/	Deploy, rollback, blue/green switch, backup/restore procedures	Operating staging or production environments
mvp-validation-and-qa/	Evidence bar and definition of done; real test-suite map	Before claiming a change is done, tested, or ready to merge
mvp-vehicle-domain-reference/	Vehicle domain theory: VIN validation/decode, MPG/unit conversion, tiers	Working on VIN, fuel-efficiency, unit-conversion, or tier-limit logic