autoworkflow 3.1.4 → 3.5.0

package/README.md

@@ -2,7 +2,9 @@
 
 > Automated workflow enforcement for Claude Code via hooks and system prompts.
 
-When you use Claude Code with AutoWorkflow, hooks automatically trigger checks and Claude follows a structured workflow for all coding tasks.
+**v3.5.0** - Full hook enforcement, 106 skills library, agent-structured commands.
+
+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.
 
 ---
 
@@ -19,35 +21,66 @@ Options:
 
 ---
 
+## What's New in v3.5.0
+
+### Hook-Based Enforcement (Not Just Instructions)
+
+| Hook | Event | Enforcement |
+|------|-------|-------------|
+| `pre-edit.sh` | PreToolUse (Write/Edit) | **BLOCKS** edits without plan approval |
+| `post-commit.sh` | PostToolUse (Bash) | Auto-triggers BLUEPRINT update reminder |
+| `session-check.sh` | UserPromptSubmit | Session resume with state display |
+
+### 106 Skills Library
+Claude loads relevant skills for each command:
+- Security patterns, debugging techniques, code review checklists
+- Framework-specific knowledge (React, Next.js, etc.)
+- Auto-loaded via `skills_required` in command frontmatter
+
+### Agent-Structured Commands
+Each command has a role, output schema, and guardrails:
+```yaml
+---
+role: Senior Code Reviewer
+skills_required:
+  - security.md
+  - code-review.md
+output_schema:
+  issues: [{severity, file, line, message}]
+guardrails:
+  - Prioritize security issues above all else
+---
+```
+
+---
+
 ## How It Works
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                    HOOKS (Automatic)                         │
 │                                                              │
-│  UserPromptSubmit  →  session-check.sh                      │
-│  PostToolUse       →  post-edit.sh (after Write/Edit)       │
-│  PreToolUse        →  pre-commit-check.sh (before git)      │
+│  UserPromptSubmit  →  session-check.sh (resume, blueprint)  │
+│  PreToolUse        →  pre-edit.sh (BLOCKS without approval) │
+│  PreToolUse        →  pre-commit-check.sh (BLOCKS bad code) │
+│  PostToolUse       →  post-edit.sh (verification loop)      │
+│  PostToolUse       →  post-commit.sh (BLUEPRINT reminder)   │
 │                                                              │
-│  Hooks output messages that Claude sees as instructions     │
+│  Hooks ENFORCE workflow - they physically block actions     │
 └─────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                 settings.json (System Prompt)                │
 │                                                              │
-│  "instructions": [                                           │
-│    "SESSION START: If BLUEPRINT.md missing, scan codebase"  │
-│    "AFTER CODE CHANGES: Run npm run verify"                 │
-│    "BEFORE COMMIT: Block if TODO/console.log found"         │
-│  ]                                                           │
+│  Workflow instructions + skill loading + task types         │
 └─────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                   CLAUDE.md + instructions/                  │
+│              .claude/skills/ (106 Knowledge Files)           │
 │                                                              │
-│  Workflow details, gates, task types, coding standards      │
+│  Security, debugging, frameworks, patterns, best practices  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -57,18 +90,21 @@ Options:
 
 ```
 ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
+                    ↑           ↑                          ↑
+               BLOCKING     BLOCKING                   BLOCKING
+                GATE          GATE                       GATE
 ```
 
-| Phase | What Happens |
-|-------|--------------|
-| 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` (auto-triggered by hook) |
-| AUDIT | Check orphan features + circular deps |
-| COMMIT | Conventional commit format |
-| UPDATE | Update BLUEPRINT.md if needed |
+| Phase | What Happens | Enforcement |
+|-------|--------------|-------------|
+| ANALYZE | Read relevant files, check BLUEPRINT.md | - |
+| 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 | Update BLUEPRINT.md if needed | **post-commit.sh reminder** |
 
 ---
 
@@ -76,20 +112,55 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 | Hook | Trigger | Action |
 |------|---------|--------|
-| `session-check.sh` | Every user message | Check if BLUEPRINT.md exists, prompt audit if missing |
-| `post-edit.sh` | After Write/Edit | Remind to run verification |
-| `pre-commit-check.sh` | Before git commit | Block if TODO/FIXME/console.log found |
+| `session-check.sh` | Every user message | Resume previous session, check BLUEPRINT.md |
+| `pre-edit.sh` | Before Write/Edit | **BLOCK if plan not approved** |
+| `post-edit.sh` | After Write/Edit | Run verification loop (max 10 iterations) |
+| `pre-commit-check.sh` | Before git commit | **BLOCK if TODO/console.log/errors** |
+| `post-commit.sh` | After git commit | Remind to update BLUEPRINT.md |
 
 ---
 
 ## Blocking Gates
 
-| Gate | Blocks If |
-|------|-----------|
-| Plan Approval | User hasn't approved the plan |
-| Verify | TypeScript or ESLint errors exist |
-| Audit | Orphan features or circular dependencies |
-| Pre-Commit | TODO/FIXME, console.log, bad commit format |
+| Gate | Blocks If | Enforced By |
+|------|-----------|-------------|
+| Plan Approval | User hasn't approved the plan | `pre-edit.sh` (exit 1) |
+| Verify | TypeScript or ESLint errors exist | `post-edit.sh` loop |
+| Audit | Orphan features or circular dependencies | Required before commit |
+| Pre-Commit | TODO/FIXME, console.log, bad format | `pre-commit-check.sh` (exit 1) |
+
+---
+
+## 3-Tier Suggestions
+
+For feature tasks, Claude provides categorized suggestions:
+
+| Tier | Priority | Examples |
+|------|----------|----------|
+| 🔴 Required | Must implement | Error handling, loading states, validation |
+| 🟡 Recommended | Improves quality | Empty states, keyboard navigation |
+| 🟢 Optional | Nice to have | Unit tests, analytics, optimizations |
+
+---
+
+## 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?
+```
 
 ---
 
@@ -97,23 +168,30 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 ```
 project/
-├── CLAUDE.md                 # Workflow + gates (auto-read)
+├── CLAUDE.md                 # Workflow summary (auto-read)
 │
 ├── .claude/
-│   ├── settings.json         # System prompt + hooks config
-│   ├── hooks/                # Auto-trigger scripts
-│   │   ├── session-check.sh
-│   │   ├── post-edit.sh
-│   │   └── pre-commit-check.sh
-│   └── commands/             # Slash commands
+│   ├── settings.json         # Hooks + system prompt
+│   ├── hooks/                # Enforcement scripts
+│   │   ├── session-check.sh  # Resume + blueprint check
+│   │   ├── pre-edit.sh       # Plan approval gate
+│   │   ├── post-edit.sh      # Verification loop
+│   │   ├── pre-commit-check.sh
+│   │   └── post-commit.sh    # BLUEPRINT reminder
+│   ├── commands/             # Slash commands (with agent structure)
+│   └── skills/               # 106 knowledge files
 │
 ├── instructions/
 │   ├── AI_RULES.md           # Your coding standards
 │   └── BLUEPRINT.md          # Project spec (auto-generated)
 │
-├── scripts/                  # Automation scripts
-├── hooks/                    # Git hooks (backup enforcement)
-└── .vscode/                  # VS Code settings (optional)
+├── 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
 ```
 
 ---
@@ -135,15 +213,17 @@ npm run audit:all        # Run all audits
 ```
 
 ### Slash Commands
-| Command | Purpose |
-|---------|---------|
-| `/analyze [task]` | Analyze codebase |
-| `/plan [task]` | Create implementation plan |
-| `/build [feature]` | Full workflow |
-| `/verify` | Run verification |
-| `/audit` | Run audits |
-| `/audit project` | Full scan → generate BLUEPRINT.md |
-| `/commit` | Pre-commit check + commit |
+| 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 → generate BLUEPRINT.md |
+| `/commit` | Git Specialist | Pre-commit check + commit |
 
 ---
 
@@ -165,13 +245,16 @@ Edit `instructions/AI_RULES.md`:
 Edit `.claude/settings.json` gates section.
 
 ### Modify Hooks
-Edit files in `.claude/hooks/` to change auto-trigger behavior.
+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
+- VS Code with Claude Code extension (or Claude Code CLI)
 - Node.js 18+ (for npm scripts)
 - TypeScript, ESLint, Prettier (for verification)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autoworkflow",
-  "version": "3.1.4",
+  "version": "3.5.0",
   "description": "Automated workflow enforcement for Claude Code via hooks and system prompts",
   "type": "module",
   "bin": {

package/system/triggers.md

@@ -12,14 +12,17 @@
 | Trigger | Hook Script | Event |
 |---------|-------------|-------|
 | `on:conversation_start` | `session-check.sh` | UserPromptSubmit |
+| `on:session_resume` | `session-check.sh` | UserPromptSubmit |
 | `on:blueprint_missing` | `session-check.sh` + `blueprint-generator.sh` | UserPromptSubmit |
 | `on:init_needed` | `session-check.sh` | UserPromptSubmit |
 | `on:task_received` | `session-check.sh` | UserPromptSubmit |
 | `on:phase_transition` | `phase-transition.sh` | Manual call |
+| `on:pre_implementation_check` | `pre-edit.sh` | PreToolUse (Write\|Edit) |
 | `on:implementation_complete` | `post-edit.sh` | PostToolUse (Write\|Edit) |
 | `on:verification_failed` | `post-edit.sh` | PostToolUse (Write\|Edit) |
 | `on:verification_passed` | `post-edit.sh` | PostToolUse (Write\|Edit) |
 | `on:commit_requested` | `pre-tool-router.sh` → `pre-commit-check.sh` | PreToolUse (Bash) |
+| `on:feature_complete` | `post-bash-router.sh` → `post-commit.sh` | PostToolUse (Bash) |
 
 ---
 
@@ -38,9 +41,10 @@ All workflow state is stored in `.claude/.autoworkflow/`:
 ├── audit-status         # PASSED/FAILED/BLOCKED
 ├── gate-status          # Last gate check result
 ├── gate-errors          # Number of gate errors
-├── plan-approved        # Plan approval status
+├── plan-approved        # Plan approval status (true/false)
 ├── changed-files        # List of modified files
-└── blueprint-checked    # Blueprint check done flag
+├── blueprint-checked    # Blueprint check done flag
+└── session-resumed      # Session resume prompt shown flag
 ```
 
 ---
@@ -81,6 +85,93 @@ All workflow state is stored in `.claude/.autoworkflow/`:
 
 ---
 
+### `on:session_resume`
+
+**When:** Existing session state detected (non-IDLE phase)
+**Hook:** `.claude/hooks/session-check.sh`
+**Function:** `check_session_resume()`
+**Event:** `UserPromptSubmit`
+
+**Trigger Condition:** Previous session has active state (phase != IDLE)
+
+**Actions:**
+1. Detect previous session state
+2. Show resume prompt with context:
+   - Current phase
+   - Task type
+   - Plan approval status
+   - Verify iteration count
+   - Changed files (if any)
+3. Offer to continue or start fresh
+4. Mark resume prompt as shown (only show once)
+
+**Output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📍 AUTOWORKFLOW: SESSION RESUME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Previous session state detected:
+
+  Phase:           IMPLEMENT
+  Task type:       feature
+  Plan approved:   true
+  Verify attempts: 2/10
+
+Pending changes:
+  - src/components/Button.tsx
+  - src/hooks/useAuth.ts
+
+Workflow: ANALYZE → PLAN → CONFIRM → IMPLEMENT → ...
+          ↑ Current: IMPLEMENT
+
+Continue from IMPLEMENT phase, or start fresh?
+```
+
+---
+
+### `on:pre_implementation_check`
+
+**When:** Claude attempts to Write/Edit a file
+**Hook:** `.claude/hooks/pre-edit.sh`
+**Event:** `PreToolUse` for `Write|Edit`
+
+**Purpose:** ENFORCE plan approval before any code changes
+
+**Gate Check:**
+1. Get current phase from state
+2. Get task type from state
+3. Check if task requires approval (feature/fix/refactor)
+4. If in ANALYZE or PLAN phase AND approval required:
+   - Check if `plan-approved` is set to "true"
+   - If NOT → **BLOCK the edit** (exit code 1)
+   - If YES → Allow the edit
+
+**Output on BLOCK:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⛔ AUTOWORKFLOW: PLAN APPROVAL REQUIRED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Current Phase: PLAN
+Task Type:    feature
+Plan Approved: NO
+
+Cannot edit files before plan approval.
+
+Required workflow:
+  1. Complete ANALYZE phase (read relevant files)
+  2. Present PLAN with suggestions
+  3. Wait for user approval
+  4. THEN implement
+```
+
+**Bypass conditions:**
+- Task type is `docs`, `style`, `config`, or `query`
+- Phase is already IMPLEMENT or later
+
+---
+
 ### `on:blueprint_missing`
 
 **When:** BLUEPRINT.md does not exist at session start
@@ -314,13 +405,49 @@ AUTOWORKFLOW: PRE-COMMIT GATE
 
 ### `on:feature_complete`
 
-**When:** A new feature, route, or API is successfully committed
-**Handling:** Manual check after commit
+**When:** A git commit is successfully executed (detected by post-bash-router)
+**Hook:** `.claude/hooks/post-bash-router.sh` → `.claude/hooks/post-commit.sh`
+**Event:** `PostToolUse` for `Bash` (git commit commands)
+
+**Behavior:** AUTOMATIC after every git commit
 
 **Actions:**
-1. Check if BLUEPRINT.md needs updating
-2. Present proposed updates
-3. Update after approval
+1. Display commit summary (hash, message, files)
+2. Check if commit type is `feat` or `refactor`
+3. If yes → Show UPDATE phase reminder:
+   - List potential new routes
+   - List potential new APIs
+   - List potential new components
+4. Remind to update BLUEPRINT.md if needed
+5. Reset workflow state to IDLE
+
+**Output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ AUTOWORKFLOW: COMMIT COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Hash:    abc1234
+  Message: feat(auth): add login page
+  Files:   3 changed
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📘 AUTOWORKFLOW: UPDATE PHASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+This commit may have added new features/routes/APIs.
+
+Check if BLUEPRINT.md needs updating:
+
+  1. New routes/pages added?
+  2. New API endpoints added?
+  3. New features/components added?
+
+Potential new routes:
+  - src/pages/Login.tsx
+
+Action: Review and update instructions/BLUEPRINT.md if needed.
+```
 
 ---
 
@@ -399,21 +526,35 @@ All hooks are configured in `.claude/settings.json`:
         }]
       }
     ],
-    "PostToolUse": [
+    "PreToolUse": [
       {
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "./.claude/hooks/post-edit.sh"
+          "command": "./.claude/hooks/pre-edit.sh"
+        }]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "./.claude/hooks/pre-tool-router.sh \"$TOOL_INPUT\""
         }]
       }
     ],
-    "PreToolUse": [
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "./.claude/hooks/post-edit.sh"
+        }]
+      },
       {
         "matcher": "Bash",
         "hooks": [{
           "type": "command",
-          "command": "./.claude/hooks/pre-tool-router.sh \"$TOOL_INPUT\""
+          "command": "./.claude/hooks/post-bash-router.sh \"$TOOL_INPUT\""
         }]
       }
     ]