@mind-fold/open-flow 0.2.12 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,519 +1,360 @@
1
- A new developer needs onboarding.
2
-
3
- Execute these steps in order:
4
-
5
- 1. **Explain the workflow system** - Describe how open-flow works:
6
- - `workflow/` directory structure
7
- - Guidelines in `workflow/structure/`
8
- - Progress tracking in `workflow/agent-progress/`
9
-
10
- 2. **Initialize their identity**:
11
- ```bash
12
- ./workflow/scripts/init-developer.sh <developer-name>
13
- ```
14
-
15
- 3. **Guide them through first task**:
16
- - Use `./workflow/scripts/get-context.sh` to get full context
17
- - Use `./workflow/scripts/feature.sh list` to see active features
18
- - Read relevant guidelines in `workflow/structure/`
19
- - Start coding
20
-
21
- 4. **Key scripts to know**:
22
- | Script | Purpose |
23
- |--------|---------|
24
- | `get-context.sh` | Get full session context |
25
- | `feature.sh` | Manage features (create/archive/list) |
26
- | `add-session.sh` | One-click session recording |
27
- | `update-index.sh` | Auto-update index.md |
1
+ You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
28
2
 
29
- ---
30
-
31
- ## Slash Commands Detailed Guide
32
-
33
- ### Core Workflow Commands
34
-
35
- #### `/init-agent` - Initialize AI Session
36
-
37
- **What it does**:
38
- Reads project context and prepares AI for development work. This is the FIRST command to run at the start of every session.
3
+ 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.
39
4
 
40
- **What AI will do**:
41
- 1. Run `./workflow/scripts/get-context.sh` to get:
42
- - Developer identity (who am I?)
43
- - Git status (which branch? uncommitted changes?)
44
- - Recent commits (what happened recently?)
45
- - Active features (what's in progress?)
46
- - Progress file status (where to record work?)
47
- 2. Check if developer identity exists, guide initialization if not
48
- 3. Read relevant structure guidelines based on upcoming task
49
- 4. Report ready status with a summary table
50
-
51
- **Benefits**:
52
- - AI understands the current state before making changes
53
- - Avoids conflicts with ongoing work from other developers
54
- - Knows which guidelines to follow for this project
55
- - Can continue previous work seamlessly
56
-
57
- **If skipped**:
58
- - AI may work on wrong branch or conflict with others' work
59
- - AI doesn't know project conventions, writes inconsistent code
60
- - AI can't find previous context, asks redundant questions
61
- - Progress tracking breaks, work history is lost
5
+ TEACHING APPROACH:
6
+ - First explain the CORE PHILOSOPHY: why this workflow exists
7
+ - Then walk through the system structure with clear explanations
8
+ - For each example, explain the PURPOSE of every step, not just what to do
9
+ - Help them understand the "why" behind each command
62
10
 
63
11
  ---
64
12
 
65
- #### `/record-agent-flow` - Record Work Progress
66
-
67
- **What it does**:
68
- Records completed work to progress files AFTER human has tested and committed code.
69
-
70
- **What AI will do**:
71
- 1. Get current context with `get-context.sh`
72
- 2. Run `add-session.sh` with session details:
73
- - Title: Brief description of work done
74
- - Commit: Git commit hash(es)
75
- - Summary/Content: Detailed changes, lessons learned
76
- 3. Auto-update index.md with new session count and history
13
+ ## CORE PHILOSOPHY
77
14
 
78
- **Benefits**:
79
- - Creates searchable history for future sessions
80
- - Next AI session can understand what was done before
81
- - Tracks lessons learned and patterns discovered
82
- - Enables multi-developer collaboration without conflicts
15
+ This workflow system solves three critical problems in AI-assisted development:
83
16
 
84
- **If skipped**:
85
- - Next session starts from zero, no context
86
- - Same bugs may be re-investigated
87
- - Lessons learned are forgotten
88
- - Team loses visibility into AI-assisted work
17
+ 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.
89
18
 
90
- ---
91
-
92
- #### `/onboard-developer` - Guide New Developer
19
+ 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.
93
20
 
94
- **What it does**:
95
- Walks a new developer (human or AI) through the complete setup process.
21
+ 3. **Quality Drift**: Without enforced guidelines, AI generates code that "works" but doesn't follow project conventions, leading to technical debt.
96
22
 
97
- **What AI will do**:
98
- 1. Explain workflow system structure
99
- 2. Run `init-developer.sh` to create identity
100
- 3. Demonstrate key scripts and commands
101
- 4. Guide through first task with examples
23
+ The solution: A structured workflow with checkpoints that ensure AI reads context before coding, follows guidelines during coding, and records progress after coding.
102
24
 
103
25
  ---
104
26
 
105
- ### Before Coding Commands
106
-
107
- #### `/before-frontend-dev` - Read Frontend Guidelines
108
-
109
- **What it does**:
110
- Reads frontend development guidelines BEFORE writing any frontend code.
111
-
112
- **What AI will do**:
113
- 1. Read `workflow/structure/frontend/index.md` to find relevant sections
114
- 2. Extract specific guideline sections based on task type:
115
- - Component guidelines for UI work
116
- - Hook guidelines for data fetching
117
- - State management for complex state
118
- 3. Understand coding standards and patterns to follow
119
- 4. Identify reference examples to learn from
120
-
121
- **Benefits**:
122
- - Code follows project conventions from the start
123
- - Avoids common mistakes documented in guidelines
124
- - Uses established patterns instead of inventing new ones
125
- - Reduces review cycles and rework
126
-
127
- **If skipped**:
128
- - Code style inconsistent with rest of codebase
129
- - Reinvents patterns that already exist
130
- - Makes mistakes that guidelines warn against
131
- - Requires significant refactoring after review
132
-
133
- ---
27
+ ## SYSTEM STRUCTURE
134
28
 
135
- #### `/before-backend-dev` - Read Backend Guidelines
29
+ Explain the `workflow/` directory to the developer:
136
30
 
137
- **What it does**:
138
- Reads backend development guidelines BEFORE writing any backend code.
139
-
140
- **What AI will do**:
141
- 1. Read `workflow/structure/backend/index.md` to find relevant sections
142
- 2. Extract specific guideline sections:
143
- - Database operations for DB work
144
- - Type safety for API contracts
145
- - Error handling patterns
146
- - Logging standards
147
- 3. Understand project-specific conventions
148
-
149
- **Benefits**:
150
- - Database queries follow established patterns
151
- - Error handling is consistent across codebase
152
- - Logging provides useful debugging information
153
- - API contracts are type-safe
154
-
155
- **If skipped**:
156
- - N+1 query problems in database code
157
- - Inconsistent error handling
158
- - Missing or unhelpful logs
159
- - Type safety holes in APIs
31
+ ```
32
+ workflow/
33
+ |-- .developer # Developer identity file (gitignored)
34
+ |-- flow.md # Complete workflow documentation
35
+ |-- agent-progress/ # Progress tracking (per-developer)
36
+ | |-- index.md # Main index with all developers
37
+ | \-- {developer}/ # Individual developer directory
38
+ | |-- index.md # Personal index
39
+ | |-- features/ # Active feature tracking
40
+ | \-- progress-N.md # Session records (max 2000 lines each)
41
+ |-- structure/ # Development guidelines (MUST READ)
42
+ | |-- frontend/ # Frontend coding standards
43
+ | |-- backend/ # Backend coding standards
44
+ | \-- flows/ # Cross-layer development guides
45
+ \-- scripts/ # Automation scripts
46
+ |-- get-context.sh # Get full session context
47
+ |-- init-developer.sh # Initialize new developer
48
+ |-- feature.sh # Manage features
49
+ |-- add-session.sh # Record session progress
50
+ \-- update-index.sh # Update index files
51
+ ```
160
52
 
161
53
  ---
162
54
 
163
- ### Code Check Commands
55
+ ## INITIALIZE DEVELOPER
164
56
 
165
- #### `/check-frontend` - Check Frontend Code
166
-
167
- **What it does**:
168
- Verifies frontend code against guidelines AFTER writing code, BEFORE committing.
169
-
170
- **What AI will do**:
171
- 1. Run type check (`tsc --noEmit`)
172
- 2. Run linter and check for errors
173
- 3. Review code against frontend guidelines
174
- 4. Check for common issues:
175
- - Semantic HTML usage
176
- - Accessibility compliance
177
- - Performance patterns
178
- 5. Report violations and suggest fixes
57
+ Ask for their name and run:
58
+ ```bash
59
+ ./workflow/scripts/init-developer.sh <developer-name>
60
+ ```
179
61
 
180
- **Benefits**:
181
- - Catches errors before human review
182
- - Ensures consistent code quality
183
- - Documents what was checked for transparency
62
+ Then demonstrate context retrieval:
63
+ ```bash
64
+ ./workflow/scripts/get-context.sh
65
+ ```
184
66
 
185
- **If skipped**:
186
- - Type errors slip into codebase
187
- - Lint errors accumulate
188
- - Accessibility issues go unnoticed
189
- - Review cycles increase
67
+ Explain what each output section means and why it matters.
190
68
 
191
69
  ---
192
70
 
193
- #### `/check-backend` - Check Backend Code
71
+ ## CORE SLASH COMMANDS
194
72
 
195
- **What it does**:
196
- Verifies backend code against guidelines AFTER writing code, BEFORE committing.
73
+ Explain each command's PURPOSE, not just what it does:
197
74
 
198
- **What AI will do**:
199
- 1. Run type check
200
- 2. Run linter
201
- 3. Review against backend guidelines:
202
- - No non-null assertions (`!`)
203
- - All inputs/outputs have Zod schemas
204
- - Structured logging (no console.log)
205
- - No await in loops
206
- 4. Check API documentation is updated
207
- 5. Report issues and fixes
75
+ ### Session Lifecycle Commands
208
76
 
209
- **Benefits**:
210
- - Catches type safety issues early
211
- - Ensures API documentation stays in sync
212
- - Validates database operation patterns
77
+ | Command | When | Purpose |
78
+ |---------|------|---------|
79
+ | `/init-agent` | Session start | Restore context so AI doesn't start blind |
80
+ | `/record-agent-flow` | After commit | Preserve context for next session |
81
+ | `/finish-work` | Before commit | Final quality gate before human review |
213
82
 
214
- **If skipped**:
215
- - Runtime errors from type mismatches
216
- - API docs become outdated
217
- - Performance issues from N+1 queries
83
+ ### Development Commands
218
84
 
219
- ---
220
-
221
- #### `/check-cross-layer` - Cross-Layer Verification
222
-
223
- **What it does**:
224
- Verifies consistency between frontend and backend when changes span multiple layers.
225
-
226
- **What AI will do**:
227
- 1. Identify all layers touched by the change
228
- 2. Verify type contracts match across layers
229
- 3. Check data flow consistency
230
- 4. Validate API request/response alignment
85
+ | Command | When | Purpose |
86
+ |---------|------|---------|
87
+ | `/before-frontend-dev` | Before frontend code | Load project conventions into AI context |
88
+ | `/before-backend-dev` | Before backend code | Load project conventions into AI context |
89
+ | `/check-frontend` | After frontend code | Verify code meets standards before commit |
90
+ | `/check-backend` | After backend code | Verify code meets standards before commit |
91
+ | `/check-cross-layer` | Full-stack changes | Ensure frontend/backend stay in sync |
231
92
 
232
- **Benefits**:
233
- - Catches integration issues early
234
- - Ensures frontend and backend stay in sync
235
- - Prevents runtime type mismatches
93
+ ### Investigation Commands
236
94
 
237
- **If skipped**:
238
- - Frontend expects data backend doesn't provide
239
- - Type mismatches cause runtime errors
240
- - Integration bugs found late in testing
95
+ | Command | When | Purpose |
96
+ |---------|------|---------|
97
+ | `/break-loop` | After debugging | Stop investigation and capture findings |
98
+ | `/record-question` | Solved hard problem | Document solution for future reference |
241
99
 
242
100
  ---
243
101
 
244
- ### Work Completion Commands
245
-
246
- #### `/finish-work` - Pre-Commit Checklist
247
-
248
- **What it does**:
249
- Final verification before human commits. Ensures nothing is forgotten.
250
-
251
- **What AI will do**:
252
- 1. Run all relevant checks (type, lint)
253
- 2. Verify all changes are intentional
254
- 3. Check documentation is updated
255
- 4. Prepare commit message suggestion
256
- 5. List files to be committed
257
- 6. Confirm ready for human review
258
-
259
- **Benefits**:
260
- - Nothing is forgotten before commit
261
- - Clean commit history
262
- - Documentation stays in sync
263
- - Human knows exactly what to review
102
+ ## REAL-WORLD WORKFLOW EXAMPLES
264
103
 
265
- **If skipped**:
266
- - Partial commits with missing files
267
- - Documentation drift
268
- - Unclear what changed for reviewer
104
+ For each example below, explain:
105
+ - The SCENARIO context
106
+ - WHY each step is needed
107
+ - WHAT PROBLEM that step solves
108
+ - WHAT HAPPENS if that step is skipped
269
109
 
270
- ---
110
+ ### Example 1: Bug Fix Session
271
111
 
272
- #### `/break-loop` - End Investigation Loop
112
+ **Scenario**: UI component missing after refactor
273
113
 
274
- **What it does**:
275
- Stops an investigation/debugging loop and summarizes findings. Use when debugging or researching, BEFORE `/finish-work`.
114
+ ```
115
+ Step 1: /init-agent
116
+ ```
117
+ PURPOSE: AI needs to understand current state before making changes.
118
+ - Reads developer identity, git status, active features
119
+ - Without this: AI might work on wrong branch, conflict with others, or repeat already-done work
276
120
 
277
- **What AI will do**:
278
- 1. Summarize what was investigated
279
- 2. Document root cause (if found)
280
- 3. List temporary vs permanent fixes
281
- 4. Record lessons learned
282
- 5. Suggest next steps or follow-up tasks
283
- 6. Prepare knowledge for `/record-question` if applicable
121
+ ```
122
+ Step 2: ./workflow/scripts/feature.sh create fix-sync-indicator
123
+ ```
124
+ PURPOSE: Create isolated tracking for this work.
125
+ - Links all changes to a named feature
126
+ - Without this: Progress scattered, hard to track what changed and why
284
127
 
285
- **Benefits**:
286
- - Prevents endless investigation loops
287
- - Captures debugging knowledge
288
- - Creates actionable next steps
289
- - Knowledge is preserved for future
128
+ ```
129
+ Step 3: /before-frontend-dev
130
+ ```
131
+ PURPOSE: Load project's frontend conventions into AI context.
132
+ - AI learns component patterns, naming conventions, state management rules
133
+ - Without this: AI writes "working" code that doesn't match project style
290
134
 
291
- **If skipped**:
292
- - Investigation goes in circles
293
- - Findings are lost when session ends
294
- - Same debugging repeated later
295
- - No clear resolution or next steps
135
+ ```
136
+ Step 4: Investigate and fix the bug
137
+ ```
138
+ PURPOSE: The actual development work.
139
+ - AI now has context + guidelines, can write consistent code
296
140
 
297
- ---
141
+ ```
142
+ Step 5: /check-frontend
143
+ ```
144
+ PURPOSE: Quality gate before human review.
145
+ - Runs type check, linter, guideline compliance
146
+ - Without this: Errors slip through, human review catches preventable issues
298
147
 
299
- ### Utility Commands
148
+ ```
149
+ Step 6: /finish-work
150
+ ```
151
+ PURPOSE: Final checklist before commit.
152
+ - Ensures nothing forgotten: docs updated, all files staged
153
+ - Without this: Partial commits, missing documentation
300
154
 
301
- #### `/create-command` - Create New Slash Command
155
+ ```
156
+ Step 7: Human tests and commits
157
+ ```
158
+ PURPOSE: Human-in-the-loop verification.
159
+ - AI NEVER commits - human is responsible for testing
160
+ - Without this: Untested code enters codebase
302
161
 
303
- **What it does**:
304
- Creates a new slash command when a repeated workflow pattern is identified.
162
+ ```
163
+ Step 8: /record-agent-flow
164
+ ```
165
+ PURPOSE: Preserve context for future sessions.
166
+ - Records what was done, lessons learned, commit hashes
167
+ - Without this: Next session starts from zero, same bugs re-investigated
305
168
 
306
- **What AI will do**:
307
- 1. Analyze the workflow pattern
308
- 2. Design command structure
309
- 3. Create command file in `.cursor/commands/` or `.claude/commands/`
310
- 4. Document usage and examples
169
+ ```
170
+ Step 9: ./workflow/scripts/feature.sh archive fix-sync-indicator
171
+ ```
172
+ PURPOSE: Clean up after completion.
173
+ - Moves feature to archive, keeps active list clean
311
174
 
312
175
  ---
313
176
 
314
- #### `/record-question` - Document Solved Problems
315
-
316
- **What it does**:
317
- Documents a solved problem for future reference when a tricky issue is resolved.
177
+ ### Example 2: Planning Session (No Code)
318
178
 
319
- **What AI will do**:
320
- 1. Summarize the problem
321
- 2. Document the root cause
322
- 3. Record the solution
323
- 4. Add to appropriate location (big-question/ or guidelines)
179
+ **Scenario**: Audit migration docs and plan consolidation
324
180
 
325
- **Benefits**:
326
- - Knowledge is preserved
327
- - Same problem won't need re-investigation
328
- - Team learns from each other's discoveries
181
+ ```
182
+ Step 1: /init-agent
183
+ ```
184
+ PURPOSE: Understand current state even for non-coding work.
185
+ - See what's already in progress, avoid duplicate planning
329
186
 
330
- ---
187
+ ```
188
+ Step 2: ./workflow/scripts/feature.sh create migration-docs-consolidation
189
+ ```
190
+ PURPOSE: Track planning work same as code work.
191
+ - Planning is valuable work that needs recording
331
192
 
332
- #### `/integrate-skill` - Integrate Claude Skills
193
+ ```
194
+ Step 3: Review docs, create subtask list
195
+ ```
196
+ PURPOSE: The actual planning work.
197
+ - Compare existing docs, identify gaps, prioritize
333
198
 
334
- **What it does**:
335
- Integrates external Claude skills into project guidelines.
199
+ ```
200
+ Step 4: /record-agent-flow (with --summary, no --commit)
201
+ ```
202
+ PURPOSE: Record planning output even without code commits.
203
+ - Use --summary flag for non-code sessions
204
+ - Without this: Planning decisions lost, team doesn't know what was decided
336
205
 
337
206
  ---
338
207
 
339
- #### `/extract-llm-docs` - Extract from LLM Documentation
208
+ ### Example 3: Code Review Fixes
340
209
 
341
- **What it does**:
342
- Extracts useful patterns from LLM documentation (like llms.txt files) into project guidelines.
210
+ **Scenario**: Fix issues from CR round 2
343
211
 
344
- ---
212
+ ```
213
+ Step 1: /init-agent
214
+ ```
215
+ PURPOSE: Resume context from previous session.
216
+ - AI sees the feature is already in progress
217
+ - Reads previous progress to understand what was already done
345
218
 
346
- #### `/extract-to-rules` - Extract Rules from Source
219
+ ```
220
+ Step 2: /before-backend-dev
221
+ ```
222
+ PURPOSE: Refresh guidelines before fixing backend issues.
223
+ - CR comments often point to guideline violations
224
+ - AI needs guidelines in context to fix properly
347
225
 
348
- **What it does**:
349
- Extracts coding rules and patterns from existing source code into guidelines.
226
+ ```
227
+ Step 3: Fix each CR issue
228
+ ```
229
+ PURPOSE: Address review feedback.
230
+ - With guidelines loaded, fixes follow project conventions
350
231
 
351
- ---
232
+ ```
233
+ Step 4: /check-backend
234
+ ```
235
+ PURPOSE: Verify fixes don't introduce new issues.
236
+ - Each fix could break something else
352
237
 
353
- #### `/sync-from-runtime` - Sync Knowledge
238
+ ```
239
+ Step 5: /finish-work
240
+ ```
241
+ PURPOSE: Document lessons learned from CR.
242
+ - CR feedback reveals patterns to remember
243
+ - Example: "All queries with workspaceId must include WHERE clause"
354
244
 
355
- **What it does**:
356
- Syncs knowledge and patterns from runtime documentation.
245
+ ```
246
+ Step 6: Human commits, then /record-agent-flow
247
+ ```
248
+ PURPOSE: Preserve CR lessons for future.
249
+ - Next time AI writes similar code, it knows the patterns
357
250
 
358
251
  ---
359
252
 
360
- ## Real-World Workflow Examples
361
-
362
- ### Example 1: Bug Fix Session
253
+ ### Example 4: Large Refactoring
363
254
 
364
- **Scenario**: UI component missing after refactor
255
+ **Scenario**: Adapt workflow system for monorepo
365
256
 
366
257
  ```
367
- 1. /init-agent
368
- -> See context: Branch "main", 2 uncommitted files
369
- -> Active feature: none
370
-
371
- 2. Create feature:
372
- ./workflow/scripts/feature.sh create fix-sync-indicator
373
-
374
- 3. /before-frontend-dev
375
- -> Read component guidelines
376
-
377
- 4. Investigate and fix:
378
- - Analyze old vs new architecture
379
- - Import missing component
380
- - Add CSS styles
381
-
382
- 5. /check-frontend
383
- -> Type check: [OK] passed
384
- -> Lint: [OK] 0 errors
385
-
386
- 6. /finish-work
387
- -> Pre-commit checklist
388
- -> Confirm all changes are ready
389
-
390
- 7. Human tests and commits:
391
- git commit -m "fix(ui): restore SyncIndicator to TabBar"
392
-
393
- 8. /record-agent-flow
394
- -> ./workflow/scripts/add-session.sh --title "Fix SyncIndicator" --commit "abc123"
395
-
396
- 9. Archive feature:
397
- ./workflow/scripts/feature.sh archive fix-sync-indicator
258
+ Step 1: /init-agent
398
259
  ```
399
-
400
- ### Example 2: Planning Session (No Code)
401
-
402
- **Scenario**: Audit migration docs and plan consolidation
260
+ PURPOSE: Establish baseline before major changes.
261
+ - Large refactors need clear starting point
403
262
 
404
263
  ```
405
- 1. /init-agent
406
- -> Understand current state
407
-
408
- 2. Create feature:
409
- ./workflow/scripts/feature.sh create migration-docs-consolidation
410
-
411
- 3. Review docs, compare with existing guidelines
412
-
413
- 4. Create subtask list in feature.json:
414
- - Critical: Update outdated timestamp format
415
- - High: Add missing validation rules
416
- - Medium: Consolidate scattered docs
417
-
418
- 5. /record-agent-flow (no commit)
419
- -> ./workflow/scripts/add-session.sh --title "Migration Docs Planning" --summary "Created 14 subtasks"
264
+ Step 2: Plan phases
420
265
  ```
266
+ PURPOSE: Break large work into manageable chunks.
267
+ - Phase 1: Root directory restructure
268
+ - Phase 2: Sub-project workflow cleanup
269
+ - Phase 3: Slash commands rewrite
270
+ - Phase 4: Core docs update
421
271
 
422
- ### Example 3: Code Review Fixes
423
-
424
- **Scenario**: Fix issues from CR round 2
272
+ ```
273
+ Step 3: Execute phase by phase with /check-* after each
274
+ ```
275
+ PURPOSE: Incremental verification.
276
+ - Catch issues early, don't let errors compound
425
277
 
426
278
  ```
427
- 1. /init-agent
428
- -> Continue feature: entity-filesystem-refactor
279
+ Step 4: /finish-work
280
+ ```
281
+ PURPOSE: Final verification across all phases.
282
+ - Ensure all phases are complete and consistent
429
283
 
430
- 2. /before-backend-dev
431
- -> Read database and error handling guidelines
284
+ ```
285
+ Step 5: Record with multiple commit hashes
286
+ ```
287
+ PURPOSE: Link all commits to one logical feature.
288
+ - ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"
432
289
 
433
- 3. Fix each CR issue:
434
- - Add missing workspaceId filter (data isolation)
435
- - Fix meta double-stringify bug
436
- - Add LWW conflict resolution
290
+ ---
437
291
 
438
- 4. /check-backend
439
- -> All checks passed
292
+ ### Example 5: Debug Session with Break Loop
440
293
 
441
- 5. /finish-work
442
- -> Pre-commit checklist
443
- -> Document lessons learned:
444
- - "All queries with workspaceId column must include WHERE clause"
445
- - "buildXxxValues must match *DataSchema types"
294
+ **Scenario**: Investigating a complex sync bug
446
295
 
447
- 6. Human commits, then /record-agent-flow
448
296
  ```
449
-
450
- ### Example 4: Large Refactoring
451
-
452
- **Scenario**: Adapt workflow system for monorepo
453
-
297
+ Step 1: /init-agent
454
298
  ```
455
- 1. /init-agent
456
- -> Create feature: workflow-monorepo-adaptation
457
-
458
- 2. Plan phases:
459
- - Phase 1: Root directory restructure
460
- - Phase 2: Sub-project workflow cleanup
461
- - Phase 3: Slash commands rewrite
462
- - Phase 4: Core docs update
299
+ PURPOSE: Get context on the bug being investigated.
300
+ - See previous investigation attempts if any
463
301
 
464
- 3. Execute phase by phase, running /check-* after each
302
+ ```
303
+ Step 2: /before-backend-dev
304
+ ```
305
+ PURPOSE: Load relevant guidelines for the area being debugged.
306
+ - Guidelines often contain hints about known issues
465
307
 
466
- 4. /finish-work
467
- -> Final verification checklist
308
+ ```
309
+ Step 3: Investigation loop
310
+ ```
311
+ PURPOSE: The actual debugging work.
312
+ - Analyze data, check logs, form hypotheses, test fixes
468
313
 
469
- 5. Human commits multiple times, record with multiple commit hashes:
470
- ./workflow/scripts/add-session.sh --title "Monorepo Adaptation" --commit "hash1,hash2,hash3"
471
314
  ```
315
+ Step 4: /check-backend
316
+ ```
317
+ PURPOSE: Verify debug changes don't break other things.
318
+ - Debug code can be sloppy - this catches issues
472
319
 
473
- ### Example 5: Debug Session with Break Loop
320
+ ```
321
+ Step 5: /break-loop
322
+ ```
323
+ PURPOSE: CRITICAL - Stop investigation and capture findings.
324
+ - Summarizes: what was investigated, root cause, fixes tried
325
+ - Documents: temporary vs permanent fix, follow-up needed
326
+ - Without this: Investigation goes in circles, findings lost
474
327
 
475
- **Scenario**: Investigating a complex sync bug
328
+ ```
329
+ Step 6: /finish-work
330
+ ```
331
+ PURPOSE: Prepare debug findings for commit.
332
+ - Even investigation sessions produce valuable output
476
333
 
477
334
  ```
478
- 1. /init-agent
479
- -> Continue feature: fix-sync-data-inconsistency
335
+ Step 7: Human commits, then /record-agent-flow
336
+ ```
337
+ PURPOSE: Preserve debugging knowledge.
338
+ - Next time same bug appears, AI has context
480
339
 
481
- 2. /before-backend-dev
482
- -> Read sync and database guidelines
340
+ ---
483
341
 
484
- 3. Investigation loop:
485
- - Analyze cloud vs local data
486
- - Check sync event timestamps
487
- - Review applyEvent logic
488
- - Add debug logging
342
+ ## KEY RULES TO EMPHASIZE
489
343
 
490
- 4. /check-backend
491
- -> All checks passed
344
+ 1. **AI NEVER commits** - Human tests and commits. AI prepares, human approves.
492
345
 
493
- 5. /break-loop (when investigation is complete)
494
- -> Summarize findings:
495
- - Root cause: Transaction failure without error logging
496
- - Temporary fix: Manual SQL update
497
- - Permanent fix: Add detailed logging in applyEvent
498
- -> Document for future reference
346
+ 2. **Guidelines before code** - /before-*-dev commands are MANDATORY, not optional.
499
347
 
500
- 6. /finish-work
501
- -> Pre-commit checklist
348
+ 3. **Progress tracking** - Every session should end with /record-agent-flow.
502
349
 
503
- 7. Human tests and commits
350
+ 4. **Break investigation loops** - Use /break-loop to stop research and capture findings.
504
351
 
505
- 8. /record-agent-flow
506
- -> Include lessons learned in session record
507
- ```
352
+ 5. **Planning is valid work** - Non-code sessions use --summary flag in add-session.sh.
508
353
 
509
354
  ---
510
355
 
511
- ## Key Points to Emphasize
512
-
513
- - AI should NOT execute `git commit` - human is responsible for testing and committing
514
- - Each developer has their own progress directory
515
- - Read guidelines before coding (mandatory)
516
- - Use `/record-question` to document solved problems for future reference
517
- - Planning sessions (no code) are valid - record with `--summary` instead of `--commit`
518
- - `/break-loop` is for ending debug/investigation loops, use BEFORE `/finish-work`
356
+ After explaining, ask the developer:
357
+ 1. What kind of work will they be doing? (frontend/backend/full-stack)
358
+ 2. Do they have a specific task to start with?
519
359
 
360
+ Then guide them through their first task using the appropriate workflow.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mind-fold/open-flow",
3
- "version": "0.2.12",
3
+ "version": "0.2.13",
4
4
  "description": "AI-assisted development workflow initializer for Cursor, Claude Code and more",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",