autoworkflow 1.2.0 → 2.0.1

package/README.md

@@ -1,250 +1,327 @@
-# autoworkflow
+# AutoWorkflow - System Prompt Layer for Claude Code
 
-Zero-config code quality enforcement. Just install and commit.
+> **Claude is the enforcement engine.** System prompts control the workflow. Scripts and hooks provide backup enforcement.
 
-[![npm version](https://img.shields.io/npm/v/autoworkflow.svg)](https://www.npmjs.com/package/autoworkflow)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+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.
 
-## Install
+---
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install autoworkflow
+```
+
+Then copy files to your project:
 
 ```bash
-npm install autoworkflow --save-dev
+# 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
 ```
 
-**That's it.** Enforcement is now active on all commits.
+### Manual Installation
+
+Clone or download this repository and copy the files to your project.
 
-## What Happens
+---
+
+## How It Works
 
 ```
-npm install autoworkflow
-         │
-         ▼
-  ┌──────────────────────────────────┐
-  │  Auto-setup (postinstall):       │
-  │  ✓ Creates .husky/pre-commit     │
-  │  ✓ Creates .husky/commit-msg     │
-  │  ✓ Creates enforce.config.json   │
-  │  ✓ Creates CLAUDE.md             │
-  │  ✓ Creates .vscode/settings.json │
-  │  ✓ Creates .vscode/tasks.json    │
-  │  ✓ Adds prepare script           │
-  └──────────────────────────────────┘
-         │
-         ▼
-  Every "git commit" runs checks automatically
+┌─────────────────────────────────────────────────────────────┐
+│                    CLAUDE.md (Entry Point)                   │
+│              Loaded automatically by Claude Code             │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    system/ (Control Layer)                   │
+│                                                              │
+│  triggers.md  │  loops.md  │  gates.md  │  router.md        │
+│  WHEN to act  │  HOW to    │  WHAT      │  WHERE to         │
+│               │  repeat    │  blocks    │  route            │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 instructions/ (Content Layer)                │
+│                                                              │
+│  CLAUDE.md    │  AI_RULES.md  │  BLUEPRINT.md               │
+│  Workflow     │  Standards     │  Project spec               │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Backup Enforcement (Runtime Layer)              │
+│                                                              │
+│  scripts/     │  hooks/        │  npm scripts               │
+│  Automation   │  Git hooks     │  Verification              │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**Note:** Existing files are never overwritten.
+---
 
-## Default Checks
+## The Workflow
 
-| Check                  | Blocking | Auto-Fix |
-| ---------------------- | -------- | -------- |
-| No TODO/FIXME comments | ✅       | -        |
-| No console.log         | ✅       | -        |
-| TypeScript errors      | ✅       | -        |
-| ESLint errors          | ✅       | ✅       |
-| Circular dependencies  | ✅       | -        |
-| Commit message format  | ✅       | -        |
+When you ask Claude to do something, it follows this 9-phase workflow:
 
-## How It Works
+```
+ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → FIX → AUDIT → COMMIT → UPDATE
+```
 
-### Pre-Commit Hook
+| 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 |
 
-Every time you run `git commit`, autoworkflow:
+### Session Start
 
-1. Runs all enabled checks
-2. If ESLint fails, auto-fixes and retries (up to 5 attempts)
-3. Blocks commit if any blocking check fails
-4. Allows commit if all checks pass
+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
 
-### Commit Message Validation
+---
 
-Enforces [Conventional Commits](https://www.conventionalcommits.org/):
+## Blocking Gates
 
-```bash
-# ✅ Valid
-git commit -m "feat: add user authentication"
-git commit -m "fix(api): resolve timeout issue"
-git commit -m "docs: update installation guide"
-
-# ❌ Invalid (blocked)
-git commit -m "fixed stuff"
-git commit -m "WIP"
-```
+Claude will STOP and cannot proceed if:
 
-## Configuration
-
-Edit `enforce.config.json` in your project root:
-
-```json
-{
-  "rules": {
-    "no-todo-comments": {
-      "enabled": true,
-      "blocking": true,
-      "patterns": ["TODO", "FIXME", "XXX", "HACK"]
-    },
-    "no-console-logs": {
-      "enabled": true,
-      "blocking": true
-    },
-    "typescript": {
-      "enabled": true,
-      "blocking": true,
-      "command": "npx tsc --noEmit"
-    },
-    "eslint": {
-      "enabled": true,
-      "blocking": true,
-      "autoFix": true,
-      "command": "npx eslint . --max-warnings 0",
-      "fixCommand": "npx eslint . --fix"
-    },
-    "circular-deps": {
-      "enabled": true,
-      "blocking": true,
-      "paths": ["src/"]
-    }
-  },
-  "fixLoop": {
-    "enabled": true,
-    "maxAttempts": 5,
-    "autoFixRules": ["eslint"]
-  },
-  "commitMessage": {
-    "enabled": true,
-    "pattern": "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(.+\\))?: .{1,72}$"
-  }
-}
-```
+| 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 |
 
-### Rule Options
+---
 
-| Option       | Type    | Description                            |
-| ------------ | ------- | -------------------------------------- |
-| `enabled`    | boolean | Enable/disable the rule                |
-| `blocking`   | boolean | If true, fails the commit on violation |
-| `autoFix`    | boolean | Enable auto-fix for this rule          |
-| `command`    | string  | Custom check command                   |
-| `fixCommand` | string  | Custom fix command                     |
+## Available Commands
 
-### Disable a Rule
+| Command | Purpose |
+|---------|---------|
+| `/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 |
 
-```json
-{
-  "rules": {
-    "no-console-logs": { "enabled": false }
-  }
-}
-```
+---
 
-### Non-Blocking Warning
+## Hard Rules
 
-```json
-{
-  "rules": {
-    "circular-deps": { "enabled": true, "blocking": false }
-  }
-}
-```
+Claude enforces these automatically:
 
-## CLI Commands
+- **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
 
+---
+
+## npm Scripts
+
+### Verification
 ```bash
-# Run all checks manually
-npx autoworkflow run
+npm run verify           # TypeScript + ESLint
+npm run typecheck        # TypeScript only
+npm run lint             # ESLint only
+npm run format           # Prettier format
+```
 
-# List all rules and their status
-npx autoworkflow list
+### Audits
+```bash
+npm run audit:ui         # Check orphan features (BLOCKING)
+npm run audit:cycles     # Check circular deps (BLOCKING)
+npm run audit:all        # Run all audits
+```
 
-# Validate a commit message
-npx autoworkflow commit-msg .git/COMMIT_EDITMSG
+### 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
+```
 
-# Show help
-npx autoworkflow --help
+### Setup
+```bash
+npm run setup:hooks      # Install git hooks
 ```
 
-## Fix Loop
+---
 
-When ESLint (or other auto-fixable rules) fail:
+## File Structure
 
 ```
-[1/5] ESLint... ❌
-     src/app.ts: 'unused' is defined but never used
+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
+│       ├── 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
+```
 
-🔧 Attempting auto-fix...
-   ✅ Fixed: ESLint
+---
 
-🔄 Fix Loop - Attempt 2/5
+## Why This Approach?
 
-[1/5] ESLint... ✅
+### Dual Enforcement Strategy
 
-✅ ALL CHECKS PASSED
-```
+**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
 
-## Skip Enforcement (Emergency)
+**Backup: Scripts & Git Hooks**
+- Git hooks catch anything Claude misses
+- Scripts automate verification
+- Pre-commit blocks bad code from reaching the repo
 
-```bash
-git commit --no-verify -m "emergency: hotfix for production"
-```
+### Benefits
 
-Use sparingly. All skipped commits are your responsibility.
+| Feature | Benefit |
+|---------|---------|
+| 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 |
 
-## Requirements
+---
 
-- Node.js >= 18.0.0
-- Git repository (initialized with `git init`)
+## Customization
 
-### Optional Peer Dependencies
+### Adding Your Coding Standards
+Edit `instructions/AI_RULES.md`:
+```markdown
+## ALWAYS
+- Use TypeScript strict mode
+- Handle all error cases
+- Add loading states for async
 
-- TypeScript >= 5.0.0 (for TypeScript checks)
-- ESLint >= 8.0.0 (for ESLint checks)
+## NEVER
+- Use `any` type
+- Leave console.logs
+- Skip error handling
+```
 
-## VSCode Integration
+### Adding Your Project Spec
+Edit `instructions/BLUEPRINT.md`:
+```markdown
+## Features
+- [ ] User authentication
+- [ ] Dashboard page
+- [ ] Settings panel
 
-### Auto-Fix on Save
+## Data Model
+User: id, email, name, role
+```
 
-The generated `.vscode/settings.json` enables:
+### Adjusting Gates
+Edit `system/gates.md` to change what blocks progress.
 
-- **Format on save** with Prettier
-- **ESLint auto-fix** on save
-- **Organize imports** on save
-- **Remove unused imports** on save
-- **Tailwind CSS** class sorting (clsx/cn support)
+### Adjusting Loops
+Edit `system/loops.md` to change retry behavior.
 
-### Quick Tasks (Cmd+Shift+B)
+---
 
-The generated `.vscode/tasks.json` provides:
+## Requirements
 
-| Task | Description |
-|------|-------------|
-| Autoworkflow: Run Checks | Run all enforcement checks |
-| Autoworkflow: TypeScript Check | TypeScript only |
-| Autoworkflow: ESLint Fix | Fix all ESLint issues |
-| Autoworkflow: List Rules | Show rule status |
-| Dev Server | Start npm run dev |
-| Quick Commit | Stage all + commit with prompt |
+- VS Code with Claude Code extension
+- Node.js 18+ (for npm scripts)
+- TypeScript, ESLint, Prettier (for verification)
 
-## AI Integration (CLAUDE.md)
+---
 
-The generated `CLAUDE.md` instructs Claude/AI assistants to:
+## What Gets Copied
 
-- Follow a structured workflow (Analyze → Plan → Confirm → Implement)
-- Show 3-tier suggestions (Required/Recommended/Optional)
-- Ask for confirmation before implementing
-- Use conventional commit messages
-- Respect all enforcement rules
+When you install via npm, these files are available to copy:
 
-## Uninstall
+| 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 |
 
-```bash
-npm uninstall autoworkflow
-rm -rf .husky
-rm enforce.config.json
-rm CLAUDE.md
-rm -rf .vscode  # Only if you want to remove VSCode settings
-```
+---
 
 ## License
 

package/eslint.config.example.js

@@ -0,0 +1,83 @@
+/**
+ * eslint.config.example.js
+ * AutoWorkflow ESLint Configuration
+ *
+ * This is a reference configuration that enforces the rules
+ * defined in CLAUDE.md and instructions/AI_RULES.md
+ *
+ * Copy to your project as: eslint.config.js
+ */
+
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules', 'coverage'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      // ─────────────────────────────────────────────────────────────
+      // React Rules
+      // ─────────────────────────────────────────────────────────────
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+
+      // ─────────────────────────────────────────────────────────────
+      // TypeScript Rules (from AI_RULES.md)
+      // ─────────────────────────────────────────────────────────────
+      '@typescript-eslint/no-unused-vars': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/no-non-null-assertion': 'error',
+      '@typescript-eslint/explicit-function-return-type': 'off',
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        { prefer: 'type-imports' },
+      ],
+
+      // ─────────────────────────────────────────────────────────────
+      // Console Rules (BLOCKING - from CLAUDE.md)
+      // ─────────────────────────────────────────────────────────────
+      'no-console': ['error', { allow: ['warn', 'error'] }],
+
+      // ─────────────────────────────────────────────────────────────
+      // Code Quality Rules (from AI_RULES.md)
+      // ─────────────────────────────────────────────────────────────
+      'max-lines': ['warn', { max: 300, skipBlankLines: true, skipComments: true }],
+      'max-lines-per-function': ['warn', { max: 75, skipBlankLines: true, skipComments: true }],
+      complexity: ['warn', 15],
+      'no-nested-ternary': 'error',
+      eqeqeq: ['error', 'always'],
+
+      // ─────────────────────────────────────────────────────────────
+      // Best Practices
+      // ─────────────────────────────────────────────────────────────
+      'prefer-const': 'error',
+      'no-var': 'error',
+      'object-shorthand': 'error',
+      'prefer-template': 'error',
+      'prefer-arrow-callback': 'error',
+      'no-duplicate-imports': 'error',
+
+      // ─────────────────────────────────────────────────────────────
+      // Accessibility Rules (optional but recommended)
+      // ─────────────────────────────────────────────────────────────
+      // Note: Install eslint-plugin-jsx-a11y for these
+      // 'jsx-a11y/alt-text': 'error',
+      // 'jsx-a11y/anchor-has-content': 'error',
+      // 'jsx-a11y/aria-props': 'error',
+      // 'jsx-a11y/click-events-have-key-events': 'warn',
+    },
+  }
+)