AutoWorkflow

Automated workflow enforcement for Claude Code via hooks and system prompts.

v3.8.4 - Updated documentation + VS Code extension hook fix.

When you use Claude Code with AutoWorkflow, hooks automatically enforce workflow phases, block unauthorized edits, and guide Claude through a structured process for all coding tasks.

Installation

npx autoworkflow init

CLI Commands

| Command | Description | |---------|-------------| | npx autoworkflow init | Fresh install (required + recommended files) | | npx autoworkflow init --all | Include .vscode and config templates | | npx autoworkflow init --minimal | Required files only | | npx autoworkflow init --force | Full reinstall (backup + overwrite all) | | npx autoworkflow update | Smart update - core files only, preserve user files | | npx autoworkflow status | Show installed version and components |

Smart Updates

The CLI tracks installed versions and preserves user customizations:

npx autoworkflow status     # Check version and what would change
npx autoworkflow update     # Update core files, preserve user files

| File Category | On init | On update | |---------------|-----------|-------------| | Core (hooks, system, CLAUDE.md) | Installed | Updated | | User (AI_RULES.md, your docs) | Created if missing | Preserved | | Commands/Skills | Installed | Updated | | Optional (.vscode, configs) | Only with --all | Skipped |

Key Features

Multi-Language Verification

Automatic verification for any project type:

| Project Type | Detection | Verification | |--------------|-----------|--------------| | Node.js | package.json | TypeScript + ESLint | | PHP | composer.json | PHPStan, PHP-CS-Fixer | | Python | pyproject.toml | mypy, ruff, flake8 | | Rust | Cargo.toml | cargo check + clippy | | Go | go.mod | go vet + golangci-lint |

Fail-Closed Enforcement

All gates are checked on every edit. Unknown state = strictest defaults:

| Gate | Blocks If | Applies To | |------|-----------|------------| | Plan Approval | User hasn't approved | feature, fix, refactor | | Suggestions | 3-tier suggestions not shown | feature tasks | | One Edit/Turn | Already edited this turn | strict task types |

3-Tier Suggestions

For feature tasks, Claude MUST show categorized suggestions:

• 🔴 Required - Must implement
• 🟡 Recommended - Should implement
• 🟢 Optional - Nice to have

106 Skills Library

Auto-loaded knowledge for each command via skills_required in command frontmatter:

• Security patterns, debugging, code review
• Framework-specific (React, Next.js, Laravel, Django, etc.)

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    HOOKS (10 Scripts)                        │
│                                                              │
│  UserPromptSubmit  →  session-check.sh                      │
│                       (resume, turn reset, blueprint check) │
│                                                              │
│  PreToolUse        →  pre-edit.sh (Write/Edit)              │
│                       (3 gates: approval, suggestions, 1/turn)│
│                   →  pre-tool-router.sh (Bash)              │
│                       → pre-commit-check.sh (7 gate checks) │
│                                                              │
│  PostToolUse       →  post-edit.sh (Write/Edit)             │
│                       (multi-lang verification loop)        │
│                   →  post-bash-router.sh (Bash)             │
│                       → post-commit.sh (commit summary)     │
│                                                              │
│  Hooks ENFORCE workflow - they physically block actions     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                 settings.json (System Prompt)                │
│                                                              │
│  Workflow instructions + skill loading + task types         │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              .claude/skills/ (106 Knowledge Files)           │
│                                                              │
│  Security, debugging, frameworks, patterns, best practices  │
└─────────────────────────────────────────────────────────────┘

The Workflow

ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
                    ↑           ↑                          ↑
               BLOCKING     BLOCKING                   BLOCKING
                GATE          GATE                       GATE

| Phase | What Happens | Enforcement | |-------|--------------|-------------| | ANALYZE | Read relevant files, check user's documentation | - | | PLAN | Design approach, show 3-tier suggestions | - | | CONFIRM | Wait for user approval | pre-edit.sh BLOCKS edits | | IMPLEMENT | Make changes (after approval only) | Allowed after approval | | VERIFY | Run npm run verify (max 10 iterations) | Auto-triggered by hook | | AUDIT | Check orphan features + circular deps | Required for features | | COMMIT | Conventional commit format | pre-commit.sh BLOCKS bad commits | | UPDATE | Note changes in session context | post-commit.sh reminder |

Auto-Triggers (10 Hooks)

| Hook | Trigger | Action | |------|---------|--------| | session-check.sh | UserPromptSubmit | Resume session, reset turn counter, check docs | | pre-edit.sh | PreToolUse (Write/Edit) | BLOCK if: no approval, no suggestions, or multiple fixes | | post-edit.sh | PostToolUse (Write/Edit) | Detect project type, run verification | | pre-tool-router.sh | PreToolUse (Bash) | Routes to pre-commit-check for git commits | | post-bash-router.sh | PostToolUse (Bash) | Routes to post-commit for git commits | | pre-commit-check.sh | Before git commit | BLOCK with 7 gate checks (TS, ESLint, TODO, etc.) | | post-commit.sh | After git commit | Commit summary | | phase-transition.sh | Manual/internal | State management between workflow phases | | audit-runner.sh | Manual/internal | Run UI enforcement + circular dep checks | | blueprint-generator.sh | Manual/internal | Scan project structure |

Session Resume

When returning to an interrupted session:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 AUTOWORKFLOW: SESSION RESUME
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Previous session state detected:

  Phase:           IMPLEMENT
  Task type:       feature
  Plan approved:   true
  Verify attempts: 2/10

Continue from IMPLEMENT phase, or start fresh?

File Structure

project/
├── CLAUDE.md                 # Workflow summary (auto-read)
│
├── .claude/
│   ├── settings.json         # Hooks + system prompt
│   ├── hooks/                # 10 enforcement scripts
│   │   ├── session-check.sh      # Session init + docs check
│   │   ├── pre-edit.sh           # Plan approval gate (3 checks)
│   │   ├── post-edit.sh          # Auto-verification loop
│   │   ├── pre-tool-router.sh    # Routes Bash commands
│   │   ├── post-bash-router.sh   # Routes post-Bash actions
│   │   ├── pre-commit-check.sh   # 7 gate checks before commit
│   │   ├── post-commit.sh        # Commit summary
│   │   ├── phase-transition.sh   # State management
│   │   ├── audit-runner.sh       # UI + cycle audits
│   │   └── blueprint-generator.sh # Scan project for technical context
│   ├── commands/             # 9 slash commands
│   └── skills/               # 106 knowledge files
│
├── instructions/
│   ├── AI_RULES.md           # Your coding standards
│   └── (user's documentation) # Single source of truth
│
├── system/                   # Detailed reference
│   ├── gates.md              # Blocking checkpoint definitions
│   ├── loops.md              # Verify/fix cycle definitions
│   ├── triggers.md           # Event → action mappings
│   └── router.md             # Task type classification
│
└── scripts/                  # Automation scripts

Commands

Verification

npm run verify           # TypeScript + ESLint
npm run typecheck        # TypeScript only
npm run lint             # ESLint only

Audits

npm run audit:ui         # Check orphan features
npm run audit:cycles     # Check circular deps
npm run audit:all        # Run all audits

Slash Commands

| Command | Role | Purpose | |---------|------|---------| | /analyze [task] | Technical Analyst | Analyze codebase, classify task | | /plan [task] | Project Manager | Create implementation plan | | /suggest [task] | Technical Advisor | Generate 3-tier suggestions | | /build [feature] | Full-Stack Engineer | Full workflow with tech detection | | /verify | QA Engineer | Run verification loop | | /fix | Debug Engineer | Fix verification errors | | /audit | Code Reviewer | Security + quality audit | | /audit project | Code Reviewer | Full scan → technical context | | /commit | Git Specialist | Pre-commit check + commit |

Customization

Your Coding Standards

Edit instructions/AI_RULES.md:

## ALWAYS
- Use TypeScript strict mode
- Handle all error cases

## NEVER
- Use `any` type
- Leave console.logs

Adjust Gates

Edit .claude/settings.json gates section.

Modify Hooks

Edit files in .claude/hooks/ to change enforcement behavior.

Add Skills

Add .md files to .claude/skills/ and reference in command frontmatter.

Requirements

• VS Code with Claude Code extension (or Claude Code CLI)
• Node.js 18+ (for npm scripts)
• TypeScript, ESLint, Prettier (for verification)

License

MIT