autoworkflow 3.0.1 → 3.1.0

package/system/triggers.md

@@ -2,130 +2,108 @@
 
 > Event-driven actions that control Claude's workflow behavior.
 > These triggers fire automatically based on context and events.
+>
+> **IMPLEMENTATION:** All triggers are now implemented as shell scripts in `.claude/hooks/`
 
 ---
 
-## Trigger Definitions
+## Trigger Implementation Map
 
-### `on:conversation_start`
+| Trigger | Hook Script | Event |
+|---------|-------------|-------|
+| `on:conversation_start` | `session-check.sh` | UserPromptSubmit |
+| `on:blueprint_missing` | `session-check.sh` + `blueprint-generator.sh` | UserPromptSubmit |
+| `on:init_needed` | `session-check.sh` | UserPromptSubmit |
+| `on:task_received` | `session-check.sh` | UserPromptSubmit |
+| `on:phase_transition` | `phase-transition.sh` | Manual call |
+| `on:implementation_complete` | `post-edit.sh` | PostToolUse (Write\|Edit) |
+| `on:verification_failed` | `post-edit.sh` | PostToolUse (Write\|Edit) |
+| `on:verification_passed` | `post-edit.sh` | PostToolUse (Write\|Edit) |
+| `on:commit_requested` | `pre-tool-router.sh` → `pre-commit-check.sh` | PreToolUse (Bash) |
 
-**When:** Claude begins a new conversation or task
-**Action:**
-1. Check if autoworkflow needs initialization
-2. Read root `CLAUDE.md` (entry point)
-3. Check if `instructions/BLUEPRINT.md` exists
-4. If NO → Trigger `on:blueprint_missing`
-5. If YES → Load blueprint and proceed
-6. Load `system/router.md` to determine task type
-7. Load `system/gates.md` for blocking rules
-8. Await user request
+---
+
+## State Management
+
+All workflow state is stored in `.claude/.autoworkflow/`:
 
 ```
-TRIGGER: conversation_start
-├── Check: node_modules/autoworkflow exists AND CLAUDE.md missing?
-│   └── YES → Trigger: on:init_needed
-├── Read: CLAUDE.md
-├── Check: instructions/BLUEPRINT.md exists?
-│   ├── NO  → Trigger: on:blueprint_missing
-│   └── YES → Read: instructions/BLUEPRINT.md
-├── Read: system/router.md
-├── Read: system/gates.md
-└── State: READY
+.claude/.autoworkflow/
+├── session-id           # Current session identifier
+├── phase                # Current workflow phase
+├── task-type            # Classified task type
+├── verify-iteration     # Current verify loop count
+├── verify-status        # PASSED/FAILED/BLOCKED
+├── audit-iteration      # Current audit loop count
+├── audit-status         # PASSED/FAILED/BLOCKED
+├── gate-status          # Last gate check result
+├── gate-errors          # Number of gate errors
+├── plan-approved        # Plan approval status
+├── changed-files        # List of modified files
+└── blueprint-checked    # Blueprint check done flag
 ```
 
 ---
 
-### `on:init_needed`
+## Trigger Definitions
 
-**When:** autoworkflow is in node_modules but CLAUDE.md is missing
-**Action:**
-1. Notify user that autoworkflow needs setup
-2. Suggest running /init command
+### `on:conversation_start`
 
-```
-TRIGGER: init_needed
-├── Notify: "AutoWorkflow detected but not initialized"
-├── Suggest: "Run /init to set up workflow files"
-└── Await: user response
-```
+**When:** Claude begins a new conversation or task
+**Hook:** `.claude/hooks/session-check.sh`
+**Event:** `UserPromptSubmit`
+
+**Actions:**
+1. Initialize session state (create session-id)
+2. Reset iteration counters
+3. Check if autoworkflow needs initialization
+4. Check if `instructions/BLUEPRINT.md` exists
+5. If NO → Trigger `on:blueprint_missing`
+6. If YES → Load blueprint and proceed
+7. Show current workflow state
 
-**Output Format:**
+```bash
+# Implementation
+./.claude/hooks/session-check.sh
 ```
-📦 **AutoWorkflow detected in node_modules**
 
-The workflow files haven't been copied to your project yet.
+---
 
-Run `/init` to set up:
-- CLAUDE.md (entry point)
-- system/ (triggers, loops, gates)
-- instructions/ (workflow, rules, blueprint)
-- .claude/ (commands)
-- scripts/ (automation)
-- hooks/ (git hooks)
+### `on:init_needed`
 
-Or run `/init --all` to include .vscode and config templates.
-```
+**When:** autoworkflow is in node_modules but CLAUDE.md is missing
+**Hook:** `.claude/hooks/session-check.sh`
+**Trigger Condition:** `[ -d "node_modules/autoworkflow" ] && [ ! -f "CLAUDE.md" ]`
+
+**Actions:**
+1. Notify user that autoworkflow needs setup
+2. Suggest running `npx autoworkflow init`
 
 ---
 
 ### `on:blueprint_missing`
 
 **When:** BLUEPRINT.md does not exist at session start
+**Hook:** `.claude/hooks/session-check.sh` + `.claude/hooks/blueprint-generator.sh`
 **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.
+**IMPORTANT:** This trigger runs AUTOMATICALLY:
+- Do NOT ask "Should I run the audit?"
+- Do NOT wait for permission to start
+- Just notify and run immediately
+- Only ask permission when presenting results to SAVE
 
-**Action:**
+**Actions:**
 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)
+3. Scan: package.json, src/, pages/, components/, api/
+4. Generate BOTH AI_RULES.md updates AND BLUEPRINT.md
+5. Present proposed updates to user
+6. Ask approval to SAVE (not to start)
 
-```
-TRIGGER: blueprint_missing
-├── 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
-│   ├── ls src/components/ → Components
-│   ├── find src/api/ → API endpoints
-│   └── grep -r "fetch\|/api/" → Connections
-│
-├── Generate: AI_RULES.md updates (Tech Stack, File Structure)
-├── Generate: BLUEPRINT.md (Features, Routes, APIs)
-├── Present: both updates to user
-├── 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.
-
-Running project audit now...
-
-[scanning happens automatically]
-
----
-
-## 🔍 Audit Complete
-
-[present AI_RULES.md updates]
-[present BLUEPRINT.md content]
-
-**Should I save these files?** (yes/no/edit first)
+```bash
+# To run the blueprint generator:
+./.claude/hooks/blueprint-generator.sh
 ```
 
 ---
@@ -133,52 +111,87 @@ Running project audit now...
 ### `on:task_received`
 
 **When:** User provides a task or request
-**Action:**
-1. Route task through `system/router.md`
-2. Identify task type (feature, fix, refactor, etc.)
-3. Load appropriate workflow from `instructions/CLAUDE.md`
-4. Enter ANALYZE phase
-
-```
-TRIGGER: task_received
-├── Parse: user request
-├── Route: system/router.md → task_type
-├── Load: instructions/CLAUDE.md#workflow
-└── Enter: ANALYZE phase
-```
+**Hook:** `.claude/hooks/session-check.sh`
+**Function:** `classify_task()`
+
+**Classification Keywords:**
+
+| Task Type | Keywords |
+|-----------|----------|
+| query | what, how, why, explain, show me, find |
+| feature | add, create, implement, build, new |
+| fix | fix, bug, broken, error, issue, problem |
+| refactor | refactor, clean up, restructure, rename |
+| style | style, css, color, layout, design |
+| docs | document, readme, comment, jsdoc |
+| test | test, spec, coverage, unit test |
+| perf | performance, optimize, speed, slow |
+| security | security, vulnerability, auth |
+| config | config, setting, environment, setup |
+
+**Actions:**
+1. Parse user request
+2. Classify task type
+3. Save to `.claude/.autoworkflow/task-type`
+4. Set phase to ANALYZE
+5. Display workflow for task type
 
 ---
 
 ### `on:phase_transition`
 
 **When:** Moving from one workflow phase to another
-**Action:**
-1. Check `system/gates.md` for phase gate
-2. If gate passes → proceed to next phase
-3. If gate fails → BLOCK and report
+**Hook:** `.claude/hooks/phase-transition.sh`
+**Usage:** Manual invocation
 
-```
-TRIGGER: phase_transition(from, to)
-├── Check: system/gates.md#{to}_gate
-├── If PASS → Enter: {to} phase
-└── If FAIL → BLOCK: report gate failure
+**Commands:**
+```bash
+# Transition between phases (checks gates)
+./.claude/hooks/phase-transition.sh transition PLAN IMPLEMENT
+
+# Record plan approval
+./.claude/hooks/phase-transition.sh approve
+
+# Record plan rejection
+./.claude/hooks/phase-transition.sh reject
+
+# Reset workflow state
+./.claude/hooks/phase-transition.sh reset
+
+# Show current state
+./.claude/hooks/phase-transition.sh status
 ```
 
+**Gate Checks:**
+- `PLAN` → Checks analyze_gate
+- `IMPLEMENT` → Checks plan_approval_gate (BLOCKING)
+- `AUDIT` → Checks verify_gate
+- `COMMIT` → Checks verify_gate + audit_gate
+
 ---
 
 ### `on:implementation_complete`
 
 **When:** Claude finishes writing/modifying code
-**Action:**
+**Hook:** `.claude/hooks/post-edit.sh`
+**Event:** `PostToolUse` for `Write|Edit`
+
+**Actions:**
 1. Enter VERIFY phase automatically
-2. Start `verify_loop` from `system/loops.md`
-3. Report results
+2. Run `npm run verify` (or typecheck + lint)
+3. Track iteration count (max 10)
+4. If PASS → Reset counter, proceed to AUDIT or COMMIT
+5. If FAIL → Enter FIX phase, report errors
 
+**Output:**
 ```
-TRIGGER: implementation_complete
-├── Enter: VERIFY phase
-├── Start: system/loops.md#verify_loop
-└── Report: verification results
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AUTOWORKFLOW: VERIFY LOOP (Iteration 1/10)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Running: npm run verify
+
+✅ VERIFICATION PASSED
 ```
 
 ---
@@ -186,54 +199,60 @@ TRIGGER: implementation_complete
 ### `on:verification_failed`
 
 **When:** `npm run verify` returns errors
-**Action:**
-1. Parse error output
-2. Enter FIX phase
-3. Start `fix_loop` from `system/loops.md`
+**Hook:** `.claude/hooks/post-edit.sh`
+**Automatic:** Triggers when verification fails
 
-```
-TRIGGER: verification_failed
-├── Parse: error output
-├── Enter: FIX phase
-├── Start: system/loops.md#fix_loop
-└── Return to: VERIFY phase when fixed
-```
+**Actions:**
+1. Parse error output
+2. Increment iteration counter
+3. Set phase to FIX
+4. Report errors with file:line
+5. Wait for fixes, then re-verify on next edit
 
 ---
 
 ### `on:verification_passed`
 
 **When:** `npm run verify` returns success
-**Action:**
-1. Check if audits required (new feature/component)
-2. If yes → enter AUDIT phase
-3. If no → proceed to COMMIT gate
+**Hook:** `.claude/hooks/post-edit.sh`
+**Automatic:** Triggers when verification passes
 
-```
-TRIGGER: verification_passed
-├── Check: is_audit_required?
-├── If YES → Enter: AUDIT phase
-├── If NO → Check: system/gates.md#pre_commit_gate
-└── Report: ready status
-```
+**Actions:**
+1. Reset iteration counter
+2. Check if audits required (feature/refactor)
+3. If yes → Set phase to AUDIT
+4. If no → Set phase to PRE_COMMIT
 
 ---
 
 ### `on:commit_requested`
 
-**When:** User asks to commit or workflow reaches commit phase
-**Action:**
-1. Check `system/gates.md#pre_commit_gate`
-2. All gates must pass
-3. If blocked → report and await fix
-4. If passed → ask for commit confirmation
+**When:** User asks to commit or runs git commit
+**Hook:** `.claude/hooks/pre-tool-router.sh` → `.claude/hooks/pre-commit-check.sh`
+**Event:** `PreToolUse` for `Bash` (only git commit commands)
+
+**Gate Checks (all must pass):**
+1. TypeScript errors = 0
+2. ESLint warnings = 0
+3. No TODO/FIXME in staged files
+4. No console.log in staged files
+5. No orphan features (audit:ui)
+6. No circular dependencies (audit:cycles)
+7. Conventional commit format
+
+**On FAIL:** Exit with code 1 → BLOCKS the commit
 
 ```
-TRIGGER: commit_requested
-├── Check: system/gates.md#pre_commit_gate
-├── If BLOCKED → Report: blocking issues
-├── If PASSED → Show: commit preview
-└── Await: user confirmation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+AUTOWORKFLOW: PRE-COMMIT GATE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[1/7] TypeScript: ✅ PASS
+[2/7] ESLint: ✅ PASS
+[3/7] TODO/FIXME: ⛔ FAIL
+      └── Found in 2 file(s)
+
+⛔ GATE BLOCKED - 1 issue(s) must be fixed
 ```
 
 ---
@@ -241,76 +260,67 @@ TRIGGER: commit_requested
 ### `on:error_detected`
 
 **When:** Any error occurs during execution
-**Action:**
+**Handling:** Inline in post-edit.sh and pre-commit-check.sh
+
+**Actions:**
 1. Identify error type
 2. Route to appropriate fix strategy
 3. Enter FIX phase if code error
 4. Report if environmental error
 
-```
-TRIGGER: error_detected(error_type)
-├── Identify: error_type
-├── If code_error → Enter: FIX phase
-├── If env_error → Report: to user
-└── If unknown → Ask: user for guidance
-```
-
 ---
 
 ### `on:file_changed`
 
 **When:** Claude modifies a file
-**Action:**
+**Hook:** `.claude/hooks/post-edit.sh`
+**Tracking:** Files added to `.claude/.autoworkflow/changed-files`
+
+**Actions:**
 1. Mark file as changed
 2. Queue for verification
-3. If in IMPLEMENT phase → continue
-4. If outside phase → trigger verification
-
-```
-TRIGGER: file_changed(file_path)
-├── Track: changed_files.add(file_path)
-├── If IMPLEMENT phase → Continue
-├── If other phase → Queue: verification
-└── Update: state
-```
+3. Auto-trigger verify loop
 
 ---
 
 ### `on:user_approval`
 
 **When:** User approves a plan or action
-**Action:**
-1. Record approval
-2. Proceed to next phase
-3. If plan approval → enter IMPLEMENT
-4. If commit approval → execute commit
+**Hook:** `.claude/hooks/phase-transition.sh approve`
 
-```
-TRIGGER: user_approval(approval_type)
-├── Record: approval
-├── If plan_approval → Enter: IMPLEMENT phase
-├── If commit_approval → Execute: git commit
-└── Continue: workflow
-```
+**Detection Keywords:**
+- "yes" / "y" / "yeah" / "yep"
+- "proceed" / "go ahead" / "do it"
+- "approved" / "lgtm" / "looks good"
+- "all" / "include all" (for suggestions)
+
+**Actions:**
+1. Record approval to `.claude/.autoworkflow/plan-approved`
+2. Proceed to IMPLEMENT phase
 
 ---
 
 ### `on:user_rejection`
 
 **When:** User rejects a plan or action
-**Action:**
+**Hook:** `.claude/hooks/phase-transition.sh reject`
+
+**Actions:**
 1. Record rejection
 2. Ask for feedback
 3. Return to PLAN phase
-4. Revise based on feedback
 
-```
-TRIGGER: user_rejection
-├── Record: rejection
-├── Ask: "What should I change?"
-├── Return to: PLAN phase
-└── Incorporate: user feedback
-```
+---
+
+### `on:feature_complete`
+
+**When:** A new feature, route, or API is successfully committed
+**Handling:** Manual check after commit
+
+**Actions:**
+1. Check if BLUEPRINT.md needs updating
+2. Present proposed updates
+3. Update after approval
 
 ---
 
@@ -373,44 +383,42 @@ When multiple triggers could fire, use this priority:
 
 ---
 
-### `on:feature_complete`
-
-**When:** A new feature, route, or API is successfully committed
-**Action:**
-1. Check if BLUEPRINT.md needs updating
-2. Present proposed updates
-3. Update after approval
-
-```
-TRIGGER: feature_complete
-├── Check: was new feature/route/api added?
-├── If YES:
-│   ├── Generate: BLUEPRINT.md update
-│   ├── Present: proposed changes
-│   ├── Await: approval
-│   └── Update: BLUEPRINT.md
-└── If NO:
-    └── Skip: no update needed
-```
-
-**Update Triggers:**
-| Event | Action |
-|-------|--------|
-| New feature added | Add to Features section |
-| New route created | Add to Routes section |
-| New API endpoint | Add to API section |
-| Feature removed | Mark as deprecated or remove |
-
-**Output Format:**
-```
-## 📘 Blueprint Update
-
-Adding to BLUEPRINT.md:
-- Feature: [name] - [description]
-- Route: [path] → [Component]
-- API: [method] [endpoint]
-
-**Should I update BLUEPRINT.md?**
+## Hook Configuration
+
+All hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "./.claude/hooks/session-check.sh"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{
+          "type": "command",
+          "command": "./.claude/hooks/post-edit.sh"
+        }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "./.claude/hooks/pre-tool-router.sh \"$TOOL_INPUT\""
+        }]
+      }
+    ]
+  }
+}
 ```
 
 ---