@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
|
-
|
|
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
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
29
|
+
Explain the `workflow/` directory to the developer:
|
|
136
30
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
-
|
|
157
|
-
|
|
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
|
-
|
|
55
|
+
## INITIALIZE DEVELOPER
|
|
164
56
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
62
|
+
Then demonstrate context retrieval:
|
|
63
|
+
```bash
|
|
64
|
+
./workflow/scripts/get-context.sh
|
|
65
|
+
```
|
|
184
66
|
|
|
185
|
-
|
|
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
|
-
|
|
71
|
+
## CORE SLASH COMMANDS
|
|
194
72
|
|
|
195
|
-
|
|
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
|
-
|
|
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
|
-
|
|
210
|
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
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
|
-
|
|
233
|
-
- Catches integration issues early
|
|
234
|
-
- Ensures frontend and backend stay in sync
|
|
235
|
-
- Prevents runtime type mismatches
|
|
93
|
+
### Investigation Commands
|
|
236
94
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
-
|
|
240
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
266
|
-
-
|
|
267
|
-
-
|
|
268
|
-
-
|
|
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
|
-
|
|
112
|
+
**Scenario**: UI component missing after refactor
|
|
273
113
|
|
|
274
|
-
|
|
275
|
-
|
|
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
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
-
|
|
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
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
304
|
-
|
|
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
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
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
|
-
|
|
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
|
-
|
|
335
|
-
|
|
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
|
-
|
|
208
|
+
### Example 3: Code Review Fixes
|
|
340
209
|
|
|
341
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
349
|
-
|
|
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
|
-
|
|
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
|
-
|
|
356
|
-
|
|
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
|
-
|
|
361
|
-
|
|
362
|
-
### Example 1: Bug Fix Session
|
|
253
|
+
### Example 4: Large Refactoring
|
|
363
254
|
|
|
364
|
-
**Scenario**:
|
|
255
|
+
**Scenario**: Adapt workflow system for monorepo
|
|
365
256
|
|
|
366
257
|
```
|
|
367
|
-
1
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
423
|
-
|
|
424
|
-
|
|
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
|
-
|
|
428
|
-
|
|
279
|
+
Step 4: /finish-work
|
|
280
|
+
```
|
|
281
|
+
PURPOSE: Final verification across all phases.
|
|
282
|
+
- Ensure all phases are complete and consistent
|
|
429
283
|
|
|
430
|
-
|
|
431
|
-
|
|
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
|
-
|
|
434
|
-
- Add missing workspaceId filter (data isolation)
|
|
435
|
-
- Fix meta double-stringify bug
|
|
436
|
-
- Add LWW conflict resolution
|
|
290
|
+
---
|
|
437
291
|
|
|
438
|
-
|
|
439
|
-
-> All checks passed
|
|
292
|
+
### Example 5: Debug Session with Break Loop
|
|
440
293
|
|
|
441
|
-
|
|
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
|
-
|
|
456
|
-
|
|
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
|
-
|
|
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
|
-
|
|
467
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
479
|
-
|
|
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
|
-
|
|
482
|
-
-> Read sync and database guidelines
|
|
340
|
+
---
|
|
483
341
|
|
|
484
|
-
|
|
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
|
-
|
|
491
|
-
-> All checks passed
|
|
344
|
+
1. **AI NEVER commits** - Human tests and commits. AI prepares, human approves.
|
|
492
345
|
|
|
493
|
-
|
|
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
|
-
|
|
501
|
-
-> Pre-commit checklist
|
|
348
|
+
3. **Progress tracking** - Every session should end with /record-agent-flow.
|
|
502
349
|
|
|
503
|
-
|
|
350
|
+
4. **Break investigation loops** - Use /break-loop to stop research and capture findings.
|
|
504
351
|
|
|
505
|
-
|
|
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
|
-
|
|
512
|
-
|
|
513
|
-
|
|
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.
|