@mind-fold/open-flow 0.2.10 → 0.2.11

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

@@ -26,46 +26,494 @@ Execute these steps in order:
    | `add-session.sh` | One-click session recording |
    | `update-index.sh` | Auto-update index.md |
 
-5. **Available slash commands**:
-
-   **Core Workflow**:
-   | Command | Purpose |
-   |---------|---------|
-   | `/init-agent` | Initialize AI session, read context |
-   | `/record-agent-flow` | Record work progress (after human commits) |
-   | `/onboard-developer` | Guide new developer through setup |
-
-   **Before Coding**:
-   | Command | Purpose |
-   |---------|---------|
-   | `/before-frontend-dev` | Read frontend guidelines first |
-   | `/before-backend-dev` | Read backend guidelines first |
-
-   **Code Checks**:
-   | Command | Purpose |
-   |---------|---------|
-   | `/check-frontend` | Check frontend code quality |
-   | `/check-backend` | Check backend code quality |
-   | `/check-cross-layer` | Verify cross-layer consistency |
-
-   **Work Completion**:
-   | Command | Purpose |
-   |---------|---------|
-   | `/finish-work` | Pre-commit checklist |
-   | `/break-loop` | End investigation loop |
-
-   **Utilities**:
-   | Command | Purpose |
-   |---------|---------|
-   | `/create-command` | Create new slash command |
-   | `/record-question` | Document solved problems |
-   | `/integrate-skill` | Integrate Claude skills into guidelines |
-   | `/extract-llm-docs` | Extract docs from LLM documentation |
-   | `/extract-to-rules` | Extract rules from source files |
-   | `/sync-from-runtime` | Sync knowledge from runtime docs |
-
-Key points to emphasize:
+---
+
+## 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
+
+---
+
+#### `/record-agent-flow` - Record Work Progress
+
+**What it does**:
+Records completed work to progress files AFTER human has tested and committed code.
+
+**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
+
+**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
+
+**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
+
+---
+
+#### `/onboard-developer` - Guide New Developer
+
+**What it does**:
+Walks a new developer (human or AI) through the complete setup process.
+
+**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
+
+---
+
+### Before Coding Commands
+
+#### `/before-frontend-dev` - Read Frontend Guidelines
+
+**What it does**:
+Reads frontend development guidelines BEFORE writing any frontend code.
+
+**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
+
+**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
+
+**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
+
+---
+
+#### `/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
+
+**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
+
+---
+
+### Code Check Commands
+
+#### `/check-frontend` - Check Frontend Code
+
+**What it does**:
+Verifies frontend code against guidelines AFTER writing code, BEFORE committing.
+
+**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
+
+**Benefits**:
+- Catches errors before human review
+- Ensures consistent code quality
+- Documents what was checked for transparency
+
+**If skipped**:
+- Type errors slip into codebase
+- Lint errors accumulate
+- Accessibility issues go unnoticed
+- Review cycles increase
+
+---
+
+#### `/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
+
+**If skipped**:
+- Runtime errors from type mismatches
+- API docs become outdated
+- Performance issues from N+1 queries
+
+---
+
+#### `/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
+
+---
+
+### Work Completion Commands
+
+#### `/finish-work` - Pre-Commit Checklist
+
+**What it does**:
+Final verification before human commits. Ensures nothing is forgotten.
+
+**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
+
+**Benefits**:
+- Nothing is forgotten before commit
+- Clean commit history
+- Documentation stays in sync
+- Human knows exactly what to review
+
+**If skipped**:
+- Partial commits with missing files
+- Documentation drift
+- Unclear what changed for reviewer
+
+---
+
+#### `/break-loop` - End Investigation Loop
+
+**What it does**:
+Stops an investigation/debugging loop and summarizes findings. Use when debugging or researching, BEFORE `/finish-work`.
+
+**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
+
+**Benefits**:
+- Prevents endless investigation loops
+- Captures debugging knowledge
+- Creates actionable next steps
+- Knowledge is preserved for future
+
+**If skipped**:
+- Investigation goes in circles
+- Findings are lost when session ends
+- Same debugging repeated later
+- No clear resolution or next steps
+
+---
+
+### Utility Commands
+
+#### `/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
+
+---
+
+#### `/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
+
+---
+
+#### `/integrate-skill` - Integrate Claude Skills
+
+**What it does**:
+Integrates external Claude skills into project guidelines.
+
+---
+
+#### `/extract-llm-docs` - Extract from LLM Documentation
+
+**What it does**:
+Extracts useful patterns from LLM documentation (like llms.txt files) into project guidelines.
+
+---
+
+#### `/extract-to-rules` - Extract Rules from Source
+
+**What it does**:
+Extracts coding rules and patterns from existing source code into guidelines.
+
+---
+
+#### `/sync-from-runtime` - Sync Knowledge
+
+**What it does**:
+Syncs knowledge and patterns from runtime documentation.
+
+---
+
+## 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
+
+5. /check-frontend
+   → Type check: ✅ passed
+   → Lint: ✅ 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
+
+2. Create feature:
+   ./workflow/scripts/feature.sh create migration-docs-consolidation
+
+3. Review docs, compare with existing guidelines
+
+4. Create subtask list in feature.json:
+   - Critical: Update outdated timestamp format
+   - High: Add missing validation rules
+   - Medium: Consolidate scattered docs
+
+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
+
+2. /before-backend-dev
+   → Read database and error handling guidelines
+
+3. Fix each CR issue:
+   - Add missing workspaceId filter (data isolation)
+   - Fix meta double-stringify bug
+   - Add LWW conflict resolution
+
+4. /check-backend
+   → All checks passed
+
+5. /finish-work
+   → Pre-commit checklist
+   → Document lessons learned:
+     - "All queries with workspaceId column must include WHERE clause"
+     - "buildXxxValues must match *DataSchema types"
+
+6. Human commits, then /record-agent-flow
+```
+
+### Example 4: Large Refactoring
+
+**Scenario**: Adapt workflow system for monorepo
+
+```
+1. /init-agent
+   → Create feature: workflow-monorepo-adaptation
+
+2. Plan phases:
+   - Phase 1: Root directory restructure
+   - Phase 2: Sub-project workflow cleanup
+   - Phase 3: Slash commands rewrite
+   - Phase 4: Core docs update
+
+3. Execute phase by phase, running /check-* after each
+
+4. /finish-work
+   → Final verification checklist
+
+5. Human commits multiple times, record with multiple commit hashes:
+   ./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
+
+3. Investigation loop:
+   - Analyze cloud vs local data
+   - Check sync event timestamps
+   - Review applyEvent logic
+   - Add debug logging
+
+4. /check-backend
+   → All checks passed
+
+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
+
+6. /finish-work
+   → Pre-commit checklist
+
+7. Human tests and commits
+
+8. /record-agent-flow
+   → Include lessons learned in session record
+```
+
+---
+
+## Key Points to Emphasize
+
 - 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`
 

package/package.json

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