autoworkflow 1.1.0 → 2.0.0

package/README.md

@@ -1,250 +1,235 @@
-# autoworkflow
+# AutoWorkflow - System Prompt Layer for Claude Code
 
-Zero-config code quality enforcement. Just install and commit.
+> **Claude is the enforcement engine.** No scripts, no git hooks - just instructions that Claude follows.
 
-[![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 will automatically follow a structured workflow for all coding tasks.
 
-## Install
+---
 
-```bash
-npm install autoworkflow --save-dev
-```
-
-**That's it.** Enforcement is now active on all commits.
-
-## 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               │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**Note:** Existing files are never overwritten.
-
-## Default Checks
-
-| Check                  | Blocking | Auto-Fix |
-| ---------------------- | -------- | -------- |
-| No TODO/FIXME comments | ✅       | -        |
-| No console.log         | ✅       | -        |
-| TypeScript errors      | ✅       | -        |
-| ESLint errors          | ✅       | ✅       |
-| Circular dependencies  | ✅       | -        |
-| Commit message format  | ✅       | -        |
+---
 
-## How It Works
+## Quick Start
 
-### Pre-Commit Hook
+1. **Copy this structure** into your project:
+   ```
+   your-project/
+   ├── CLAUDE.md                 # Entry point
+   ├── system/                   # Control layer
+   │   ├── triggers.md
+   │   ├── loops.md
+   │   ├── gates.md
+   │   └── router.md
+   ├── instructions/             # Content layer
+   │   ├── CLAUDE.md
+   │   ├── AI_RULES.md
+   │   └── BLUEPRINT.md
+   ├── .claude/                  # Claude Code integration
+   │   ├── settings.json
+   │   └── commands/
+   └── .vscode/                  # VS Code integration
+       ├── settings.json
+       ├── tasks.json
+       └── extensions.json
+   ```
 
-Every time you run `git commit`, autoworkflow:
+2. **Customize the instructions**:
+   - Edit `instructions/AI_RULES.md` with your coding standards
+   - Edit `instructions/BLUEPRINT.md` with your project spec
 
-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
+3. **Use Claude Code** - Claude will automatically follow the workflow!
 
-### Commit Message Validation
+---
 
-Enforces [Conventional Commits](https://www.conventionalcommits.org/):
+## The Workflow
 
-```bash
-# ✅ Valid
-git commit -m "feat: add user authentication"
-git commit -m "fix(api): resolve timeout issue"
-git commit -m "docs: update installation guide"
+When you ask Claude to do something, it follows this workflow:
 
-# ❌ Invalid (blocked)
-git commit -m "fixed stuff"
-git commit -m "WIP"
 ```
-
-## 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}$"
-  }
-}
+ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT
 ```
 
-### Rule Options
+| Phase | What Claude Does |
+|-------|------------------|
+| **ANALYZE** | Reads relevant files, understands context |
+| **PLAN** | Designs approach, shows suggestions |
+| **CONFIRM** | Waits for your approval |
+| **IMPLEMENT** | Makes changes (only after approval) |
+| **VERIFY** | Runs `npm run verify` (typecheck + lint) |
+| **AUDIT** | Checks for orphan features, circular deps |
+| **COMMIT** | Creates conventional commit (after approval) |
 
-| 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                     |
+---
 
-### Disable a Rule
+## Blocking Gates
 
-```json
-{
-  "rules": {
-    "no-console-logs": { "enabled": false }
-  }
-}
-```
+Claude will STOP and cannot proceed if:
 
-### Non-Blocking Warning
+| 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 |
 
-```json
-{
-  "rules": {
-    "circular-deps": { "enabled": true, "blocking": false }
-  }
-}
-```
+---
 
-## CLI Commands
+## Available Commands
 
-```bash
-# Run all checks manually
-npx autoworkflow run
+| 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 |
+| `/suggest [task]` | Generate suggestions |
+| `/commit [msg]` | Pre-commit check + commit |
 
-# List all rules and their status
-npx autoworkflow list
+---
 
-# Validate a commit message
-npx autoworkflow commit-msg .git/COMMIT_EDITMSG
+## Hard Rules
 
-# Show help
-npx autoworkflow --help
-```
+Claude enforces these automatically:
 
-## Fix Loop
+- **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
 
-When ESLint (or other auto-fixable rules) fail:
+---
 
-```
-[1/5] ESLint... ❌
-     src/app.ts: 'unused' is defined but never used
+## File Structure
 
-🔧 Attempting auto-fix...
-   ✅ Fixed: ESLint
-
-🔄 Fix Loop - Attempt 2/5
-
-[1/5] ESLint... ✅
-
-✅ ALL CHECKS PASSED
 ```
-
-## Skip Enforcement (Emergency)
-
-```bash
-git commit --no-verify -m "emergency: hotfix for production"
+@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
+│   ├── 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
+│
+└── .vscode/                  # VS Code Integration
+    ├── settings.json         # Editor settings
+    ├── tasks.json            # Runnable tasks
+    └── extensions.json       # Recommended extensions
 ```
 
-Use sparingly. All skipped commits are your responsibility.
+---
 
-## Requirements
+## Why This Approach?
 
-- Node.js >= 18.0.0
-- Git repository (initialized with `git init`)
+### Traditional Enforcement
+- Git hooks run scripts
+- Scripts check code
+- Blocks commit on failure
 
-### Optional Peer Dependencies
+### AutoWorkflow (This Approach)
+- Claude reads instructions
+- Claude follows the workflow
+- Claude enforces rules as it works
 
-- TypeScript >= 5.0.0 (for TypeScript checks)
-- ESLint >= 8.0.0 (for ESLint checks)
+**Benefits:**
+- No runtime code to maintain
+- Works in any project (just copy files)
+- Claude explains what's happening
+- Flexible - Claude can adapt to context
+- Suggestions improve code quality proactively
 
-## VSCode Integration
+---
 
-### Auto-Fix on Save
+## Customization
 
-The generated `.vscode/settings.json` enables:
+### Adding Your Coding Standards
+Edit `instructions/AI_RULES.md`:
+```markdown
+## ALWAYS
+- Use TypeScript strict mode
+- Handle all error cases
+- Add loading states for async
 
-- **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)
+## NEVER
+- Use `any` type
+- Leave console.logs
+- Skip error handling
+```
 
-### Quick Tasks (Cmd+Shift+B)
+### Adding Your Project Spec
+Edit `instructions/BLUEPRINT.md`:
+```markdown
+## Features
+- [ ] User authentication
+- [ ] Dashboard page
+- [ ] Settings panel
 
-The generated `.vscode/tasks.json` provides:
+## Data Model
+User: id, email, name, role
+```
 
-| 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 |
+### Adjusting Gates
+Edit `system/gates.md` to change what blocks progress.
 
-## AI Integration (CLAUDE.md)
+### Adjusting Loops
+Edit `system/loops.md` to change retry behavior.
 
-The generated `CLAUDE.md` instructs Claude/AI assistants to:
+---
 
-- 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
+## Requirements
 
-## Uninstall
+- VS Code with Claude Code extension
+- That's it! No npm install needed for the workflow itself.
 
-```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
-```
+If you want the verification commands (`npm run verify`, etc.) to work, you'll need:
+- Node.js 18+
+- TypeScript, ESLint, etc. in your project
+
+---
 
 ## 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',
+    },
+  }
+)

package/hooks/commit-msg

@@ -0,0 +1,137 @@
+#!/bin/bash
+# commit-msg
+# Git commit-msg hook that enforces conventional commit format
+# Install: cp hooks/commit-msg .git/hooks/commit-msg && chmod +x .git/hooks/commit-msg
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+COMMIT_MSG_FILE=$1
+COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
+
+# Skip merge commits
+if echo "$COMMIT_MSG" | grep -qE "^Merge"; then
+    exit 0
+fi
+
+# Skip revert commits
+if echo "$COMMIT_MSG" | grep -qE "^Revert"; then
+    exit 0
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔍 COMMIT MESSAGE VALIDATION"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# ─────────────────────────────────────────────────────────────
+# Conventional Commit Format
+# ─────────────────────────────────────────────────────────────
+# type(scope): description
+#
+# Valid types:
+#   feat     - New feature
+#   fix      - Bug fix
+#   docs     - Documentation only
+#   style    - Formatting, no code change
+#   refactor - Code change, no feature/fix
+#   perf     - Performance improvement
+#   test     - Adding tests
+#   build    - Build system changes
+#   ci       - CI/CD changes
+#   chore    - Maintenance
+#   revert   - Revert commit
+
+VALID_TYPES="feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert"
+
+# Pattern: type(scope): description
+# - type is required
+# - scope is optional (in parentheses)
+# - colon and space are required
+# - description is required
+
+PATTERN="^($VALID_TYPES)(\([a-z0-9_-]+\))?: .+"
+
+# Get first line (subject)
+SUBJECT=$(echo "$COMMIT_MSG" | head -1)
+
+echo "Message: \"$SUBJECT\""
+echo ""
+
+# ─────────────────────────────────────────────────────────────
+# Validation
+# ─────────────────────────────────────────────────────────────
+
+VALID=1
+ERRORS=""
+
+# Check 1: Matches conventional format
+if ! echo "$SUBJECT" | grep -qE "$PATTERN"; then
+    VALID=0
+    ERRORS="${ERRORS}  ❌ Does not match format: type(scope): description\n"
+fi
+
+# Check 2: Subject length (max 72 characters)
+SUBJECT_LENGTH=${#SUBJECT}
+if [ $SUBJECT_LENGTH -gt 72 ]; then
+    VALID=0
+    ERRORS="${ERRORS}  ❌ Subject too long: ${SUBJECT_LENGTH}/72 characters\n"
+fi
+
+# Check 3: Subject doesn't end with period
+if echo "$SUBJECT" | grep -qE "\.$"; then
+    VALID=0
+    ERRORS="${ERRORS}  ❌ Subject should not end with a period\n"
+fi
+
+# Check 4: Subject starts with lowercase (after type)
+if echo "$SUBJECT" | grep -qE "^[a-z]+(\([a-z0-9_-]+\))?: [A-Z]"; then
+    ERRORS="${ERRORS}  ⚠️  Description should start with lowercase (optional)\n"
+fi
+
+# ─────────────────────────────────────────────────────────────
+# Result
+# ─────────────────────────────────────────────────────────────
+
+if [ $VALID -eq 0 ]; then
+    echo -e "${RED}╔══════════════════════════════════════════════════════════════╗${NC}"
+    echo -e "${RED}║              ⛔ INVALID COMMIT MESSAGE ⛔                     ║${NC}"
+    echo -e "${RED}╚══════════════════════════════════════════════════════════════╝${NC}"
+    echo ""
+    echo "Issues found:"
+    echo -e "$ERRORS"
+    echo ""
+    echo "Expected format:"
+    echo -e "  ${YELLOW}type(scope): description${NC}"
+    echo ""
+    echo "Valid types:"
+    echo "  feat      New feature"
+    echo "  fix       Bug fix"
+    echo "  docs      Documentation"
+    echo "  style     Formatting"
+    echo "  refactor  Code restructure"
+    echo "  perf      Performance"
+    echo "  test      Tests"
+    echo "  build     Build system"
+    echo "  ci        CI/CD"
+    echo "  chore     Maintenance"
+    echo "  revert    Revert"
+    echo ""
+    echo "Examples:"
+    echo "  feat(auth): add login page"
+    echo "  fix(api): handle null response"
+    echo "  refactor(utils): extract date helpers"
+    echo "  docs: update README"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Commit message is valid${NC}"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+exit 0