diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 9bc8c9e..09cf4d6 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -4,26 +4,29 @@ | Directory | What | When to read | | --------- | ---- | ------------ | -| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution | -| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work | -| `skills/` | Reusable skills | Complex multi-step workflows | -| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior | -| `output-styles/` | Output formatting templates | Customizing agent output | -| `tdd-guard/` | TDD enforcement utilities | Test-driven development | +| `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 | -## Quick Reference +## Skills (`skills/`) -| Path | What | When | -|------|------|------| -| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution | -| `role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review | -| `skills/planner/` | Planning workflow | Complex features | -| `skills/problem-analysis/` | Problem decomposition | Uncertain approach | -| `skills/decision-critic/` | Stress-test decisions | Architectural choices | -| `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas | -| `skills/doc-sync/` | Documentation sync | After refactors | -| `skills/incoherence/` | Detect doc/code drift | Periodic audits | -| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts | -| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work | -| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior | -| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow | +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 | diff --git a/CLAUDE.md b/CLAUDE.md index 1c047a0..b6e084c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,12 +25,12 @@ Maintain a constructive approach. Your role is not to argue for the sake of argu | --------- | ---- | ------------ | | `backend/` | Fastify API server with feature capsules | Backend development | | `frontend/` | React/Vite SPA with MUI | Frontend development | -| `ocr/` | Python OCR microservice (Tesseract) | OCR pipeline, receipt/VIN extraction | +| `ocr/` | Python OCR microservice (PaddleOCR / Google Cloud Vision engines, Gemini for schedule/VIN extraction) | OCR pipeline, receipt/VIN extraction | | `docs/` | Project documentation hub | Architecture, APIs, testing | | `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup | | `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks | | `.ai/` | AI context and workflow contracts | AI-assisted development | -| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills | +| `.claude/` | Claude Code skill library and configuration | Using a skill, checking project conventions | | `.gitea/` | Gitea workflows and templates | CI/CD, issue templates | | `ansible/` | Ansible deployment playbooks | Server provisioning | | `certs/` | TLS certificates | SSL/TLS configuration | @@ -46,10 +46,14 @@ make rebuild # Rebuild containers ## Test +Root `package.json` has no `scripts` block — `npm test` at repo root fails. Run per workspace: + ```bash -npm test # Run all tests -npm run lint # Linting -npm run type-check # TypeScript validation +cd backend && npm test && npm run lint && npm run type-check +cd frontend && npm test && npm run lint && npm run type-check +# lint and type-check across both workspaces without cd: +make lint +make type-check ``` --- @@ -104,35 +108,32 @@ All methods returning data to the API must use these mappers - never return raw ## Development Workflow (Local + CI/CD) ### Local Development +Root `package.json` has no `scripts` block; install and run dev servers per workspace: ```bash -npm install # Install dependencies -npm run dev # Start dev server -npm test # Run tests -npm run lint # Linting -npm run type-check # TypeScript validation +cd backend && npm install && npm run dev +cd frontend && npm install && npm run dev ``` +Test/lint/type-check commands: see the Test section above. ### CI/CD Pipeline (on PR) -- Container builds and integration tests -- Mobile/desktop viewport validation -- Security scanning +The Gitea pipeline (`.gitea/workflows/staging.yaml`) builds the backend, frontend, and ocr Docker images, deploys them to the shared staging environment, and health-checks the deployment (container health checks plus `/api/health`). It runs no tests, no lint, no type-check, and no security scan. Validation is entirely the author's responsibility before opening a PR — see `.claude/skills/mvp-validation-and-qa/SKILL.md` for the evidence bar and definition of done. -**Flow**: Local dev -> Push to Gitea -> CI/CD runs -> PR review -> Merge +**Flow**: Local dev -> author self-gates (lint/type-check/tests) -> Push to Gitea -> CI builds images and deploys/health-checks staging -> PR review -> Merge ## Quality Standards ### Automated Checks Are Mandatory -**ALL hook issues are BLOCKING - EVERYTHING must be ✅ GREEN!** +**ALL hook issues are BLOCKING - EVERYTHING must be GREEN!** - No errors. No formatting issues. No linting problems. Zero tolerance - These are not suggestions. Fix ALL issues before continuing ### Code Completion Criteria Our code is complete when: -- ✅ All linters pass with zero issues -- ✅ All tests pass -- ✅ Feature works end-to-end -- ✅ Old code is deleted +- All linters pass with zero issues +- All tests pass +- Feature works end-to-end +- Old code is deleted ## AI Collaboration Strategy @@ -165,15 +166,15 @@ Leverage subagents aggressively for better results: Canonical sources only - avoid duplication: - Architecture and metadata: `.ai/context.json` -- Sprint workflow contract: `.ai/workflow-contract.json` +- Issue workflow: `.claude/skills/mvp-change-control/SKILL.md` - Documentation hub: `docs/README.md` - Feature work: `backend/src/features/{feature}/README.md` - Platform architecture: `docs/PLATFORM-SERVICES.md` - Testing workflow: `docs/TESTING.md` -## Sprint Workflow +## Issue Workflow -Issues are the source of truth. See `.ai/workflow-contract.json` for complete workflow. +Issues are the source of truth; work flows directly from issues by priority (sprints and milestones are not used). Full workflow, quality-review taxonomy (RULE 0/1/2), and label discipline: `.claude/skills/mvp-change-control/SKILL.md`. ### Quick Reference - Every PR must link to at least one issue @@ -183,7 +184,7 @@ Issues are the source of truth. See `.ai/workflow-contract.json` for complete wo - Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`) ### Sub-Issue Decomposition -Multi-file features (3+ files) must be broken into sub-issues for smaller AI context windows: +Multi-file changes (3+ files) must be broken into sub-issues for smaller AI context windows: - **Sub-issue title**: `{type}: {summary} (#{parent_index})` -- parent index in title - **Sub-issue body**: First line `Relates to #{parent_index}` - **ONE branch** per parent issue only. Never branch per sub-issue. @@ -201,24 +202,24 @@ Multi-file features (3+ files) must be broken into sub-issues for smaller AI con - **Feature Capsule Organization**: Application features are self-contained modules within the backend - **Single-Tenant**: All data belongs to a single user/tenant - **User-Scoped Data**: All application data isolated by user_id -- **Local Dev + CI/CD**: Development locally, container testing in CI/CD pipeline +- **Local Dev + CI/CD**: Development and testing locally; CI/CD builds images and health-checks the staging deploy (see CI/CD Pipeline section) - **Integrated Platform**: Platform capabilities integrated into main backend service ### Common AI Tasks See `Makefile` for authoritative commands and `docs/README.md` for navigation. -## Agent System +## Skill Library -| Directory | Contents | When to Read | -|-----------|----------|--------------| -| `.claude/role-agents/` | Developer, TW, QR, Debugger | Delegating execution | -| `.claude/role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review | -| `.claude/skills/planner/` | Planning workflow | Complex features (3+ files) | -| `.claude/skills/problem-analysis/` | Problem decomposition | Uncertain approach | -| `.claude/agents/` | Domain agents | Feature/Frontend/Platform work | -| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow | +Reusable domain knowledge lives in `.claude/skills/` as 16 `mvp-*` skills, one directory per topic. Each skill's `SKILL.md` frontmatter `description` states exactly when to load it — full index at `.claude/CLAUDE.md`. Key entry points: -### Quality Rules (see quality-reviewer.md for full definitions) +| Skill | Use for | +|-------|---------| +| `.claude/skills/mvp-change-control/SKILL.md` | Issue/branch/PR workflow, quality-review taxonomy (RULE 0/1/2) | +| `.claude/skills/mvp-debugging-playbook/SKILL.md` | Triaging a live failure | +| `.claude/skills/mvp-architecture-contract/SKILL.md` | System invariants (e.g. mobile/desktop screen registration) | +| `.claude/skills/mvp-validation-and-qa/SKILL.md` | Definition of done, test evidence bar | + +### Quality Rules (see `mvp-change-control` for full definitions) - **RULE 0 (CRITICAL)**: Production reliability - unhandled errors, security, resource exhaustion - **RULE 1 (HIGH)**: Project standards - mobile+desktop, naming, patterns, CI/CD pass - **RULE 2 (SHOULD_FIX)**: Structural quality - god objects, duplication, dead code