From b933329539c4b69b573b8fe9d87fdb5cec14f3ab Mon Sep 17 00:00:00 2001 From: Eric Gullickson <16152721+ericgullickson@users.noreply.github.com> Date: Sat, 3 Jan 2026 11:59:47 -0600 Subject: [PATCH] feat: update docs for token efficient usage --- .ai/CLAUDE.md | 11 +++++ .claude/CLAUDE.md | 15 ++++++- .claude/agents/CLAUDE.md | 11 +++++ .claude/role-agents/CLAUDE.md | 10 +++++ .claude/skills/CLAUDE.md | 13 ++++++ .claude/skills/doc-sync/CLAUDE.md | 14 +++++++ .gitea/ISSUE_TEMPLATE/feature.yml | 70 ------------------------------- CLAUDE.md | 44 +++++++++++++++++++ backend/CLAUDE.md | 18 ++++++++ backend/src/CLAUDE.md | 18 ++++++++ backend/src/core/CLAUDE.md | 20 +++++++++ backend/src/features/CLAUDE.md | 22 ++++++++++ config/CLAUDE.md | 13 ++++++ docs/CLAUDE.md | 28 +++++++++++++ frontend/CLAUDE.md | 24 +++++++++++ frontend/src/CLAUDE.md | 20 +++++++++ frontend/src/core/CLAUDE.md | 17 ++++++++ frontend/src/features/CLAUDE.md | 19 +++++++++ scripts/CLAUDE.md | 17 ++++++++ 19 files changed, 333 insertions(+), 71 deletions(-) create mode 100644 .ai/CLAUDE.md create mode 100644 .claude/agents/CLAUDE.md create mode 100644 .claude/role-agents/CLAUDE.md create mode 100644 .claude/skills/CLAUDE.md create mode 100644 .claude/skills/doc-sync/CLAUDE.md delete mode 100644 .gitea/ISSUE_TEMPLATE/feature.yml create mode 100644 backend/CLAUDE.md create mode 100644 backend/src/CLAUDE.md create mode 100644 backend/src/core/CLAUDE.md create mode 100644 backend/src/features/CLAUDE.md create mode 100644 config/CLAUDE.md create mode 100644 docs/CLAUDE.md create mode 100644 frontend/CLAUDE.md create mode 100644 frontend/src/CLAUDE.md create mode 100644 frontend/src/core/CLAUDE.md create mode 100644 frontend/src/features/CLAUDE.md create mode 100644 scripts/CLAUDE.md diff --git a/.ai/CLAUDE.md b/.ai/CLAUDE.md new file mode 100644 index 0000000..34c6680 --- /dev/null +++ b/.ai/CLAUDE.md @@ -0,0 +1,11 @@ +# .ai/ + +AI context and workflow configuration for Claude Code. + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `context.json` | Architecture metadata, feature registry | Understanding system structure | +| `workflow-contract.json` | Sprint workflow, issue lifecycle | Issue/PR workflow, labels | +| `WORKFLOW-PROMPTS.md` | Workflow prompt templates | Workflow automation | diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 553867a..0e86b14 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -1,4 +1,16 @@ -# .claude/ Index +# .claude/ + +## Subdirectories + +| 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 | +| `output-styles/` | Output formatting templates | Customizing agent output | +| `tdd-guard/` | TDD enforcement utilities | Test-driven development | + +## Quick Reference | Path | What | When | |------|------|------| @@ -10,5 +22,6 @@ | `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 | | `.ai/workflow-contract.json` | Sprint process, skill integration | Issue workflow | diff --git a/.claude/agents/CLAUDE.md b/.claude/agents/CLAUDE.md new file mode 100644 index 0000000..67016e0 --- /dev/null +++ b/.claude/agents/CLAUDE.md @@ -0,0 +1,11 @@ +# agents/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Agent team overview and coordination | Understanding agent workflow | +| `feature-agent.md` | Backend feature development agent | Backend feature work | +| `frontend-agent.md` | React/mobile-first UI agent | Frontend component work | +| `platform-agent.md` | Platform services agent | Platform microservice work | +| `quality-agent.md` | Final validation agent | Pre-merge quality checks | diff --git a/.claude/role-agents/CLAUDE.md b/.claude/role-agents/CLAUDE.md new file mode 100644 index 0000000..d0f4f3b --- /dev/null +++ b/.claude/role-agents/CLAUDE.md @@ -0,0 +1,10 @@ +# role-agents/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `developer.md` | Developer role agent | Code implementation tasks | +| `technical-writer.md` | Technical writer agent | Documentation tasks | +| `quality-reviewer.md` | Quality reviewer with RULE 0/1/2 | Code review, quality gates | +| `debugger.md` | Debugging specialist agent | Bug investigation, troubleshooting | diff --git a/.claude/skills/CLAUDE.md b/.claude/skills/CLAUDE.md new file mode 100644 index 0000000..fa0668f --- /dev/null +++ b/.claude/skills/CLAUDE.md @@ -0,0 +1,13 @@ +# skills/ + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `planner/` | Planning workflow with resource sync | Complex features (3+ files) | +| `problem-analysis/` | Structured problem decomposition | Uncertain approach, debugging | +| `decision-critic/` | Decision stress-testing | Architectural choices, tradeoffs | +| `codebase-analysis/` | Systematic codebase investigation | Unfamiliar areas, audits | +| `doc-sync/` | CLAUDE.md/README.md synchronization | After refactors, periodic audits | +| `incoherence/` | Detect doc/code drift | Documentation inconsistencies | +| `prompt-engineer/` | Prompt optimization techniques | Improving AI prompts | diff --git a/.claude/skills/doc-sync/CLAUDE.md b/.claude/skills/doc-sync/CLAUDE.md new file mode 100644 index 0000000..3e111d5 --- /dev/null +++ b/.claude/skills/doc-sync/CLAUDE.md @@ -0,0 +1,14 @@ +# skills/doc-sync/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Skill overview and usage examples | Understanding when to use doc-sync | +| `SKILL.md` | Complete skill workflow definition | Executing the doc-sync skill | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `references/` | Trigger pattern examples | Writing good CLAUDE.md triggers | diff --git a/.gitea/ISSUE_TEMPLATE/feature.yml b/.gitea/ISSUE_TEMPLATE/feature.yml deleted file mode 100644 index 2342fd6..0000000 --- a/.gitea/ISSUE_TEMPLATE/feature.yml +++ /dev/null @@ -1,70 +0,0 @@ -name: "Feature" -about: "New capability or enhancement" -title: "[Feature]: " -labels: - - "type/feature" - - "status/backlog" -body: - - type: markdown - attributes: - value: | - Use this for a new feature or enhancement. Keep scope tight and include clear acceptance criteria. - - - type: textarea - id: problem - attributes: - label: "Problem / user need" - description: "What problem are we solving, and for whom?" - placeholder: "As a user, I want..., so that..." - validations: - required: true - - - type: textarea - id: solution - attributes: - label: "Proposed solution" - description: "Describe the expected behavior at a high level." - placeholder: "When the user does X, the system should..." - validations: - required: true - - - type: textarea - id: non_goals - attributes: - label: "Non-goals / out of scope" - description: "What are we explicitly not doing in this feature?" - placeholder: "- Not doing...\n- Not doing..." - validations: - required: false - - - type: textarea - id: acceptance - attributes: - label: "Acceptance criteria" - description: "Concrete checks for ‘done’. Prefer bullets and testable statements." - placeholder: | - - [ ] ... - - [ ] ... - - [ ] ... - validations: - required: true - - - type: textarea - id: notes - attributes: - label: "Implementation notes (optional)" - description: "Links, APIs, file paths, edge cases." - validations: - required: false - - - type: textarea - id: test_plan - attributes: - label: "Test plan" - description: "How will we verify? Include commands or steps." - placeholder: | - - Unit: - - Integration: - - Manual: - validations: - required: true diff --git a/CLAUDE.md b/CLAUDE.md index 4863540..af27ef6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,47 @@ +# MotoVaultPro + +Single-tenant vehicle management application with 5-container architecture (Traefik, Frontend, Backend, PostgreSQL, Redis). + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `Makefile` | Build, test, deploy commands | Running any make command | +| `docker-compose.yml` | Development container orchestration | Local development setup | +| `package.json` | Root workspace dependencies | Dependency management | +| `README.md` | Project overview | First-time setup | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `backend/` | Fastify API server with feature capsules | Backend development | +| `frontend/` | React/Vite SPA with MUI | Frontend development | +| `docs/` | Project documentation hub | Architecture, APIs, testing | +| `config/` | Configuration files (Traefik, monitoring) | Infrastructure setup | +| `scripts/` | Utility scripts (backup, deploy) | Automation tasks | +| `.ai/` | AI context and workflow contracts | AI-assisted development | +| `.claude/` | Claude Code agents and skills | Delegating to agents, using skills | +| `.gitea/` | Gitea workflows and templates | CI/CD, issue templates | +| `ansible/` | Ansible deployment playbooks | Server provisioning | + +## Build + +```bash +make setup # First-time setup (builds containers, runs migrations) +make rebuild # Rebuild containers after changes +``` + +## Test + +```bash +npm test # Run all tests +npm run lint # Linting +npm run type-check # TypeScript validation +``` + +--- + # Development Partnership Guidelines ## Core Development Principles diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md new file mode 100644 index 0000000..a6fdab6 --- /dev/null +++ b/backend/CLAUDE.md @@ -0,0 +1,18 @@ +# backend/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Backend quickstart and commands | Getting started with backend development | +| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build | +| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases | +| `jest.config.ts` | Jest test configuration | Test setup, coverage settings | +| `Dockerfile` | Container build definition | Docker builds, deployment | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `src/` | Application source code | Any backend development | +| `scripts/` | Utility scripts | Database scripts, automation | diff --git a/backend/src/CLAUDE.md b/backend/src/CLAUDE.md new file mode 100644 index 0000000..ab7a365 --- /dev/null +++ b/backend/src/CLAUDE.md @@ -0,0 +1,18 @@ +# backend/src/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `app.ts` | Fastify application setup and routes | Route registration, middleware setup | +| `index.ts` | Application entry point | Server startup, initialization | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `features/` | Feature capsules (self-contained modules) | Feature development, API endpoints | +| `core/` | Shared infrastructure (auth, config, logging) | Cross-cutting concerns, plugins | +| `_system/` | System utilities (migrations, CLI, schema) | Database migrations, schema generation | +| `shared-minimal/` | Minimal shared utilities | Shared type utilities | +| `scripts/` | Backend-specific scripts | Utility scripts | diff --git a/backend/src/core/CLAUDE.md b/backend/src/core/CLAUDE.md new file mode 100644 index 0000000..cf75124 --- /dev/null +++ b/backend/src/core/CLAUDE.md @@ -0,0 +1,20 @@ +# backend/src/core/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Core module index with code examples | Understanding core infrastructure | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `auth/` | Authentication utilities | JWT handling, user context | +| `config/` | Configuration loading (env, database, redis) | Environment setup, connection pools | +| `logging/` | Winston structured logging | Log configuration, debugging | +| `middleware/` | Fastify middleware | Request processing, user extraction | +| `plugins/` | Fastify plugins (auth, error, logging) | Plugin registration, hooks | +| `scheduler/` | Job scheduling infrastructure | Scheduled tasks, cron jobs | +| `storage/` | Storage abstraction and adapters | File storage, S3/filesystem | +| `user-preferences/` | User preferences data and migrations | User settings storage | diff --git a/backend/src/features/CLAUDE.md b/backend/src/features/CLAUDE.md new file mode 100644 index 0000000..a08ccfc --- /dev/null +++ b/backend/src/features/CLAUDE.md @@ -0,0 +1,22 @@ +# backend/src/features/ + +Feature capsule directory. Each feature is 100% self-contained with api/, domain/, data/, migrations/, tests/. + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `admin/` | Admin role management, catalog CRUD | Admin functionality, user oversight | +| `auth/` | Authentication endpoints | Login, logout, session management | +| `backup/` | Database backup and restore | Backup jobs, data export/import | +| `documents/` | Document storage and management | File uploads, document handling | +| `fuel-logs/` | Fuel consumption tracking | Fuel log CRUD, statistics | +| `maintenance/` | Maintenance record management | Service records, reminders | +| `notifications/` | Email and push notifications | Alert system, email templates | +| `onboarding/` | User onboarding flow | First-time user setup | +| `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation | +| `stations/` | Gas station search and favorites | Google Maps integration, station data | +| `user-export/` | User data export | GDPR compliance, data portability | +| `user-preferences/` | User preference management | User settings API | +| `user-profile/` | User profile management | Profile CRUD, avatar handling | +| `vehicles/` | Vehicle management | Vehicle CRUD, fleet operations | diff --git a/config/CLAUDE.md b/config/CLAUDE.md new file mode 100644 index 0000000..5e688c8 --- /dev/null +++ b/config/CLAUDE.md @@ -0,0 +1,13 @@ +# config/ + +Configuration files for the 5-container architecture. + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `app/` | Application configuration | App-specific settings | +| `deployment/` | Deployment configuration | Deploy scripts, environment configs | +| `monitoring/` | Monitoring and alerts | Prometheus, alerting rules | +| `shared/` | Shared configuration | Cross-service settings | +| `traefik/` | Traefik reverse proxy config | Routing, SSL, middleware | diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md new file mode 100644 index 0000000..56d8943 --- /dev/null +++ b/docs/CLAUDE.md @@ -0,0 +1,28 @@ +# docs/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Documentation hub and navigation | Starting point for any docs | +| `PLATFORM-SERVICES.md` | 5-container architecture overview | Understanding system topology | +| `ARCHITECTURE-OVERVIEW.md` | Detailed architecture documentation | Deep dive into system design | +| `DATABASE-SCHEMA.md` | Database table definitions | Schema changes, data modeling | +| `DATABASE-MIGRATION.md` | Migration procedures | Running or writing migrations | +| `VEHICLES-API.md` | Vehicles API specification | Vehicle-related API work | +| `ADMIN.md` | Admin feature documentation | Admin role management, catalog CRUD | +| `TESTING.md` | Testing strategy and commands | Writing or running tests | +| `E2E-TESTING.md` | End-to-end testing guide | Cypress E2E test setup | +| `SECURITY.md` | Security guidelines | Security considerations | +| `CICD-DEPLOY.md` | CI/CD and deployment | Pipeline configuration, deployments | +| `BUILD-SERVER-SETUP.md` | Build server setup | Infrastructure setup | +| `AUDIT.md` | Audit documentation | Security audits, compliance | +| `MVP-COLOR-SCHEME.md` | Color scheme reference | UI styling decisions | +| `UX-DEBUGGING.md` | UX debugging techniques | Debugging UI issues | +| `PROMPTS.md` | AI prompt templates | AI-assisted development | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `changes/` | Change logs and migration notes | Understanding historical changes | diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md new file mode 100644 index 0000000..443ae05 --- /dev/null +++ b/frontend/CLAUDE.md @@ -0,0 +1,24 @@ +# frontend/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `README.md` | Frontend quickstart and patterns | Getting started with frontend development | +| `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build | +| `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases | +| `vite.config.ts` | Vite build configuration | Build optimization, plugins | +| `jest.config.ts` | Jest test configuration | Test setup | +| `tailwind.config.js` | Tailwind CSS configuration | Styling, theme customization | +| `Dockerfile` | Container build definition | Docker builds, deployment | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `src/` | Application source code | Any frontend development | +| `public/` | Static assets (images, docs) | Adding static files | +| `cypress/` | E2E test definitions | End-to-end testing | +| `docs/` | Frontend-specific documentation | Frontend patterns, guidelines | +| `test/` | Test utilities and mocks | Test setup, mock data | +| `scripts/` | Frontend utility scripts | Automation scripts | diff --git a/frontend/src/CLAUDE.md b/frontend/src/CLAUDE.md new file mode 100644 index 0000000..6878041 --- /dev/null +++ b/frontend/src/CLAUDE.md @@ -0,0 +1,20 @@ +# frontend/src/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `App.tsx` | Root component with routing | Route configuration, layout structure | +| `main.tsx` | Application entry point | Provider setup, initialization | +| `index.css` | Global styles | Base styling, CSS imports | +| `vite-env.d.ts` | Vite type definitions | TypeScript environment types | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `features/` | Feature modules (pages, components, hooks) | Feature development | +| `core/` | Shared infrastructure (auth, api, store) | Cross-cutting concerns | +| `components/` | Root-level shared components | App-wide UI components | +| `pages/` | Page-level components | Page structure, routing targets | +| `shared-minimal/` | Minimal shared UI (skeletons, theme) | Reusable UI primitives | diff --git a/frontend/src/core/CLAUDE.md b/frontend/src/core/CLAUDE.md new file mode 100644 index 0000000..dd910ed --- /dev/null +++ b/frontend/src/core/CLAUDE.md @@ -0,0 +1,17 @@ +# frontend/src/core/ + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `api/` | API client and request handling | HTTP calls, error handling | +| `auth/` | Auth0 provider and auth hooks | Authentication setup, user context | +| `config/` | Runtime configuration | Environment-specific settings | +| `debug/` | Debug utilities | Development helpers | +| `error-boundaries/` | React error boundaries | Error handling UI | +| `hooks/` | Shared React hooks | Reusable hook patterns | +| `query/` | React Query configuration | Server state management | +| `store/` | Zustand state management | Client state, global stores | +| `sync/` | Data synchronization | Offline support, sync logic | +| `units/` | Unit conversion utilities | Measurement formatting | +| `utils/` | General utilities | Helper functions | diff --git a/frontend/src/features/CLAUDE.md b/frontend/src/features/CLAUDE.md new file mode 100644 index 0000000..8325d4a --- /dev/null +++ b/frontend/src/features/CLAUDE.md @@ -0,0 +1,19 @@ +# frontend/src/features/ + +Feature module directory. Each feature contains pages/, components/, hooks/, api/, types/. + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `admin/` | Admin panel and catalog management | Admin UI, user management | +| `auth/` | Authentication pages and components | Login, logout, auth flows | +| `dashboard/` | Dashboard and fleet overview | Home page, summary widgets | +| `documents/` | Document management UI | File upload, document viewer | +| `fuel-logs/` | Fuel log tracking UI | Fuel entry forms, statistics | +| `maintenance/` | Maintenance record UI | Service tracking, reminders | +| `notifications/` | Notification display | Alert UI, notification center | +| `onboarding/` | Onboarding wizard | First-time user experience | +| `settings/` | User settings pages | Preferences, account settings | +| `stations/` | Gas station finder UI | Station search, favorites, map | +| `vehicles/` | Vehicle management UI | Vehicle list, details, forms | diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md new file mode 100644 index 0000000..dae0b0e --- /dev/null +++ b/scripts/CLAUDE.md @@ -0,0 +1,17 @@ +# scripts/ + +## Files + +| File | What | When to read | +| ---- | ---- | ------------ | +| `config-validator.sh` | Validate configuration files | Pre-deploy validation | +| `export-database.sh` | Export database to backup | Database backup operations | +| `import-database.sh` | Import database from backup | Database restore operations | +| `inject-secrets.sh` | Inject secrets into config | Secret management | +| `rollback.sh` | Rollback deployment | Emergency rollback procedures | + +## Subdirectories + +| Directory | What | When to read | +| --------- | ---- | ------------ | +| `ci/` | CI/CD scripts | Pipeline automation, build scripts |