wogiflow 1.6.0 → 1.6.2

package/.claude/commands/wogi-audit.md

@@ -0,0 +1,359 @@
+Comprehensive project-wide deep analysis that goes far beyond code review. While `/wogi-review` asks "did I introduce problems?", `/wogi-audit` asks "how can we make this project better?"
+
+**Triggers**: `/wogi-audit`, "audit project", "project audit", "full project analysis", "full analysis"
+
+## Usage
+
+```bash
+/wogi-audit                    # Full 7-dimension audit
+/wogi-audit --skip-deps        # Skip dependency analysis
+/wogi-audit --skip-web         # Skip web searches (faster, offline)
+/wogi-audit --focus arch       # Focus on architecture only
+/wogi-audit --focus perf,debt  # Focus on specific dimensions
+```
+
+## Comparison
+
+| Dimension | /wogi-health | /wogi-review | /wogi-audit |
+|-----------|-------------|-------------|-------------|
+| Checks | WogiFlow files/config | Code quality in specific files | Entire project holistically |
+| Finds | Missing files, broken JSON | Bugs, security, standards violations | Architecture, opportunities, modernization |
+| Scope | WogiFlow infrastructure | Git diff (or NL-scoped files) | All project code |
+| When | After install/config changes | After coding, before commit | Periodically, or when onboarding |
+| Output | Health status (pass/fail) | Findings with fix recommendations | Strategic report with prioritized opportunities |
+
+## Architecture Note
+
+The audit system has **two layers**:
+1. **Runtime script** (`flow-audit.js`) — provides helper functions for file scanning, TODO finding, dependency checking, and score calculation.
+2. **AI instructions** (this document) — describe the 7-agent parallel analysis, scoring, and post-audit workflow. You (the AI) orchestrate the full audit.
+
+## How It Works
+
+### Step 1: Gather Project Files
+
+```bash
+node scripts/flow-audit.js files
+```
+
+This returns all tracked project files (excluding node_modules, dist, .workflow/state/, etc.). Use this as the base file set for all agents.
+
+### Step 2: Launch 7 Parallel Agents
+
+Launch ALL enabled agents as parallel `Task` calls in a single message. Each agent uses `subagent_type=Explore` and `model="sonnet"` (per decisions.md: use Sonnet for routine exploration).
+
+**Agent configuration** is in `config.audit.agents` — skip any agent set to `false`.
+
+---
+
+#### Agent 1: Architecture Analyzer
+
+```
+Analyze the architecture of this project.
+
+1. Read the project's main entry points and directory structure
+2. Check separation of concerns:
+   - Are controllers/routes separate from business logic?
+   - Are utilities separate from domain code?
+   - Is configuration separate from implementation?
+3. Find layer violations:
+   - UI code calling database directly
+   - Route handlers containing business logic (>50 LOC)
+   - Utility files importing domain-specific modules
+4. Find god files (files with >300 LOC or >10 exported functions)
+5. Check for circular dependencies between modules
+6. Identify missing abstractions (repeated patterns that could be extracted)
+
+Return a structured report with:
+- Strengths (good patterns found)
+- Opportunities (improvements), each tagged [HIGH/MED/LOW]
+- Score: A (excellent) through F (critical issues)
+```
+
+#### Agent 2: Dependency Auditor
+
+```
+Audit the project's dependencies.
+
+1. Read package.json for all dependencies and devDependencies
+2. Run: node scripts/flow-audit.js outdated
+   → This runs npm outdated and returns structured results
+3. Check for:
+   - Major version updates available (HIGH priority)
+   - Deprecated packages (check npm registry via web search if --skip-web not set)
+   - Lighter alternatives (e.g., moment.js → date-fns, lodash → native)
+   - Unused dependencies (in package.json but never imported)
+   - Missing peer dependencies
+4. Check for known security vulnerabilities:
+   - Run: node scripts/flow-audit.js audit
+   → This runs npm audit and returns structured results
+
+Return:
+- Dependencies summary (total, outdated, vulnerable)
+- Each finding tagged [HIGH/MED/LOW]
+- Score: A through F
+```
+
+#### Agent 3: Duplication & Consolidation Scanner
+
+```
+Scan for code duplication and consolidation opportunities.
+
+1. Read ALL registry maps:
+   - .workflow/state/app-map.md (components)
+   - .workflow/state/function-map.md (functions)
+   - .workflow/state/api-map.md (APIs)
+   - Any other *-map.md files in .workflow/state/
+2. Find similar entries that could be merged:
+   - Functions with similar names and purposes
+   - Components with overlapping functionality
+   - API endpoints that share 80%+ logic
+3. Search for copy-paste code patterns:
+   - Similar function bodies across different files
+   - Repeated error handling patterns (>3 occurrences)
+   - Utility functions that duplicate native language features
+4. Find consolidation opportunities:
+   - Similar utility functions in different directories
+   - Multiple implementations of the same pattern
+
+Return:
+- Duplication findings, each tagged [HIGH/MED/LOW]
+- Consolidation recommendations
+- Score: A through F
+```
+
+#### Agent 4: Performance & Optimization Analyzer
+
+```
+Analyze the project for performance issues and optimization opportunities.
+
+1. Search for common performance anti-patterns:
+   - Sequential awaits that could be Promise.all (look for: await X; await Y;)
+   - N+1 query patterns (loops containing DB/API calls)
+   - Large synchronous file operations in request handlers
+   - Missing caching on frequently-accessed data
+2. Check for bundle size concerns:
+   - Large library imports (lodash, moment, etc.)
+   - Importing entire libraries when only one function is needed
+3. Check for memory leak patterns:
+   - Event listeners not cleaned up
+   - Growing arrays/maps without bounds
+   - Closures holding references to large objects
+4. Framework-specific checks:
+   - React: unnecessary re-renders, missing useMemo/useCallback
+   - Express/Fastify: missing compression, no request timeouts
+   - Node.js: sync file operations in async contexts
+
+Return:
+- Performance findings, each tagged [HIGH/MED/LOW]
+- Score: A through F
+```
+
+#### Agent 5: Consistency & Patterns Auditor
+
+```
+Audit consistency of patterns across the project.
+
+1. Error handling consistency:
+   - How many different error handling patterns exist? (try/catch, .catch(), middleware, etc.)
+   - Are errors logged consistently?
+   - Is there a standard error format?
+2. Logging patterns:
+   - Mix of console.log and structured logging?
+   - Consistent log levels?
+3. Naming convention adherence:
+   - File naming: kebab-case throughout?
+   - Variable naming: camelCase consistently?
+   - Catch block variables: always 'err'?
+4. API response format consistency:
+   - Do all endpoints return the same shape ({ data } vs { result } vs raw)?
+   - Consistent HTTP status codes?
+5. Configuration patterns:
+   - Are config values accessed consistently?
+   - Any hardcoded values that should be configurable?
+
+Return:
+- Consistency findings, each tagged [HIGH/MED/LOW]
+- Dominant patterns vs outliers
+- Score: A through F
+```
+
+#### Agent 6: Modernization & Alternatives Scout
+
+```
+Scout for modernization opportunities in this project.
+
+1. Check for outdated patterns:
+   - var usage (should be const/let)
+   - Callback-based code (could be async/await)
+   - Manual null checks (could use optional chaining ?.)
+   - Verbose conditionals (could use nullish coalescing ??)
+2. Check framework best practices (if --skip-web not set):
+   - Web search for "[framework] best practices 2026"
+   - Compare current patterns against recommended approaches
+3. Check for newer library alternatives:
+   - Web search for lightweight alternatives to heavy dependencies
+4. Look for simplification opportunities:
+   - Complex logic that could use modern language features
+   - Manual implementations of things available in the standard library
+   - Overly defensive code that could trust framework guarantees
+
+Return:
+- Modernization opportunities, each tagged [HIGH/MED/LOW]
+- Score: A through F
+```
+
+#### Agent 7: Tech Debt Cataloger
+
+```
+Catalog technical debt in this project.
+
+1. Find all TODO, FIXME, HACK, WORKAROUND, TEMPORARY comments:
+   - Run: node scripts/flow-audit.js todos
+   → Returns structured list of all TODO/FIXME/HACK comments with file:line
+2. Find commented-out code blocks (>3 consecutive commented lines)
+3. Find functions with high complexity:
+   - Deep nesting (>4 levels)
+   - Many branches (>8 if/else chains)
+   - Long functions (>100 LOC)
+4. Find dead code:
+   - Unused exports (exported but never imported elsewhere)
+   - Unreachable branches
+5. Cross-reference with existing tech debt:
+   - Read .workflow/state/tech-debt.json if it exists
+   - Identify new debt vs already-tracked debt
+
+Return:
+- Tech debt items, each tagged [HIGH/MED/LOW]
+- Summary: TODOs count, FIXMEs count, HACKs count
+- Commented-out code blocks count
+- Score: A through F
+```
+
+### Step 3: Consolidate Results
+
+After all agents complete, consolidate into a single report.
+
+**Use `node scripts/flow-audit.js score` with the agent scores to calculate a weighted overall score.**
+
+### Step 4: Display Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+PROJECT AUDIT REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project: [name] | Files scanned: N | Date: YYYY-MM-DD
+
+HEALTH SCORE: [A/B/C/D/F] (weighted across all dimensions)
+
+━━━ ARCHITECTURE (score: X) ━━━
+  Strengths:
+  - [good patterns found]
+
+  Opportunities:
+  [HIGH] [description]
+  [MED]  [description]
+  [LOW]  [description]
+
+━━━ DEPENDENCIES (score: X) ━━━
+  [findings...]
+
+━━━ DUPLICATION (score: X) ━━━
+  [findings...]
+
+━━━ PERFORMANCE (score: X) ━━━
+  [findings...]
+
+━━━ CONSISTENCY (score: X) ━━━
+  [findings...]
+
+━━━ MODERNIZATION (score: X) ━━━
+  [findings...]
+
+━━━ TECH DEBT (score: X) ━━━
+  TODOs: N | FIXMEs: N | HACKs: N
+  [findings...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SUMMARY: N opportunities found
+  High: N | Medium: N | Low: N
+
+Top 5 Quick Wins (highest impact, lowest effort):
+  1. [description]
+  2. [description]
+  3. [description]
+  4. [description]
+  5. [description]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 5: Post-Audit Actions
+
+After displaying the report, offer these options using AskUserQuestion:
+
+1. **Create tasks** — Convert high-priority findings to stories/tasks in ready.json
+2. **Add to tech debt** — Add findings to `.workflow/state/tech-debt.json` via `/wogi-debt`
+3. **Save report** — Persist to `.workflow/audits/YYYY-MM-DD-audit.md`
+4. **Create rules** — Promote recurring patterns to decisions.md via `/wogi-decide`
+
+### Step 6: Persist Report
+
+Regardless of user choice, always save the audit results to `.workflow/state/last-audit.json`:
+
+```json
+{
+  "date": "YYYY-MM-DD",
+  "overallScore": "B+",
+  "scores": {
+    "architecture": "B+",
+    "dependencies": "A-",
+    "duplication": "C+",
+    "performance": "B",
+    "consistency": "B-",
+    "modernization": "B+",
+    "techDebt": "B"
+  },
+  "findings": {
+    "total": 45,
+    "high": 8,
+    "medium": 18,
+    "low": 19
+  },
+  "topFindings": [...]
+}
+```
+
+## Configuration
+
+Controlled by `config.audit`:
+
+```json
+{
+  "audit": {
+    "agents": {
+      "architecture": true,
+      "dependencies": true,
+      "duplication": true,
+      "performance": true,
+      "consistency": true,
+      "modernization": true,
+      "techDebt": true
+    },
+    "scoring": {
+      "enabled": true,
+      "weights": {
+        "architecture": 0.25,
+        "dependencies": 0.15,
+        "duplication": 0.15,
+        "performance": 0.15,
+        "consistency": 0.10,
+        "modernization": 0.10,
+        "techDebt": 0.10
+      }
+    },
+    "exclude": ["node_modules", ".workflow/state", "dist", "build"],
+    "maxFilesPerAgent": 100
+  }
+}
+```

package/.claude/commands/wogi-export.md

@@ -81,7 +81,7 @@ Run the export script directly:
 After installing WogiFlow, import a team profile:
 
 ```bash
-npm install wogiflow
+npm install -D wogiflow
 npx flow import-profile ~/my-team.zip
 ```
 

package/.claude/commands/wogi-onboard.md

@@ -691,6 +691,36 @@ Display:
 
 ---
 
+### Phase 6.5: Generate CLAUDE.md (CRITICAL)
+
+**Now that config.json exists, generate the full CLAUDE.md from templates.**
+
+This replaces the bootstrap CLAUDE.md (created by postinstall) with the complete version rendered from Handlebars templates using the project's actual config values.
+
+```bash
+npx flow bridge sync
+```
+
+This runs the bridge which:
+1. Reads `.workflow/config.json` (just created in Phase 6)
+2. Renders `.workflow/templates/claude-md.hbs` with config values
+3. Writes the full `CLAUDE.md` with all enforcement rules, file locations, and commands
+
+Display:
+```
+  CLAUDE.md...           ✓ Generated from templates (full version)
+```
+
+**If bridge sync fails:**
+- Log warning: `⚠️ CLAUDE.md generation failed: [error]. Bootstrap version remains.`
+- The bootstrap CLAUDE.md from postinstall still provides basic task gating
+- User can manually run `npx flow bridge sync` later
+
+**Why this step matters:**
+Without it, the user completes onboarding but CLAUDE.md is either missing or still the bootstrap version. The full CLAUDE.md contains file locations, quality gate configs, commit behavior rules, and natural language command detection — all essential for the full WogiFlow experience.
+
+---
+
 ### Phase 7: Summary
 
 Display:
@@ -719,6 +749,8 @@ Template extraction...   ✓ Found 4 templates (component, service, test, hook)
 
 ━━━ Generated Files ━━━
 
+CLAUDE.md                    # Full project instructions (from templates)
+
 .workflow/
   config.json              # Project configuration
   context/
@@ -778,6 +810,7 @@ You can:
 
 | File | Purpose |
 |------|---------|
+| `CLAUDE.md` | Full project instructions for Claude Code (generated from templates) |
 | `.workflow/config.json` | Project configuration (quality gates, temporal thresholds) |
 | `.workflow/context/stack.md` | Detected tech stack |
 | `.workflow/context/product.md` | Product description and features |

package/.claude/commands/wogi-review.md

@@ -87,6 +87,70 @@ The review system has **two layers**:
 
 **The runtime script does NOT execute all 5 phases.** It handles pre-flight only. You (the AI) are responsible for orchestrating the complete review.
 
+## Step 0: Scope Resolution (Natural Language Scoping)
+
+**Before Phase 1, resolve what files to review.** When the user provides a description instead of (or in addition to) flags, the AI interprets it and resolves a file list.
+
+**Default behavior (no args)**: Standard git diff — unchanged from previous behavior. Skip this step.
+
+**When args are provided**, interpret the natural language and resolve scope:
+
+```
+Step 0: Scope Resolution
+  ├── No args (just /wogi-review)? → Default git diff, skip this step
+  ├── Has --commits, --staged flags? → Use those flags directly, skip NL
+  └── Has natural language args? → AI interprets:
+        ├── Session-based ("last 3 sessions", "since yesterday's session")
+        │     → Use getSessionBoundaryCommits(n) from flow-review.js
+        │     → git diff between session boundary commits
+        ├── Feature-based ("auth feature", "payment flow")
+        │     → Grep codebase for related files
+        │     → Check app-map.md, function-map.md for feature groupings
+        │     → Read request-log.md for tagged entries (#screen:X, #component:Y)
+        ├── Branch-based ("this branch", "feature/xyz", "everything on this branch")
+        │     → Use getBranchFiles() from flow-review.js
+        │     → git diff main...HEAD (or specified branch)
+        ├── Time-based ("last week", "since Monday", "past 2 days")
+        │     → Use getFilesSinceDate() from flow-review.js
+        │     → git log --since to find commit range
+        ├── Path-based ("the API layer", "all services", "just the hooks")
+        │     → Glob for matching file patterns (e.g., scripts/hooks/**)
+        └── Full project ("everything", "the whole project", "all files")
+              → Use getAllProjectFiles() from flow-review.js
+              → Auto-enable multi-pass mode for large file sets
+```
+
+**After resolving scope, display it before proceeding:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SCOPE RESOLUTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Request: "check the last 3 sessions"
+Resolved: 23 files from last 3 sessions (commits abc1234..xyz5678)
+
+Files:
+  scripts/flow-review.js
+  scripts/hooks/core/routing-gate.js
+  ... (list first 10, summarize rest)
+
+Mode: multi-pass (auto-enabled: 23 files)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Helper functions available** (exported from `scripts/flow-review.js`):
+- `getSessionBoundaryCommits(n)` — finds last N "End session" commits
+- `getFilesBetweenCommits(fromSha, toSha)` — git diff between two commits
+- `getFilesSinceDate(dateStr)` — git log --since to find commit range
+- `getBranchFiles(baseBranch)` — git diff against merge-base
+- `getAllProjectFiles()` — all tracked files excluding node_modules, dist, etc.
+
+**When scope resolves to 20+ files**: Auto-suggest multi-pass mode.
+**When scope is "full project"**: Cap to relevant code files, always use multi-pass.
+
+The resolved file list replaces the default git diff in Phase 1. All subsequent phases operate on the resolved scope.
+
+---
+
 ## How It Works (MANDATORY 5-PHASE SEQUENTIAL EXECUTION)
 
 **CRITICAL: You MUST execute ALL 5 phases sequentially. Do NOT stop after Phase 2.**

package/.claude/docs/commands.md

@@ -169,7 +169,7 @@ When user types these commands, execute the corresponding action immediately.
 
 ```bash
 # Setup
-npm install wogiflow              # Install WogiFlow in your project
+npm install -D wogiflow            # Install WogiFlow as dev dependency
 npx flow onboard                  # Analyze existing project & set up context
 
 # Task Management

package/.claude/docs/knowledge-base/01-setup-onboarding/README.md

@@ -21,7 +21,9 @@ The setup and onboarding process gathers this context automatically and stores i
 ### Install
 
 ```bash
-npm install wogiflow
+npm install -D wogiflow
+# or
+bun add -d --trust wogiflow   # --trust is required for bun to run postinstall
 ```
 
 The postinstall script automatically creates the `.workflow/` directory structure.
@@ -150,7 +152,7 @@ This analyzes your codebase and populates:
 
 | Command | Purpose |
 |---------|---------|
-| `npm install wogiflow` | Install WogiFlow and create .workflow structure |
+| `npm install -D wogiflow` (or `bun add -d --trust wogiflow`) | Install WogiFlow and create .workflow structure |
 | `npx flow onboard` | Analyze existing project |
 | `/wogi-map-index` | Show/regenerate component index |
 | `/wogi-map-scan` | Scan for unmapped components |

package/.claude/docs/knowledge-base/01-setup-onboarding/installation.md

@@ -7,13 +7,29 @@ Set up WogiFlow for your project.
 ## Quick Install
 
 ```bash
-npm install wogiflow
+npm install -D wogiflow
+# or
+bun add -d --trust wogiflow
 ```
 
 This automatically:
 1. Creates the `.workflow/` directory structure
 2. Copies template files to `.workflow/state/`
-3. Sets up necessary subdirectories
+3. Generates a bootstrap `CLAUDE.md` for immediate use
+4. Sets up necessary subdirectories
+
+### Bun Users
+
+Bun does not run lifecycle scripts (postinstall) from third-party packages by default — this is a security measure. The `--trust` flag is **required** for WogiFlow to set up properly.
+
+Without `--trust`, the postinstall script never runs, so no `.workflow/` directory, no `.claude/commands/`, no scripts — nothing gets set up.
+
+To persist trust so future updates also run lifecycle scripts, add to `bunfig.toml`:
+
+```toml
+[install]
+trustedDependencies = ["wogiflow"]
+```
 
 ---
 
@@ -96,6 +112,8 @@ Or in Claude:
 
 ```bash
 npm update wogiflow
+# or
+bun update wogiflow   # requires trustedDependencies in bunfig.toml (see above)
 ```
 
 ---
@@ -117,6 +135,24 @@ The installer creates a balanced config:
 
 ## Troubleshooting
 
+### Bun: Nothing Got Set Up
+
+If `.workflow/` and `.claude/` directories don't exist after install, you likely forgot `--trust`:
+
+```bash
+# Remove and reinstall with --trust
+bun remove wogiflow
+bun add -d --trust wogiflow
+```
+
+Or add to `bunfig.toml` for persistent trust:
+```toml
+[install]
+trustedDependencies = ["wogiflow"]
+```
+
+Then reinstall: `bun install`
+
 ### Permission Denied
 
 ```bash
@@ -125,9 +161,10 @@ chmod +x ./node_modules/wogiflow/scripts/flow*
 
 ### Missing Dependencies
 
-Ensure Node.js 18+ is installed:
+Ensure Node.js 18+ or Bun 1.0+ is installed:
 ```bash
 node --version  # Should be 18+
+bun --version   # Should be 1.0+
 ```
 
 ### Config Validation Errors

package/.claude/docs/knowledge-base/README.md

@@ -21,7 +21,9 @@ Welcome to the comprehensive knowledge base for WogiFlow, an AI workflow framewo
 
 ### Install
 ```bash
-npm install wogiflow
+npm install -D wogiflow
+# or
+bun add -d --trust wogiflow   # --trust is required for bun to run postinstall
 ```
 
 ### Analyze Existing Project

package/.claude/settings.json

@@ -104,4 +104,4 @@
   "_wogiFlowManaged": true,
   "_wogiFlowVersion": "1.5.9",
   "_comment": "Shared WogiFlow hook configuration. Committed to repo for team use. User-specific overrides go in settings.local.json."
-}
+}

package/.workflow/templates/claude-md.hbs

@@ -34,9 +34,11 @@ Check `.workflow/state/ready.json` for existing tasks.
 
 ---
 
-## Post-Compaction Routing (CRITICAL)
+## Post-Compaction / Session Continuation Routing (CRITICAL)
 
-**After context compaction or conversation resumption, the routing requirement is NOT relaxed.**
+**After context compaction, conversation resumption, or session continuation, the routing requirement is NOT relaxed.**
+
+**"Continue with the last task" is NOT permission to skip routing.** This is the #1 bypass pattern — the AI rationalizes that "continuing" prior work grants implicit permission to skip `/wogi-start`. It then goes into autopilot, directly editing ready.json to create fake tasks and coding without routing. This produces untracked, inconsistent work.
 
 When you resume from a compacted/summarized conversation:
 1. You may have compressed context from prior work — that is fine
@@ -44,10 +46,12 @@ When you resume from a compacted/summarized conversation:
 3. Do NOT answer from compacted memory without routing first
 4. Do NOT assume "I already know the answer" justifies skipping routing
 5. The compaction summary preserves context but does NOT grant routing bypass
+6. Do NOT edit `ready.json` or any `.workflow/state/` file to create tasks manually — that is a routing bypass
+7. "Continue where we left off" still requires `/wogi-start` — invoke it with the task ID
 
-**Why this matters**: After compaction, CLAUDE.md rules may be compressed. The AI may "feel" confident answering directly because it has context from the summary. This is the exact scenario that causes routing bypass. The routing hooks (UserPromptSubmit, PreToolUse, Stop) enforce this mechanically, but this instruction ensures you comply proactively.
+**Why this matters**: After compaction, CLAUDE.md rules may be compressed. The AI may "feel" confident answering directly because it has context from the summary. This is the exact scenario that causes routing bypass. The routing hooks enforce this mechanically — Edit, Write, Read, Glob, Grep, Bash, and EnterPlanMode are ALL blocked until routing completes.
 
-**If you catch yourself about to respond without routing**: STOP. Invoke the Skill tool with skill="wogi-start" first. The Stop hook will block you from completing a response that bypassed routing.
+**If you catch yourself about to respond without routing**: STOP. Invoke the Skill tool with skill="wogi-start" first. The PreToolUse hook will block ANY tool call (including Edit/Write) before routing.
 
 {{/if}}
 
@@ -75,7 +79,7 @@ When unsure, ASK the user rather than deviate from source patterns.
 ## Quick Start
 
 ```bash
-npm install wogiflow && npx flow onboard
+npm install -D wogiflow && npx flow onboard
 ```
 
 ## Core Principles
@@ -115,6 +119,7 @@ npm install wogiflow && npx flow onboard
 | `/wogi-health` | Check workflow health |
 | `/wogi-roadmap` | View/manage deferred work |
 | `/wogi-suggest "text"` | Submit suggestion for WogiFlow |
+| `/wogi-audit` | Comprehensive project-wide analysis (7 dimensions) |
 
 See `.claude/docs/commands.md` for complete command reference.
 
@@ -141,6 +146,7 @@ See `.claude/docs/commands.md` for complete command reference.
 | "finalize branch", "merge to master", "create a PR", "discard this branch", "what to do with this branch" | `/wogi-finalize` |
 | "rescan project", "re-evaluate project", "project changed", "others made changes", "sync wogi", "things changed", "out of sync" | `/wogi-rescan` |
 | "suggest improvement", "feature request for wogi", "wogi suggestion", "submit feedback" | `/wogi-suggest` |
+| "audit project", "project audit", "full project analysis", "full analysis" | `/wogi-audit` |
 
 **IMPORTANT**: When a user's message matches one of these patterns, immediately invoke the Skill tool with the corresponding command. Do not ask for confirmation. These `/wogi-*` commands satisfy the mandatory routing requirement — you do NOT also need to invoke `/wogi-start` when a detection match exists. `/wogi-start` is the fallback for messages that don't match this table.
 

package/.workflow/templates/partials/user-commands.hbs

@@ -14,5 +14,6 @@
 | Learn from patterns | "let's learn from this" or "promote pattern" |
 | Session retro | "retro" or "what went well" |
 | Rescan project | "rescan project" or "things changed" or "out of sync" |
+| Project audit | "audit project" or "full analysis" |
 
 `/wogi-start` is the universal fallback router — it classifies any request and routes to the right action. Detailed per-command docs live in each skill's `.md` file under `.claude/commands/`.