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

``bash
npx autoworkflow init
`

$3

| 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 |

$3

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

$3

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 |

$3

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

For feature tasks, Claude MUST show categorized suggestions:
- 🔴 Required - Must implement
- 🟡 Recommended - Should implement
- 🟢 Optional - Nice to have

$3

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

$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 cases

NEVER

- 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.

---

Requirements

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

---

License

MIT