@mind-fold/open-flow 0.2.12 → 0.2.14

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

@@ -1,519 +1,406 @@
-A new developer needs onboarding.
-
-Execute these steps in order:
-
-1. **Explain the workflow system** - Describe how open-flow works:
-   - `workflow/` directory structure
-   - Guidelines in `workflow/structure/`
-   - Progress tracking in `workflow/agent-progress/`
-
-2. **Initialize their identity**:
-   ```bash
-   ./workflow/scripts/init-developer.sh <developer-name>
-   ```
-
-3. **Guide them through first task**:
-   - Use `./workflow/scripts/get-context.sh` to get full context
-   - Use `./workflow/scripts/feature.sh list` to see active features
-   - Read relevant guidelines in `workflow/structure/`
-   - Start coding
-
-4. **Key scripts to know**:
-   | Script | Purpose |
-   |--------|---------|
-   | `get-context.sh` | Get full session context |
-   | `feature.sh` | Manage features (create/archive/list) |
-   | `add-session.sh` | One-click session recording |
-   | `update-index.sh` | Auto-update index.md |
+You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
 
----
-
-## Slash Commands Detailed Guide
-
-### Core Workflow Commands
-
-#### `/init-agent` - Initialize AI Session
-
-**What it does**:
-Reads project context and prepares AI for development work. This is the FIRST command to run at the start of every session.
-
-**What AI will do**:
-1. Run `./workflow/scripts/get-context.sh` to get:
-   - Developer identity (who am I?)
-   - Git status (which branch? uncommitted changes?)
-   - Recent commits (what happened recently?)
-   - Active features (what's in progress?)
-   - Progress file status (where to record work?)
-2. Check if developer identity exists, guide initialization if not
-3. Read relevant structure guidelines based on upcoming task
-4. Report ready status with a summary table
-
-**Benefits**:
-- AI understands the current state before making changes
-- Avoids conflicts with ongoing work from other developers
-- Knows which guidelines to follow for this project
-- Can continue previous work seamlessly
-
-**If skipped**:
-- AI may work on wrong branch or conflict with others' work
-- AI doesn't know project conventions, writes inconsistent code
-- AI can't find previous context, asks redundant questions
-- Progress tracking breaks, work history is lost
+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.
 
 ---
 
-#### `/record-agent-flow` - Record Work Progress
-
-**What it does**:
-Records completed work to progress files AFTER human has tested and committed code.
+## CORE PHILOSOPHY: Why This Workflow Exists
 
-**What AI will do**:
-1. Get current context with `get-context.sh`
-2. Run `add-session.sh` with session details:
-   - Title: Brief description of work done
-   - Commit: Git commit hash(es)
-   - Summary/Content: Detailed changes, lessons learned
-3. Auto-update index.md with new session count and history
+AI-assisted development has three fundamental challenges:
 
-**Benefits**:
-- Creates searchable history for future sessions
-- Next AI session can understand what was done before
-- Tracks lessons learned and patterns discovered
-- Enables multi-developer collaboration without conflicts
+### Challenge 1: AI Has No Memory
 
-**If skipped**:
-- Next session starts from zero, no context
-- Same bugs may be re-investigated
-- Lessons learned are forgotten
-- Team loses visibility into AI-assisted work
+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.
 
----
-
-#### `/onboard-developer` - Guide New Developer
+**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
 
-**What it does**:
-Walks a new developer (human or AI) through the complete setup process.
+**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."
 
-**What AI will do**:
-1. Explain workflow system structure
-2. Run `init-developer.sh` to create identity
-3. Demonstrate key scripts and commands
-4. Guide through first task with examples
+### 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.
 
-### Before Coding Commands
+**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.
 
-#### `/before-frontend-dev` - Read Frontend Guidelines
+**The Solution**: The `workflow/structure/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
 
-**What it does**:
-Reads frontend development guidelines BEFORE writing any frontend code.
+### Challenge 3: AI Context Window Is Limited
 
-**What AI will do**:
-1. Read `workflow/structure/frontend/index.md` to find relevant sections
-2. Extract specific guideline sections based on task type:
-   - Component guidelines for UI work
-   - Hook guidelines for data fetching
-   - State management for complex state
-3. Understand coding standards and patterns to follow
-4. Identify reference examples to learn from
+Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
 
-**Benefits**:
-- Code follows project conventions from the start
-- Avoids common mistakes documented in guidelines
-- Uses established patterns instead of inventing new ones
-- Reduces review cycles and rework
+**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
 
-**If skipped**:
-- Code style inconsistent with rest of codebase
-- Reinvents patterns that already exist
-- Makes mistakes that guidelines warn against
-- Requires significant refactoring after review
+**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.
 
 ---
 
-#### `/before-backend-dev` - Read Backend Guidelines
-
-**What it does**:
-Reads backend development guidelines BEFORE writing any backend code.
-
-**What AI will do**:
-1. Read `workflow/structure/backend/index.md` to find relevant sections
-2. Extract specific guideline sections:
-   - Database operations for DB work
-   - Type safety for API contracts
-   - Error handling patterns
-   - Logging standards
-3. Understand project-specific conventions
+## SYSTEM STRUCTURE
 
-**Benefits**:
-- Database queries follow established patterns
-- Error handling is consistent across codebase
-- Logging provides useful debugging information
-- API contracts are type-safe
-
-**If skipped**:
-- N+1 query problems in database code
-- Inconsistent error handling
-- Missing or unhelpful logs
-- Type safety holes in APIs
+```
+workflow/
+|-- .developer              # Your identity (gitignored)
+|-- flow.md                 # Complete workflow documentation
+|-- 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)
+|-- structure/              # "AI Training Data" - project knowledge
+|   |-- frontend/           # Frontend conventions
+|   |-- backend/            # Backend conventions
+|   \-- flows/              # Cross-layer patterns
+\-- scripts/                # Automation tools
+```
 
 ---
 
-### Code Check Commands
-
-#### `/check-frontend` - Check Frontend Code
+## COMMAND DEEP DIVE
 
-**What it does**:
-Verifies frontend code against guidelines AFTER writing code, BEFORE committing.
+### /init-agent - Restore AI Memory
 
-**What AI will do**:
-1. Run type check (`tsc --noEmit`)
-2. Run linter and check for errors
-3. Review code against frontend guidelines
-4. Check for common issues:
-   - Semantic HTML usage
-   - Accessibility compliance
-   - Performance patterns
-5. Report violations and suggest fixes
+**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?
 
-**Benefits**:
-- Catches errors before human review
-- Ensures consistent code quality
-- Documents what was checked for transparency
+AI needs the same onboarding - but compressed into seconds at session start.
 
-**If skipped**:
-- Type errors slip into codebase
-- Lint errors accumulate
-- Accessibility issues go unnoticed
-- Review cycles increase
+**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
 
----
-
-#### `/check-backend` - Check Backend Code
-
-**What it does**:
-Verifies backend code against guidelines AFTER writing code, BEFORE committing.
-
-**What AI will do**:
-1. Run type check
-2. Run linter
-3. Review against backend guidelines:
-   - No non-null assertions (`!`)
-   - All inputs/outputs have Zod schemas
-   - Structured logging (no console.log)
-   - No await in loops
-4. Check API documentation is updated
-5. Report issues and fixes
-
-**Benefits**:
-- Catches type safety issues early
-- Ensures API documentation stays in sync
-- Validates database operation patterns
+**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.
 
-**If skipped**:
-- Runtime errors from type mismatches
-- API docs become outdated
-- Performance issues from N+1 queries
+**ANALOGY**: Like a human engineer reading their notes from yesterday before starting today's work.
 
 ---
 
-#### `/check-cross-layer` - Cross-Layer Verification
-
-**What it does**:
-Verifies consistency between frontend and backend when changes span multiple layers.
-
-**What AI will do**:
-1. Identify all layers touched by the change
-2. Verify type contracts match across layers
-3. Check data flow consistency
-4. Validate API request/response alignment
-
-**Benefits**:
-- Catches integration issues early
-- Ensures frontend and backend stay in sync
-- Prevents runtime type mismatches
-
-**If skipped**:
-- Frontend expects data backend doesn't provide
-- Type mismatches cause runtime errors
-- Integration bugs found late in testing
+### /before-frontend-dev and /before-backend-dev - Inject Specialized Knowledge
 
----
-
-### Work Completion Commands
+**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.
 
-#### `/finish-work` - Pre-Commit Checklist
+Human engineers learn project conventions by:
+- Reading existing code
+- Getting mentored by teammates
+- Reading internal documentation
 
-**What it does**:
-Final verification before human commits. Ensures nothing is forgotten.
+AI needs the same "training" - but injected at runtime before each coding task.
 
-**What AI will do**:
-1. Run all relevant checks (type, lint)
-2. Verify all changes are intentional
-3. Check documentation is updated
-4. Prepare commit message suggestion
-5. List files to be committed
-6. Confirm ready for human review
+**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
 
-**Benefits**:
-- Nothing is forgotten before commit
-- Clean commit history
-- Documentation stays in sync
-- Human knows exactly what to review
+**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.
 
-**If skipped**:
-- Partial commits with missing files
-- Documentation drift
-- Unclear what changed for reviewer
+**ANALOGY**: Like a human engineer reading the team's coding standards document before writing their first PR.
 
 ---
 
-#### `/break-loop` - End Investigation Loop
-
-**What it does**:
-Stops an investigation/debugging loop and summarizes findings. Use when debugging or researching, BEFORE `/finish-work`.
+### /check-frontend and /check-backend - Combat Context Drift
 
-**What AI will do**:
-1. Summarize what was investigated
-2. Document root cause (if found)
-3. List temporary vs permanent fixes
-4. Record lessons learned
-5. Suggest next steps or follow-up tasks
-6. Prepare knowledge for `/record-question` if applicable
+**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
 
-**Benefits**:
-- Prevents endless investigation loops
-- Captures debugging knowledge
-- Creates actionable next steps
-- Knowledge is preserved for future
+This causes "context drift" - AI starts following guidelines but gradually reverts to generic patterns.
 
-**If skipped**:
-- Investigation goes in circles
-- Findings are lost when session ends
-- Same debugging repeated later
-- No clear resolution or next steps
-
----
+**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
 
-### Utility 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.
 
-#### `/create-command` - Create New Slash Command
-
-**What it does**:
-Creates a new slash command when a repeated workflow pattern is identified.
-
-**What AI will do**:
-1. Analyze the workflow pattern
-2. Design command structure
-3. Create command file in `.cursor/commands/` or `.claude/commands/`
-4. Document usage and examples
+**ANALOGY**: Like code review, but automated and immediate. Catches what the "tired" AI missed.
 
 ---
 
-#### `/record-question` - Document Solved Problems
-
-**What it does**:
-Documents a solved problem for future reference when a tricky issue is resolved.
-
-**What AI will do**:
-1. Summarize the problem
-2. Document the root cause
-3. Record the solution
-4. Add to appropriate location (big-question/ or guidelines)
-
-**Benefits**:
-- Knowledge is preserved
-- Same problem won't need re-investigation
-- Team learns from each other's discoveries
+### /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.
 
 ---
 
-#### `/integrate-skill` - Integrate Claude Skills
+### /record-agent-flow - Persist Memory for Future
 
-**What it does**:
-Integrates external Claude skills into project guidelines.
+**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.
 
----
+The next session's `/init-agent` needs this information to avoid starting from zero.
 
-#### `/extract-llm-docs` - Extract from LLM Documentation
+**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
 
-**What it does**:
-Extracts useful patterns from LLM documentation (like llms.txt files) into project guidelines.
+**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.
 
----
+**ANALOGY**: Like writing notes at end of workday for tomorrow's you (or your colleague taking over).
 
-#### `/extract-to-rules` - Extract Rules from Source
+---
 
-**What it does**:
-Extracts coding rules and patterns from existing source code into guidelines.
+### /break-loop - Stop Investigation, Capture Findings
 
----
+**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.
 
-#### `/sync-from-runtime` - Sync Knowledge
+**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`
 
-**What it does**:
-Syncs knowledge and patterns from runtime documentation.
+**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
+## REAL-WORLD WORKFLOW EXAMPLES
 
 ### Example 1: Bug Fix Session
 
 **Scenario**: UI component missing after refactor
 
-```
-1. /init-agent
-   -> See context: Branch "main", 2 uncommitted files
-   -> Active feature: none
-
-2. Create feature:
-   ./workflow/scripts/feature.sh create fix-sync-indicator
-
-3. /before-frontend-dev
-   -> Read component guidelines
-
-4. Investigate and fix:
-   - Analyze old vs new architecture
-   - Import missing component
-   - Add CSS styles
+**[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
 
-5. /check-frontend
-   -> Type check: [OK] passed
-   -> Lint: [OK] 0 errors
-
-6. /finish-work
-   -> Pre-commit checklist
-   -> Confirm all changes are ready
-
-7. Human tests and commits:
-   git commit -m "fix(ui): restore SyncIndicator to TabBar"
-
-8. /record-agent-flow
-   -> ./workflow/scripts/add-session.sh --title "Fix SyncIndicator" --commit "abc123"
-
-9. Archive feature:
-   ./workflow/scripts/feature.sh archive fix-sync-indicator
-```
+---
 
 ### Example 2: Planning Session (No Code)
 
 **Scenario**: Audit migration docs and plan consolidation
 
-```
-1. /init-agent
-   -> Understand current state
+**[1/4] /init-agent**
+- PRINCIPLE: Context needed even for non-coding work
+- WHAT HAPPENS: AI sees what planning was done before, avoids duplicate work
 
-2. Create feature:
-   ./workflow/scripts/feature.sh create migration-docs-consolidation
+**[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
 
-3. Review docs, compare with existing guidelines
+**[3/4] Review docs, create subtask list**
+- PRINCIPLE: Actual planning work
+- WHAT HAPPENS: Compare docs, identify gaps, prioritize tasks
 
-4. Create subtask list in feature.json:
-   - Critical: Update outdated timestamp format
-   - High: Add missing validation rules
-   - Medium: Consolidate scattered docs
+**[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
 
-5. /record-agent-flow (no commit)
-   -> ./workflow/scripts/add-session.sh --title "Migration Docs Planning" --summary "Created 14 subtasks"
-```
+---
 
 ### Example 3: Code Review Fixes
 
 **Scenario**: Fix issues from CR round 2
 
-```
-1. /init-agent
-   -> Continue feature: entity-filesystem-refactor
+**[1/6] /init-agent**
+- PRINCIPLE: Resume context from previous session
+- WHAT HAPPENS: AI sees this feature is in progress, reads CR feedback context
 
-2. /before-backend-dev
-   -> Read database and error handling guidelines
+**[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
 
-3. Fix each CR issue:
-   - Add missing workspaceId filter (data isolation)
-   - Fix meta double-stringify bug
-   - Add LWW conflict resolution
+**[3/6] Fix each CR issue**
+- PRINCIPLE: Address feedback with guidelines in context
+- WHAT HAPPENS: Fixes follow project conventions, not generic patterns
 
-4. /check-backend
-   -> All checks passed
+**[4/6] /check-backend**
+- PRINCIPLE: Verify fixes didn't introduce new issues
+- WHAT HAPPENS: Each fix could break something else - this catches it
 
-5. /finish-work
-   -> Pre-commit checklist
-   -> Document lessons learned:
-     - "All queries with workspaceId column must include WHERE clause"
-     - "buildXxxValues must match *DataSchema types"
+**[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
 
-6. Human commits, then /record-agent-flow
-```
+**[6/6] Human commits, then /record-agent-flow**
+- PRINCIPLE: Preserve CR lessons
+- WHAT HAPPENS: Next time AI writes similar code, it has this context
+
+---
 
 ### Example 4: Large Refactoring
 
 **Scenario**: Adapt workflow system for monorepo
 
-```
-1. /init-agent
-   -> Create feature: workflow-monorepo-adaptation
+**[1/5] /init-agent**
+- PRINCIPLE: Clear baseline before major changes
+- WHAT HAPPENS: Large refactors need documented starting point
 
-2. Plan phases:
-   - 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
 
-3. Execute phase by phase, running /check-* after each
+**[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
 
-4. /finish-work
-   -> Final verification checklist
+**[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
 
-5. Human commits multiple times, record with multiple commit hashes:
-   ./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"
+
+---
 
 ### Example 5: Debug Session with Break Loop
 
 **Scenario**: Investigating a complex sync bug
 
-```
-1. /init-agent
-   -> Continue feature: fix-sync-data-inconsistency
-
-2. /before-backend-dev
-   -> Read sync and database guidelines
+**[1/7] /init-agent**
+- PRINCIPLE: See if this bug was investigated before
+- WHAT HAPPENS: Previous investigation attempts might have clues
 
-3. Investigation loop:
-   - Analyze cloud vs local data
-   - Check sync event timestamps
-   - Review applyEvent logic
-   - Add debug logging
+**[2/7] /before-backend-dev**
+- PRINCIPLE: Guidelines often document known gotchas
+- WHAT HAPPENS: Sync-related guidelines might hint at common issues
 
-4. /check-backend
-   -> All checks passed
+**[3/7] Investigation loop**
+- PRINCIPLE: Actual debugging work
+- WHAT HAPPENS: Analyze data, check logs, form hypotheses, test fixes
 
-5. /break-loop (when investigation is complete)
-   -> Summarize findings:
-     - Root cause: Transaction failure without error logging
-     - Temporary fix: Manual SQL update
-     - Permanent fix: Add detailed logging in applyEvent
-   -> Document for future reference
+**[4/7] /check-backend**
+- PRINCIPLE: Debug code can be sloppy
+- WHAT HAPPENS: Verify debug changes don't break other things
 
-6. /finish-work
-   -> Pre-commit checklist
+**[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
 
-7. Human tests and commits
+**[6/7] /finish-work**
+- PRINCIPLE: Debug findings might need documentation
+- WHAT HAPPENS: If this was a common bug pattern, add to guidelines
 
-8. /record-agent-flow
-   -> Include lessons learned in session record
-```
+**[7/7] Human commits, then /record-agent-flow**
+- PRINCIPLE: Debug knowledge is valuable
+- WHAT HAPPENS: Next time same bug appears, AI has context
 
 ---
 
-## Key Points to Emphasize
+## KEY RULES TO EMPHASIZE
+
+1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
+
+2. **Guidelines before code** - /before-*-dev commands inject project knowledge. Without them, AI writes generic code.
+
+3. **Check after code** - /check-* commands catch context drift. Without them, drift goes unnoticed.
+
+4. **Finish-work updates guidelines** - If you discover new patterns or fix pattern violations, consider updating workflow/structure/ so future sessions benefit.
+
+5. **Record everything** - /record-agent-flow persists memory. Without it, next session starts blind.
+
+---
 
-- AI should NOT execute `git commit` - human is responsible for testing and committing
-- Each developer has their own progress directory
-- Read guidelines before coding (mandatory)
-- Use `/record-question` to document solved problems for future reference
-- Planning sessions (no code) are valid - record with `--summary` instead of `--commit`
-- `/break-loop` is for ending debug/investigation loops, use BEFORE `/finish-work`
+After explaining, ask the developer:
+1. What kind of work will they be doing? (frontend/backend/full-stack)
+2. Do they have a specific task to start with?
 
+Then guide them through their first task using the appropriate workflow.

package/package.json

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