Automated workflow enforcement for Claude Code via hooks and system prompts
npm install 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.
---
``bash`
npx autoworkflow init
| 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 |
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 |--all
|---------------|-----------|-------------|
| 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 | Skipped |
---
| Project Type | Detection | Verification |
|--------------|-----------|--------------|
| Node.js | package.json | TypeScript + ESLint |composer.json
| PHP | | PHPStan, PHP-CS-Fixer |pyproject.toml
| Python | | mypy, ruff, flake8 |Cargo.toml
| Rust | | cargo check + clippy |go.mod
| Go | | go vet + golangci-lint |
| 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 |
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
$3
`bash
npm run verify # TypeScript + ESLint
npm run typecheck # TypeScript only
npm run lint # ESLint only
`$3
`bash
npm run audit:ui # Check orphan features
npm run audit:cycles # Check circular deps
npm run audit:all # Run all audits
`$3
| 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
$3
Edit instructions/AI_RULES.md:
`markdown
ALWAYS
- Use TypeScript strict mode
- Handle all error casesNEVER
- Use any type
- Leave console.logs
`$3
Edit .claude/settings.json gates section.$3
Edit files in .claude/hooks/ to change enforcement behavior.$3
Add .md files to .claude/skills/` and reference in command frontmatter.---
- VS Code with Claude Code extension (or Claude Code CLI)
- Node.js 18+ (for npm scripts)
- TypeScript, ESLint, Prettier (for verification)
---
MIT