autoworkflow 1.2.0 → 2.0.0

package/hooks/pre-commit

@@ -0,0 +1,152 @@
+#!/bin/bash
+# pre-commit
+# Git pre-commit hook that enforces AutoWorkflow rules
+# Install: cp hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔒 AUTOWORKFLOW PRE-COMMIT CHECK"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+BLOCKED=0
+
+# Get list of staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E "\.(ts|tsx|js|jsx)$" || true)
+
+# ─────────────────────────────────────────────────────────────
+# Check 1: TypeScript Errors
+# ─────────────────────────────────────────────────────────────
+
+echo "📋 [1/5] TypeScript check..."
+
+TSC_OUTPUT=$(npm run typecheck 2>&1) || true
+
+if echo "$TSC_OUTPUT" | grep -q "error TS"; then
+    ERROR_COUNT=$(echo "$TSC_OUTPUT" | grep -c "error TS" || echo "0")
+    echo -e "${RED}   ⛔ Found $ERROR_COUNT TypeScript error(s)${NC}"
+    echo ""
+    echo "$TSC_OUTPUT" | grep "error TS" | head -10
+    if [ "$ERROR_COUNT" -gt 10 ]; then
+        echo "   ... and $(($ERROR_COUNT - 10)) more"
+    fi
+    BLOCKED=1
+else
+    echo -e "${GREEN}   ✓ No TypeScript errors${NC}"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Check 2: ESLint Warnings
+# ─────────────────────────────────────────────────────────────
+
+echo ""
+echo "📋 [2/5] ESLint check..."
+
+LINT_OUTPUT=$(npm run lint 2>&1) || true
+
+if echo "$LINT_OUTPUT" | grep -qE "[0-9]+ error|[0-9]+ warning"; then
+    echo -e "${RED}   ⛔ ESLint issues found${NC}"
+    echo "$LINT_OUTPUT" | grep -E "error|warning" | head -10
+    BLOCKED=1
+else
+    echo -e "${GREEN}   ✓ No ESLint issues${NC}"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Check 3: TODO/FIXME Comments
+# ─────────────────────────────────────────────────────────────
+
+echo ""
+echo "📋 [3/5] TODO/FIXME check..."
+
+if [ -n "$STAGED_FILES" ]; then
+    TODO_FILES=$(echo "$STAGED_FILES" | xargs grep -l "TODO\|FIXME\|XXX\|HACK" 2>/dev/null || true)
+    if [ -n "$TODO_FILES" ]; then
+        echo -e "${RED}   ⛔ Found TODO/FIXME comments in:${NC}"
+        echo "$TODO_FILES" | while read file; do
+            echo "      - $file"
+            grep -n "TODO\|FIXME\|XXX\|HACK" "$file" 2>/dev/null | head -3 | sed 's/^/        /'
+        done
+        BLOCKED=1
+    else
+        echo -e "${GREEN}   ✓ No TODO/FIXME comments${NC}"
+    fi
+else
+    echo -e "${GREEN}   ✓ No TODO/FIXME comments${NC}"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Check 4: Console.log Statements
+# ─────────────────────────────────────────────────────────────
+
+echo ""
+echo "📋 [4/5] console.log check..."
+
+if [ -n "$STAGED_FILES" ]; then
+    CONSOLE_FILES=$(echo "$STAGED_FILES" | xargs grep -l "console\.\(log\|debug\|info\)" 2>/dev/null || true)
+    if [ -n "$CONSOLE_FILES" ]; then
+        echo -e "${RED}   ⛔ Found console.log statements in:${NC}"
+        echo "$CONSOLE_FILES" | while read file; do
+            echo "      - $file"
+            grep -n "console\.\(log\|debug\|info\)" "$file" 2>/dev/null | head -3 | sed 's/^/        /'
+        done
+        BLOCKED=1
+    else
+        echo -e "${GREEN}   ✓ No console.log statements${NC}"
+    fi
+else
+    echo -e "${GREEN}   ✓ No console.log statements${NC}"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Check 5: Circular Dependencies (if madge available)
+# ─────────────────────────────────────────────────────────────
+
+echo ""
+echo "📋 [5/5] Circular dependencies check..."
+
+if command -v npx &> /dev/null && [ -d "src" ]; then
+    CYCLES=$(npx madge --circular --extensions ts,tsx src/ 2>/dev/null || true)
+    if [ -n "$CYCLES" ] && ! echo "$CYCLES" | grep -q "No circular"; then
+        echo -e "${RED}   ⛔ Circular dependencies found:${NC}"
+        echo "$CYCLES" | head -10
+        BLOCKED=1
+    else
+        echo -e "${GREEN}   ✓ No circular dependencies${NC}"
+    fi
+else
+    echo -e "${YELLOW}   ○ Skipped (madge not available or no src/)${NC}"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Result
+# ─────────────────────────────────────────────────────────────
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ $BLOCKED -eq 1 ]; then
+    echo -e "${RED}╔══════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${RED}║                    ⛔ COMMIT BLOCKED ⛔                       ║${NC}"
+    echo -e "${RED}╠══════════════════════════════════════════════════════════════╣${NC}"
+    echo -e "${RED}║  Fix the issues above before committing.                     ║${NC}"
+    echo -e "${RED}║                                                              ║${NC}"
+    echo -e "${RED}║  Quick fixes:                                                ║${NC}"
+    echo -e "${RED}║    npm run lint:fix     Auto-fix ESLint issues               ║${NC}"
+    echo -e "${RED}║    npm run typecheck    See all TypeScript errors            ║${NC}"
+    echo -e "${RED}╚══════════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    exit 1
+fi
+
+echo -e "${GREEN}╔══════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${GREEN}║                    ✅ ALL CHECKS PASSED                       ║${NC}"
+echo -e "${GREEN}╚══════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+exit 0

package/instructions/AI_RULES.md

@@ -0,0 +1,284 @@
+# AI Rules - Project Standards
+
+> Coding standards and conventions that Claude MUST follow.
+> This defines WHAT quality looks like for this project.
+
+---
+
+## Project Configuration
+
+**Name:** [Your Project Name]
+**Description:** [One-line description]
+**Target Users:** [Who uses this?]
+**Core Value:** [What problem does it solve?]
+
+> Full specification in `instructions/BLUEPRINT.md`
+
+---
+
+## Tech Stack
+
+- React 18 + TypeScript + Vite
+- Tailwind CSS + shadcn/ui
+- lucide-react icons
+- React Router DOM
+
+---
+
+## File Structure
+
+```
+src/
+├── components/    # Reusable UI (PascalCase.tsx)
+├── pages/         # Route pages
+├── hooks/         # Custom hooks (use*.ts)
+├── lib/           # Utilities
+├── types/         # TypeScript types (*.types.ts)
+└── api/           # API functions
+```
+
+---
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase.tsx | `UserCard.tsx` |
+| Hooks | use*.ts | `useAuth.ts` |
+| Utilities | camelCase.ts | `formatDate.ts` |
+| Types | *.types.ts | `user.types.ts` |
+| Constants | UPPER_SNAKE | `MAX_ITEMS` |
+
+---
+
+## Component Rules
+
+### Structure
+- Max 150 lines per file
+- Extract hooks for logic
+- Use TypeScript interfaces (not types)
+- Handle loading/error/empty states
+
+### Required States
+Every component with async data MUST have:
+- Loading state (skeleton/spinner)
+- Error state (error message)
+- Empty state (no data message)
+
+### Props Interface
+```typescript
+interface ComponentProps {
+  // Required props first
+  id: string
+  data: DataType
+
+  // Optional props after
+  className?: string
+  onAction?: () => void
+}
+```
+
+---
+
+## Styling Rules
+
+- Tailwind utilities only
+- Use `cn()` for conditional classes
+- Mobile-first responsive design
+- No inline styles
+- No CSS files (use Tailwind)
+
+```typescript
+// Good
+<div className={cn("p-4 bg-white", isActive && "bg-blue-500")} />
+
+// Bad
+<div style={{ padding: 16 }} />
+```
+
+---
+
+## API Patterns
+
+### Response Type
+```typescript
+interface ApiResponse<T> {
+  data: T | null
+  error: string | null
+  loading: boolean
+}
+```
+
+### Error Handling
+```typescript
+try {
+  const data = await fetchData()
+  return { data, error: null }
+} catch (error) {
+  toast.error('Failed to load data')
+  return { data: null, error: error.message }
+}
+```
+
+---
+
+## Quality Standards
+
+### Every New Page MUST Have:
+- [ ] Loading skeleton
+- [ ] Error boundary
+- [ ] Empty state
+- [ ] SEO meta tags
+- [ ] Mobile layout
+
+### Every New Form MUST Have:
+- [ ] Client validation
+- [ ] Server error display
+- [ ] Submit loading state
+- [ ] Success feedback
+- [ ] Disabled state while submitting
+
+### Every New Component MUST Have:
+- [ ] TypeScript props interface
+- [ ] Default props where sensible
+- [ ] Loading prop (if async)
+
+---
+
+## ALWAYS / NEVER Rules
+
+### ALWAYS:
+- Handle API errors gracefully
+- Show loading states for async operations
+- Validate user input
+- Use semantic HTML
+- Add aria-labels for icons
+- Complete features fully (UI + Backend)
+
+### NEVER:
+- Use `any` type
+- Leave console.log statements
+- Skip error handling
+- Hardcode strings (use constants)
+- Commit with TypeScript errors
+- Build backend WITHOUT UI
+- Create API WITHOUT UI that calls it
+- Add database table WITHOUT UI
+- Commit orphan features
+
+---
+
+## UI Enforcement
+
+### Definition of Done
+
+A feature is **NOT COMPLETE** until:
+
+| Requirement | Must Exist |
+|-------------|------------|
+| Backend/API | Logic implemented |
+| UI Component | User-facing component |
+| Connection | UI calls the backend |
+| Navigation | User can access it |
+
+### Self-Check Before Commit
+```
+□ Can a user SEE this feature in the app?
+□ Can a user INTERACT with this feature?
+□ Is the UI CONNECTED to the backend?
+□ Is there a WAY to navigate to it?
+
+ALL must be YES to commit.
+```
+
+---
+
+## ESLint Rules (Enforced)
+
+| Rule | Setting | Purpose |
+|------|---------|---------|
+| `no-console` | error | No debug logs |
+| `max-lines` | 300 | Files focused |
+| `max-lines-per-function` | 75 | Functions small |
+| `complexity` | 15 | Prevent complexity |
+| `no-nested-ternary` | error | Readable code |
+| `eqeqeq` | error | Strict equality |
+| `@typescript-eslint/no-explicit-any` | error | Type safety |
+| `@typescript-eslint/no-non-null-assertion` | error | Safe nulls |
+
+---
+
+## Coverage Thresholds
+
+```
+Lines:      80%
+Functions:  80%
+Branches:   70%
+Statements: 80%
+```
+
+---
+
+## Commit Message Format
+
+```
+type(scope): description
+
+Types:
+- feat: New feature
+- fix: Bug fix
+- docs: Documentation
+- style: Formatting
+- refactor: Code restructure
+- perf: Performance
+- test: Tests
+- build: Build system
+- ci: CI/CD
+- chore: Maintenance
+- revert: Revert commit
+```
+
+Examples:
+- `feat(auth): add login page`
+- `fix(api): handle null response`
+- `refactor(utils): extract date helpers`
+
+---
+
+## Commands
+
+```bash
+npm run dev        # Start dev server
+npm run typecheck  # TypeScript check
+npm run lint       # ESLint check
+npm run verify     # TypeScript + ESLint
+npm run test       # Run tests
+npm run audit:ui   # Check orphan features
+npm run audit:cycles # Check circular deps
+```
+
+---
+
+## Feature Completeness Checklist
+
+When Claude suggests improvements, check against:
+
+- [ ] Error state UI
+- [ ] Loading state UI
+- [ ] Empty state UI
+- [ ] Success feedback (toast/notification)
+- [ ] Form validation messages
+- [ ] Keyboard navigation
+- [ ] Mobile layout
+
+---
+
+## Notes for Claude
+
+When building features:
+1. Check `BLUEPRINT.md` for requirements
+2. Follow these standards for quality
+3. Match existing patterns in codebase
+4. Complete features fully before commit
+
+**Feature completeness = BLUEPRINT requirements + these standards**

package/instructions/BLUEPRINT.md

@@ -0,0 +1,170 @@
+# Project Blueprint
+
+> This is your project's source of truth.
+> Claude reads this to understand WHAT to build.
+
+---
+
+## Project Overview
+
+**Name:** [Project Name]
+**Tagline:** [One-line description]
+**Domain:** [e.g., yourproject.com]
+
+### Problem Statement
+[What problem does this solve? Who has this problem?]
+
+### Solution
+[How does your project solve it?]
+
+### Target Users
+- **Primary:** [Main user type]
+- **Secondary:** [Other users]
+
+---
+
+## Features
+
+### Phase 1: MVP (Current)
+- [ ] **Feature 1** - [Description]
+  - Sub-requirement 1
+  - Sub-requirement 2
+- [ ] **Feature 2** - [Description]
+- [ ] **Feature 3** - [Description]
+
+### Phase 2: Growth
+- [ ] **Feature 4** - [Description]
+- [ ] **Feature 5** - [Description]
+
+### Phase 3: Scale
+- [ ] **Feature 6** - [Description]
+
+---
+
+## Data Model
+
+### Core Entities
+
+```
+User
+├── id: string (UUID)
+├── email: string (unique)
+├── name: string
+├── role: enum (user, admin)
+├── createdAt: timestamp
+└── updatedAt: timestamp
+
+[Entity 2]
+├── id: string (UUID)
+├── [field]: [type]
+└── userId: string (FK → User)
+```
+
+### Relationships
+- User → [Entity] (one-to-many)
+- [Entity] → [Entity] (many-to-many)
+
+---
+
+## API Endpoints
+
+### Public Routes
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | /api/[resource] | List all |
+| GET | /api/[resource]/:id | Get one |
+| POST | /api/[resource] | Create |
+
+### Protected Routes (Auth Required)
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| PUT | /api/[resource]/:id | Update |
+| DELETE | /api/[resource]/:id | Delete |
+
+### Admin Routes
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | /api/admin/[resource] | Admin list |
+
+---
+
+## Pages & Routes
+
+| Route | Page | Auth | Description |
+|-------|------|------|-------------|
+| `/` | HomePage | No | Landing page |
+| `/[resource]` | ListPage | No | Browse items |
+| `/[resource]/:id` | DetailPage | No | View item |
+| `/dashboard` | Dashboard | Yes | User dashboard |
+| `/admin` | AdminPanel | Admin | Admin controls |
+
+---
+
+## Authentication & Authorization
+
+### Auth Method
+[e.g., JWT, Session, OAuth]
+
+### Roles
+| Role | Permissions |
+|------|-------------|
+| guest | View public content |
+| user | + Create, edit own content |
+| admin | + Manage all content, users |
+
+---
+
+## UI/UX Requirements
+
+### Design System
+- **Colors:** [Primary, Secondary, Accent]
+- **Typography:** [Font family]
+- **Components:** [shadcn/ui, custom]
+
+### Key UI Patterns
+- [ ] Mobile-first responsive
+- [ ] Dark mode support
+- [ ] Loading skeletons
+- [ ] Toast notifications
+- [ ] Form validation feedback
+
+---
+
+## Third-Party Integrations
+
+| Service | Purpose | Priority |
+|---------|---------|----------|
+| [Service 1] | [Purpose] | Required |
+| [Service 2] | [Purpose] | Optional |
+
+---
+
+## Success Metrics
+
+- [ ] [Metric 1]: [Target]
+- [ ] [Metric 2]: [Target]
+
+---
+
+## Out of Scope (v1)
+
+Things we're NOT building initially:
+- [Feature X] - Deferred to v2
+- [Feature Y] - Requires more research
+
+---
+
+## Notes for Claude
+
+### When building features:
+1. Check this blueprint for requirements
+2. Reference the Data Model for types
+3. Follow the API patterns established
+4. Match the UI/UX requirements
+
+### Feature completeness:
+- Blueprint requirements (this file)
+- Quality standards (`AI_RULES.md`)
+- Workflow process (`CLAUDE.md`)
+
+**Build what's specified. Build it completely.**