autoworkflow 3.0.1 → 3.1.0

package/CLAUDE.md

@@ -1,12 +1,34 @@
 # AutoWorkflow
 
 > Automated workflow enforcement via hooks + system prompts.
+> **All automation is hook-driven → Claude executes the actual work**
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  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 (run on events)
-.claude/settings.json    →  SYSTEM PROMPT (core instructions)
+.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)
@@ -16,83 +38,120 @@ system/                  →  DETAILED REFERENCE (gates, loops, triggers, router
 
 ---
 
+## 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
 
 ```
 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** |
 | 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 |
 
 ---
 
-## Task Types
+## Auto-Verification Loop
 
-| Type | Workflow | Audit Required? |
-|------|----------|-----------------|
-| feature | Full 9 phases | Yes |
-| fix | ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → COMMIT | No |
-| refactor | ANALYZE → ... → VERIFY → AUDIT → COMMIT | Yes |
-| docs | ANALYZE → IMPLEMENT → COMMIT | No |
-| query | ANALYZE → RESPOND | No |
+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)
 
-See `system/router.md` for detailed task classification.
+```
+EDIT → HOOK RUNS VERIFY → ERRORS? → CLAUDE FIXES → VERIFY AGAIN → ...
+```
 
 ---
 
-## Blocking Gates
+## Pre-Commit Gate (7 Checks)
 
-| Gate | Blocks If | Reference |
-|------|-----------|-----------|
-| Plan Approval | User hasn't approved | `system/gates.md` |
-| Verify | TypeScript/ESLint errors | `system/gates.md` |
-| Audit | Orphan features or circular deps | `system/gates.md` |
-| Pre-Commit | TODO/FIXME, console.log, bad format | `system/gates.md` |
+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)**
 
 ---
 
-## Blocking Rules
+## Task Types
 
-- **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`
+| Type | Workflow | Audit? |
+|------|----------|--------|
+| feature | Full (all phases) | Yes |
+| fix | Standard (no audit) | No |
+| refactor | With audit | Yes |
+| docs | Simple | No |
+| query | Analyze → Respond | No |
 
 ---
 
-## Auto-Triggers (Hooks)
-
-| Event | Hook | Action |
-|-------|------|--------|
-| User message | `session-check.sh` | Check BLUEPRINT.md exists |
-| After Write/Edit | `post-edit.sh` | Remind to verify |
-| Before git commit | `pre-commit-check.sh` | Block bad commits |
+## State Tracking
 
-See `system/triggers.md` for all trigger definitions.
+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
 
 ---
 
-## Verification Loop
+## Blocking Rules
 
-```
-VERIFY → Failed? → FIX → VERIFY → Failed? → FIX → ... (max 10 iterations)
-```
+- **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`
+
+---
 
-See `system/loops.md` for loop definitions.
+## 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
@@ -103,6 +162,20 @@ npm run format        # Prettier
 
 ---
 
+## 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 |
@@ -110,7 +183,7 @@ npm run format        # Prettier
 | `instructions/AI_RULES.md` | Your coding standards |
 | `instructions/BLUEPRINT.md` | Project specification |
 
-If BLUEPRINT.md is missing, the session-check hook will trigger an automatic audit.
+If BLUEPRINT.md is missing → Hook triggers AUTO-AUDIT (no permission needed)
 
 ---
 
@@ -118,11 +191,10 @@ If BLUEPRINT.md is missing, the session-check hook will trigger an automatic aud
 
 | File | Contains |
 |------|----------|
-| `system/triggers.md` | Event → Action mappings |
+| `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 |
-| `instructions/CLAUDE.md` | Full 9-phase workflow details |
 
 ---
 
@@ -130,12 +202,12 @@ If BLUEPRINT.md is missing, the session-check hook will trigger an automatic aud
 
 **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.1",
+  "version": "3.1.0",
   "description": "Automated workflow enforcement for Claude Code via hooks and system prompts",
   "type": "module",
   "bin": {