autoworkflow 3.6.1 → 3.8.0

package/.claude/hooks/pre-edit.sh

@@ -1,10 +1,14 @@
 #!/bin/bash
-# AutoWorkflow Pre-Edit Hook
+# AutoWorkflow Pre-Edit Hook (v3.7.0 - Fail-Closed Design)
 # Runs on: PreToolUse for Write/Edit tools
-# Purpose: Enforce plan approval before implementation
+# Purpose: BLOCK edits by default unless workflow state is properly set
 #
-# This hook implements the plan_approval_gate enforcement
-# It BLOCKS Write/Edit operations if plan hasn't been approved
+# DESIGN PRINCIPLE: Fail-closed
+# - If state is not initialized → BLOCK (auto-init as feature)
+# - If plan not approved → BLOCK
+# - If suggestions not shown (feature tasks) → BLOCK
+# - If multiple edits per turn → BLOCK
+# - Only allow edit if ALL checks pass
 
 # Colors
 RED='\033[0;31m'
@@ -24,14 +28,43 @@ TASK_TYPE_FILE="$STATE_DIR/task-type"
 PLAN_APPROVED_FILE="$STATE_DIR/plan-approved"
 SUGGESTIONS_SHOWN_FILE="$STATE_DIR/suggestions-shown"
 CURRENT_TURN_EDITS_FILE="$STATE_DIR/current-turn-edits"
-SELECTED_ITEMS_FILE="$STATE_DIR/selected-items"
+WORKFLOW_INITIALIZED_FILE="$STATE_DIR/workflow-initialized"
+
+# Auto-initialize workflow state with safe defaults
+auto_init_state() {
+    mkdir -p "$STATE_DIR"
+
+    # Set safe defaults - assume feature task (strictest)
+    echo "feature" > "$TASK_TYPE_FILE"
+    echo "IMPLEMENT" > "$PHASE_FILE"
+    echo "false" > "$PLAN_APPROVED_FILE"
+    echo "false" > "$SUGGESTIONS_SHOWN_FILE"
+    echo "0" > "$CURRENT_TURN_EDITS_FILE"
+    echo "true" > "$WORKFLOW_INITIALIZED_FILE"
+
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo -e "${CYAN}${BOLD}📋 AUTOWORKFLOW: STATE INITIALIZED${NC}"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "Workflow state auto-initialized with safe defaults:"
+    echo "  Task type:        feature (strictest)"
+    echo "  Plan approved:    false"
+    echo "  Suggestions shown: false"
+    echo ""
+}
+
+# Check if workflow is initialized
+is_workflow_initialized() {
+    [ -d "$STATE_DIR" ] && [ -f "$WORKFLOW_INITIALIZED_FILE" ]
+}
 
 # Get current phase
 get_phase() {
     if [ -f "$PHASE_FILE" ]; then
         cat "$PHASE_FILE"
     else
-        echo "IDLE"
+        echo "UNKNOWN"
     fi
 }
 
@@ -40,7 +73,7 @@ get_task_type() {
     if [ -f "$TASK_TYPE_FILE" ]; then
         cat "$TASK_TYPE_FILE"
     else
-        echo "unknown"
+        echo "feature"  # Default to strictest
     fi
 }
 
@@ -53,7 +86,7 @@ is_plan_approved() {
     return 1
 }
 
-# Check if suggestions were shown (for feature tasks)
+# Check if suggestions were shown
 suggestions_shown() {
     if [ -f "$SUGGESTIONS_SHOWN_FILE" ]; then
         local status=$(cat "$SUGGESTIONS_SHOWN_FILE")
@@ -79,142 +112,182 @@ increment_turn_edits() {
     echo "$next"
 }
 
-# Check if user has selected items to implement
-has_selected_items() {
-    if [ -f "$SELECTED_ITEMS_FILE" ]; then
-        local content=$(cat "$SELECTED_ITEMS_FILE")
-        [ -n "$content" ] && return 0
-    fi
-    return 1
-}
-
-# Check if task type requires approval
-requires_approval() {
+# Check if task type requires strict workflow
+requires_strict_workflow() {
     local task_type="$1"
     case "$task_type" in
-        # These task types require plan approval
+        # Strict workflow required
         feature|fix|refactor|perf|security|test)
             return 0
             ;;
-        # These can proceed without explicit approval
-        docs|style|config|query)
+        # Relaxed workflow
+        docs|style|config)
             return 1
             ;;
-        # Unknown defaults to requiring approval
+        # Unknown = strict
         *)
             return 0
             ;;
     esac
 }
 
-# Main check
-main() {
-    local phase=$(get_phase)
-    local task_type=$(get_task_type)
+# GATE 1: Plan Approval Check
+check_plan_approval() {
+    local task_type="$1"
 
-    # Skip check if no task is active
-    if [ "$phase" = "IDLE" ]; then
-        exit 0
+    if ! requires_strict_workflow "$task_type"; then
+        return 0  # Pass for relaxed task types
     fi
 
-    # Skip check for task types that don't require approval
-    if ! requires_approval "$task_type"; then
-        exit 0
+    if ! is_plan_approved; then
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo -e "${RED}${BOLD}⛔ GATE 1: PLAN APPROVAL REQUIRED${NC}"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        echo -e "${CYAN}Task Type:${NC}     $task_type"
+        echo -e "${CYAN}Plan Approved:${NC} NO"
+        echo ""
+        echo "You MUST get user approval before making any edits."
+        echo ""
+        echo -e "${BOLD}Required steps:${NC}"
+        echo "  1. Analyze the codebase"
+        echo "  2. Present your plan to the user"
+        echo "  3. Wait for explicit approval (yes/proceed/approved)"
+        echo "  4. THEN implement"
+        echo ""
+        echo -e "${DIM}To mark approved: echo 'true' > $PLAN_APPROVED_FILE${NC}"
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        return 1
     fi
+    return 0
+}
 
-    # Skip check if already in IMPLEMENT or later phases
-    case "$phase" in
-        IMPLEMENT|VERIFY|FIX|AUDIT|PRE_COMMIT|COMMIT|UPDATE)
-            # Already past approval, allow edits
-            exit 0
-            ;;
-    esac
+# GATE 2: Suggestions Check (for feature tasks)
+check_suggestions() {
+    local task_type="$1"
+
+    # Only enforce for feature tasks
+    if [ "$task_type" != "feature" ]; then
+        return 0
+    fi
+
+    if ! suggestions_shown; then
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo -e "${RED}${BOLD}⛔ GATE 2: SUGGESTIONS REQUIRED${NC}"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        echo -e "${CYAN}Task Type:${NC} feature"
+        echo ""
+        echo "For feature tasks, you MUST show 3-tier suggestions FIRST:"
+        echo ""
+        echo "  🔴 Required     - Must implement"
+        echo "  🟡 Recommended  - Should implement"
+        echo "  🟢 Optional     - Nice to have"
+        echo ""
+        echo "Show suggestions, let user select, THEN implement ONE at a time."
+        echo ""
+        echo -e "${DIM}To mark shown: echo 'true' > $SUGGESTIONS_SHOWN_FILE${NC}"
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        return 1
+    fi
+    return 0
+}
+
+# GATE 3: One Edit Per Turn Check (applies to ALL implementation)
+check_one_edit_per_turn() {
+    local task_type="$1"
 
-    # Check if we're in a pre-approval phase
-    if [ "$phase" = "ANALYZE" ] || [ "$phase" = "PLAN" ]; then
-        if ! is_plan_approved; then
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo -e "${RED}${BOLD}⛔ AUTOWORKFLOW: PLAN APPROVAL REQUIRED${NC}"
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-            echo -e "${CYAN}Current Phase:${NC} $phase"
-            echo -e "${CYAN}Task Type:${NC}    $task_type"
-            echo -e "${CYAN}Plan Approved:${NC} NO"
-            echo ""
-            echo "Cannot edit files before plan approval."
-            echo ""
-            echo -e "${BOLD}Required workflow:${NC}"
-            echo "  1. Complete ANALYZE phase (read relevant files)"
-            echo "  2. Present PLAN with suggestions"
-            echo "  3. Wait for user approval"
-            echo "  4. THEN implement"
-            echo ""
-            echo -e "${DIM}To approve, user must say: yes, proceed, approved, go ahead${NC}"
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-
-            # Exit with error to BLOCK the edit
-            exit 1
-        fi
+    if ! requires_strict_workflow "$task_type"; then
+        return 0  # Pass for relaxed task types
     fi
 
-    # CHECK: Suggestions must be shown for feature tasks before implementing
-    if [ "$task_type" = "feature" ] && [ "$phase" = "IMPLEMENT" ]; then
-        if ! suggestions_shown; then
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo -e "${RED}${BOLD}⛔ AUTOWORKFLOW: SUGGESTIONS REQUIRED${NC}"
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-            echo -e "${CYAN}Task Type:${NC} feature"
-            echo ""
-            echo "For feature tasks, you MUST show 3-tier suggestions first:"
-            echo ""
-            echo "  🔴 Required    - Must implement"
-            echo "  🟡 Recommended - Should implement"
-            echo "  🟢 Optional    - Nice to have"
-            echo ""
-            echo "Show suggestions, let user select items, THEN implement."
-            echo ""
-            echo -e "${DIM}To mark suggestions shown: echo 'true' > $SUGGESTIONS_SHOWN_FILE${NC}"
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-            exit 1
-        fi
+    local edit_count=$(get_turn_edit_count)
+
+    if [ "$edit_count" -ge 1 ]; then
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo -e "${YELLOW}${BOLD}⛔ GATE 3: ONE EDIT PER TURN${NC}"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        echo -e "${CYAN}Edits this turn:${NC} $edit_count"
+        echo ""
+        echo "You can only make ONE edit per user turn."
+        echo ""
+        echo "This ensures:"
+        echo "  1. Easier to track changes"
+        echo "  2. Errors caught early"
+        echo "  3. User can review incrementally"
+        echo ""
+        echo "Wait for user's next message before making another edit."
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        return 1
     fi
 
-    # CHECK: One fix at a time (max 1 edit per turn in FIX phase)
-    if [ "$phase" = "FIX" ]; then
-        local edit_count=$(get_turn_edit_count)
-        if [ "$edit_count" -ge 1 ]; then
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo -e "${YELLOW}${BOLD}⚠ AUTOWORKFLOW: ONE FIX AT A TIME${NC}"
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-            echo -e "${CYAN}Edits this turn:${NC} $edit_count"
-            echo ""
-            echo "Fix ONE issue at a time, then verify."
-            echo ""
-            echo "This ensures:"
-            echo "  1. Easier to track what changed"
-            echo "  2. Errors caught early"
-            echo "  3. User can review incrementally"
-            echo ""
-            echo "Wait for verification to complete before next fix."
-            echo ""
-            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-            echo ""
-            exit 1
-        fi
-        # Track this edit
-        increment_turn_edits > /dev/null
+    return 0
+}
+
+# Main execution
+main() {
+    # STEP 1: Check if workflow is initialized
+    if ! is_workflow_initialized; then
+        # Auto-initialize with safe defaults
+        auto_init_state
+
+        # After init, BLOCK this edit attempt
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo -e "${RED}${BOLD}⛔ AUTOWORKFLOW: EDIT BLOCKED${NC}"
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        echo "Workflow just initialized. Cannot edit yet."
+        echo ""
+        echo "You must first:"
+        echo "  1. Show your analysis/plan to the user"
+        echo "  2. Get user approval"
+        echo "  3. For features: Show 3-tier suggestions"
+        echo "  4. THEN implement one fix at a time"
+        echo ""
+        echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        echo ""
+        exit 1
     fi
 
-    # All checks passed, allow edit
+    # Get current state
+    local task_type=$(get_task_type)
+    local phase=$(get_phase)
+
+    # STEP 2: Run all gates
+
+    # GATE 1: Plan Approval
+    if ! check_plan_approval "$task_type"; then
+        exit 1
+    fi
+
+    # GATE 2: Suggestions (feature tasks only)
+    if ! check_suggestions "$task_type"; then
+        exit 1
+    fi
+
+    # GATE 3: One Edit Per Turn
+    if ! check_one_edit_per_turn "$task_type"; then
+        exit 1
+    fi
+
+    # ALL GATES PASSED - Allow edit and track it
+    increment_turn_edits > /dev/null
+
+    echo ""
+    echo -e "${GREEN}✓${NC} Edit allowed (turn edit #$(get_turn_edit_count))"
+    echo ""
+
     exit 0
 }
 

package/README.md

@@ -2,7 +2,7 @@
 
 > Automated workflow enforcement for Claude Code via hooks and system prompts.
 
-**v3.6.0** - Multi-language support, one-fix-at-a-time enforcement, suggestions gate.
+**v3.8.0** - Smart CLI updates: version tracking + user file preservation.
 
 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.
 
@@ -14,10 +14,61 @@ When you use Claude Code with AutoWorkflow, hooks automatically enforce workflow
 npx autoworkflow init
 ```
 
-Options:
-- `npx autoworkflow init` - Required + recommended files
-- `npx autoworkflow init --all` - Include .vscode and config templates
-- `npx autoworkflow init --minimal` - Required files only
+### 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 (v3.8.0)
+
+The CLI now tracks installed versions and preserves user customizations:
+
+```
+npx autoworkflow status     # Check version and what would change
+npx autoworkflow update     # Update core files, preserve BLUEPRINT.md
+```
+
+| File Category | On `init` | On `update` |
+|---------------|-----------|-------------|
+| **Core** (hooks, system, CLAUDE.md) | Installed | Updated |
+| **User** (BLUEPRINT.md, AI_RULES.md) | Created if missing | **Preserved** |
+| **Commands/Skills** | Installed | Updated |
+| **Optional** (.vscode, configs) | Only with `--all` | Skipped |
+
+---
+
+## What's New in v3.7.0
+
+### Fail-Closed Enforcement Design
+Previous versions "failed open" - if state wasn't set, edits were allowed. v3.7.0 "fails closed":
+
+| Scenario | Before (v3.6) | After (v3.7) |
+|----------|---------------|--------------|
+| No workflow state | ✅ Allowed | ⛔ BLOCKED |
+| Plan not approved | ⛔ Blocked (in PLAN phase only) | ⛔ BLOCKED (always) |
+| No suggestions shown | ⛔ Blocked (in IMPLEMENT only) | ⛔ BLOCKED (always for features) |
+| Multiple edits/turn | ⛔ Blocked (in FIX only) | ⛔ BLOCKED (always) |
+
+### Auto-Initialization with Safe Defaults
+When Claude attempts the first edit without workflow state:
+1. Auto-creates state with `task-type: feature` (strictest)
+2. Sets `plan-approved: false`
+3. Sets `suggestions-shown: false`
+4. **BLOCKS the edit** immediately
+5. Claude must show plan/suggestions first, get approval, then try again
+
+### Three Gates (All Must Pass)
+```
+GATE 1: Plan Approval     → Must have user approval
+GATE 2: Suggestions       → Must show 3-tier suggestions (features)
+GATE 3: One Edit/Turn     → Max 1 edit per user message
+```
 
 ---
 
@@ -149,16 +200,18 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 ---
 
-## Blocking Gates
+## Blocking Gates (Fail-Closed)
+
+| Gate | Blocks If | Applies To |
+|------|-----------|------------|
+| **State Init** | No workflow state exists | ALL tasks |
+| **Plan Approval** | User hasn't approved | feature, fix, refactor, perf, security, test |
+| **Suggestions** | 3-tier suggestions not shown | feature tasks |
+| **One Edit/Turn** | Already edited this turn | feature, fix, refactor, perf, security, test |
+| **Verify** | Language-specific errors | ALL (post-edit) |
+| **Pre-Commit** | TODO/FIXME, console.log | ALL commits |
 
-| Gate | Blocks If | Enforced By |
-|------|-----------|-------------|
-| Plan Approval | User hasn't approved the plan | `pre-edit.sh` (exit 1) |
-| Suggestions | Feature task without 3-tier suggestions shown | `pre-edit.sh` (exit 1) |
-| One-Fix-At-A-Time | Multiple edits in FIX phase per turn | `pre-edit.sh` (exit 1) |
-| Verify | TypeScript/ESLint/language-specific errors | `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) |
+**Design:** All gates are checked on EVERY edit. Unknown state = strictest defaults.
 
 ---
 

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, cpSync, mkdirSync, chmodSync, renameSync, unlinkSync } from 'fs';
+import { existsSync, cpSync, mkdirSync, chmodSync, renameSync, unlinkSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -11,6 +11,10 @@ const packageRoot = join(__dirname, '..');
 const args = process.argv.slice(2);
 const command = args[0];
 
+// Get package version
+const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+const PACKAGE_VERSION = packageJson.version;
+
 const colors = {
   green: (text) => `\x1b[32m${text}\x1b[0m`,
   yellow: (text) => `\x1b[33m${text}\x1b[0m`,
@@ -20,50 +24,147 @@ const colors = {
   dim: (text) => `\x1b[2m${text}\x1b[0m`,
 };
 
+// File categories for smart updates
+const FILE_CATEGORIES = {
+  // Core files - always updated (system functionality)
+  core: [
+    { src: '.claude/hooks', dest: '.claude/hooks', name: '.claude/hooks/' },
+    { src: '.claude/settings.json', dest: '.claude/settings.json', name: '.claude/settings.json' },
+    { src: 'system', dest: 'system', name: 'system/' },
+    { src: 'CLAUDE.md', dest: 'CLAUDE.md', name: 'CLAUDE.md' },
+  ],
+  // User-customizable files - preserved on update, created on init
+  user: [
+    { src: 'instructions/AI_RULES.md', dest: 'instructions/AI_RULES.md', name: 'instructions/AI_RULES.md' },
+    // BLUEPRINT.md is special - never overwrite if user has content
+  ],
+  // Commands and skills - updated (but could have user additions)
+  commands: [
+    { src: '.claude/commands', dest: '.claude/commands', name: '.claude/commands/' },
+    { src: '.claude/skills', dest: '.claude/skills', name: '.claude/skills/' },
+  ],
+  // Scripts and git hooks
+  scripts: [
+    { src: 'scripts', dest: 'scripts', name: 'scripts/' },
+    { src: 'hooks', dest: 'hooks', name: 'hooks/' },
+  ],
+  // Optional config templates - skip if exists
+  optional: [
+    { src: '.vscode', dest: '.vscode', name: '.vscode/' },
+    { src: '.prettierrc', dest: '.prettierrc', name: '.prettierrc' },
+    { src: 'eslint.config.example.js', dest: 'eslint.config.js', name: 'eslint.config.js' },
+    { src: 'tsconfig.example.json', dest: 'tsconfig.json', name: 'tsconfig.json' },
+  ],
+};
+
 function printHelp() {
   console.log(`
-${colors.bold('AutoWorkflow CLI')}
+${colors.bold('AutoWorkflow CLI')} ${colors.dim(`v${PACKAGE_VERSION}`)}
 
 Usage: npx autoworkflow <command> [options]
 
 Commands:
-  init          Set up AutoWorkflow in current directory
-  init --all    Include optional files (.vscode, configs)
-  init --minimal Required files only
-  help          Show this help message
+  ${colors.cyan('init')}              Set up AutoWorkflow in current directory
+  ${colors.cyan('init --all')}        Include optional files (.vscode, configs)
+  ${colors.cyan('init --minimal')}    Required files only
+  ${colors.cyan('init --force')}      Full reinstall (backup + overwrite all)
+
+  ${colors.cyan('update')}            Smart update - core files only, preserve user files
+  ${colors.cyan('status')}            Show installed version and what would change
+
+  ${colors.cyan('help')}              Show this help message
 
 Options:
-  --no-backup   Overwrite existing files without backup
+  --no-backup       Overwrite existing files without backup
+  --force           Force overwrite all files (with backup)
 
 Examples:
-  npx autoworkflow init
-  npx autoworkflow init --all
+  npx autoworkflow init          # Fresh install
+  npx autoworkflow update        # Update core files only
+  npx autoworkflow status        # Check what would change
+  npx autoworkflow init --force  # Full reinstall
 `);
 }
 
+// Version tracking
+function getInstalledVersion(cwd) {
+  const versionFile = join(cwd, '.claude', '.autoworkflow', 'version');
+  if (existsSync(versionFile)) {
+    try {
+      return readFileSync(versionFile, 'utf8').trim();
+    } catch (e) {
+      return null;
+    }
+  }
+  return null;
+}
+
+function setInstalledVersion(cwd, version) {
+  const stateDir = join(cwd, '.claude', '.autoworkflow');
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, 'version'), version);
+}
+
+// Check if BLUEPRINT.md has user content (not just template)
+function hasUserBlueprint(cwd) {
+  const blueprintPath = join(cwd, 'instructions', 'BLUEPRINT.md');
+  if (!existsSync(blueprintPath)) {
+    return false;
+  }
+
+  try {
+    const content = readFileSync(blueprintPath, 'utf8');
+    // Check if it's just a template or has real content
+    const templateMarkers = [
+      '<!-- TEMPLATE',
+      '<!-- AUTO-GENERATED TEMPLATE',
+      '## Features\n\n(To be documented)',
+      '## Features\n\n_None documented yet_',
+    ];
+
+    // If it has any template markers, it's not user content
+    for (const marker of templateMarkers) {
+      if (content.includes(marker)) {
+        return false;
+      }
+    }
+
+    // If it has substantial content (more than 200 chars after stripping headers), it's user content
+    const strippedContent = content.replace(/^#.*$/gm, '').replace(/\s+/g, ' ').trim();
+    return strippedContent.length > 200;
+  } catch (e) {
+    return false;
+  }
+}
+
 function backupFile(dest, name) {
   if (existsSync(dest)) {
     const backupPath = `${dest}.backup`;
-    // If backup already exists, add timestamp
     const finalBackupPath = existsSync(backupPath)
       ? `${dest}.backup.${Date.now()}`
       : backupPath;
     try {
       renameSync(dest, finalBackupPath);
-      console.log(`  ${colors.yellow('↪')} ${name} ${colors.dim(`→ backed up to ${finalBackupPath.split('/').pop()}`)}`);
+      console.log(`  ${colors.yellow('↪')} ${name} ${colors.dim(`→ backed up`)}`);
       return true;
     } catch (err) {
       console.log(`  ${colors.red('✗')} Failed to backup ${name}: ${err.message}`);
       return false;
     }
   }
-  return true; // No backup needed
+  return true;
 }
 
 function copyFile(src, dest, name, options = {}) {
-  const noBackup = args.includes('--no-backup');
+  const { noBackup = false, skipIfExists = false } = options;
 
   if (existsSync(src)) {
+    // Skip if exists and skipIfExists is true
+    if (skipIfExists && existsSync(dest)) {
+      console.log(`  ${colors.dim('○')} ${name} ${colors.dim('(exists, skipped)')}`);
+      return true;
+    }
+
     // Backup existing file/folder if it exists
     if (!noBackup && existsSync(dest)) {
       const backed = backupFile(dest, name);
@@ -84,49 +185,19 @@ function copyFile(src, dest, name, options = {}) {
   }
 }
 
-function init(options = {}) {
-  const cwd = process.cwd();
-  const all = options.all || args.includes('--all');
-  const minimal = options.minimal || args.includes('--minimal');
-  const noBackup = args.includes('--no-backup');
-
-  console.log(`\n${colors.bold('AutoWorkflow Setup')}\n`);
-  console.log(`Installing to: ${colors.cyan(cwd)}`);
-  if (!noBackup) {
-    console.log(`${colors.dim('Existing files will be backed up with .backup suffix')}\n`);
-  } else {
-    console.log(`${colors.yellow('⚠')} ${colors.dim('--no-backup: Existing files will be overwritten')}\n`);
-  }
-
-  // Required files
-  console.log(colors.bold('Required files:'));
-  copyFile(join(packageRoot, 'CLAUDE.md'), join(cwd, 'CLAUDE.md'), 'CLAUDE.md');
-  copyFile(join(packageRoot, 'system'), join(cwd, 'system'), 'system/');
-  copyFile(join(packageRoot, '.claude'), join(cwd, '.claude'), '.claude/');
-
-  // Copy instructions folder but remove BLUEPRINT.md (hook will auto-generate it)
-  copyFile(join(packageRoot, 'instructions'), join(cwd, 'instructions'), 'instructions/');
-  const blueprintPath = join(cwd, 'instructions', 'BLUEPRINT.md');
-  if (existsSync(blueprintPath)) {
-    try {
-      unlinkSync(blueprintPath);
-      console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md removed (will be auto-generated on first run)`);
-    } catch (e) {
-      // Ignore
-    }
-  }
-
-  // Make Claude hooks executable
+function makeHooksExecutable(cwd) {
   if (process.platform !== 'win32' && existsSync(join(cwd, '.claude', 'hooks'))) {
     try {
       const hookFiles = [
         'session-check.sh',
         'post-edit.sh',
+        'pre-edit.sh',
         'pre-commit-check.sh',
         'pre-tool-router.sh',
         'phase-transition.sh',
         'audit-runner.sh',
-        'blueprint-generator.sh'
+        'blueprint-generator.sh',
+        'post-commit.sh',
       ];
       hookFiles.forEach(hook => {
         const hookPath = join(cwd, '.claude', 'hooks', hook);
@@ -134,36 +205,15 @@ function init(options = {}) {
           chmodSync(hookPath, 0o755);
         }
       });
-      console.log(`  ${colors.green('✓')} Claude hooks made executable`);
+      console.log(`  ${colors.green('✓')} Hooks made executable`);
     } catch (e) {
       // Ignore chmod errors
     }
   }
+}
 
-  if (!minimal) {
-    // Recommended files
-    console.log(`\n${colors.bold('Recommended files:')}`);
-    copyFile(join(packageRoot, 'scripts'), join(cwd, 'scripts'), 'scripts/');
-    copyFile(join(packageRoot, 'hooks'), join(cwd, 'hooks'), 'hooks/');
-  }
-
-  if (all) {
-    // Optional files
-    console.log(`\n${colors.bold('Optional files:')}`);
-    copyFile(join(packageRoot, '.vscode'), join(cwd, '.vscode'), '.vscode/');
-    copyFile(join(packageRoot, '.prettierrc'), join(cwd, '.prettierrc'), '.prettierrc');
-
-    // Copy example configs with proper names
-    if (existsSync(join(packageRoot, 'eslint.config.example.js'))) {
-      copyFile(join(packageRoot, 'eslint.config.example.js'), join(cwd, 'eslint.config.js'), 'eslint.config.js');
-    }
-    if (existsSync(join(packageRoot, 'tsconfig.example.json'))) {
-      copyFile(join(packageRoot, 'tsconfig.example.json'), join(cwd, 'tsconfig.json'), 'tsconfig.json');
-    }
-  }
-
-  // Setup git hooks if hooks were copied
-  if (!minimal && existsSync(join(cwd, 'hooks')) && existsSync(join(cwd, '.git'))) {
+function setupGitHooks(cwd) {
+  if (existsSync(join(cwd, 'hooks')) && existsSync(join(cwd, '.git'))) {
     console.log(`\n${colors.bold('Git hooks:')}`);
     const hooksDir = join(cwd, '.git', 'hooks');
     mkdirSync(hooksDir, { recursive: true });
@@ -171,7 +221,6 @@ function init(options = {}) {
     const hooksCopied = copyFile(join(cwd, 'hooks', 'pre-commit'), join(hooksDir, 'pre-commit'), 'pre-commit');
     copyFile(join(cwd, 'hooks', 'commit-msg'), join(hooksDir, 'commit-msg'), 'commit-msg');
 
-    // Make hooks executable (Unix only)
     if (hooksCopied && process.platform !== 'win32') {
       try {
         chmodSync(join(hooksDir, 'pre-commit'), 0o755);
@@ -181,6 +230,217 @@ function init(options = {}) {
       }
     }
   }
+}
+
+// STATUS command
+function status() {
+  const cwd = process.cwd();
+  const installedVersion = getInstalledVersion(cwd);
+
+  console.log(`\n${colors.bold('AutoWorkflow Status')}\n`);
+  console.log(`Package version:   ${colors.cyan(PACKAGE_VERSION)}`);
+  console.log(`Installed version: ${installedVersion ? colors.cyan(installedVersion) : colors.dim('not installed')}`);
+
+  if (installedVersion && installedVersion === PACKAGE_VERSION) {
+    console.log(`\n${colors.green('✓')} You're on the latest version.\n`);
+  } else if (installedVersion) {
+    console.log(`\n${colors.yellow('⚠')} Update available: ${installedVersion} → ${PACKAGE_VERSION}`);
+    console.log(`  Run: ${colors.cyan('npx autoworkflow update')}\n`);
+  } else {
+    console.log(`\n${colors.yellow('⚠')} AutoWorkflow not initialized in this directory.`);
+    console.log(`  Run: ${colors.cyan('npx autoworkflow init')}\n`);
+    return;
+  }
+
+  // Check what exists
+  console.log(`${colors.bold('Installed components:')}`);
+  const components = [
+    { path: 'CLAUDE.md', name: 'CLAUDE.md' },
+    { path: '.claude/hooks', name: 'Hooks' },
+    { path: '.claude/settings.json', name: 'Settings' },
+    { path: '.claude/commands', name: 'Commands' },
+    { path: '.claude/skills', name: 'Skills' },
+    { path: 'system', name: 'System docs' },
+    { path: 'instructions/AI_RULES.md', name: 'AI Rules' },
+    { path: 'instructions/BLUEPRINT.md', name: 'Blueprint' },
+    { path: 'scripts', name: 'Scripts' },
+    { path: 'hooks', name: 'Git hooks' },
+  ];
+
+  components.forEach(({ path, name }) => {
+    const exists = existsSync(join(cwd, path));
+    const status = exists ? colors.green('✓') : colors.dim('○');
+    console.log(`  ${status} ${name}`);
+  });
+
+  // Check for user customizations
+  const hasBlueprint = hasUserBlueprint(cwd);
+  if (hasBlueprint) {
+    console.log(`\n${colors.cyan('ℹ')} User BLUEPRINT.md detected - will be preserved on update.`);
+  }
+
+  console.log('');
+}
+
+// UPDATE command - smart update, preserve user files
+function update() {
+  const cwd = process.cwd();
+  const installedVersion = getInstalledVersion(cwd);
+  const noBackup = args.includes('--no-backup');
+
+  console.log(`\n${colors.bold('AutoWorkflow Update')}\n`);
+
+  if (!installedVersion) {
+    console.log(`${colors.yellow('⚠')} AutoWorkflow not initialized. Run ${colors.cyan('npx autoworkflow init')} instead.\n`);
+    return;
+  }
+
+  console.log(`Updating: ${colors.dim(installedVersion)} → ${colors.cyan(PACKAGE_VERSION)}`);
+  console.log(`${colors.dim('User files (BLUEPRINT.md, AI_RULES.md) will be preserved')}\n`);
+
+  // Update core files
+  console.log(colors.bold('Updating core files:'));
+  FILE_CATEGORIES.core.forEach(({ src, dest, name }) => {
+    copyFile(join(packageRoot, src), join(cwd, dest), name, { noBackup });
+  });
+
+  // Update commands and skills
+  console.log(`\n${colors.bold('Updating commands/skills:')}`);
+  FILE_CATEGORIES.commands.forEach(({ src, dest, name }) => {
+    copyFile(join(packageRoot, src), join(cwd, dest), name, { noBackup });
+  });
+
+  // Make hooks executable
+  makeHooksExecutable(cwd);
+
+  // Update version
+  setInstalledVersion(cwd, PACKAGE_VERSION);
+
+  console.log(`\n${colors.green('✓')} ${colors.bold('Updated to v' + PACKAGE_VERSION)}`);
+  console.log(`\n${colors.dim('User files preserved. Run')} ${colors.cyan('npx autoworkflow init --force')} ${colors.dim('for full reinstall.')}\n`);
+}
+
+// INIT command
+function init(options = {}) {
+  const cwd = process.cwd();
+  const all = options.all || args.includes('--all');
+  const minimal = options.minimal || args.includes('--minimal');
+  const force = options.force || args.includes('--force');
+  const noBackup = args.includes('--no-backup');
+
+  const installedVersion = getInstalledVersion(cwd);
+
+  // IMPORTANT: Check for user BLUEPRINT BEFORE any copying happens
+  const userHasBlueprint = hasUserBlueprint(cwd);
+  const blueprintPath = join(cwd, 'instructions', 'BLUEPRINT.md');
+  let savedBlueprintContent = null;
+
+  // Save user's BLUEPRINT.md content before any operations
+  if (userHasBlueprint) {
+    try {
+      savedBlueprintContent = readFileSync(blueprintPath, 'utf8');
+    } catch (e) {
+      // Ignore read errors
+    }
+  }
+
+  console.log(`\n${colors.bold('AutoWorkflow Setup')} ${colors.dim(`v${PACKAGE_VERSION}`)}\n`);
+  console.log(`Installing to: ${colors.cyan(cwd)}`);
+
+  if (installedVersion && !force) {
+    console.log(`\n${colors.yellow('⚠')} AutoWorkflow v${installedVersion} already installed.`);
+    console.log(`  Use ${colors.cyan('npx autoworkflow update')} to update core files`);
+    console.log(`  Use ${colors.cyan('npx autoworkflow init --force')} to reinstall everything\n`);
+    return;
+  }
+
+  if (!noBackup) {
+    console.log(`${colors.dim('Existing files will be backed up with .backup suffix')}\n`);
+  } else {
+    console.log(`${colors.yellow('⚠')} ${colors.dim('--no-backup: Existing files will be overwritten')}\n`);
+  }
+
+  // Required files
+  console.log(colors.bold('Core files:'));
+  copyFile(join(packageRoot, 'CLAUDE.md'), join(cwd, 'CLAUDE.md'), 'CLAUDE.md', { noBackup });
+  copyFile(join(packageRoot, 'system'), join(cwd, 'system'), 'system/', { noBackup });
+  copyFile(join(packageRoot, '.claude'), join(cwd, '.claude'), '.claude/', { noBackup });
+
+  // Handle instructions folder - preserve user BLUEPRINT.md
+  console.log(`\n${colors.bold('Instructions:')}`);
+  const instructionsDir = join(cwd, 'instructions');
+  mkdirSync(instructionsDir, { recursive: true });
+
+  // Copy AI_RULES.md (skip if exists and not forcing)
+  const aiRulesPath = join(cwd, 'instructions', 'AI_RULES.md');
+  if (!existsSync(aiRulesPath) || force) {
+    copyFile(
+      join(packageRoot, 'instructions', 'AI_RULES.md'),
+      aiRulesPath,
+      'instructions/AI_RULES.md',
+      { noBackup }
+    );
+  } else {
+    console.log(`  ${colors.dim('○')} instructions/AI_RULES.md ${colors.dim('(exists, preserved)')}`);
+  }
+
+  // BLUEPRINT.md - Restore user content if we saved it
+  if (savedBlueprintContent) {
+    // Restore the user's BLUEPRINT.md content
+    try {
+      writeFileSync(blueprintPath, savedBlueprintContent);
+      console.log(`  ${colors.cyan('★')} instructions/BLUEPRINT.md ${colors.dim('(user content preserved)')}`);
+    } catch (e) {
+      console.log(`  ${colors.red('✗')} Failed to restore BLUEPRINT.md: ${e.message}`);
+    }
+  } else if (existsSync(blueprintPath)) {
+    // Check if current file is a template (package just copied it)
+    const currentContent = readFileSync(blueprintPath, 'utf8');
+    const isTemplate = currentContent.includes('<!-- TEMPLATE') ||
+                       currentContent.includes('(To be documented)') ||
+                       currentContent.includes('_None documented yet_') ||
+                       currentContent.replace(/^#.*$/gm, '').replace(/\s+/g, ' ').trim().length < 200;
+
+    if (isTemplate) {
+      // Remove template so hook can regenerate project-specific one
+      try {
+        unlinkSync(blueprintPath);
+        console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md template removed (will be auto-generated)`);
+      } catch (e) {
+        // Ignore
+      }
+    } else {
+      console.log(`  ${colors.cyan('★')} instructions/BLUEPRINT.md ${colors.dim('(content preserved)')}`);
+    }
+  } else {
+    console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md will be auto-generated on first run`);
+  }
+
+  // Make Claude hooks executable
+  makeHooksExecutable(cwd);
+
+  if (!minimal) {
+    // Recommended files
+    console.log(`\n${colors.bold('Scripts:')}`);
+    copyFile(join(packageRoot, 'scripts'), join(cwd, 'scripts'), 'scripts/', { noBackup });
+    copyFile(join(packageRoot, 'hooks'), join(cwd, 'hooks'), 'hooks/', { noBackup });
+  }
+
+  if (all) {
+    // Optional files - skip if exists
+    console.log(`\n${colors.bold('Optional files:')}`);
+    FILE_CATEGORIES.optional.forEach(({ src, dest, name }) => {
+      copyFile(join(packageRoot, src), join(cwd, dest), name, { noBackup, skipIfExists: !force });
+    });
+  }
+
+  // Setup git hooks
+  if (!minimal) {
+    setupGitHooks(cwd);
+  }
+
+  // Save installed version
+  setInstalledVersion(cwd, PACKAGE_VERSION);
 
   console.log(`\n${colors.green('✓')} ${colors.bold('AutoWorkflow initialized!')}\n`);
 
@@ -198,12 +458,22 @@ switch (command) {
   case 'init':
     init();
     break;
+  case 'update':
+    update();
+    break;
+  case 'status':
+    status();
+    break;
   case 'help':
   case '--help':
   case '-h':
   case undefined:
     printHelp();
     break;
+  case '--version':
+  case '-v':
+    console.log(PACKAGE_VERSION);
+    break;
   default:
     console.log(`${colors.red('Unknown command:')} ${command}`);
     printHelp();

package/package.json

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