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

### 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
```bash
npm run verify           # TypeScript + ESLint
npm run typecheck        # TypeScript only
npm run lint             # ESLint only
```

### Audits
```bash
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`:
```markdown
## 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