autoworkflow 3.0.0 → 3.1.0

package/CLAUDE.md

@@ -1,16 +1,53 @@
 # AutoWorkflow
 
 > Automated workflow enforcement via hooks + system prompts.
+> **All automation is hook-driven → Claude executes the actual work**
 
 ## How It Works
 
 ```
-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)
+┌─────────────────────────────────────────────────────────────┐
+│  USER MESSAGE                                               │
+│       ↓                                                     │
+│  HOOK TRIGGERS (shell scripts)                              │
+│       ↓                                                     │
+│  HOOK OUTPUT (instructions/prompts for Claude)              │
+│       ↓                                                     │
+│  CLAUDE READS OUTPUT + ACTS                                 │
+│       ↓                                                     │
+│  RESPONSE TO USER                                           │
+└─────────────────────────────────────────────────────────────┘
 ```
 
+**Key:** Hooks OUTPUT instructions → Claude READS them → Claude DOES the work
+
+---
+
+## Architecture
+
+```
+.claude/hooks/           →  AUTO-TRIGGERS (output prompts to Claude)
+.claude/settings.json    →  HOOK CONFIG + SYSTEM INSTRUCTIONS
+.claude/.autoworkflow/   →  STATE FILES (phase, iterations, etc.)
+CLAUDE.md (this file)    →  WORKFLOW SUMMARY
+instructions/            →  AI_RULES.md + BLUEPRINT.md
+system/                  →  DETAILED REFERENCE (gates, loops, triggers, router)
+```
+
+**Priority:** Hooks → settings.json → This file → system/*.md
+
+---
+
+## Auto-Triggers (Hooks)
+
+| Event | Hook | Output to Claude |
+|-------|------|------------------|
+| User message | `session-check.sh` | "BLUEPRINT missing - run audit NOW" |
+| After Write/Edit | `post-edit.sh` | Runs `npm run verify`, shows errors |
+| Before git commit | `pre-tool-router.sh` | Runs all 7 gate checks, BLOCKS if fail |
+
+**Hooks don't do the work - they tell Claude what to do!**
+
 ---
 
 ## Workflow
@@ -19,69 +56,102 @@ instructions/         →  AI_RULES.md + BLUEPRINT.md (project-specific)
 ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
 ```
 
-| Phase | Action |
-|-------|--------|
+| Phase | What Claude Does |
+|-------|------------------|
 | ANALYZE | Read relevant files, check BLUEPRINT.md |
 | PLAN | Design approach, show suggestions |
-| CONFIRM | Wait for user approval |
+| CONFIRM | **Wait for user approval** |
 | IMPLEMENT | Make changes (after approval only) |
-| VERIFY | Run `npm run verify` |
+| VERIFY | Run `npm run verify` - **AUTO-TRIGGERED** |
 | AUDIT | Run `npm run audit:ui` + `audit:cycles` |
-| COMMIT | Conventional commit format |
+| COMMIT | Conventional commit format - **BLOCKED if checks fail** |
 | UPDATE | Update BLUEPRINT.md if new feature/route/API |
 
 ---
 
+## Auto-Verification Loop
+
+After EVERY code edit, `post-edit.sh` automatically:
+1. Runs `npm run verify`
+2. Shows errors to Claude
+3. Claude fixes them
+4. Repeats until passing (max 10 iterations)
+
+```
+EDIT → HOOK RUNS VERIFY → ERRORS? → CLAUDE FIXES → VERIFY AGAIN → ...
+```
+
+---
+
+## Pre-Commit Gate (7 Checks)
+
+Before `git commit`, `pre-commit-check.sh` runs:
+
+| Check | Pass Condition |
+|-------|----------------|
+| TypeScript | 0 errors |
+| ESLint | 0 warnings |
+| TODO/FIXME | None in staged files |
+| console.log | None in staged files |
+| UI Enforcement | No orphan features |
+| Circular Deps | No import cycles |
+| Commit Format | `type(scope): description` |
+
+**If ANY check fails → Commit is BLOCKED (exit 1)**
+
+---
+
 ## Task Types
 
 | 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 |
+| feature | Full (all phases) | Yes |
+| fix | Standard (no audit) | No |
+| refactor | With audit | Yes |
+| docs | Simple | No |
+| query | Analyze → Respond | No |
 
 ---
 
-## Gates (Blocking)
+## State Tracking
 
-### 1. Plan Approval Gate
-**Before:** IMPLEMENT
-**Requires:** User says "yes", "proceed", "approved", etc.
+All state stored in `.claude/.autoworkflow/`:
+- `phase` - Current workflow phase
+- `task-type` - Classified task type
+- `verify-iteration` - Loop count (max 10)
+- `verify-status` - PASSED/FAILED
+- `plan-approved` - User approval status
 
-### 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)
+## Blocking Rules
 
-### 4. Pre-Commit Gate
-**Before:** git commit
-**Blocks if:**
-- TODO/FIXME comments in diff
-- console.log statements in diff
-- Invalid commit message format
+- **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`
 
 ---
 
-## Blocking Rules
-
-| 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` |
+## Slash Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/analyze [topic]` | Analyze codebase for a task |
+| `/plan [task]` | Create implementation plan |
+| `/verify` | Run TypeScript + ESLint |
+| `/audit` | Run UI + cycle audits |
+| `/audit project` | Full project scan → generate BLUEPRINT.md |
+| `/commit [msg]` | Pre-commit gate + commit |
+| `/init` | Set up AutoWorkflow files |
+| `/fix` | Fix verification errors |
+| `/suggest` | Show suggestions for current task |
+| `/build` | Build a feature end-to-end |
 
 ---
 
-## Commands
+## NPM Commands
 
 ```bash
 npm run verify        # TypeScript + ESLint
@@ -92,13 +162,39 @@ npm run format        # Prettier
 
 ---
 
-## Instructions
+## Hook Files
+
+| Hook | Trigger Event | Purpose |
+|------|---------------|---------|
+| `session-check.sh` | UserPromptSubmit | Init, blueprint check, task classify |
+| `post-edit.sh` | PostToolUse (Write\|Edit) | Auto-verify with loop tracking |
+| `pre-tool-router.sh` | PreToolUse (Bash) | Route to appropriate check |
+| `pre-commit-check.sh` | Before git commit | All 7 gate checks, BLOCKS |
+| `phase-transition.sh` | Manual call | State management |
+| `audit-runner.sh` | Manual call | Run UI + cycle audits |
+| `blueprint-generator.sh` | Manual call | Scan project |
+
+---
+
+## Required Reading
+
+| File | Purpose |
+|------|---------|
+| `instructions/AI_RULES.md` | Your coding standards |
+| `instructions/BLUEPRINT.md` | Project specification |
+
+If BLUEPRINT.md is missing → Hook triggers AUTO-AUDIT (no permission needed)
+
+---
 
-Read `instructions/AI_RULES.md` for coding standards.
-Read `instructions/BLUEPRINT.md` for project specification.
+## Detailed Reference
 
-If BLUEPRINT.md is missing, the session-check hook will trigger.
-Run a project audit and generate it.
+| File | Contains |
+|------|----------|
+| `system/triggers.md` | Event → Hook → Claude action mappings |
+| `system/gates.md` | Blocking checkpoint definitions |
+| `system/loops.md` | Verify/fix cycle definitions |
+| `system/router.md` | Task type classification |
 
 ---
 
@@ -106,12 +202,12 @@ Run a project audit and generate it.
 
 **New feature:**
 ```
-Analyze → Plan+Suggest → [approval] → Implement → Verify → Audit → Commit → Update Blueprint
+Analyze → Plan+Suggest → [approval] → Implement → VERIFY(auto) → Audit → Commit(blocked) → Update
 ```
 
 **Bug fix:**
 ```
-Analyze → Plan → [approval] → Implement → Verify → Commit
+Analyze → Plan → [approval] → Implement → VERIFY(auto) → Commit(blocked)
 ```
 
 **Question:**

package/bin/cli.js

@@ -107,7 +107,15 @@ function init(options = {}) {
   // Make Claude hooks executable
   if (process.platform !== 'win32' && existsSync(join(cwd, '.claude', 'hooks'))) {
     try {
-      const hookFiles = ['session-check.sh', 'post-edit.sh', 'pre-commit-check.sh'];
+      const hookFiles = [
+        'session-check.sh',
+        'post-edit.sh',
+        'pre-commit-check.sh',
+        'pre-tool-router.sh',
+        'phase-transition.sh',
+        'audit-runner.sh',
+        'blueprint-generator.sh'
+      ];
       hookFiles.forEach(hook => {
         const hookPath = join(cwd, '.claude', 'hooks', hook);
         if (existsSync(hookPath)) {

package/instructions/CLAUDE.md

@@ -5,6 +5,28 @@
 
 ---
 
+## Hook Integration
+
+Hooks automatically trigger workflow phases:
+
+| Hook | Triggers On | Phase Triggered |
+|------|-------------|-----------------|
+| `session-check.sh` | Every user message | ANALYZE (init, blueprint check) |
+| `post-edit.sh` | After Write/Edit | VERIFY (auto-runs npm run verify) |
+| `pre-commit-check.sh` | Before git commit | COMMIT gate (blocks if fails) |
+
+**State tracked in:** `.claude/.autoworkflow/`
+
+| File | Purpose | Max |
+|------|---------|-----|
+| `phase` | Current workflow phase | - |
+| `task-type` | Classified task type | - |
+| `verify-iteration` | Verify loop count | 10 |
+| `audit-iteration` | Audit loop count | 5 |
+| `plan-approved` | User approval status | - |
+
+---
+
 ## Workflow Phases
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoworkflow",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Automated workflow enforcement for Claude Code via hooks and system prompts",
   "type": "module",
   "bin": {