cmp-standards 2.0.0

package/templates/workflows/expert-review.md

@@ -0,0 +1,153 @@
+---
+description: "/experts - Multi-lens code review with consensus-based approval"
+---
+
+# Expert Review Workflow
+
+This workflow provides structured code review through multiple expert lenses.
+
+## When to Use
+- Before committing critical code (finance, auth, schema)
+- After completing a large refactor
+- When you want structured code feedback
+
+## Steps
+
+### 1. Identify Criticality
+
+Analyze the files being reviewed:
+- **CRITICAL**: finance/*, auth/*, schema/*, payments/*
+- **NORMAL**: components/*, utils/*, pages/*
+
+### 2. Run Expert Lenses
+
+For each file, analyze through these lenses:
+
+**Security Lens:**
+- SQL injection risks (no raw SQL)
+- Input validation (Zod schemas)
+- Auth checks (protected procedures)
+- Finance dual-write compliance
+
+**Performance Lens:**
+- API waterfalls
+- N+1 queries
+- Missing lazy loading
+- Inline functions in JSX
+
+**Architecture Lens:**
+- Type inference chain (DB -> API -> UI)
+- Domain-driven structure
+- Circular dependencies
+- SOLID principles
+
+**UX Lens:**
+- Accessibility (ARIA, keyboard nav)
+- Mobile-first (320px, touch targets)
+- Semantic tokens
+- Correct modal system
+
+**Database Lens:**
+- Schema consistency
+- Migration safety
+- Query optimization
+- Relation integrity
+
+**Memory Lens:**
+- Pattern detection
+- ESLint rule generation
+- Knowledge extraction
+- Recurring issue tracking
+
+### 3. Collect Issues
+
+Document findings:
+```
+APPROVE / REJECT / ABSTAIN per lens
+If REJECT: clearly state why and how to fix
+```
+
+### 4. Verdict
+
+**For CRITICAL code:**
+- All lenses must APPROVE (0 REJECT)
+
+**For NORMAL code:**
+- Majority (3/4+) must APPROVE
+
+### 5. Self-Improvement Check
+
+If you found a pattern that occurred 3+ times:
+1. Propose an ESLint rule
+2. Record in memory system as 'knowledge'
+3. Consider creating a check script
+
+### 6. Record Review
+
+```bash
+cmp-memory capture --type knowledge --title "Review: {files}" --content "{summary}"
+```
+
+## Example Output Format
+
+```
+## Expert Review: src/server/api/routers/finances/expenses.ts
+
+Criticality: CRITICAL (finance code)
+Consensus: UNANIMITY required
+
+Security: APPROVE
+   Zod validation present, no SQL injection
+
+Performance: APPROVE
+   No N+1 queries, proper pagination
+
+Architecture: APPROVE
+   Type inference correct, domain structure valid
+
+UX: ABSTAIN
+   No UI changes
+
+Database: APPROVE
+   Queries optimized, indexes used correctly
+
+Verdict: APPROVED (4 APPROVE, 0 REJECT, 1 ABSTAIN)
+```
+
+## Criticality Mapping
+
+| Path Pattern | Criticality | Required Consensus |
+|:---|:---|:---|
+| `*/finance/*` | CRITICAL | Unanimity |
+| `*/auth/*` | CRITICAL | Unanimity |
+| `*/schema/*` | CRITICAL | Unanimity |
+| `*/payments/*` | CRITICAL | Unanimity |
+| `*/api/*` | HIGH | 4/5 Approve |
+| `*/components/*` | NORMAL | Majority |
+| `*/utils/*` | NORMAL | Majority |
+| `*/pages/*` | NORMAL | Majority |
+
+## Expert Specializations
+
+Each expert has specific focus areas:
+
+- **Security Expert**: OWASP Top 10, input validation, auth/authz
+- **Performance Expert**: Bundle size, render optimization, caching
+- **Architecture Expert**: SOLID, DDD, type chains, circular deps
+- **UX Expert**: A11y, mobile-first, brand compliance
+- **Database Expert**: Schema design, migrations, query optimization
+- **Memory Expert**: Pattern learning, rule generation
+- **Documentation Expert**: Code comments, API docs, README updates
+
+## Integration with CI/CD
+
+```yaml
+# Example GitHub Action
+- name: Expert Review
+  run: cmp-memory experts --files "${{ github.event.pull_request.files }}"
+```
+
+---
+
+**Last Updated**: {{date}}
+**Status**: Production Ready

package/templates/workflows/internal-app.md

@@ -0,0 +1,245 @@
+---
+description: "Create complex admin sections following the Internal App pattern (3+ tabs, mobile-first)"
+---
+
+# Creating an Internal App Section
+
+Use this workflow when creating complex admin sections with 3+ tabs.
+
+**Examples**: EditEntity, EntitySettings, ComplexDashboard
+
+---
+
+## Prerequisites
+
+- [ ] Component will have 3+ distinct sections/tabs
+- [ ] Mobile usage is important (used in field/on-the-go)
+- [ ] Complex data management required
+
+---
+
+## Implementation Steps
+
+### 1. Check Qualification
+
+Ask yourself:
+- Does it have 3+ tabs? -> YES
+- Will it be used on mobile? -> YES
+- Is it data-heavy? -> YES
+
+If 2/3 are YES, proceed with Internal App pattern.
+
+### 2. Create File Structure
+
+```bash
+mkdir -p src/components/[domain]/edit-component
+mkdir -p src/components/[domain]/edit-component/components
+mkdir -p src/components/[domain]/edit-component/hooks
+mkdir -p src/components/[domain]/edit-component/sections
+mkdir -p src/components/[domain]/edit-component/logic
+```
+
+### 3. Implement Core Components
+
+#### Main Component
+```typescript
+import { useState } from 'react'
+import { useIsMobile } from '~/hooks/useIsMobile'
+import { MobileBottomNav } from './edit-component/components/MobileBottomNav'
+import { ErrorBoundary } from '~/components/shared/ErrorBoundary'
+
+type Section = 'GENERAL' | 'DETAILS' | 'ADVANCED'
+
+export const EditComponent = ({ id }: { id: string }) => {
+  const [section, setSection] = useState<Section>('GENERAL')
+  const isMobile = useIsMobile()
+
+  // Data fetching
+  const { data } = api.component.get.useQuery({ id })
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyPress = (e: KeyboardEvent) => {
+      if (!(e.metaKey || e.ctrlKey)) return
+      // Add shortcuts...
+    }
+
+    window.addEventListener('keydown', handleKeyPress)
+    return () => window.removeEventListener('keydown', handleKeyPress)
+  }, [])
+
+  return (
+    <>
+      <ModalBase
+        variant="sidePanel"
+        customHeader={<Header isMobile={isMobile} />}
+      >
+        {/* Sections */}
+        {section === 'GENERAL' && (
+          <ErrorBoundary>
+            <GeneralSection data={data} />
+          </ErrorBoundary>
+        )}
+
+        {section === 'DETAILS' && (
+          <ErrorBoundary>
+            <DetailsSection data={data} />
+          </ErrorBoundary>
+        )}
+      </ModalBase>
+
+      {isMobile && (
+        <MobileBottomNav
+          section={section}
+          onSectionChange={setSection}
+        />
+      )}
+    </>
+  )
+}
+```
+
+#### MobileBottomNav
+```typescript
+const tabs = [
+  { id: 'GENERAL', label: t('General'), icon: <HomeIcon /> },
+  { id: 'DETAILS', label: t('Details'), icon: <ListIcon /> },
+  // Max 6 tabs
+]
+```
+
+### 4. Add Optional Enhancements
+
+**Progress Tracking:**
+```typescript
+// hooks/useCompletion.ts
+export function useCompletion(data) {
+  return useMemo(() => {
+    const checks = [
+      { key: 'name', value: !!data.name },
+      { key: 'description', value: !!data.description },
+      // ...
+    ]
+
+    const percentage = Math.round(
+      (checks.filter(c => c.value).length / checks.length) * 100
+    )
+
+    return { percentage }
+  }, [data])
+}
+```
+
+**Smart Suggestions:**
+```typescript
+// hooks/useNextSuggestion.ts
+export function useNextSuggestion(data) {
+  if (!data.name) return { message: 'Add a name', priority: 'high' }
+  if (!data.description) return { message: 'Add description', priority: 'medium' }
+  // ...
+}
+```
+
+### 5. Test Compliance
+
+```bash
+# Run compliance checker
+npm run lint:internal-app
+
+# Expected output for new component:
+# EditComponent......... 100% (7/7 criteria)
+```
+
+### 6. Manual Testing
+
+**Mobile** (Chrome DevTools -> Toggle device toolbar):
+- [ ] Bottom nav appears (< 768px)
+- [ ] All 3+ tabs clickable
+- [ ] Smooth section transitions
+- [ ] Icons render correctly
+- [ ] Active state visible
+
+**Desktop** (>= 768px):
+- [ ] Top tabs visible in header
+- [ ] Bottom nav hidden
+- [ ] Keyboard shortcuts work (Cmd+G, Cmd+D, etc)
+- [ ] Tab overflow scrolls if > 5 tabs
+
+**Error Handling:**
+- [ ] Inject error in one section
+- [ ] ErrorBoundary catches it
+- [ ] Other sections still work
+- [ ] "Try Again" button works
+
+**Accessibility:**
+- [ ] Screen reader announces tabs
+- [ ] All buttons have aria-label
+- [ ] Keyboard navigation works
+- [ ] Focus management correct
+
+---
+
+## Common Issues & Solutions
+
+### Issue: "Component has 4 tabs but missing MobileBottomNav"
+
+**Solution:**
+1. Import MobileBottomNav
+2. Import useIsMobile hook
+3. Render conditionally: `{isMobile && <MobileBottomNav />}`
+4. Wrap in fragment: `<>...</>`
+
+### Issue: "Section not wrapped in ErrorBoundary"
+
+**Solution:**
+```typescript
+{section === 'GENERAL' && (
+  <ErrorBoundary>  // <- Add this
+    <GeneralSection />
+  </ErrorBoundary>  // <- And this
+)}
+```
+
+### Issue: Bottom nav not showing on mobile
+
+**Check:**
+1. Viewport is < 768px
+2. `isMobile` returns true (console.log it)
+3. Z-index is 50 or higher
+4. No CSS `display: none` overrides
+
+---
+
+## Performance Tips
+
+1. **Lazy load sections:**
+   ```typescript
+   const AdvancedSection = lazy(() => import('./sections/AdvancedSection'))
+   ```
+
+2. **Prefetch on hover** (desktop):
+   ```typescript
+   onMouseEnter={() => void ctx.component.getData.prefetch({ id })}
+   ```
+
+3. **Memoize calculations:**
+   ```typescript
+   const processedData = useMemo(() => process(rawData), [rawData])
+   ```
+
+---
+
+## Verification Checklist
+
+Before marking complete:
+
+- [ ] Lint check passes
+- [ ] TypeScript check passes
+- [ ] Manual mobile testing complete
+- [ ] Manual desktop testing complete
+- [ ] Accessibility verified
+- [ ] Documentation updated
+
+---
+
+**Status**: Production Ready

package/templates/workflows/sync-docs.md

@@ -0,0 +1,187 @@
+---
+description: "/sync - Synchronize and validate all project documentation automatically"
+---
+
+# Documentation Sync Workflow
+
+This workflow executes all documentation validations and updates.
+
+## Overview
+
+The `/sync` command ensures all project documentation is:
+- Up to date with code changes
+- Consistent across files
+- Following established patterns
+- Properly validated
+
+## Execution Steps
+
+### 1. Health Check
+
+Run documentation health check:
+```bash
+npm run docs:health
+# Or custom command for your project
+```
+
+Verifies:
+- All required docs exist
+- No broken internal links
+- Timestamps are recent
+
+### 2. Schema Documentation
+
+Generate schema documentation:
+```bash
+npm run docs:schema
+# Or: npx drizzle-kit generate
+```
+
+Updates:
+- Database schema docs
+- Type definitions
+- API documentation
+
+### 3. AI Context Sync
+
+Sync AI context files:
+```bash
+cmp-memory sync
+```
+
+Updates:
+- CLAUDE.md with latest project state
+- Skills registry
+- Agent configurations
+
+### 4. Translation Check
+
+Verify translations (if applicable):
+```bash
+npm run i18n:check
+```
+
+Checks:
+- Missing translation keys
+- Inconsistent translations
+- Unused keys
+
+### 5. Finance Sync (if applicable)
+
+Verify finance-ledger synchronization:
+```bash
+npm run lint:finance-sync
+```
+
+Ensures:
+- All finance operations have ledger entries
+- Cash flow integrity maintained
+
+### 6. Lint Report
+
+Generate intelligent lint report:
+```bash
+npm run lint:report
+# Or: npx eslint . --format json > .lint/report.json
+```
+
+Produces:
+- Categorized issues
+- Priority ranking
+- Fix suggestions
+
+## Full Report
+
+The sync produces a comprehensive report:
+
+```
+Documentation Sync Report
+========================
+
+Health Check:
+  - CLAUDE.md: OK (updated 2h ago)
+  - README.md: OK
+  - API docs: STALE (updated 7d ago) <-- Action needed
+
+Schema:
+  - 47 tables documented
+  - 3 new columns since last sync
+  - Types: up to date
+
+AI Context:
+  - 12 agents configured
+  - 8 skills registered
+  - Hooks: synchronized
+
+Translations:
+  - en: 100% (847/847)
+  - es: 98% (834/847) <-- 13 missing
+  - de: 95% (805/847) <-- 42 missing
+
+Lint Summary:
+  - Errors: 0
+  - Warnings: 12
+  - Info: 45
+
+Overall: NEEDS_ATTENTION
+Action Items:
+  1. Update API documentation
+  2. Add 13 Spanish translations
+  3. Review 12 lint warnings
+```
+
+## Automation
+
+### Pre-commit Hook
+
+Add to `.claude/hooks/pre-commit.sh`:
+```bash
+#!/bin/bash
+cmp-memory sync --quick
+if [ $? -ne 0 ]; then
+  echo "Documentation sync failed"
+  exit 1
+fi
+```
+
+### CI Integration
+
+```yaml
+- name: Documentation Sync
+  run: |
+    cmp-memory sync
+    git diff --exit-code docs/
+```
+
+## Customization
+
+Configure in `project.config.json`:
+
+```json
+{
+  "sync": {
+    "healthCheck": true,
+    "schemaDoc": true,
+    "aiContext": true,
+    "i18n": false,
+    "financeSync": false,
+    "lintReport": true
+  }
+}
+```
+
+## When to Run
+
+### Automatic Triggers
+- Pre-commit (quick mode)
+- PR creation
+- Release preparation
+
+### Manual Triggers
+- After major refactors
+- Before important demos
+- Monthly maintenance
+
+---
+
+**Status**: Production Ready