autoworkflow 3.8.3 → 3.9.0

package/CLAUDE.md

@@ -30,7 +30,7 @@
 .claude/settings.json    →  HOOK CONFIG + SYSTEM INSTRUCTIONS
 .claude/.autoworkflow/   →  STATE FILES (phase, iterations, etc.)
 CLAUDE.md (this file)    →  WORKFLOW SUMMARY
-instructions/            →  AI_RULES.md + BLUEPRINT.md
+instructions/            →  AI_RULES.md + user's documentation
 system/                  →  DETAILED REFERENCE (gates, loops, triggers, router)
 ```
 
@@ -42,7 +42,7 @@ system/                  →  DETAILED REFERENCE (gates, loops, triggers, router
 
 | Event | Hook | Output to Claude |
 |-------|------|------------------|
-| User message | `session-check.sh` | "BLUEPRINT missing - run audit NOW" |
+| User message | `session-check.sh` | "Provide your project documentation" |
 | After Write/Edit | `post-edit.sh` | Runs `npm run verify`, shows errors |
 | Before git commit | `pre-tool-router.sh` | Runs all 7 gate checks, BLOCKS if fail |
 
@@ -58,14 +58,14 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 | Phase | What Claude Does |
 |-------|------------------|
-| ANALYZE | Read relevant files, check BLUEPRINT.md |
+| ANALYZE | Read relevant files, check user's documentation |
 | PLAN | Design approach, show suggestions |
 | CONFIRM | **Wait for user approval** |
 | IMPLEMENT | Make changes (after approval only) |
 | VERIFY | Run `npm run verify` - **AUTO-TRIGGERED** |
 | AUDIT | Run `npm run audit:ui` + `audit:cycles` |
 | COMMIT | Conventional commit format - **BLOCKED if checks fail** |
-| UPDATE | Update BLUEPRINT.md if new feature/route/API |
+| UPDATE | Note changes in session context |
 
 ---
 
@@ -124,6 +124,72 @@ All state stored in `.claude/.autoworkflow/`:
 
 ---
 
+## Memory System (Serena-inspired)
+
+Persistent context that survives across sessions. Stored in `.claude/.autoworkflow/memories/`.
+
+| File | Purpose |
+|------|---------|
+| `decisions.md` | Document architectural/implementation choices |
+| `patterns.md` | Record discovered codebase patterns |
+| `blockers.md` | Track known issues and workarounds |
+| `context.md` | Session continuity (auto-generated) |
+
+**Memory Commands:**
+```bash
+# Save a decision
+.claude/hooks/phase-transition.sh memory-save decisions "auth-approach" "Chose JWT over sessions for stateless API"
+
+# Read memories
+.claude/hooks/phase-transition.sh memory-read decisions
+
+# List all categories
+.claude/hooks/phase-transition.sh memory-list
+
+# Save context for next session
+.claude/hooks/phase-transition.sh context-save "Implementing user auth"
+
+# Load previous context
+.claude/hooks/phase-transition.sh context-load
+```
+
+---
+
+## Reflection Prompts (Serena-inspired)
+
+Before each phase transition, Claude receives reflection prompts to self-assess:
+
+| Phase | Reflection |
+|-------|------------|
+| PLAN | Have you read all relevant files? Understood existing patterns? |
+| IMPLEMENT | Does this match the request? Considered all affected files? |
+| VERIFY | Is implementation complete? Edge cases handled? |
+| COMMIT | Would you be confident shipping this? |
+
+**Manual reflection:**
+```bash
+.claude/hooks/phase-transition.sh reflect PLAN
+```
+
+---
+
+## Mode Restrictions (Serena-inspired)
+
+Task types have different allowed operations:
+
+| Mode | Restrictions |
+|------|--------------|
+| `docs` | Warn on non-.md file creation |
+| `fix` | Warn on new file creation, dependency changes |
+| `refactor` | Warn on behavior-changing operations (migrations) |
+| `query` | Warn on any modifications (read-only) |
+
+Phase restrictions:
+- `ANALYZE`/`PLAN` phases warn on file creation/dependency changes
+- Must reach `IMPLEMENT` phase before making modifications
+
+---
+
 ## Blocking Rules
 
 - **No orphan features** - Backend must have UI
@@ -142,7 +208,7 @@ All state stored in `.claude/.autoworkflow/`:
 | `/plan [task]` | Create implementation plan |
 | `/verify` | Run TypeScript + ESLint |
 | `/audit` | Run UI + cycle audits |
-| `/audit project` | Full project scan → generate BLUEPRINT.md |
+| `/audit project` | Full project scan → technical context |
 | `/commit [msg]` | Pre-commit gate + commit |
 | `/init` | Set up AutoWorkflow files |
 | `/fix` | Fix verification errors |
@@ -172,7 +238,51 @@ npm run format        # Prettier
 | `pre-commit-check.sh` | Before git commit | All 7 gate checks, BLOCKS |
 | `phase-transition.sh` | Manual call | State management |
 | `audit-runner.sh` | Manual call | Run UI + cycle audits |
-| `blueprint-generator.sh` | Manual call | Scan project |
+| `blueprint-generator.sh` | Manual call | Enhanced project discovery (8 scans) |
+
+---
+
+## Documentation Workflow
+
+Your project documentation is the single source of truth:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Session Start                                              │
+│       ↓                                                     │
+│  USER PROVIDES: PRD / Spec / Userflow / Implementation      │
+│       ↓                                                     │
+│  THAT DOCUMENT = SOURCE OF TRUTH                            │
+│       ↓                                                     │
+│  Referenced for ALL tasks                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**How it works:**
+1. Provide your documentation (PRD, spec, userflow, implementation guide)
+2. That document is used directly - no transformation or format conversion
+3. All tasks reference your document as the single source of truth
+
+**No BLUEPRINT.md generation.** Your document IS the blueprint.
+
+---
+
+## Project Discovery (Serena-inspired)
+
+`/audit project` runs 8 scans for technical context:
+
+| Scan | What It Detects |
+|------|-----------------|
+| Architecture | Monorepo, microservices, modular, feature-based, layered |
+| Essential Commands | npm scripts, Makefile targets, tool configs |
+| Tech Stack | Framework, styling, database, state, testing |
+| Structure | Source directories, organization |
+| Routes | App Router, Pages Router, SPA routes |
+| Components | React/Vue/Svelte components |
+| API | REST endpoints, GraphQL |
+| Environment | .env files, required variables, configs |
+
+**Note:** Scans provide technical context. BLUEPRINT.md content comes from your documentation.
 
 ---
 
@@ -181,9 +291,9 @@ npm run format        # Prettier
 | File | Purpose |
 |------|---------|
 | `instructions/AI_RULES.md` | Your coding standards |
-| `instructions/BLUEPRINT.md` | Project specification |
+| User's documentation | Single source of truth (PRD/spec/userflow) |
 
-If BLUEPRINT.md is missing → Hook triggers AUTO-AUDIT (no permission needed)
+If no documentation provided → Hook prompts user to provide it
 
 ---
 

package/README.md

@@ -2,7 +2,7 @@
 
 > Automated workflow enforcement for Claude Code via hooks and system prompts.
 
-**v3.8.0** - Smart CLI updates: version tracking + user file preservation.
+**v3.8.4** - Updated documentation + VS Code extension hook fix.
 
 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.
 
@@ -25,56 +25,27 @@ npx autoworkflow init
 | `npx autoworkflow update` | Smart update - core files only, preserve user files |
 | `npx autoworkflow status` | Show installed version and components |
 
-### Smart Updates (v3.8.0)
+### Smart Updates
 
-The CLI now tracks installed versions and preserves user customizations:
+The CLI 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
+npx autoworkflow update     # Update core files, preserve user files
 ```
 
 | File Category | On `init` | On `update` |
 |---------------|-----------|-------------|
 | **Core** (hooks, system, CLAUDE.md) | Installed | Updated |
-| **User** (BLUEPRINT.md, AI_RULES.md) | Created if missing | **Preserved** |
+| **User** (AI_RULES.md, your docs) | Created if missing | **Preserved** |
 | **Commands/Skills** | Installed | Updated |
 | **Optional** (.vscode, configs) | Only with `--all` | Skipped |
 
 ---
 
-## What's New in v3.7.0
+## Key Features
 
-### 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
-```
-
----
-
-## What's New in v3.6.0
-
-### Multi-Language Project Support
+### Multi-Language Verification
 Automatic verification for any project type:
 
 | Project Type | Detection | Verification |
@@ -85,51 +56,25 @@ Automatic verification for any project type:
 | Rust | `Cargo.toml` | cargo check + clippy |
 | Go | `go.mod` | go vet + golangci-lint |
 
-### One-Fix-At-A-Time Enforcement
-Claude MUST fix issues incrementally:
-- ❌ "I found 14 issues, fixing them all now..."
-- ✅ "I found 14 issues. Here are my suggestions. Which first?"
+### Fail-Closed Enforcement
+All gates are checked on every edit. Unknown state = strictest defaults:
 
-### 3-Tier Suggestions Gate
+| Gate | Blocks If | Applies To |
+|------|-----------|------------|
+| **Plan Approval** | User hasn't approved | feature, fix, refactor |
+| **Suggestions** | 3-tier suggestions not shown | feature tasks |
+| **One Edit/Turn** | Already edited this turn | strict task types |
+
+### 3-Tier Suggestions
 For feature tasks, Claude MUST show categorized suggestions:
 - 🔴 **Required** - Must implement
 - 🟡 **Recommended** - Should implement
 - 🟢 **Optional** - Nice to have
 
-Hook blocks implementation until suggestions are shown and user selects items.
-
----
-
-## What's New in v3.5.0
-
-### Hook-Based Enforcement (Not Just Instructions)
-
-| Hook | Event | Enforcement |
-|------|-------|-------------|
-| `pre-edit.sh` | PreToolUse (Write/Edit) | **BLOCKS** edits without plan approval |
-| `post-commit.sh` | PostToolUse (Bash) | Auto-triggers BLUEPRINT update reminder |
-| `session-check.sh` | UserPromptSubmit | Session resume with state display |
-
 ### 106 Skills Library
-Claude loads relevant skills for each command:
-- Security patterns, debugging techniques, code review checklists
-- Framework-specific knowledge (React, Next.js, etc.)
-- Auto-loaded via `skills_required` in command frontmatter
-
-### Agent-Structured Commands
-Each command has a role, output schema, and guardrails:
-```yaml
----
-role: Senior Code Reviewer
-skills_required:
-  - security.md
-  - code-review.md
-output_schema:
-  issues: [{severity, file, line, message}]
-guardrails:
-  - Prioritize security issues above all else
----
-```
+Auto-loaded knowledge for each command via `skills_required` in command frontmatter:
+- Security patterns, debugging, code review
+- Framework-specific (React, Next.js, Laravel, Django, etc.)
 
 ---
 
@@ -137,14 +82,20 @@ guardrails:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                    HOOKS (Automatic)                         │
+│                    HOOKS (10 Scripts)                        │
+│                                                              │
+│  UserPromptSubmit  →  session-check.sh                      │
+│                       (resume, turn reset, blueprint check) │
+│                                                              │
+│  PreToolUse        →  pre-edit.sh (Write/Edit)              │
+│                       (3 gates: approval, suggestions, 1/turn)│
+│                   →  pre-tool-router.sh (Bash)              │
+│                       → pre-commit-check.sh (7 gate checks) │
 │                                                              │
-│  UserPromptSubmit  →  session-check.sh (resume, turn reset) │
-│  PreToolUse        →  pre-edit.sh (3 gates: approval,       │
-│                       suggestions, one-fix-at-a-time)       │
-│  PreToolUse        →  pre-commit-check.sh (BLOCKS bad code) │
-│  PostToolUse       →  post-edit.sh (multi-lang verify)      │
-│  PostToolUse       →  post-commit.sh (BLUEPRINT reminder)   │
+│  PostToolUse       →  post-edit.sh (Write/Edit)             │
+│                       (multi-lang verification loop)        │
+│                   →  post-bash-router.sh (Bash)             │
+│                       → post-commit.sh (commit summary)     │
 │                                                              │
 │  Hooks ENFORCE workflow - they physically block actions     │
 └─────────────────────────────────────────────────────────────┘
@@ -177,53 +128,31 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 | Phase | What Happens | Enforcement |
 |-------|--------------|-------------|
-| ANALYZE | Read relevant files, check BLUEPRINT.md | - |
+| ANALYZE | Read relevant files, check user's documentation | - |
 | PLAN | Design approach, show 3-tier suggestions | - |
 | CONFIRM | Wait for user approval | **pre-edit.sh BLOCKS edits** |
 | IMPLEMENT | Make changes (after approval only) | Allowed after approval |
 | VERIFY | Run `npm run verify` (max 10 iterations) | Auto-triggered by hook |
 | AUDIT | Check orphan features + circular deps | Required for features |
 | COMMIT | Conventional commit format | **pre-commit.sh BLOCKS bad commits** |
-| UPDATE | Update BLUEPRINT.md if needed | **post-commit.sh reminder** |
+| UPDATE | Note changes in session context | **post-commit.sh reminder** |
 
 ---
 
-## Auto-Triggers (Hooks)
+## Auto-Triggers (10 Hooks)
 
 | Hook | Trigger | Action |
 |------|---------|--------|
-| `session-check.sh` | Every user message | Resume session, reset turn counter |
-| `pre-edit.sh` | Before Write/Edit | **BLOCK** if: no approval, no suggestions, or multiple fixes |
-| `post-edit.sh` | After Write/Edit | Detect project type, run verification |
-| `pre-commit-check.sh` | Before git commit | **BLOCK if TODO/console.log/errors** |
-| `post-commit.sh` | After git commit | Remind to update BLUEPRINT.md |
-
----
-
-## 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 |
-
-**Design:** All gates are checked on EVERY edit. Unknown state = strictest defaults.
-
----
-
-## 3-Tier Suggestions
-
-For feature tasks, Claude provides categorized suggestions:
-
-| Tier | Priority | Examples |
-|------|----------|----------|
-| 🔴 Required | Must implement | Error handling, loading states, validation |
-| 🟡 Recommended | Improves quality | Empty states, keyboard navigation |
-| 🟢 Optional | Nice to have | Unit tests, analytics, optimizations |
+| `session-check.sh` | UserPromptSubmit | Resume session, reset turn counter, check docs |
+| `pre-edit.sh` | PreToolUse (Write/Edit) | **BLOCK** if: no approval, no suggestions, or multiple fixes |
+| `post-edit.sh` | PostToolUse (Write/Edit) | Detect project type, run verification |
+| `pre-tool-router.sh` | PreToolUse (Bash) | Routes to pre-commit-check for git commits |
+| `post-bash-router.sh` | PostToolUse (Bash) | Routes to post-commit for git commits |
+| `pre-commit-check.sh` | Before git commit | **BLOCK** with 7 gate checks (TS, ESLint, TODO, etc.) |
+| `post-commit.sh` | After git commit | Commit summary |
+| `phase-transition.sh` | Manual/internal | State management between workflow phases |
+| `audit-runner.sh` | Manual/internal | Run UI enforcement + circular dep checks |
+| `blueprint-generator.sh` | Manual/internal | Scan project structure |
 
 ---
 
@@ -256,18 +185,23 @@ project/
 │
 ├── .claude/
 │   ├── settings.json         # Hooks + system prompt
-│   ├── hooks/                # Enforcement scripts
-│   │   ├── session-check.sh  # Resume + blueprint check
-│   │   ├── pre-edit.sh       # Plan approval gate
-│   │   ├── post-edit.sh      # Verification loop
-│   │   ├── pre-commit-check.sh
-│   │   └── post-commit.sh    # BLUEPRINT reminder
-│   ├── commands/             # Slash commands (with agent structure)
+│   ├── hooks/                # 10 enforcement scripts
+│   │   ├── session-check.sh      # Session init + docs check
+│   │   ├── pre-edit.sh           # Plan approval gate (3 checks)
+│   │   ├── post-edit.sh          # Auto-verification loop
+│   │   ├── pre-tool-router.sh    # Routes Bash commands
+│   │   ├── post-bash-router.sh   # Routes post-Bash actions
+│   │   ├── pre-commit-check.sh   # 7 gate checks before commit
+│   │   ├── post-commit.sh        # Commit summary
+│   │   ├── phase-transition.sh   # State management
+│   │   ├── audit-runner.sh       # UI + cycle audits
+│   │   └── blueprint-generator.sh # Scan project for technical context
+│   ├── commands/             # 9 slash commands
 │   └── skills/               # 106 knowledge files
 │
 ├── instructions/
 │   ├── AI_RULES.md           # Your coding standards
-│   └── BLUEPRINT.md          # Project spec (auto-generated)
+│   └── (user's documentation) # Single source of truth
 │
 ├── system/                   # Detailed reference
 │   ├── gates.md              # Blocking checkpoint definitions
@@ -306,7 +240,7 @@ npm run audit:all        # Run all audits
 | `/verify` | QA Engineer | Run verification loop |
 | `/fix` | Debug Engineer | Fix verification errors |
 | `/audit` | Code Reviewer | Security + quality audit |
-| `/audit project` | Code Reviewer | Full scan → generate BLUEPRINT.md |
+| `/audit project` | Code Reviewer | Full scan → technical context |
 | `/commit` | Git Specialist | Pre-commit check + commit |
 
 ---

package/bin/cli.js

@@ -402,10 +402,10 @@ function init(options = {}) {
                        currentContent.replace(/^#.*$/gm, '').replace(/\s+/g, ' ').trim().length < 200;
 
     if (isTemplate) {
-      // Remove template so hook can regenerate project-specific one
+      // Remove template - user will provide their own documentation
       try {
         unlinkSync(blueprintPath);
-        console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md template removed (will be auto-generated)`);
+        console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md template removed (provide your docs on first run)`);
       } catch (e) {
         // Ignore
       }
@@ -413,7 +413,7 @@ function init(options = {}) {
       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`);
+    console.log(`  ${colors.cyan('ℹ')} BLUEPRINT.md will be created from your documentation on first run`);
   }
 
   // Make Claude hooks executable
@@ -446,9 +446,9 @@ function init(options = {}) {
 
   console.log(`${colors.bold('Next steps:')}`);
   console.log(`  1. Open VS Code with Claude Code extension`);
-  console.log(`  2. Send any message - Claude will ${colors.cyan('auto-scan')} your project`);
-  console.log(`  3. Claude generates ${colors.cyan('BLUEPRINT.md')} with your features/routes/APIs`);
-  console.log(`  4. Review and approve the generated blueprint\n`);
+  console.log(`  2. Provide your documentation (PRD, spec, userflow)`);
+  console.log(`  3. Your document = ${colors.cyan('single source of truth')}`);
+  console.log(`  4. Claude references your docs for all tasks\n`);
 
   console.log(`${colors.dim('Optional: Edit instructions/AI_RULES.md to customize coding standards')}\n`);
 }

package/package.json

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