egullickson/motovaultpro
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: correct CLAUDE.md CI claims and repoint to the mvp-* skill library
Deploy to Staging / Build Images (push) Successful in 11s
Details
Deploy to Staging / Deploy to Staging (push) Successful in 42s
Details
Deploy to Staging / Verify Staging (push) Successful in 4s
Details
Deploy to Staging / Notify Staging Ready (push) Successful in 3s
Details
Deploy to Staging / Notify Staging Failure (push) Has been skipped
Details
Mirror Base Images / Mirror Base Images (push) Successful in 18s
Details

Browse Source 
Root CLAUDE.md: state the actual CI pipeline (image builds + staging deploy
+ health checks; no tests, lint, or security scanning), replace root-level
npm commands with per-workspace equivalents, correct the OCR engine
description, rename Sprint Workflow to Issue Workflow (sprints unused), and
replace the retired agent-system references with the skill library entry
points. Remove emoji from Quality Standards per the project's own rule.
.claude/CLAUDE.md: rewrite as a pure index of the current .claude/ contents
with one row per mvp-* skill.

Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
Eric Gullickson
2026-07-10 19:02:43 -05:00
co-authored by Claude Fable 5
parent c239bb9347
commit 59fdb85e4e
2 changed files with 59 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/CLAUDE.md
+24 -21
View File
@@ -4,26 +4,29 @@
| Directory | What | When to read | | Directory | What | When to read |
| --------- | ---- | ------------ | | --------- | ---- | ------------ |
| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution | | `skills/` | 16 `mvp-*` reusable knowledge skills, one directory each (see Skills table below) | Loading project-specific knowledge before a task |
| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work | | `output-styles/` | Output formatting templates (`direct.md`) | Customizing response style |
| `skills/` | Reusable skills | Complex multi-step workflows | | `tdd-guard/` | TDD-guard tool state (test/modification tracking data) | Debugging TDD-guard behavior |
| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior |
| `output-styles/` | Output formatting templates | Customizing agent output |
| `tdd-guard/` | TDD enforcement utilities | Test-driven development |
## Quick Reference ## Skills (`skills/`)
| Path | What | When | 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.
|------|------|------|
| `role-agents/` | Developer, TW, QR, Debugger agents | Delegating execution | | Skill | What | When to read |
| `role-agents/quality-reviewer.md` | RULE 0/1/2 definitions | Quality review | | ----- | ---- | ------------- |
| `skills/planner/` | Planning workflow | Complex features | | `mvp-architecture-contract/` | Load-bearing architecture decisions, invariants, and known weak points | Designing, extending, or reviewing a feature or refactor |
| `skills/problem-analysis/` | Problem decomposition | Uncertain approach | | `mvp-build-and-env/` | Fresh-checkout setup and build/test/install failure triage | Any local build, install, or test command fails |
| `skills/decision-critic/` | Stress-test decisions | Architectural choices | | `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" |
| `skills/codebase-analysis/` | Systematic investigation | Unfamiliar areas | | `mvp-config-and-secrets/` | Env vars, config fields, Docker secrets, feature flags, tier gates | Adding/changing config or secrets; startup config errors |
| `skills/doc-sync/` | Documentation sync | After refactors | | `mvp-debugging-playbook/` | Symptom-to-root-cause triage index | Diagnosing a live bug from its symptom |
| `skills/incoherence/` | Detect doc/code drift | Periodic audits | | `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 |
| `skills/prompt-engineer/` | Prompt optimization | Improving AI prompts | | `mvp-diagnostics-and-logging/` | Grafana/Loki/LogQL, health checks, redis-cli, shipped diagnostic scripts | Observing or measuring the running system instead of guessing |
| `agents/` | Domain agents (Feature, Frontend, Platform, Quality) | Domain-specific work | | `mvp-docs-and-writing/` | Doc trust map, house style, doc-sync discipline, temporal-contamination rule | Reading or writing any documentation, including CLAUDE.md files |
| `hooks/` | PreToolUse hooks (model enforcement) | Debugging hook behavior | | `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 |
| `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow | | `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 |
CLAUDE.md
+35 -34
View File
@@ -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 | | `backend/` | Fastify API server with feature capsules | Backend development |
| `frontend/` | React/Vite SPA with MUI | Frontend 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 | | `docs/` | Project documentation hub | Architecture, APIs, testing |
| `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup | | `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
| `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks | | `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks |
| `.ai/` | AI context and workflow contracts | AI-assisted development | | `.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 | | `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
| `ansible/` | Ansible deployment playbooks | Server provisioning | | `ansible/` | Ansible deployment playbooks | Server provisioning |
| `certs/` | TLS certificates | SSL/TLS configuration | | `certs/` | TLS certificates | SSL/TLS configuration |
@@ -46,10 +46,14 @@ make rebuild # Rebuild containers
## Test ## Test
Root `package.json` has no `scripts` block — `npm test` at repo root fails. Run per workspace:
```bash ```bash
npm test # Run all tests cd backend && npm test && npm run lint && npm run type-check
npm run lint # Linting cd frontend && npm test && npm run lint && npm run type-check
npm run type-check # TypeScript validation # 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) ## Development Workflow (Local + CI/CD)
### Local Development ### Local Development
Root `package.json` has no `scripts` block; install and run dev servers per workspace:
```bash ```bash
npm install # Install dependencies cd backend && npm install && npm run dev
npm run dev # Start dev server cd frontend && npm install && npm run dev
npm test # Run tests
npm run lint # Linting
npm run type-check # TypeScript validation
``` ```
Test/lint/type-check commands: see the Test section above.
### CI/CD Pipeline (on PR) ### CI/CD Pipeline (on PR)
- Container builds and integration tests 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.
- Mobile/desktop viewport validation
- Security scanning
**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 ## Quality Standards
### Automated Checks Are Mandatory ### 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 - No errors. No formatting issues. No linting problems. Zero tolerance
- These are not suggestions. Fix ALL issues before continuing - These are not suggestions. Fix ALL issues before continuing
### Code Completion Criteria ### Code Completion Criteria
Our code is complete when: Our code is complete when:
- ✅ All linters pass with zero issues - All linters pass with zero issues
- ✅ All tests pass - All tests pass
- ✅ Feature works end-to-end - Feature works end-to-end
- ✅ Old code is deleted - Old code is deleted
## AI Collaboration Strategy ## AI Collaboration Strategy
@@ -165,15 +166,15 @@ Leverage subagents aggressively for better results:
Canonical sources only - avoid duplication: Canonical sources only - avoid duplication:
- Architecture and metadata: `.ai/context.json` - 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` - Documentation hub: `docs/README.md`
- Feature work: `backend/src/features/{feature}/README.md` - Feature work: `backend/src/features/{feature}/README.md`
- Platform architecture: `docs/PLATFORM-SERVICES.md` - Platform architecture: `docs/PLATFORM-SERVICES.md`
- Testing workflow: `docs/TESTING.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 ### Quick Reference
- Every PR must link to at least one issue - 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)`) - Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`)
### Sub-Issue Decomposition ### 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 title**: `{type}: {summary} (#{parent_index})` -- parent index in title
- **Sub-issue body**: First line `Relates to #{parent_index}` - **Sub-issue body**: First line `Relates to #{parent_index}`
- **ONE branch** per parent issue only. Never branch per sub-issue. - **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 - **Feature Capsule Organization**: Application features are self-contained modules within the backend
- **Single-Tenant**: All data belongs to a single user/tenant - **Single-Tenant**: All data belongs to a single user/tenant
- **User-Scoped Data**: All application data isolated by user_id - **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 - **Integrated Platform**: Platform capabilities integrated into main backend service
### Common AI Tasks ### Common AI Tasks
See `Makefile` for authoritative commands and `docs/README.md` for navigation. See `Makefile` for authoritative commands and `docs/README.md` for navigation.
## Agent System ## Skill Library
| Directory | Contents | When to Read | 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:
|-----------|----------|--------------|
| `.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 |
### 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 0 (CRITICAL)**: Production reliability - unhandled errors, security, resource exhaustion
- **RULE 1 (HIGH)**: Project standards - mobile+desktop, naming, patterns, CI/CD pass - **RULE 1 (HIGH)**: Project standards - mobile+desktop, naming, patterns, CI/CD pass
- **RULE 2 (SHOULD_FIX)**: Structural quality - god objects, duplication, dead code - **RULE 2 (SHOULD_FIX)**: Structural quality - god objects, duplication, dead code