autoworkflow 1.2.0 → 2.0.1

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.**

package/instructions/CLAUDE.md

@@ -0,0 +1,472 @@
+# Workflow Instructions
+
+> The complete workflow that Claude MUST follow for all coding tasks.
+> This is the source of truth for HOW to work on this project.
+
+---
+
+## Workflow Phases
+
+```
+1. ANALYZE   → Read files, understand context
+2. PLAN      → Design approach, show suggestions
+3. CONFIRM   → Wait for user approval
+4. IMPLEMENT → Make changes (after approval only)
+5. VERIFY    → npm run verify (typecheck + lint)
+6. FIX       → If errors: fix → verify → repeat
+7. AUDIT     → npm run audit:ui + audit:cycles
+8. COMMIT    → Conventional commit (after approval)
+9. UPDATE    → Update BLUEPRINT.md (if new feature/route/api)
+```
+
+---
+
+## Phase 1: ANALYZE
+
+**Purpose:** Understand what exists before making changes
+
+**Actions:**
+1. Read `instructions/AI_RULES.md` for project standards
+2. Read `instructions/BLUEPRINT.md` for requirements
+3. Read relevant source files
+4. Identify affected files and patterns
+5. Note existing conventions to follow
+
+**Output:**
+```
+## Analysis
+
+**Request:** [what user asked for]
+**Affected files:** [list]
+**Existing patterns:** [observations]
+**Requirements from BLUEPRINT:** [relevant items]
+```
+
+**Gate:** `analyze_gate` - Must have read relevant files
+
+---
+
+## Phase 2: PLAN
+
+**Purpose:** Design the implementation approach
+
+**Actions:**
+1. Break task into specific changes
+2. List files to create/modify
+3. Identify potential issues
+4. Prepare suggestions (for features)
+
+**Output:**
+```
+## Plan
+
+**Task:** [description]
+
+### Proposed Changes
+1. [Change 1] - [file]
+2. [Change 2] - [file]
+3. [Change 3] - [file]
+
+### Suggestions (for features)
+
+🔴 **Required:**
+- [ ] [Must-have item 1]
+- [ ] [Must-have item 2]
+
+🟡 **Recommended:**
+- [ ] [Should-have item 1]
+- [ ] [Should-have item 2]
+
+🟢 **Optional:**
+- [ ] [Nice-to-have item 1]
+
+**Should I proceed?**
+**Which suggestions to include?** (all/required/none/1,2,4)
+```
+
+**When to show suggestions:**
+| Task Type | Show Suggestions? |
+|-----------|-------------------|
+| New feature | Always |
+| New component | Always |
+| New page/route | Always |
+| Bug fix | Only if reveals missing handling |
+| Refactor | Only if scope expands |
+| Style changes | Skip |
+| Config changes | Skip |
+
+---
+
+## Phase 3: CONFIRM
+
+**Purpose:** Get explicit user approval before implementing
+
+**Actions:**
+1. Wait for user response
+2. Parse approval or rejection
+3. Note which suggestions to include
+4. Proceed only with explicit approval
+
+**Approval signals:**
+- "yes", "y", "proceed", "go ahead"
+- "approved", "lgtm", "looks good"
+- "all" (include all suggestions)
+- "required" (required suggestions only)
+- "1, 3, 5" (specific suggestion numbers)
+
+**Rejection signals:**
+- "no", "wait", "hold on"
+- "change [x]", questions asking for revision
+
+**Gate:** `plan_approval_gate` - MUST have user approval
+
+---
+
+## Phase 4: IMPLEMENT
+
+**Purpose:** Make the actual code changes
+
+**Rules:**
+1. Only change files mentioned in plan
+2. Include approved suggestions
+3. Follow patterns from AI_RULES.md
+4. No TODO/FIXME comments
+5. No console.log statements
+6. No partial implementations
+7. Complete feature fully
+
+**Actions:**
+1. Create/modify files as planned
+2. Implement all approved items
+3. Follow existing code patterns
+4. Ensure feature is complete (UI + Backend)
+
+**Output:**
+```
+## Implementation
+
+### Changes Made
+- [x] [Change 1] - [file]
+- [x] [Change 2] - [file]
+- [x] [Change 3] - [file]
+
+### Suggestions Included
+- [x] [Suggestion 1]
+- [x] [Suggestion 3]
+
+Proceeding to verification...
+```
+
+---
+
+## Phase 5: VERIFY
+
+**Purpose:** Ensure code quality before commit
+
+**Commands:**
+```bash
+npm run verify
+# Runs: npm run typecheck && npm run lint
+```
+
+**Actions:**
+1. Run verification command
+2. Parse output for errors
+3. If errors → enter FIX phase
+4. If clean → proceed to AUDIT (or COMMIT)
+
+**Output (Success):**
+```
+## Verification
+
+✅ **PASSED**
+
+| Check | Status |
+|-------|--------|
+| TypeScript | ✅ 0 errors |
+| ESLint | ✅ 0 warnings |
+
+Proceeding to audit...
+```
+
+**Output (Failure):**
+```
+## Verification
+
+❌ **FAILED**
+
+Found 3 error(s):
+
+1. `src/Button.tsx:15` - Property 'onClick' missing
+2. `src/useAuth.ts:42` - Type mismatch
+3. `src/Home.tsx:8` - Unused variable
+
+Entering fix loop...
+```
+
+**Loop:** `verify_loop` - Repeat until pass (max 10 iterations)
+
+---
+
+## Phase 6: FIX
+
+**Purpose:** Resolve verification errors
+
+**Actions:**
+1. Parse each error
+2. Read error context
+3. Apply fix
+4. Return to VERIFY
+
+**Output:**
+```
+## Fix Loop (Iteration 2/10)
+
+**Fixing:**
+- [x] `src/Button.tsx:15` - Added onClick prop
+- [x] `src/useAuth.ts:42` - Fixed return type
+- [x] `src/Home.tsx:8` - Removed unused import
+
+Re-running verification...
+```
+
+**Loop:** `fix_loop` - Fix errors one by one
+
+---
+
+## Phase 7: AUDIT
+
+**Purpose:** Enforce UI completeness and architecture rules
+
+**When required:**
+- New features
+- New components
+- Refactoring
+- Performance changes
+
+**Commands:**
+```bash
+npm run audit:ui       # Check orphan features
+npm run audit:cycles   # Check circular deps
+```
+
+**Checks:**
+1. **UI Enforcement:**
+   - Every API has a UI that calls it
+   - Every hook is used by a component
+   - User can access every feature
+
+2. **Circular Dependencies:**
+   - No import cycles (A → B → A)
+
+**Output (Success):**
+```
+## Audit
+
+| Check | Status |
+|-------|--------|
+| UI Enforcement | ✅ No orphans |
+| Circular Deps | ✅ No cycles |
+
+Ready to commit.
+```
+
+**Output (Failure):**
+```
+## Audit
+
+| Check | Status |
+|-------|--------|
+| UI Enforcement | ⛔ BLOCKED |
+| Circular Deps | ✅ No cycles |
+
+**Orphan features detected:**
+- `/api/users` has no UI component
+- `useAuth` hook is not used
+
+BLOCKED: Must add UI before commit.
+
+Building missing components...
+```
+
+**Gate:** `audit_gate` - No orphans, no cycles
+
+---
+
+## Phase 8: COMMIT
+
+**Purpose:** Create a conventional commit
+
+**Pre-commit checks:**
+1. Verification passed
+2. Audits passed (if applicable)
+3. No TODO/FIXME in diff
+4. No console.log in diff
+5. Valid commit message format
+
+**Commit message format:**
+```
+type(scope): description
+
+Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+```
+
+**Actions:**
+1. Run pre-commit gate
+2. Show commit preview
+3. Wait for user confirmation
+4. Execute commit
+
+**Output:**
+```
+## Pre-Commit Check
+
+| Check | Status |
+|-------|--------|
+| TypeScript | ✅ |
+| ESLint | ✅ |
+| UI Enforcement | ✅ |
+| Circular Deps | ✅ |
+| TODO/FIXME | ✅ |
+| console.log | ✅ |
+
+**Ready to commit:**
+- 3 files changed
+- Message: `feat(auth): add login page`
+
+**Should I commit?**
+```
+
+**Gate:** `pre_commit_gate` - All checks must pass
+
+---
+
+## Blocking Rules
+
+### Cannot Proceed Without:
+
+| Rule | Enforcement |
+|------|-------------|
+| No orphan features | `npm run audit:ui` |
+| No TODO/FIXME | grep in pre-commit |
+| No console.log | grep in pre-commit |
+| No circular deps | `npm run audit:cycles` |
+| TypeScript clean | `npm run typecheck` |
+| ESLint clean | `npm run lint` |
+| Conventional commits | commitlint |
+
+### Feature Completeness:
+```
+FEATURE IS NOT COMPLETE UNLESS:
+├── Backend (API/logic)     ✓
+├── Frontend (UI component) ✓  ← REQUIRED
+├── Connection (UI calls API) ✓
+└── Access (user can reach it) ✓
+```
+
+---
+
+## Response Format
+
+For every task, Claude MUST follow this format:
+
+```
+## Task: [description]
+
+### 1. Analysis
+[findings from codebase]
+
+### 2. Plan + Suggestions
+📋 **Proposed changes:**
+1. [Change 1]
+2. [Change 2]
+
+💡 **Suggestions:**
+🔴 Required: [list]
+🟡 Recommended: [list]
+🟢 Optional: [list]
+
+**Should I proceed? Which suggestions?**
+
+--- (wait for approval) ---
+
+### 3. Implementation
+[changes made]
+
+### 4. Verification
+[npm run verify output]
+Status: ✅ PASSED / ❌ FAILED
+
+### 5. Audit (if required)
+[npm run audit:ui && audit:cycles output]
+Status: ✅ PASSED / ❌ FAILED
+
+### 6. Fix (if errors)
+[fixes applied, re-verify]
+
+### 7. Commit
+**Should I commit: "type(scope): description"?**
+
+### Summary
+✅ [what was completed]
+Suggestions included: [list]
+```
+
+---
+
+## Phase 9: UPDATE BLUEPRINT
+
+**Purpose:** Keep BLUEPRINT.md in sync with codebase
+
+**When required:**
+- New feature added
+- New route created
+- New API endpoint added
+- Feature removed or deprecated
+
+**Actions:**
+1. Check if new feature/route/API was added
+2. Prepare BLUEPRINT.md update
+3. Present update to user
+4. Apply after approval
+
+**Output:**
+```
+## 📘 Blueprint Update
+
+Adding to BLUEPRINT.md:
+
+**Features:**
+- [Feature name] - [description]
+
+**Routes:**
+- [path] → [Component]
+
+**APIs:**
+- [method] [endpoint] - [description]
+
+**Should I update BLUEPRINT.md?**
+```
+
+See `system/triggers.md#on:feature_complete` for trigger details.
+
+---
+
+## Quick Reference
+
+**For new features:**
+```
+Analyze → Plan+Suggest → Confirm → Implement → Verify → Audit → Commit → Update Blueprint
+```
+
+**For bug fixes:**
+```
+Analyze → Plan → Confirm → Implement → Verify → Commit
+```
+
+**For queries:**
+```
+Analyze → Respond
+```
+
+**VERIFY ALWAYS. AUDIT FEATURES. UPDATE BLUEPRINT. ASK BEFORE ACTIONS.**