@mind-fold/open-flow 0.2.13 → 0.2.15

package/dist/templates/commands/onboard-developer.txt

@@ -1,176 +1,287 @@
 You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
 
-YOUR ROLE: Be a mentor and teacher. Don't just execute commands - EXPLAIN why each step matters, what problems it solves, and what happens if skipped.
+YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level.
 
-TEACHING APPROACH:
-- First explain the CORE PHILOSOPHY: why this workflow exists
-- Then walk through the system structure with clear explanations
-- For each example, explain the PURPOSE of every step, not just what to do
-- Help them understand the "why" behind each command
+## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
+
+This onboarding has TWO equally important parts:
+
+**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each command does and WHY
+
+**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
+- Walk through ALL 5 examples in detail
+- For EACH step in EACH example, explain:
+  - PRINCIPLE: Why this step exists
+  - WHAT HAPPENS: What the command actually does
+  - IF SKIPPED: What goes wrong without it
+
+DO NOT skip Part 2. The examples are NOT optional - they are the most important part for understanding how the workflow works in practice. A developer cannot truly understand the system without seeing real workflow examples.
+
+After completing BOTH parts, ask the developer about their first task.
 
 ---
 
-## CORE PHILOSOPHY
+## CORE PHILOSOPHY: Why This Workflow Exists
+
+AI-assisted development has three fundamental challenges:
+
+### Challenge 1: AI Has No Memory
+
+Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
+
+**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
+
+**The Solution**: The `workflow/agent-progress/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/init-agent` command reads this history at session start, giving AI "artificial memory."
+
+### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
+
+AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
+
+**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
 
-This workflow system solves three critical problems in AI-assisted development:
+**The Solution**: The `workflow/structure/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
 
-1. **Context Loss**: AI starts each session with zero memory. Without a system to capture and restore context, every session starts from scratch, leading to repeated explanations and inconsistent code.
+### Challenge 3: AI Context Window Is Limited
 
-2. **Multi-Developer Conflicts**: When multiple developers (human or AI) work on the same codebase, they can overwrite each other's work or make conflicting changes.
+Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
 
-3. **Quality Drift**: Without enforced guidelines, AI generates code that "works" but doesn't follow project conventions, leading to technical debt.
+**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
 
-The solution: A structured workflow with checkpoints that ensure AI reads context before coding, follows guidelines during coding, and records progress after coding.
+**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/finish-work` command does a final holistic review.
 
 ---
 
 ## SYSTEM STRUCTURE
 
-Explain the `workflow/` directory to the developer:
-
 ```
 workflow/
-|-- .developer              # Developer identity file (gitignored)
+|-- .developer              # Your identity (gitignored)
 |-- flow.md                 # Complete workflow documentation
-|-- agent-progress/         # Progress tracking (per-developer)
-|   |-- index.md            # Main index with all developers
-|   \-- {developer}/        # Individual developer directory
-|       |-- index.md        # Personal index
+|-- agent-progress/         # "AI Memory" - session history
+|   |-- index.md            # All developers' progress
+|   \-- {developer}/        # Per-developer directory
+|       |-- index.md        # Personal progress index
 |       |-- features/       # Active feature tracking
-|       \-- progress-N.md   # Session records (max 2000 lines each)
-|-- structure/              # Development guidelines (MUST READ)
-|   |-- frontend/           # Frontend coding standards
-|   |-- backend/            # Backend coding standards
-|   \-- flows/              # Cross-layer development guides
-\-- scripts/                # Automation scripts
-    |-- get-context.sh      # Get full session context
-    |-- init-developer.sh   # Initialize new developer
-    |-- feature.sh          # Manage features
-    |-- add-session.sh      # Record session progress
-    \-- update-index.sh     # Update index files
+|       \-- progress-N.md   # Session records (max 2000 lines)
+|-- structure/              # "AI Training Data" - project knowledge
+|   |-- frontend/           # Frontend conventions
+|   |-- backend/            # Backend conventions
+|   \-- flows/              # Cross-layer patterns
+\-- scripts/                # Automation tools
 ```
 
 ---
 
-## INITIALIZE DEVELOPER
+## COMMAND DEEP DIVE
 
-Ask for their name and run:
-```bash
-./workflow/scripts/init-developer.sh <developer-name>
-```
+### /init-agent - Restore AI Memory
 
-Then demonstrate context retrieval:
-```bash
-./workflow/scripts/get-context.sh
-```
+**WHY IT EXISTS**:
+When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
+
+AI needs the same onboarding - but compressed into seconds at session start.
 
-Explain what each output section means and why it matters.
+**WHAT IT ACTUALLY DOES**:
+1. Reads developer identity (who am I in this project?)
+2. Checks git status (what branch? uncommitted changes?)
+3. Reads recent session history from `agent-progress/` (what happened before?)
+4. Identifies active features (what's in progress?)
+5. Understands current project state before making any changes
+
+**WHY THIS MATTERS**:
+- Without init-agent: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
+- With init-agent: AI knows project context, can continue where previous session left off, avoids conflicts.
+
+**ANALOGY**: Like a human engineer reading their notes from yesterday before starting today's work.
 
 ---
 
-## CORE SLASH COMMANDS
+### /before-frontend-dev and /before-backend-dev - Inject Specialized Knowledge
+
+**WHY IT EXISTS**:
+AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
 
-Explain each command's PURPOSE, not just what it does:
+Human engineers learn project conventions by:
+- Reading existing code
+- Getting mentored by teammates
+- Reading internal documentation
+
+AI needs the same "training" - but injected at runtime before each coding task.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reads `workflow/structure/frontend/` or `workflow/structure/backend/` index
+2. Extracts relevant guideline sections based on the task
+3. Loads project-specific patterns into AI's working context:
+   - Component naming conventions
+   - State management patterns
+   - Database query patterns
+   - Error handling standards
+   - Logging formats
+   - Type safety rules
+
+**WHY THIS MATTERS**:
+- Without before-*-dev: AI writes generic code. It "works" but doesn't match project style. Other engineers can't read it. It creates inconsistency.
+- With before-*-dev: AI writes code that looks like the rest of the codebase. It follows established patterns. It's consistent.
+
+**ANALOGY**: Like a human engineer reading the team's coding standards document before writing their first PR.
+
+---
 
-### Session Lifecycle Commands
+### /check-frontend and /check-backend - Combat Context Drift
 
-| Command | When | Purpose |
-|---------|------|---------|
-| `/init-agent` | Session start | Restore context so AI doesn't start blind |
-| `/record-agent-flow` | After commit | Preserve context for next session |
-| `/finish-work` | Before commit | Final quality gate before human review |
+**WHY IT EXISTS**:
+AI context window has limited capacity. As conversation progresses:
+- New messages push older context (including guidelines) toward the edge
+- AI attention becomes diluted across more content
+- Guidelines injected at session start become less influential
 
-### Development Commands
+This causes "context drift" - AI starts following guidelines but gradually reverts to generic patterns.
 
-| Command | When | Purpose |
-|---------|------|---------|
-| `/before-frontend-dev` | Before frontend code | Load project conventions into AI context |
-| `/before-backend-dev` | Before backend code | Load project conventions into AI context |
-| `/check-frontend` | After frontend code | Verify code meets standards before commit |
-| `/check-backend` | After backend code | Verify code meets standards before commit |
-| `/check-cross-layer` | Full-stack changes | Ensure frontend/backend stay in sync |
+**WHAT IT ACTUALLY DOES**:
+1. Re-reads the guidelines that were injected earlier
+2. Compares written code against those guidelines
+3. Runs type checker and linter
+4. Identifies violations:
+   - Style inconsistencies
+   - Pattern violations
+   - Type safety issues
+   - Logic bugs
+5. Reports findings and suggests fixes
 
-### Investigation Commands
+**WHY THIS MATTERS**:
+- Without check-*: Context drift goes unnoticed. Code that seemed right during writing violates guidelines when reviewed.
+- With check-*: Drift is caught and corrected before commit. Code quality is verified, not assumed.
 
-| Command | When | Purpose |
-|---------|------|---------|
-| `/break-loop` | After debugging | Stop investigation and capture findings |
-| `/record-question` | Solved hard problem | Document solution for future reference |
+**ANALOGY**: Like code review, but automated and immediate. Catches what the "tired" AI missed.
 
 ---
 
-## REAL-WORLD WORKFLOW EXAMPLES
+### /finish-work - Holistic Pre-Commit Review
+
+**WHY IT EXISTS**:
+The `/check-*` commands focus on code quality within a layer (frontend OR backend). But real changes often have cross-cutting concerns:
+- Does frontend change break backend contract?
+- Does backend change require frontend update?
+- Does infrastructure change need documentation?
+- Are there side effects on other features?
+
+**WHAT IT ACTUALLY DOES**:
+1. Reviews all changes holistically (not just one layer)
+2. Checks cross-layer consistency:
+   - API contracts match between frontend/backend
+   - Type definitions are synchronized
+   - Data flow is consistent end-to-end
+3. Identifies broader impacts:
+   - Will this change affect other features?
+   - Are there edge cases not considered?
+   - Is documentation needed?
+4. **CRITICAL**: If there are significant infrastructure or pattern changes:
+   - Checks if these should be documented in `workflow/structure/`
+   - Ensures future `/before-*-dev` commands will include this new knowledge
+   - Prevents knowledge from being lost
+
+**WHY THIS MATTERS**:
+- Without finish-work: Individual layers pass checks, but integration fails. New patterns aren't documented. Knowledge is lost.
+- With finish-work: Cross-layer issues caught before commit. New patterns documented for future sessions.
+
+**ANALOGY**: Like the final review before merging a PR - checking not just code quality, but overall impact and documentation.
 
-For each example below, explain:
-- The SCENARIO context
-- WHY each step is needed
-- WHAT PROBLEM that step solves
-- WHAT HAPPENS if that step is skipped
+---
 
-### Example 1: Bug Fix Session
+### /record-agent-flow - Persist Memory for Future
 
-**Scenario**: UI component missing after refactor
+**WHY IT EXISTS**:
+All the context AI built during this session - what was done, what was learned, what problems were solved - will be lost when session ends.
 
-```
-Step 1: /init-agent
-```
-PURPOSE: AI needs to understand current state before making changes.
-- Reads developer identity, git status, active features
-- Without this: AI might work on wrong branch, conflict with others, or repeat already-done work
+The next session's `/init-agent` needs this information to avoid starting from zero.
 
-```
-Step 2: ./workflow/scripts/feature.sh create fix-sync-indicator
-```
-PURPOSE: Create isolated tracking for this work.
-- Links all changes to a named feature
-- Without this: Progress scattered, hard to track what changed and why
+**WHAT IT ACTUALLY DOES**:
+1. Records session summary to `agent-progress/{developer}/progress-N.md`
+2. Captures:
+   - What task was worked on
+   - What commits were made (for code sessions)
+   - What was learned (patterns discovered, bugs found)
+   - What's remaining (if work continues next session)
+3. Updates index files for quick lookup
 
-```
-Step 3: /before-frontend-dev
-```
-PURPOSE: Load project's frontend conventions into AI context.
-- AI learns component patterns, naming conventions, state management rules
-- Without this: AI writes "working" code that doesn't match project style
+**WHY THIS MATTERS**:
+- Without record-agent-flow: Next session starts blind. Same bugs re-investigated. Same patterns re-discovered.
+- With record-agent-flow: Next session has context. AI can continue work. Knowledge compounds over time.
 
-```
-Step 4: Investigate and fix the bug
-```
-PURPOSE: The actual development work.
-- AI now has context + guidelines, can write consistent code
+**ANALOGY**: Like writing notes at end of workday for tomorrow's you (or your colleague taking over).
 
-```
-Step 5: /check-frontend
-```
-PURPOSE: Quality gate before human review.
-- Runs type check, linter, guideline compliance
-- Without this: Errors slip through, human review catches preventable issues
+---
 
-```
-Step 6: /finish-work
-```
-PURPOSE: Final checklist before commit.
-- Ensures nothing forgotten: docs updated, all files staged
-- Without this: Partial commits, missing documentation
+### /break-loop - Stop Investigation, Capture Findings
 
-```
-Step 7: Human tests and commits
-```
-PURPOSE: Human-in-the-loop verification.
-- AI NEVER commits - human is responsible for testing
-- Without this: Untested code enters codebase
+**WHY IT EXISTS**:
+Debugging and investigation can spiral - AI keeps trying things without concluding. Findings get scattered across conversation. When session ends, insights are lost.
 
-```
-Step 8: /record-agent-flow
-```
-PURPOSE: Preserve context for future sessions.
-- Records what was done, lessons learned, commit hashes
-- Without this: Next session starts from zero, same bugs re-investigated
+**WHAT IT ACTUALLY DOES**:
+1. Forces a stop point in investigation
+2. Summarizes:
+   - What was investigated
+   - What was the root cause (if found)
+   - What fixes were tried (temporary vs permanent)
+   - What follow-up is needed
+3. Prepares findings for `/record-agent-flow`
 
-```
-Step 9: ./workflow/scripts/feature.sh archive fix-sync-indicator
-```
-PURPOSE: Clean up after completion.
-- Moves feature to archive, keeps active list clean
+**WHY THIS MATTERS**:
+- Without break-loop: Investigation spirals endlessly. Findings scattered. Same debugging repeated next time.
+- With break-loop: Investigation has clear conclusion. Findings documented. Future sessions have context.
+
+---
+
+## REAL-WORLD WORKFLOW EXAMPLES
+
+### Example 1: Bug Fix Session
+
+**Scenario**: UI component missing after refactor
+
+**[1/9] /init-agent**
+- PRINCIPLE: AI needs project context before touching code
+- WHAT HAPPENS: AI reads session history, sees this is a React project, understands current branch/state
+- IF SKIPPED: AI might not know project conventions, could work on wrong branch
+
+**[2/9] ./workflow/scripts/feature.sh create fix-sync-indicator**
+- PRINCIPLE: Track work for future reference
+- WHAT HAPPENS: Creates feature record linking all subsequent work
+- IF SKIPPED: Work scattered, hard to trace what changed and why
+
+**[3/9] /before-frontend-dev**
+- PRINCIPLE: Inject project-specific frontend knowledge
+- WHAT HAPPENS: AI learns YOUR component patterns, not generic React patterns
+- IF SKIPPED: AI writes generic code that doesn't match project style
+
+**[4/9] Investigate and fix the bug**
+- PRINCIPLE: Actual development work
+- WHAT HAPPENS: AI has context + guidelines, writes consistent code
+
+**[5/9] /check-frontend**
+- PRINCIPLE: Combat context drift
+- WHAT HAPPENS: Re-verifies code against guidelines, catches style violations, type errors
+- IF SKIPPED: Drift goes unnoticed, code quality degrades
+
+**[6/9] /finish-work**
+- PRINCIPLE: Holistic cross-layer review
+- WHAT HAPPENS: Checks if this frontend change has backend implications, documentation needs
+- IF SKIPPED: Integration issues missed, patterns undocumented
+
+**[7/9] Human tests and commits**
+- PRINCIPLE: Human-in-the-loop verification
+- WHAT HAPPENS: AI NEVER commits - human validates before code enters repo
+- IF SKIPPED: Untested code in production
+
+**[8/9] /record-agent-flow**
+- PRINCIPLE: Persist memory for future
+- WHAT HAPPENS: Records what was done, learned patterns, commit hashes
+- IF SKIPPED: Next session starts from zero
+
+**[9/9] ./workflow/scripts/feature.sh archive**
+- PRINCIPLE: Clean tracking state
+- WHAT HAPPENS: Moves completed feature to archive
 
 ---
 
@@ -178,30 +289,22 @@ PURPOSE: Clean up after completion.
 
 **Scenario**: Audit migration docs and plan consolidation
 
-```
-Step 1: /init-agent
-```
-PURPOSE: Understand current state even for non-coding work.
-- See what's already in progress, avoid duplicate planning
+**[1/4] /init-agent**
+- PRINCIPLE: Context needed even for non-coding work
+- WHAT HAPPENS: AI sees what planning was done before, avoids duplicate work
 
-```
-Step 2: ./workflow/scripts/feature.sh create migration-docs-consolidation
-```
-PURPOSE: Track planning work same as code work.
-- Planning is valuable work that needs recording
+**[2/4] ./workflow/scripts/feature.sh create migration-docs-consolidation**
+- PRINCIPLE: Planning is valuable work worth tracking
+- WHAT HAPPENS: Creates record for this planning effort
 
-```
-Step 3: Review docs, create subtask list
-```
-PURPOSE: The actual planning work.
-- Compare existing docs, identify gaps, prioritize
+**[3/4] Review docs, create subtask list**
+- PRINCIPLE: Actual planning work
+- WHAT HAPPENS: Compare docs, identify gaps, prioritize tasks
 
-```
-Step 4: /record-agent-flow (with --summary, no --commit)
-```
-PURPOSE: Record planning output even without code commits.
-- Use --summary flag for non-code sessions
-- Without this: Planning decisions lost, team doesn't know what was decided
+**[4/4] /record-agent-flow (with --summary, no --commit)**
+- PRINCIPLE: Planning decisions must be recorded
+- WHAT HAPPENS: Uses --summary flag since no code commits
+- IF SKIPPED: Planning decisions lost, team doesn't know what was decided
 
 ---
 
@@ -209,44 +312,30 @@ PURPOSE: Record planning output even without code commits.
 
 **Scenario**: Fix issues from CR round 2
 
-```
-Step 1: /init-agent
-```
-PURPOSE: Resume context from previous session.
-- AI sees the feature is already in progress
-- Reads previous progress to understand what was already done
+**[1/6] /init-agent**
+- PRINCIPLE: Resume context from previous session
+- WHAT HAPPENS: AI sees this feature is in progress, reads CR feedback context
 
-```
-Step 2: /before-backend-dev
-```
-PURPOSE: Refresh guidelines before fixing backend issues.
-- CR comments often point to guideline violations
-- AI needs guidelines in context to fix properly
+**[2/6] /before-backend-dev**
+- PRINCIPLE: Re-inject guidelines before fixes
+- WHAT HAPPENS: CR comments often point to guideline violations - AI needs guidelines fresh in context
 
-```
-Step 3: Fix each CR issue
-```
-PURPOSE: Address review feedback.
-- With guidelines loaded, fixes follow project conventions
+**[3/6] Fix each CR issue**
+- PRINCIPLE: Address feedback with guidelines in context
+- WHAT HAPPENS: Fixes follow project conventions, not generic patterns
 
-```
-Step 4: /check-backend
-```
-PURPOSE: Verify fixes don't introduce new issues.
-- Each fix could break something else
+**[4/6] /check-backend**
+- PRINCIPLE: Verify fixes didn't introduce new issues
+- WHAT HAPPENS: Each fix could break something else - this catches it
 
-```
-Step 5: /finish-work
-```
-PURPOSE: Document lessons learned from CR.
-- CR feedback reveals patterns to remember
-- Example: "All queries with workspaceId must include WHERE clause"
+**[5/6] /finish-work**
+- PRINCIPLE: Document lessons from CR
+- WHAT HAPPENS: CR feedback reveals patterns worth documenting
+- KEY: If CR revealed a pattern violation, consider adding to workflow/structure/ so future /before-*-dev catches it
 
-```
-Step 6: Human commits, then /record-agent-flow
-```
-PURPOSE: Preserve CR lessons for future.
-- Next time AI writes similar code, it knows the patterns
+**[6/6] Human commits, then /record-agent-flow**
+- PRINCIPLE: Preserve CR lessons
+- WHAT HAPPENS: Next time AI writes similar code, it has this context
 
 ---
 
@@ -254,38 +343,26 @@ PURPOSE: Preserve CR lessons for future.
 
 **Scenario**: Adapt workflow system for monorepo
 
-```
-Step 1: /init-agent
-```
-PURPOSE: Establish baseline before major changes.
-- Large refactors need clear starting point
+**[1/5] /init-agent**
+- PRINCIPLE: Clear baseline before major changes
+- WHAT HAPPENS: Large refactors need documented starting point
 
-```
-Step 2: Plan phases
-```
-PURPOSE: Break large work into manageable chunks.
-- Phase 1: Root directory restructure
-- Phase 2: Sub-project workflow cleanup
-- Phase 3: Slash commands rewrite
-- Phase 4: Core docs update
+**[2/5] Plan phases**
+- PRINCIPLE: Break into verifiable chunks
+- WHAT HAPPENS: Define phases that can each be checked independently
 
-```
-Step 3: Execute phase by phase with /check-* after each
-```
-PURPOSE: Incremental verification.
-- Catch issues early, don't let errors compound
+**[3/5] Execute phase by phase with /check-* after each**
+- PRINCIPLE: Incremental verification
+- WHAT HAPPENS: Catch issues early, don't let drift compound across phases
 
-```
-Step 4: /finish-work
-```
-PURPOSE: Final verification across all phases.
-- Ensure all phases are complete and consistent
+**[4/5] /finish-work**
+- PRINCIPLE: Major refactor likely needs documentation update
+- WHAT HAPPENS: Check if new patterns should be added to workflow/structure/
+- KEY: This ensures future /before-*-dev commands include the new patterns
 
-```
-Step 5: Record with multiple commit hashes
-```
-PURPOSE: Link all commits to one logical feature.
-- ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"
+**[5/5] Record with multiple commit hashes**
+- PRINCIPLE: Link all commits to one logical feature
+- COMMAND: ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"
 
 ---
 
@@ -293,63 +370,51 @@ PURPOSE: Link all commits to one logical feature.
 
 **Scenario**: Investigating a complex sync bug
 
-```
-Step 1: /init-agent
-```
-PURPOSE: Get context on the bug being investigated.
-- See previous investigation attempts if any
+**[1/7] /init-agent**
+- PRINCIPLE: See if this bug was investigated before
+- WHAT HAPPENS: Previous investigation attempts might have clues
 
-```
-Step 2: /before-backend-dev
-```
-PURPOSE: Load relevant guidelines for the area being debugged.
-- Guidelines often contain hints about known issues
+**[2/7] /before-backend-dev**
+- PRINCIPLE: Guidelines often document known gotchas
+- WHAT HAPPENS: Sync-related guidelines might hint at common issues
 
-```
-Step 3: Investigation loop
-```
-PURPOSE: The actual debugging work.
-- Analyze data, check logs, form hypotheses, test fixes
+**[3/7] Investigation loop**
+- PRINCIPLE: Actual debugging work
+- WHAT HAPPENS: Analyze data, check logs, form hypotheses, test fixes
 
-```
-Step 4: /check-backend
-```
-PURPOSE: Verify debug changes don't break other things.
-- Debug code can be sloppy - this catches issues
+**[4/7] /check-backend**
+- PRINCIPLE: Debug code can be sloppy
+- WHAT HAPPENS: Verify debug changes don't break other things
 
-```
-Step 5: /break-loop
-```
-PURPOSE: CRITICAL - Stop investigation and capture findings.
-- Summarizes: what was investigated, root cause, fixes tried
-- Documents: temporary vs permanent fix, follow-up needed
-- Without this: Investigation goes in circles, findings lost
+**[5/7] /break-loop**
+- PRINCIPLE: CRITICAL - Force conclusion to investigation
+- WHAT HAPPENS: Stop spiraling, document findings:
+  - Root cause identified?
+  - Temporary fix vs permanent fix?
+  - Follow-up needed?
+- IF SKIPPED: Investigation goes in circles, findings scattered and lost
 
-```
-Step 6: /finish-work
-```
-PURPOSE: Prepare debug findings for commit.
-- Even investigation sessions produce valuable output
+**[6/7] /finish-work**
+- PRINCIPLE: Debug findings might need documentation
+- WHAT HAPPENS: If this was a common bug pattern, add to guidelines
 
-```
-Step 7: Human commits, then /record-agent-flow
-```
-PURPOSE: Preserve debugging knowledge.
-- Next time same bug appears, AI has context
+**[7/7] Human commits, then /record-agent-flow**
+- PRINCIPLE: Debug knowledge is valuable
+- WHAT HAPPENS: Next time same bug appears, AI has context
 
 ---
 
 ## KEY RULES TO EMPHASIZE
 
-1. **AI NEVER commits** - Human tests and commits. AI prepares, human approves.
+1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
 
-2. **Guidelines before code** - /before-*-dev commands are MANDATORY, not optional.
+2. **Guidelines before code** - /before-*-dev commands inject project knowledge. Without them, AI writes generic code.
 
-3. **Progress tracking** - Every session should end with /record-agent-flow.
+3. **Check after code** - /check-* commands catch context drift. Without them, drift goes unnoticed.
 
-4. **Break investigation loops** - Use /break-loop to stop research and capture findings.
+4. **Finish-work updates guidelines** - If you discover new patterns or fix pattern violations, consider updating workflow/structure/ so future sessions benefit.
 
-5. **Planning is valid work** - Non-code sessions use --summary flag in add-session.sh.
+5. **Record everything** - /record-agent-flow persists memory. Without it, next session starts blind.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mind-fold/open-flow",
-	"version": "0.2.13",
+	"version": "0.2.15",
 	"description": "AI-assisted development workflow initializer for Cursor, Claude Code and more",
 	"type": "module",
 	"main": "./dist/index.js",