autoworkflow 2.2.1 → 3.0.0

package/CLAUDE.md

@@ -1,344 +1,120 @@
-# AutoWorkflow - System Prompt Layer
+# AutoWorkflow
 
-> **This file is the ENTRY POINT.** Claude MUST read this at the start of EVERY task.
+> Automated workflow enforcement via hooks + system prompts.
 
----
-
-## Session Start - FIRST THING
+## How It Works
 
-**Before ANY work, run this check:**
-
-```
-1. Check if instructions/BLUEPRINT.md exists
-2. If NO  → Run ONE audit → Update BOTH AI_RULES.md & BLUEPRINT.md
-3. If YES → Read both files and proceed
 ```
-
-### No Blueprint? Single Audit → Dual Output
-
+Hooks (automatic)     →  Trigger checks on events
+settings.json         →  Core instructions (system prompt)
+This file             →  Workflow details + gates
+instructions/         →  AI_RULES.md + BLUEPRINT.md (project-specific)
 ```
-⚠️ No BLUEPRINT.md found in this project.
-
-I'll run ONE audit to update TWO files:
-
-📄 AI_RULES.md → Tech Stack & File Structure (HOW to code)
-📘 BLUEPRINT.md → Features, Routes, APIs (WHAT exists)
 
-Running project audit now...
-```
+---
 
-### Single Audit Architecture
+## Workflow
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    ONE AUDIT SCAN                            │
-│                                                              │
-│  $ cat package.json        → Detect tech stack              │
-│  $ find src -type d        → Map file structure             │
-│  $ ls src/pages/           → Discover routes                │
-│  $ ls src/components/      → List components                │
-│  $ find src/api/           → Find API endpoints             │
-│  $ cat prisma/schema.prisma → Database models               │
-│  $ grep -r "fetch\|/api/"  → Map connections                │
-│                                                              │
-└─────────────────────────┬────────────────────────────────────┘
-                          │
-            ┌─────────────┴─────────────┐
-            ▼                           ▼
-   ┌─────────────────┐        ┌─────────────────┐
-   │  AI_RULES.md    │        │  BLUEPRINT.md   │
-   │  (Update)       │        │  (Generate)     │
-   │                 │        │                 │
-   │  ## Tech Stack  │        │  ## Features    │
-   │  - Framework: X │        │  - Feature 1 ✅ │
-   │  - Styling: Y   │        │  - Feature 2 ⚠️ │
-   │  - Database: Z  │        │                 │
-   │                 │        │  ## Routes      │
-   │  ## File Struct │        │  - / → Home     │
-   │  src/           │        │  - /about → ... │
-   │  ├── components │        │                 │
-   │  ├── pages      │        │  ## APIs        │
-   │  └── ...        │        │  - GET /api/x   │
-   └─────────────────┘        └─────────────────┘
-```
-
-**This prevents double audit runs - ONE scan updates BOTH files.**
-
-### Audit Output Format
-
-After scanning, present BOTH updates together:
-
+ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
 ```
-## 🔍 Audit Complete - Proposed Updates
-
-### 📄 AI_RULES.md Updates
 
-**Tech Stack** (will update):
-- Framework: [detected]
-- Styling: [detected]
-- Database: [detected]
-
-**File Structure** (will update):
-src/
-├── [directories found]
-└── [file counts]
+| Phase | Action |
+|-------|--------|
+| ANALYZE | Read relevant files, check BLUEPRINT.md |
+| PLAN | Design approach, show suggestions |
+| CONFIRM | Wait for user approval |
+| IMPLEMENT | Make changes (after approval only) |
+| VERIFY | Run `npm run verify` |
+| AUDIT | Run `npm run audit:ui` + `audit:cycles` |
+| COMMIT | Conventional commit format |
+| UPDATE | Update BLUEPRINT.md if new feature/route/API |
 
 ---
 
-### 📘 BLUEPRINT.md (will create)
-
-**Features Discovered:**
-| Feature | Frontend | Backend | Route | Status |
-|---------|----------|---------|-------|--------|
-| Auth | LoginForm.tsx | /api/auth | /login | ✅ |
-| Dashboard | Dashboard.tsx | /api/stats | /dashboard | ✅ |
-| Settings | ❌ None | /api/settings | ❌ None | ⚠️ ORPHAN |
+## Task Types
 
-**⚠️ Issues Found:**
-- Orphan API: /api/settings (no UI)
+| Type | Workflow | Audit? |
+|------|----------|--------|
+| feature | Full (9 phases) | Yes |
+| fix | ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → COMMIT | No |
+| refactor | ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT | Yes |
+| docs | ANALYZE → IMPLEMENT → COMMIT | No |
+| query | ANALYZE → RESPOND | No |
 
 ---
 
-**Should I save these updates?**
-- AI_RULES.md → Update Tech Stack & File Structure sections
-- BLUEPRINT.md → Create with discovered features
+## Gates (Blocking)
 
-(yes/no/edit first)
-```
+### 1. Plan Approval Gate
+**Before:** IMPLEMENT
+**Requires:** User says "yes", "proceed", "approved", etc.
 
-See `system/triggers.md#on:blueprint_missing` for trigger details.
+### 2. Verify Gate
+**Before:** AUDIT/COMMIT
+**Requires:** `npm run verify` passes (0 errors)
 
----
+### 3. Audit Gate
+**Before:** COMMIT (for features/refactors)
+**Requires:**
+- `npm run audit:ui` passes (no orphan features)
+- `npm run audit:cycles` passes (no circular deps)
 
-## System Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    THIS FILE (Entry Point)                   │
-│              Load on every task, route to system             │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    system/ (Control Layer)                   │
-│                                                              │
-│  triggers.md  │  loops.md  │  gates.md  │  router.md        │
-│  (events)     │  (cycles)  │  (blocks)  │  (routing)        │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                 instructions/ (Content Layer)                │
-│                                                              │
-│  CLAUDE.md    │  AI_RULES.md  │  BLUEPRINT.md               │
-│  (workflow)   │  (standards)   │  (project spec)             │
-└─────────────────────────────────────────────────────────────┘
-```
+### 4. Pre-Commit Gate
+**Before:** git commit
+**Blocks if:**
+- TODO/FIXME comments in diff
+- console.log statements in diff
+- Invalid commit message format
 
 ---
 
-## On Task Start - MANDATORY
-
-When you receive ANY task, you MUST:
-
-### 1. Route the Task
-Read `system/router.md` to classify:
-- Is this a feature, fix, refactor, query, etc.?
-- What workflow applies?
-- What gates are required?
-
-### 2. Load Control Systems
-- `system/triggers.md` - Event handling
-- `system/loops.md` - Verification cycles
-- `system/gates.md` - Blocking checkpoints
+## Blocking Rules
 
-### 3. Load Instructions
-- `instructions/CLAUDE.md` - Workflow steps
-- `instructions/AI_RULES.md` - Coding standards
-- `instructions/BLUEPRINT.md` - Project requirements
+| Rule | Description |
+|------|-------------|
+| No orphan features | Backend must have UI |
+| No TODO/FIXME | Complete the work |
+| No console.log | No debug logs |
+| No circular deps | Clean imports |
+| Conventional commits | `type(scope): description` |
 
 ---
 
-## Workflow Overview
-
-```
-ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
-   │        │       │          │          │        │        │        │
-   ▼        ▼       ▼          ▼          ▼        ▼        ▼        ▼
- Read    Design   Wait for   Write     Run npm   Check   Create   Update
- files   approach approval   code      verify   orphans  commit  BLUEPRINT
-```
-
-### Conditional Flows
-
-```
-Session Start:
-┌─────────────────────────────────────────────────┐
-│ Check BLUEPRINT.md exists?                       │
-├─────────────────────────────────────────────────┤
-│ NO  → Run /audit project → Generate both files  │
-│ YES → Read AI_RULES.md + BLUEPRINT.md → Proceed │
-└─────────────────────────────────────────────────┘
+## Commands
 
-After Commit:
-┌─────────────────────────────────────────────────┐
-│ Was new feature/route/API added?                 │
-├─────────────────────────────────────────────────┤
-│ YES → Prompt to update BLUEPRINT.md             │
-│ NO  → Skip update phase                          │
-└─────────────────────────────────────────────────┘
+```bash
+npm run verify        # TypeScript + ESLint
+npm run audit:ui      # Check orphan features
+npm run audit:cycles  # Check circular deps
+npm run format        # Prettier
 ```
 
 ---
 
-## Hard Rules (NEVER Bypass)
-
-### Blocking Gates
-| Gate | When | Blocks If |
-|------|------|-----------|
-| `plan_approval_gate` | Before implement | User hasn't approved |
-| `verify_gate` | After implement | TypeScript/ESLint errors |
-| `audit_gate` | Before commit (features) | Orphan features or cycles |
-| `pre_commit_gate` | Before commit | TODO/FIXME, console.log, etc. |
-
-### Blocking Rules
-- **No orphan features** - Backend MUST have UI
-- **No TODO/FIXME** - Complete the work
-- **No console.log** - No debug logs in code
-- **No circular deps** - Clean architecture
-- **Conventional commits** - type(scope): description
-
----
+## Instructions
 
-## Available Commands
+Read `instructions/AI_RULES.md` for coding standards.
+Read `instructions/BLUEPRINT.md` for project specification.
 
-| Command | Purpose |
-|---------|---------|
-| `/analyze [task]` | Analyze codebase for a task |
-| `/plan [task]` | Create implementation plan |
-| `/build [feature]` | Full workflow for features |
-| `/verify` | Run TypeScript + ESLint |
-| `/fix` | Fix verification errors |
-| `/audit` | Run UI + cycle audits |
-| `/audit project` | Full project scan → update BLUEPRINT.md |
-| `/suggest [task]` | Generate suggestions |
-| `/commit [msg]` | Pre-commit check + commit |
+If BLUEPRINT.md is missing, the session-check hook will trigger.
+Run a project audit and generate it.
 
 ---
 
 ## Quick Reference
 
-### Session Start
+**New feature:**
 ```
-Check BLUEPRINT.md exists?
-├── NO  → Run /audit project → Update AI_RULES.md + Create BLUEPRINT.md
-└── YES → Read both → Proceed
+Analyze → Plan+Suggest → [approval] → Implement → Verify → Audit → Commit → Update Blueprint
 ```
 
-### For Features
+**Bug fix:**
 ```
-/build [description]
-→ Runs: ANALYZE → PLAN+SUGGEST → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
+Analyze → Plan → [approval] → Implement → Verify → Commit
 ```
 
-### For Fixes
-```
-/analyze [issue] → /plan → [approval] → implement → /verify → /commit
-```
-
-### For Questions
-```
-/analyze [question]
-→ Returns information, no implementation
-```
-
----
-
-## File Map
-
+**Question:**
 ```
-@autoworkflow/
-├── CLAUDE.md                 ← YOU ARE HERE (Entry Point)
-│
-├── system/                   ← Control Layer
-│   ├── triggers.md           Event → Action mappings
-│   ├── loops.md              Repeat-until definitions
-│   ├── gates.md              Blocking checkpoints
-│   └── router.md             Task type routing
-│
-├── instructions/             ← Content Layer
-│   ├── CLAUDE.md             Workflow steps
-│   ├── AI_RULES.md           Coding standards
-│   └── BLUEPRINT.md          Project specification
-│
-├── scripts/                  ← Automation Scripts
-│   ├── setup.sh              One-command project setup
-│   ├── autoworkflow.sh       CLI orchestrator
-│   ├── run-verification.sh   Verification with output
-│   ├── ensure-no-errors.sh   Pre-commit check
-│   └── check-ui-enforcement.sh  Orphan feature detection
-│
-├── hooks/                    ← Git Hooks
-│   ├── pre-commit            Blocks bad commits
-│   └── commit-msg            Validates commit format
-│
-├── .claude/                  ← Claude Code Integration
-│   ├── settings.json         Settings + instructions
-│   └── commands/             Slash command definitions
-│       ├── analyze.md
-│       ├── plan.md
-│       ├── build.md
-│       ├── verify.md
-│       ├── fix.md
-│       ├── audit.md
-│       ├── suggest.md
-│       └── commit.md
-│
-├── .vscode/                  ← VS Code Integration
-│   ├── settings.json         Editor settings
-│   ├── tasks.json            Runnable tasks
-│   └── extensions.json       Recommended extensions
-│
-├── .prettierrc               ← Prettier config
-├── eslint.config.example.js  ← ESLint reference
-└── tsconfig.example.json     ← TypeScript reference
+Analyze → Respond
 ```
-
----
-
-## Enforcement Summary
-
-**Claude is the PRIMARY enforcement engine.** These files control behavior:
-
-1. **system/triggers.md** - WHEN to act
-2. **system/loops.md** - HOW to repeat until success
-3. **system/gates.md** - WHAT blocks progress
-4. **system/router.md** - WHERE to route tasks
-5. **instructions/CLAUDE.md** - THE workflow to follow
-6. **instructions/AI_RULES.md** - THE standards to meet
-
-**Backup enforcement via automation:**
-
-7. **hooks/pre-commit** - Blocks commits with errors (git hook)
-8. **hooks/commit-msg** - Validates commit format (git hook)
-9. **scripts/check-ui-enforcement.sh** - Detects orphan features
-10. **scripts/autoworkflow.sh** - CLI for manual workflow runs
-
-Claude follows the instructions. Hooks catch anything that slips through.
-
----
-
-## Start Here
-
-For every task:
-1. Read this file (done)
-2. Check if `instructions/BLUEPRINT.md` exists
-   - If NO → Run `/audit project` first
-   - If YES → Read it and proceed
-3. Read `system/router.md` to classify task
-4. Follow the appropriate workflow
-5. Never skip gates
-6. Complete features fully
-7. Update BLUEPRINT.md after adding features
-
-**VERIFY ALWAYS. CHECK BLUEPRINT. NO ORPHANS. ONE AUDIT → TWO FILES.**