wogiflow 1.4.2 → 1.4.4

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

@@ -1053,6 +1053,27 @@ if (fs.existsSync(pendingPath)) {
 }
 ```
 
+#### 4.6 Register Hooks with Claude Code (CRITICAL)
+
+**Run `flow hooks setup` to ensure hooks are registered with Claude Code.**
+
+The postinstall script copies `.claude/settings.json` which contains hook definitions,
+but this step regenerates `settings.local.json` with absolute paths as a safety net.
+
+```bash
+./scripts/flow hooks setup 2>&1
+```
+
+If this fails, hooks may not fire. Display a warning:
+```
+⚠️ Hook setup failed. Hooks may not work.
+   Run manually: ./scripts/flow hooks setup
+```
+
+**Why this matters**: Without hooks registered in `.claude/settings.json` or
+`.claude/settings.local.json`, Claude Code doesn't know WogiFlow's hook scripts
+exist. Task gating, scope validation, and loop enforcement all depend on hooks.
+
 ### Step 5: Summary & Learning Explanation
 
 Display the completion summary:

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

@@ -192,7 +192,9 @@ This command implements a **structured execution loop**:
 │  │     → Agent 1: Codebase Analyzer (Glob/Grep/Read) │  │
 │  │     → Agent 2: Best Practices (WebSearch)          │  │
 │  │     → Agent 3: Version Verifier (Read/WebSearch)   │  │
-│  │     → All 3 run in parallel as Task agents         │  │
+│  │     → Agent 4: Risk & History (local reads)        │  │
+│  │     → Agent 5: Standards Preview (local reads)     │  │
+│  │     → All 5 run in parallel as Task agents         │  │
 │  │     → Consolidated research summary displayed      │  │
 │  └───────────────────────────────────────────────────┘  │
 │  1.5 SPEC PHASE: Generate specification                 │
@@ -398,8 +400,8 @@ This step invests more tokens up front to get things right. Three specialized ag
 **Research Cache**: Before launching agents, check `.workflow/state/research-cache.json` for cached results from recent identical queries (TTL: 24 hours). If a cache hit exists and is still valid, use the cached result instead of re-running the research. Cache misses trigger fresh research which is then cached for future use.
 
 **Research Depth** (controlled by `config.planMode.researchDepth`):
-- `"thorough"` (default): All 3 agents run in parallel
-- `"standard"`: Codebase Analyzer + quick best practices search
+- `"thorough"` (default): All 5 agents run in parallel
+- `"standard"`: Codebase Analyzer + Best Practices + Risk & History (3 agents, no web for version/standards)
 - `"minimal"`: Codebase Analyzer only (legacy behavior)
 
 **Skip conditions**: L3 (Subtask/trivial) tasks always skip this phase.
@@ -472,15 +474,88 @@ Return:
 - Version-specific considerations
 ```
 
+#### Agent 4: Risk & History Analyzer
+
+Launch as `Task` with `subagent_type=Explore` (local only, no web searches):
+
+```
+Analyze risk and history for task: "[TASK_TITLE]"
+Task type: [TASK_TYPE]
+Planned files: [FILES_TO_CHANGE]
+
+1. Read .workflow/state/feedback-patterns.md
+   - Search for entries matching this task type (feature, bugfix, refactor, etc.)
+   - Search for entries matching the planned file extensions (.js, .ts, .tsx, etc.)
+   - Extract the top 5 most relevant patterns with their occurrence counts
+2. Search .workflow/corrections/ directory for correction reports
+   - Use Glob to find *.md files in corrections/
+   - Read any that relate to the same feature area or file paths
+   - Extract lessons learned
+3. Search .workflow/state/decisions.md for rules tagged with the task type
+   - Focus on rules that were promoted from repeated violations (count >= 3)
+   - Extract the specific verification steps required
+4. If a memory database exists (.workflow/memory/local.db or via MCP):
+   - Query for rejected approaches from past tasks touching the same files
+   - Query for observations tagged with the planned file paths
+   - Surface any "approach X was tried and failed" warnings
+
+Return a structured summary:
+- Known risks for this task type (from feedback-patterns)
+- Past corrections in this area (from corrections/)
+- Promoted rules that apply (from decisions.md, count >= 3)
+- Rejected approaches from similar past work (from memory-db)
+- Confidence: HIGH (many data points) / MEDIUM / LOW (no history)
+```
+
+#### Agent 5: Standards Preview
+
+Launch as `Task` with `subagent_type=Explore` (local only, no web searches):
+
+```
+Preview applicable standards for task: "[TASK_TITLE]"
+Task type: [TASK_TYPE]
+Planned files: [FILES_TO_CHANGE]
+
+1. Determine which standard checks apply based on planned file paths:
+   - If files include components (.tsx, .jsx) → check: naming, components, security
+   - If files include utilities (utils/, helpers/) → check: naming, functions, security
+   - If files include API routes (api/, routes/) → check: naming, api, security
+   - If task type is "bugfix" → check: naming, security (minimal)
+   - If task type is "feature" or "refactor" → check: all
+2. Read .claude/rules/code-style/naming-conventions.md
+   - Extract rules that apply to the planned file types
+3. Read .claude/rules/security/security-patterns.md
+   - Extract security patterns relevant to the planned operations
+4. Read .workflow/state/app-map.md
+   - For each planned NEW component, check similarity against existing entries
+   - Flag any where name or purpose overlaps > 80% with an existing component
+   - This is the SAME check that flow-standards-gate.js will run post-implementation
+5. Read .workflow/state/decisions.md
+   - Extract coding rules that will be enforced for this task type
+
+Return a structured checklist:
+- Task type classification: [type]
+- Standards that WILL be enforced (these will block completion if violated):
+  * [rule name]: [what it checks] - [how to comply]
+  * [rule name]: [what it checks] - [how to comply]
+- Component duplication warnings (if any new components planned):
+  * "[PlannedName]" is similar to existing "[ExistingName]" in app-map
+  * Recommendation: extend existing / create new
+- Security patterns that apply:
+  * [pattern]: [when it triggers] - [correct approach]
+```
+
 #### Launching the Agents
 
-**All 3 agents are launched as parallel `Task` calls in a single message** (established pattern from `/wogi-review`):
+**All 5 agents are launched as parallel `Task` calls in a single message** (established pattern from `/wogi-review`):
 
 ```javascript
-// Launch all 3 in parallel (single message, 3 Task tool calls)
+// Launch all 5 in parallel (single message, 5 Task tool calls)
 Task(subagent_type=Explore, prompt="Codebase Analyzer: ...")
 Task(subagent_type=Explore, prompt="Best Practices: ...")
 Task(subagent_type=Explore, prompt="Version Verifier: ...")
+Task(subagent_type=Explore, prompt="Risk & History Analyzer: ...")
+Task(subagent_type=Explore, prompt="Standards Preview: ...")
 ```
 
 **After all agents complete**, display a consolidated research summary:
@@ -519,6 +594,24 @@ Task(subagent_type=Explore, prompt="Version Verifier: ...")
    - [package]@[version]: APIs confirmed compatible
    - [package]@[version]: ⚠️ [deprecated API] - use [alternative]
 
+⚠️ Risk & History:
+   Confidence: [HIGH/MEDIUM/LOW]
+   Known Risks:
+   - [pattern name] (occurred N times): [description]
+   Past Corrections:
+   - [correction]: [lesson learned]
+   Rejected Approaches:
+   - [approach]: tried in [task], failed because [reason]
+
+📋 Standards Preview:
+   Task type: [type] → Checks: [list]
+   Rules to follow:
+   - [rule]: [how to comply]
+   Component Duplication:
+   - ⚠️ "[PlannedName]" similar to "[ExistingName]" → extend existing
+   Security Patterns:
+   - [pattern]: [correct approach]
+
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -541,13 +634,16 @@ If user chooses "Deepen":
 
 #### Graceful Fallback
 
-If web search fails for any agent (network issues, rate limits, timeouts):
-- Log a warning: `⚠️ Web research unavailable for [Agent Name]. Proceeding with codebase analysis only.`
-- The Codebase Analyzer always runs locally and never fails due to network issues
-- If Best Practices agent fails: proceed without best practices (codebase + version verifier only)
-- If Version Verifier agent fails: proceed using local package.json versions only (no web validation)
-- If ALL web-based agents fail: proceed with codebase analysis only, equivalent to `researchDepth: "minimal"`
-- Task proceeds normally without blocking — web research is always best-effort
+If any agent fails (network issues, rate limits, timeouts, missing files):
+- Log a warning: `⚠️ Research unavailable for [Agent Name]. Proceeding with remaining agents.`
+- Agents 1, 4, 5 are **local-only** and should almost never fail (no network dependency)
+- Agents 2, 3 use **web search** and may fail due to network issues
+- If Best Practices agent fails: proceed without best practices
+- If Version Verifier agent fails: proceed using local package.json versions only
+- If Risk & History agent fails: proceed without history (no feedback-patterns data)
+- If Standards Preview agent fails: standards will still be enforced post-implementation (Step 3.7)
+- If ALL agents fail: proceed with codebase analysis only, equivalent to `researchDepth: "minimal"`
+- Task proceeds normally without blocking — research is always best-effort
 
 **IMPORTANT CONSTRAINTS:**
 - **READ-ONLY**: Do NOT use Edit, Write, or NotebookEdit during this phase
@@ -562,7 +658,9 @@ If web search fails for any agent (network issues, rate limits, timeouts):
     "researchAgents": {
       "codebaseAnalyzer": { "enabled": true },
       "bestPractices": { "enabled": true, "maxWebSearches": 3 },
-      "versionVerifier": { "enabled": true }
+      "versionVerifier": { "enabled": true },
+      "riskHistory": { "enabled": true },
+      "standardsPreview": { "enabled": true }
     },
     "researchDepth": "thorough",
     "deepenPromptThreshold": "L1"

package/.claude/docs/claude-code-compatibility.md

@@ -64,6 +64,7 @@ flow parallel check  # See available parallel tasks
 | 1.0.46+ | 2.1.20+ | Task deletion, improved compaction |
 | 1.2.0+ | 2.1.33+ | TaskCompleted, TeammateIdle hooks, agent frontmatter |
 | 1.3.0+ | 2.1.33+ | WebMCP integration, model registry (Opus 4.6/Sonnet 4.6) |
+| 1.5.0+ | latest | ConfigChange hook, native worktree awareness, settings.json plugin, Sonnet 4.6 1M context |
 
 ### Environment Variables (2.1.19+)
 
@@ -158,6 +159,40 @@ await cancelTask('wf-123', 'superseded', false);
 | SessionEnd | session-end.js | Request logging, progress update |
 | TaskCompleted | task-completed.js | Move task to recentlyCompleted |
 | TeammateIdle | teammate-idle.js | Suggest next task (disabled by default) |
+| ConfigChange | config-change.js | Re-sync bridge on mid-session config changes |
+
+### Features in Latest Release
+
+- **ConfigChange hook event**: New hook event fired when configuration files change during a session. WogiFlow uses this to automatically re-sync the bridge (regenerate CLAUDE.md) when `.workflow/config.json` is modified mid-session. Always non-blocking.
+- **Sonnet 4.6 with 1M context**: Sonnet 4.5 with 1M context has been removed from the Max plan in favor of Sonnet 4.6, which now has 1M context. WogiFlow's model registry updated with `contextWindowBeta: 1000000` for Sonnet 4.6.
+- **Native `--worktree` flag**: Claude Code now supports `--worktree` (`-w`) to start sessions in an isolated git worktree (under `.claude/worktrees/`). WogiFlow's `createWorktree()` detects this and skips nested worktree creation.
+- **Plugin `settings.json`**: Plugins can now ship `settings.json` for default configuration. WogiFlow now generates `.claude/settings.json` (committed, shared) with hook registrations using relative paths, while `.claude/settings.local.json` (gitignored) holds user-specific permissions.
+- **Managed settings hierarchy**: `disableAllHooks` now respects managed settings hierarchy - non-managed settings cannot disable managed hooks set by policy. WogiFlow hooks in `settings.json` (shared) are protected from user disabling via this mechanism.
+- **Background agent improvements**: Ctrl+F kills background agents (two-press confirmation). Ctrl+C/ESC no longer silently ignored when background agents are running.
+- **MCP startup performance**: Auth failure caching and batched tool token counting improve startup when WogiFlow's MCP servers are configured.
+
+### Simple Mode Naming Distinction
+
+Claude Code's `CLAUDE_CODE_SIMPLE` environment variable (which enables a simplified tool set) is **unrelated** to WogiFlow's `loops.simpleMode` (a lightweight task completion loop using string detection). They are separate features that happen to share the word "simple":
+
+| Feature | Scope | Purpose |
+|---------|-------|---------|
+| `CLAUDE_CODE_SIMPLE` | Claude Code | Restricts available tools to Bash + Edit |
+| `loops.simpleMode` | WogiFlow | Completion-promise loop using `TASK_COMPLETE` string |
+
+Both can be active simultaneously without conflict.
+
+### Native Worktree vs WogiFlow Worktree
+
+| Feature | Claude Code `--worktree` | WogiFlow `flow-worktree.js` |
+|---------|-------------------------|----------------------------|
+| Location | `.claude/worktrees/` | OS temp dir (`wogi-worktrees-{uid}`) |
+| Branch naming | Auto-generated | `wogi-task-{taskId}-{timestamp}` |
+| Squash merge | No (manual) | Yes (`squashOnMerge` config) |
+| Task linking | No | Yes (links to task ID) |
+| Cleanup | Prompted on session exit | Auto after 24h (`autoCleanupHours`) |
+
+WogiFlow detects native worktrees and avoids nesting. When launched with `--worktree`, WogiFlow uses the native worktree as-is.
 
 ## Best Practices
 
@@ -269,4 +304,4 @@ Run `/keybindings` in Claude Code to customize your shortcuts.
 
 ---
 
-*Last updated: 2026-02-19*
+*Last updated: 2026-02-20*

package/.claude/rules/README.md

@@ -0,0 +1,60 @@
+# Project Rules
+
+This directory contains coding rules and patterns for this project, organized by category.
+
+## Structure
+
+```
+.claude/rules/
+├── code-style/           # Naming conventions, formatting
+│   └── naming-conventions.md
+├── security/             # Security patterns and practices
+│   └── security-patterns.md
+├── architecture/         # Design decisions and patterns
+│   ├── component-reuse.md
+│   └── model-management.md
+└── README.md
+```
+
+## How Rules Work
+
+Rules are automatically loaded by Claude Code based on:
+- **alwaysApply: true** - Rule is always loaded
+- **alwaysApply: false** - Rule is loaded based on `globs` or `description` relevance
+- **globs** - File patterns that trigger rule loading
+
+## Adding New Rules
+
+1. Choose the appropriate category subdirectory
+2. Create a `.md` file with frontmatter:
+
+```yaml
+---
+alwaysApply: false
+description: "Brief description for relevance matching"
+globs: src/**/*.ts  # Optional: only load for these files
+---
+```
+
+3. Write the rule content in markdown
+
+## Categories
+
+| Category | Purpose |
+|----------|---------|
+| code-style | Naming conventions, formatting, file structure |
+| security | Security patterns, input validation, safe practices |
+| architecture | Design decisions, component patterns, system organization |
+
+## Auto-Generation
+
+Some rules can be auto-generated from `.workflow/state/decisions.md`:
+
+```bash
+node scripts/flow-rules-sync.js
+```
+
+The sync script will route rules to appropriate category subdirectories.
+
+---
+Last updated: 2026-01-12

package/.claude/rules/architecture/component-reuse.md

@@ -0,0 +1,38 @@
+---
+globs: src/components/**/*
+alwaysApply: false
+description: "Component reuse policy - always check app-map.md before creating components"
+---
+
+# Component Reuse Policy
+
+**Rule**: Always check `app-map.md` before creating any component.
+
+## Priority Order
+
+1. **Use existing** - Check if component already exists in app-map
+2. **Add variant** - Extend existing component with a new variant
+3. **Extend** - Create a wrapper/HOC around existing component
+4. **Create new** - Only as last resort
+
+## Before Creating Components
+
+```bash
+# Check app-map first
+cat .workflow/state/app-map.md | grep -i "button"
+
+# Or search codebase
+grep -r "Button" src/components/
+```
+
+## Variant vs New Component
+
+Prefer variants when:
+- Same base functionality, different appearance
+- Same HTML structure, different styling
+- Same component, different size/color/state
+
+Create new component when:
+- Fundamentally different functionality
+- Different DOM structure
+- Different state management

package/.claude/rules/architecture/document-structure.md

@@ -0,0 +1,76 @@
+---
+alwaysApply: true
+description: "All AI-context documents must use PIN markers for targeted context loading"
+---
+
+# Document Structure for AI Context
+
+All documents in `.workflow/` that are used as AI context MUST follow the PIN standard.
+
+## Required Structure
+
+### 1. Header with PIN List
+Every document starts with a comment listing all pins in the document:
+```markdown
+<!-- PINS: pin1, pin2, pin3 -->
+```
+
+### 2. Section PIN Markers
+Each major section has a PIN marker comment:
+```markdown
+### Section Title
+<!-- PIN: section-specific-pin -->
+[Content]
+```
+
+### 3. PIN Naming Convention
+- Use kebab-case: `user-authentication`, not `userAuthentication`
+- Use semantic names: `error-handling`, not `eh`
+- Use compound names for specificity: `json-parse-safety`
+
+## Why PINs Matter
+
+The PIN system enables:
+1. **Targeted context loading**: Only load sections relevant to current task
+2. **Cheaper model routing**: Haiku can fetch only relevant sections for Opus
+3. **Change detection**: Hash sections independently for smart invalidation
+4. **Cross-reference**: Link sections by PIN across documents
+
+## Example Document
+
+```markdown
+# Config Reference
+
+<!-- PINS: database, authentication, api-keys, environment -->
+
+## Database Settings
+<!-- PIN: database -->
+| Setting | Default | Description |
+|---------|---------|-------------|
+
+## Authentication
+<!-- PIN: authentication -->
+| Setting | Default | Description |
+|---------|---------|-------------|
+```
+
+## Parsing
+
+The PIN system automatically parses documents with:
+- `flow-section-index.js` - Generates section index with pins
+- `flow-section-resolver.js` - Resolves sections by PIN lookup
+- `getSectionsByPins(['auth', 'security'])` - Fetch only relevant sections
+
+## Files That Must Have PINs
+
+| File | Required PINs |
+|------|---------------|
+| `decisions.md` | Per coding rule/pattern |
+| `app-map.md` | Per component/screen |
+| `product.md` | Per product section |
+| `stack.md` | Per technology |
+
+## Validation
+
+Run `node scripts/flow-section-index.js --force` to regenerate the index.
+Check `.workflow/state/section-index.json` for indexed sections and their pins.

package/.claude/rules/architecture/feature-refactoring-cleanup.md

@@ -0,0 +1,87 @@
+---
+alwaysApply: false
+description: "Cleanup checklist when refactoring or renaming features"
+globs:
+  - "scripts/*.js"
+  - ".claude/skills/**/*"
+---
+
+# Feature Refactoring Cleanup
+
+When refactoring, renaming, or replacing a feature, ensure complete cleanup of the old implementation.
+
+## Mandatory Cleanup Checklist
+
+When a feature is refactored or renamed, you MUST:
+
+### 1. Remove Old Code
+- [ ] Delete old script files (e.g., `flow-old-feature.js`)
+- [ ] Remove old skill directories (e.g., `.claude/skills/old-feature/`)
+- [ ] Remove old hook files if applicable
+
+### 2. Update Configuration
+- [ ] Rename config keys (e.g., `oldFeature` → `newFeature`)
+- [ ] Remove from `skills.installed` array if skill was removed
+- [ ] Update any feature flags
+
+### 3. Update Documentation
+- [ ] Rename/update doc files in `.claude/docs/`
+- [ ] Update command references in `commands.md`
+- [ ] Update skill-matching.md if skill changed
+- [ ] Search for old name in all `.md` files
+
+### 4. Clean References
+- [ ] Search codebase: `grep -r "old-feature-name" .`
+- [ ] Update imports in dependent scripts
+- [ ] Update any hardcoded references
+
+### 5. Update State Files
+- [ ] Clean `.workflow/state/` of old state files
+- [ ] Update `ready.json` if tasks reference old feature
+- [ ] Archive old change specs
+
+## Search Commands
+
+Run these to find lingering references:
+
+```bash
+# Find all references to old feature
+grep -r "old-feature-name" --include="*.js" --include="*.md" --include="*.json" .
+
+# Find in config
+grep "oldFeatureName" .workflow/config.json
+
+# Find skill references
+grep -r "old-feature" .claude/
+```
+
+## Why This Matters
+
+Incomplete cleanup causes:
+- **Confusion**: Old commands/skills appear to work but don't
+- **Bloat**: Dead code accumulates
+- **Errors**: Old references cause runtime failures
+- **Documentation drift**: Docs describe non-existent features
+
+## Example: transcript-digestion → long-input-gate
+
+When this refactoring happened without proper cleanup:
+
+| Artifact | Status | Should Have Been |
+|----------|--------|------------------|
+| `.claude/skills/transcript-digestion/` | Left behind | Deleted |
+| `config.transcriptDigestion` | Left as-is | Renamed to `longInputGate` |
+| `skills.installed` array | Still listed | Removed |
+| `skill-matching.md` | Old references | Updated |
+| `transcript-digestion.md` doc | Still existed | Renamed/rewritten |
+
+## Automation Opportunity
+
+Consider adding a `flow refactor-cleanup <old-name> <new-name>` command that:
+1. Searches for all references
+2. Shows what needs updating
+3. Optionally auto-updates simple cases
+
+---
+
+Last updated: 2026-01-14

package/.claude/rules/architecture/model-management.md

@@ -0,0 +1,35 @@
+---
+globs: scripts/flow-model*.js
+alwaysApply: false
+description: "Model management architecture - two separate systems for different purposes"
+---
+
+# Model Management Architecture
+
+**Context**: Phase 1 introduced model registry and stats system alongside existing model-adapter.
+
+## Two Model Systems
+
+### 1. flow-model-adapter.js - Prompt Adaptation
+
+- `getCurrentModel()` returns normalized model name (string)
+- Focus: Per-model prompt adjustments, learning, and corrections
+- Imports: Used by flow-knowledge-router.js
+
+### 2. flow-models.js - Registry and Stats
+
+- `getCurrentModel()` returns `{name, info, source}` object
+- Focus: Model listing, routing recommendations, cost tracking
+- Standalone CLI commands: `flow models [subcommand]`
+
+## Design Decision
+
+**Keep them separate** because:
+- Different return types serve different consumers
+- Adapter system needs just the name for pattern matching
+- Registry system needs full model metadata for display/routing
+- Merging would create unnecessary coupling
+
+## Future Consideration
+
+Could extract shared model detection logic into a common utility if they drift apart, but avoid premature abstraction.

package/.claude/rules/architecture/self-maintenance.md

@@ -0,0 +1,87 @@
+---
+description: "Patterns for modifying WogiFlow itself (scripts, templates, config)"
+alwaysApply: false
+globs: "scripts/**,*.workflow/**,.claude/**,templates/**,agents/**,lib/**"
+---
+
+# WogiFlow Self-Maintenance Patterns
+
+When modifying WogiFlow's own code (scripts/, templates/, config, hooks), follow these patterns.
+
+## 1. Template-First Changes
+
+CLAUDE.md is **generated**, not hand-edited. Changes must go through the template system:
+
+```
+.workflow/templates/claude-md.hbs       # Main template
+.workflow/templates/partials/*.hbs      # Partial templates
+```
+
+After editing templates, regenerate:
+```bash
+node scripts/flow-bridge.js sync claude-code
+```
+
+**Never edit CLAUDE.md directly** - changes will be overwritten on next sync.
+
+## 2. Three-Layer Hook Architecture
+
+All hooks follow: Entry → Core → Adapter
+
+```
+scripts/hooks/entry/claude-code/<name>.js  # CLI-specific entry point
+scripts/hooks/core/<name>.js               # CLI-agnostic logic
+scripts/hooks/adapters/claude-code.js      # Transform results
+```
+
+When adding/modifying hooks:
+- Logic goes in `core/` (not entry)
+- Entry files only parse input and call core
+- Register hook in `.claude/settings.local.json`
+- Add config toggle in `.workflow/config.json` under `hooks.rules`
+
+## 3. Config Changes Need Documentation
+
+When adding config keys:
+- Use `_comment_<keyName>` for inline documentation of non-obvious settings
+- Update config.schema.json if it exists
+- Ensure `lib/installer.js` handles the new key for fresh installs
+
+## 4. State File Templates
+
+For files in `.workflow/state/` that target projects need:
+- Create both the file AND a `.template` version
+- Templates go in `.workflow/state/<name>.template` (for init/onboard)
+- Also add to `templates/` directory (for npm distribution)
+
+## 5. Slash Commands Are Flat Files
+
+Slash commands in `.claude/commands/` must be flat `.md` files:
+```
+.claude/commands/wogi-start.md     ← Correct (flat file)
+.claude/commands/wogi-start/       ← Wrong (directory)
+```
+
+## 6. Two Agent Directories
+
+| Directory | Purpose | Used By |
+|-----------|---------|---------|
+| `agents/` | 11 persona files | Health checks, CLI |
+| `.workflow/agents/` | Review checklists | wogi-review |
+
+Don't confuse them. `agents/security.md` (persona) is different from `.workflow/agents/security.md` (OWASP checklist).
+
+## 7. Regression Prevention
+
+When modifying flow-*.js scripts:
+- Run `node --check scripts/<file>.js` after edits
+- WogiFlow has no test suite - syntax checking is the safety net
+- Check for circular dependencies when moving shared functions
+
+## 8. Feature Refactoring Cleanup
+
+When renaming/replacing a feature, follow the full checklist in `.claude/rules/architecture/feature-refactoring-cleanup.md`. Key steps:
+- Remove old script files
+- Update config keys
+- Update documentation references
+- Search all `.md` files for old name