autoworkflow 2.2.1 → 3.0.0

package/README.md

@@ -1,91 +1,53 @@
-# AutoWorkflow - System Prompt Layer for Claude Code
+# AutoWorkflow
 
-> **Claude is the enforcement engine.** System prompts control the workflow. Scripts and hooks provide backup enforcement.
+> Automated workflow enforcement for Claude Code via hooks and system prompts.
 
-A system prompt architecture that controls Claude Code's behavior through triggers, loops, gates, and routing. When you use Claude Code in VS Code with this project, Claude automatically follows a structured 9-phase workflow for all coding tasks.
+When you use Claude Code with AutoWorkflow, hooks automatically trigger checks and Claude follows a structured workflow for all coding tasks.
 
 ---
 
 ## Installation
 
-### One Command Setup (Recommended)
-
 ```bash
 npx autoworkflow init
 ```
 
-This copies all workflow files to your project. Options:
+Options:
 - `npx autoworkflow init` - Required + recommended files
 - `npx autoworkflow init --all` - Include .vscode and config templates
 - `npx autoworkflow init --minimal` - Required files only
 
-### Or Install as Dependency
-
-```bash
-npm install autoworkflow
-npx autoworkflow init
-```
-
-**Or copy manually:**
-
-```bash
-# Copy all workflow files
-cp -r node_modules/autoworkflow/CLAUDE.md .
-cp -r node_modules/autoworkflow/system ./system
-cp -r node_modules/autoworkflow/instructions ./instructions
-cp -r node_modules/autoworkflow/.claude ./.claude
-cp -r node_modules/autoworkflow/scripts ./scripts
-cp -r node_modules/autoworkflow/hooks ./hooks
-
-# Optional: Copy VS Code settings
-cp -r node_modules/autoworkflow/.vscode ./.vscode
-
-# Optional: Copy config examples
-cp node_modules/autoworkflow/.prettierrc .
-cp node_modules/autoworkflow/eslint.config.example.js ./eslint.config.js
-cp node_modules/autoworkflow/tsconfig.example.json ./tsconfig.json
-
-# Setup git hooks
-npm run setup:hooks
-```
-
-### Manual Installation
-
-Clone or download this repository and copy the files to your project.
-
 ---
 
 ## How It Works
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                    CLAUDE.md (Entry Point)                   │
-│              Loaded automatically by Claude Code             │
-└───────────────────────────┬─────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    system/ (Control Layer)                   │
+│                    HOOKS (Automatic)                         │
 │                                                              │
-│  triggers.md  │  loops.md  │  gates.md  │  router.md        │
-│  WHEN to act  │  HOW to    │  WHAT      │  WHERE to         │
-│               │  repeat    │  blocks    │  route            │
-└───────────────────────────┬─────────────────────────────────┘
+│  UserPromptSubmit  →  session-check.sh                      │
+│  PostToolUse       →  post-edit.sh (after Write/Edit)       │
+│  PreToolUse        →  pre-commit-check.sh (before git)      │
+│                                                              │
+│  Hooks output messages that Claude sees as instructions     │
+└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
-│                 instructions/ (Content Layer)                │
+│                 settings.json (System Prompt)                │
 │                                                              │
-│  CLAUDE.md    │  AI_RULES.md  │  BLUEPRINT.md               │
-│  Workflow     │  Standards     │  Project spec               │
-└───────────────────────────┬─────────────────────────────────┘
+│  "instructions": [                                           │
+│    "SESSION START: If BLUEPRINT.md missing, scan codebase"  │
+│    "AFTER CODE CHANGES: Run npm run verify"                 │
+│    "BEFORE COMMIT: Block if TODO/console.log found"         │
+│  ]                                                           │
+└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌─────────────────────────────────────────────────────────────┐
-│              Backup Enforcement (Runtime Layer)              │
+│                   CLAUDE.md + instructions/                  │
 │                                                              │
-│  scripts/     │  hooks/        │  npm scripts               │
-│  Automation   │  Git hooks     │  Verification              │
+│  Workflow details, gates, task types, coding standards      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -93,222 +55,117 @@ Clone or download this repository and copy the files to your project.
 
 ## The Workflow
 
-When you ask Claude to do something, it follows this 9-phase workflow:
-
 ```
-ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → FIX → AUDIT → COMMIT → UPDATE
+ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → UPDATE
 ```
 
-| Phase | What Claude Does |
-|-------|------------------|
-| **ANALYZE** | Reads relevant files, checks BLUEPRINT.md |
-| **PLAN** | Designs approach, shows categorized suggestions |
-| **CONFIRM** | Waits for your approval |
-| **IMPLEMENT** | Makes changes (only after approval) |
-| **VERIFY** | Runs `npm run verify` (typecheck + lint) |
-| **FIX** | Fixes errors, loops back to VERIFY |
-| **AUDIT** | Checks for orphan features, circular deps |
-| **COMMIT** | Creates conventional commit (after approval) |
-| **UPDATE** | Updates BLUEPRINT.md if new feature/route/API added |
-
-### Session Start
-
-At the start of every session, Claude:
-1. Checks if `instructions/BLUEPRINT.md` exists
-2. If missing → Runs `/audit project` to generate it
-3. If exists → Reads AI_RULES.md + BLUEPRINT.md and proceeds
+| 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 |
 
 ---
 
-## Blocking Gates
+## Auto-Triggers (Hooks)
 
-Claude will STOP and cannot proceed if:
-
-| Gate | Blocks If |
-|------|-----------|
-| `plan_approval_gate` | You haven't approved the plan |
-| `verify_gate` | TypeScript or ESLint errors exist |
-| `audit_gate` | Orphan features or circular dependencies |
-| `pre_commit_gate` | TODO/FIXME, console.log, bad commit format |
+| 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 |
 
 ---
 
-## Available Commands
+## Blocking Gates
 
-| Command | Purpose |
-|---------|---------|
-| `/init` | Set up AutoWorkflow files from node_modules |
-| `/analyze [task]` | Analyze codebase for a task |
-| `/plan [task]` | Create implementation plan |
-| `/build [feature]` | Full workflow for features |
-| `/verify` | Run TypeScript + ESLint |
-| `/fix` | Fix verification errors |
-| `/audit` | Run UI + cycle audits |
-| `/audit project` | Full project scan → generates BLUEPRINT.md |
-| `/suggest [task]` | Generate suggestions |
-| `/commit [msg]` | Pre-commit check + commit |
+| 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 |
 
 ---
 
-## Hard Rules
-
-Claude enforces these automatically:
+## File Structure
 
-- **No orphan features** - Backend MUST have corresponding UI
-- **No TODO/FIXME** - Complete the work, don't leave placeholders
-- **No console.log** - No debug logs in production code
-- **No circular deps** - Clean architecture required
-- **Conventional commits** - `type(scope): description` format
+```
+project/
+├── CLAUDE.md                 # Workflow + gates (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
+│
+├── 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)
+```
 
 ---
 
-## npm Scripts
+## Commands
 
 ### Verification
 ```bash
 npm run verify           # TypeScript + ESLint
 npm run typecheck        # TypeScript only
 npm run lint             # ESLint only
-npm run format           # Prettier format
 ```
 
 ### Audits
 ```bash
-npm run audit:ui         # Check orphan features (BLOCKING)
-npm run audit:cycles     # Check circular deps (BLOCKING)
+npm run audit:ui         # Check orphan features
+npm run audit:cycles     # Check circular deps
 npm run audit:all        # Run all audits
 ```
 
-### Workflow Automation
-```bash
-npm run dyad:status      # Show workflow status
-npm run dyad:verify      # Run verification
-npm run dyad:commit      # Commit with checks
-npm run dyad:full        # Full workflow
-```
-
-### Setup
-```bash
-npm run setup:hooks      # Install git hooks
-```
-
----
-
-## File Structure
-
-```
-autoworkflow/
-├── CLAUDE.md                 # Entry point (Claude reads this first)
-│
-├── system/                   # Control Layer
-│   ├── triggers.md           # Event → Action mappings
-│   ├── loops.md              # Verify/fix cycle definitions
-│   ├── gates.md              # Blocking checkpoints
-│   └── router.md             # Task type routing
-│
-├── instructions/             # Content Layer
-│   ├── CLAUDE.md             # Workflow steps (9 phases)
-│   ├── AI_RULES.md           # Coding standards
-│   └── BLUEPRINT.md          # Project specification
-│
-├── .claude/                  # Claude Code Integration
-│   ├── settings.json         # Settings + hard rules
-│   └── commands/             # Slash command definitions
-│       ├── init.md
-│       ├── analyze.md
-│       ├── plan.md
-│       ├── build.md
-│       ├── verify.md
-│       ├── fix.md
-│       ├── audit.md
-│       ├── suggest.md
-│       └── commit.md
-│
-├── scripts/                  # Automation Scripts
-│   ├── setup.sh              # Initial setup
-│   ├── autoworkflow.sh       # Workflow automation
-│   ├── check-ui-enforcement.sh
-│   ├── run-verification.sh
-│   └── ensure-no-errors.sh
-│
-├── hooks/                    # Git Hooks (backup enforcement)
-│   ├── pre-commit            # Blocks bad commits
-│   └── commit-msg            # Validates commit messages
-│
-├── .vscode/                  # VS Code Integration (optional)
-│   ├── settings.json         # Editor settings
-│   ├── tasks.json            # Runnable tasks
-│   └── extensions.json       # Recommended extensions
-│
-├── .prettierrc               # Prettier config
-├── eslint.config.example.js  # ESLint config template
-└── tsconfig.example.json     # TypeScript config template
-```
-
----
-
-## Why This Approach?
-
-### Dual Enforcement Strategy
-
-**Primary: Claude as Enforcement Engine**
-- Claude reads instructions from system prompts
-- Claude follows the 9-phase workflow
-- Claude enforces rules proactively as it works
-- Claude explains what's happening
-
-**Backup: Scripts & Git Hooks**
-- Git hooks catch anything Claude misses
-- Scripts automate verification
-- Pre-commit blocks bad code from reaching the repo
-
-### Benefits
-
-| Feature | Benefit |
+### Slash Commands
+| Command | Purpose |
 |---------|---------|
-| System prompts | No runtime code to maintain |
-| Portable | Just copy files to any project |
-| Transparent | Claude explains the workflow |
-| Flexible | Claude adapts to context |
-| Suggestions | Proactively improves code quality |
-| Git hooks | Backup enforcement layer |
-| npm scripts | Easy automation |
+| `/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 |
 
 ---
 
 ## Customization
 
-### Adding Your Coding Standards
+### Your Coding Standards
 Edit `instructions/AI_RULES.md`:
 ```markdown
 ## ALWAYS
 - Use TypeScript strict mode
 - Handle all error cases
-- Add loading states for async
 
 ## NEVER
 - Use `any` type
 - Leave console.logs
-- Skip error handling
 ```
 
-### Adding Your Project Spec
-Edit `instructions/BLUEPRINT.md`:
-```markdown
-## Features
-- [ ] User authentication
-- [ ] Dashboard page
-- [ ] Settings panel
-
-## Data Model
-User: id, email, name, role
-```
+### Adjust Gates
+Edit `.claude/settings.json` gates section.
 
-### Adjusting Gates
-Edit `system/gates.md` to change what blocks progress.
-
-### Adjusting Loops
-Edit `system/loops.md` to change retry behavior.
+### Modify Hooks
+Edit files in `.claude/hooks/` to change auto-trigger behavior.
 
 ---
 
@@ -320,23 +177,6 @@ Edit `system/loops.md` to change retry behavior.
 
 ---
 
-## What Gets Copied
-
-When you install via npm, these files are available to copy:
-
-| Category | Files | Required? |
-|----------|-------|-----------|
-| Entry point | `CLAUDE.md` | ✅ Yes |
-| Control layer | `system/` | ✅ Yes |
-| Content layer | `instructions/` | ✅ Yes |
-| Claude integration | `.claude/` | ✅ Yes |
-| Automation | `scripts/` | Recommended |
-| Git hooks | `hooks/` | Recommended |
-| VS Code | `.vscode/` | Optional |
-| Configs | `.prettierrc`, `*.example.*` | Optional |
-
----
-
 ## License
 
 MIT

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, cpSync, mkdirSync, chmodSync } from 'fs';
+import { existsSync, cpSync, mkdirSync, chmodSync, renameSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -17,6 +17,7 @@ const colors = {
   red: (text) => `\x1b[31m${text}\x1b[0m`,
   cyan: (text) => `\x1b[36m${text}\x1b[0m`,
   bold: (text) => `\x1b[1m${text}\x1b[0m`,
+  dim: (text) => `\x1b[2m${text}\x1b[0m`,
 };
 
 function printHelp() {
@@ -31,14 +32,44 @@ Commands:
   init --minimal Required files only
   help          Show this help message
 
+Options:
+  --no-backup   Overwrite existing files without backup
+
 Examples:
   npx autoworkflow init
   npx autoworkflow init --all
 `);
 }
 
-function copyFile(src, dest, name) {
+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()}`)}`);
+      return true;
+    } catch (err) {
+      console.log(`  ${colors.red('✗')} Failed to backup ${name}: ${err.message}`);
+      return false;
+    }
+  }
+  return true; // No backup needed
+}
+
+function copyFile(src, dest, name, options = {}) {
+  const noBackup = args.includes('--no-backup');
+
   if (existsSync(src)) {
+    // Backup existing file/folder if it exists
+    if (!noBackup && existsSync(dest)) {
+      const backed = backupFile(dest, name);
+      if (!backed) return false;
+    }
+
     try {
       cpSync(src, dest, { recursive: true });
       console.log(`  ${colors.green('✓')} ${name}`);
@@ -57,23 +88,38 @@ 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)}\n`);
-
-  // Check if already initialized
-  if (existsSync(join(cwd, 'CLAUDE.md'))) {
-    console.log(`${colors.yellow('⚠')} CLAUDE.md already exists.`);
-    console.log(`  Use --force to overwrite (not implemented yet)\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, 'instructions'), join(cwd, 'instructions'), 'instructions/');
   copyFile(join(packageRoot, '.claude'), join(cwd, '.claude'), '.claude/');
 
+  // Make Claude hooks executable
+  if (process.platform !== 'win32' && existsSync(join(cwd, '.claude', 'hooks'))) {
+    try {
+      const hookFiles = ['session-check.sh', 'post-edit.sh', 'pre-commit-check.sh'];
+      hookFiles.forEach(hook => {
+        const hookPath = join(cwd, '.claude', 'hooks', hook);
+        if (existsSync(hookPath)) {
+          chmodSync(hookPath, 0o755);
+        }
+      });
+      console.log(`  ${colors.green('✓')} Claude hooks made executable`);
+    } catch (e) {
+      // Ignore chmod errors
+    }
+  }
+
   if (!minimal) {
     // Recommended files
     console.log(`\n${colors.bold('Recommended files:')}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "autoworkflow",
-  "version": "2.2.1",
-  "description": "System prompt layer that controls Claude Code's workflow with triggers, loops, and gates",
+  "version": "3.0.0",
+  "description": "Automated workflow enforcement for Claude Code via hooks and system prompts",
   "type": "module",
   "bin": {
     "autoworkflow": "bin/cli.js"
@@ -11,7 +11,9 @@
     "claude-code",
     "workflow",
     "system-prompts",
-    "ai-instructions"
+    "ai-instructions",
+    "hooks",
+    "automation"
   ],
   "author": "",
   "license": "MIT",

package/system/triggers.md

@@ -71,16 +71,22 @@ Or run `/init --all` to include .vscode and config templates.
 ### `on:blueprint_missing`
 
 **When:** BLUEPRINT.md does not exist at session start
+**Behavior:** AUTOMATIC - runs without asking permission
+
+**IMPORTANT:** This trigger runs AUTOMATICALLY. Do NOT ask "Should I run the audit?" - just run it.
+Only ask for approval when SAVING the generated files, not when starting the scan.
+
 **Action:**
-1. Run single audit scan of codebase
-2. Generate BOTH AI_RULES.md updates AND BLUEPRINT.md
-3. Present proposed updates to user
-4. Save after approval
+1. Notify user (brief message)
+2. **RUN audit immediately** (no permission needed)
+3. Generate BOTH AI_RULES.md updates AND BLUEPRINT.md
+4. Present proposed updates to user
+5. Ask approval to SAVE (not to start)
 
 ```
 TRIGGER: blueprint_missing
-├── Notify: "No BLUEPRINT.md found. Running project audit..."
-├── Scan: codebase (single pass)
+├── Notify: "No BLUEPRINT.md found. Running project audit..."  ← Just notify
+├── RUN IMMEDIATELY (no permission needed):                     ← Auto-run
 │   ├── cat package.json → Tech stack
 │   ├── find src -type d → File structure
 │   ├── ls src/pages/ → Routes
@@ -91,19 +97,35 @@ TRIGGER: blueprint_missing
 ├── Generate: AI_RULES.md updates (Tech Stack, File Structure)
 ├── Generate: BLUEPRINT.md (Features, Routes, APIs)
 ├── Present: both updates to user
-├── Await: user approval
+├── Await: approval TO SAVE (not to start)                      ← Only save needs approval
 └── Save: both files after approval
 ```
 
+**DO NOT:**
+- Ask "Should I run the audit?"
+- Ask "Do you want me to scan the project?"
+- Wait for permission to start scanning
+
+**DO:**
+- Notify and immediately start scanning
+- Only ask permission when presenting results to save
+
 **Output Format:**
 ```
-⚠️ No BLUEPRINT.md found in this project.
+⚠️ No BLUEPRINT.md found.
+
+Running project audit now...
+
+[scanning happens automatically]
+
+---
+
+## 🔍 Audit Complete
 
-Running ONE audit to update TWO files:
-- 📄 AI_RULES.md → Tech Stack & File Structure
-- 📘 BLUEPRINT.md → Features, Routes, APIs
+[present AI_RULES.md updates]
+[present BLUEPRINT.md content]
 
-Scanning codebase...
+**Should I save these files?** (yes/no/edit first)
 ```
 
 ---