autoworkflow 3.8.4 → 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

@@ -31,13 +31,13 @@ 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 |
 
@@ -95,7 +95,7 @@ Auto-loaded knowledge for each command via `skills_required` in command frontmat
 │  PostToolUse       →  post-edit.sh (Write/Edit)             │
 │                       (multi-lang verification loop)        │
 │                   →  post-bash-router.sh (Bash)             │
-│                       → post-commit.sh (BLUEPRINT reminder) │
+│                       → post-commit.sh (commit summary)     │
 │                                                              │
 │  Hooks ENFORCE workflow - they physically block actions     │
 └─────────────────────────────────────────────────────────────┘
@@ -128,14 +128,14 @@ 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** |
 
 ---
 
@@ -143,16 +143,16 @@ ANALYZE → PLAN → CONFIRM → IMPLEMENT → VERIFY → AUDIT → COMMIT → U
 
 | Hook | Trigger | Action |
 |------|---------|--------|
-| `session-check.sh` | UserPromptSubmit | Resume session, reset turn counter, check blueprint |
+| `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 | Remind to update BLUEPRINT.md |
+| `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 | Auto-scan project structure |
+| `blueprint-generator.sh` | Manual/internal | Scan project structure |
 
 ---
 
@@ -186,22 +186,22 @@ project/
 ├── .claude/
 │   ├── settings.json         # Hooks + system prompt
 │   ├── hooks/                # 10 enforcement scripts
-│   │   ├── session-check.sh      # Session init + blueprint check
+│   │   ├── 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        # BLUEPRINT update reminder
+│   │   ├── post-commit.sh        # Commit summary
 │   │   ├── phase-transition.sh   # State management
 │   │   ├── audit-runner.sh       # UI + cycle audits
-│   │   └── blueprint-generator.sh # Auto-scan project
+│   │   └── 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
@@ -240,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.4",
+  "version": "3.9.0",
   "description": "Automated workflow enforcement for Claude Code via hooks and system prompts",
   "type": "module",
   "bin": {