@mind-fold/open-flow 0.2.14 → 0.2.16
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.
|
@@ -2,6 +2,25 @@ You are a senior developer onboarding a new team member to this project's AI-ass
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
+
## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
|
|
6
|
+
|
|
7
|
+
This onboarding has TWO equally important parts:
|
|
8
|
+
|
|
9
|
+
**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
|
|
10
|
+
- Explain WHY this workflow exists
|
|
11
|
+
- Explain WHAT each command does and WHY
|
|
12
|
+
|
|
13
|
+
**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
|
|
14
|
+
- Walk through ALL 5 examples in detail
|
|
15
|
+
- For EACH step in EACH example, explain:
|
|
16
|
+
- PRINCIPLE: Why this step exists
|
|
17
|
+
- WHAT HAPPENS: What the command actually does
|
|
18
|
+
- IF SKIPPED: What goes wrong without it
|
|
19
|
+
|
|
20
|
+
DO NOT skip Part 2. The examples are NOT optional - they are the most important part for understanding how the workflow works in practice. A developer cannot truly understand the system without seeing real workflow examples.
|
|
21
|
+
|
|
22
|
+
After completing BOTH parts, ask the developer about their first task.
|
|
23
|
+
|
|
5
24
|
---
|
|
6
25
|
|
|
7
26
|
## CORE PHILOSOPHY: Why This Workflow Exists
|
|
@@ -53,6 +72,56 @@ workflow/
|
|
|
53
72
|
\-- scripts/ # Automation tools
|
|
54
73
|
```
|
|
55
74
|
|
|
75
|
+
### Understanding structure/ subdirectories
|
|
76
|
+
|
|
77
|
+
**frontend/** - Single-layer frontend knowledge:
|
|
78
|
+
- Component patterns (how to write components in THIS project)
|
|
79
|
+
- State management rules (Redux? Zustand? Context?)
|
|
80
|
+
- Styling conventions (CSS modules? Tailwind? Styled-components?)
|
|
81
|
+
- Hook patterns (custom hooks, data fetching)
|
|
82
|
+
|
|
83
|
+
**backend/** - Single-layer backend knowledge:
|
|
84
|
+
- API design patterns (REST? GraphQL? tRPC?)
|
|
85
|
+
- Database conventions (query patterns, migrations)
|
|
86
|
+
- Error handling standards
|
|
87
|
+
- Logging and monitoring rules
|
|
88
|
+
|
|
89
|
+
**flows/** - Cross-layer integration knowledge:
|
|
90
|
+
|
|
91
|
+
This is the CRITICAL directory that many developers overlook. It answers questions that NEITHER frontend nor backend docs can answer alone:
|
|
92
|
+
|
|
93
|
+
**WHY flows/ EXISTS**:
|
|
94
|
+
When a feature spans multiple layers (frontend + backend + database), there are integration concerns that don't belong in either layer's docs:
|
|
95
|
+
- How does data flow from UI click to database write and back?
|
|
96
|
+
- What's the contract between frontend and backend for this feature?
|
|
97
|
+
- What happens when one layer changes - what must the other layer update?
|
|
98
|
+
- How do we handle cross-layer error propagation?
|
|
99
|
+
- What's the deployment order when both layers change?
|
|
100
|
+
|
|
101
|
+
**WHAT flows/ CONTAINS**:
|
|
102
|
+
1. **Feature flow documentation**: End-to-end data flow for complex features
|
|
103
|
+
2. **API contracts**: Shared type definitions, request/response schemas
|
|
104
|
+
3. **Cross-layer checklists**: "When changing X, also check Y"
|
|
105
|
+
4. **Integration patterns**: How layers communicate in this project
|
|
106
|
+
5. **Deployment guides**: Order of operations for multi-layer changes
|
|
107
|
+
|
|
108
|
+
**WHEN TO READ flows/**:
|
|
109
|
+
- Before implementing ANY feature that touches both frontend and backend
|
|
110
|
+
- When debugging issues that might be integration-related
|
|
111
|
+
- Before making API changes
|
|
112
|
+
- When planning new features
|
|
113
|
+
|
|
114
|
+
**EXAMPLE**:
|
|
115
|
+
A "user authentication" flow doc might include:
|
|
116
|
+
- Frontend: What happens when user clicks login
|
|
117
|
+
- API: What endpoint is called, what's the request/response format
|
|
118
|
+
- Backend: How credentials are validated, session created
|
|
119
|
+
- Database: What gets stored, what gets returned
|
|
120
|
+
- Error cases: How each layer handles auth failures
|
|
121
|
+
- Security: Token handling, refresh logic
|
|
122
|
+
|
|
123
|
+
Without flows/ documentation, AI treats frontend and backend as isolated islands. With flows/, AI understands how the layers work TOGETHER.
|
|
124
|
+
|
|
56
125
|
---
|
|
57
126
|
|
|
58
127
|
## COMMAND DEEP DIVE
|
|
@@ -139,6 +208,71 @@ This causes "context drift" - AI starts following guidelines but gradually rever
|
|
|
139
208
|
|
|
140
209
|
---
|
|
141
210
|
|
|
211
|
+
### /check-cross-layer - Multi-Dimension Verification
|
|
212
|
+
|
|
213
|
+
**WHY IT EXISTS**:
|
|
214
|
+
`/check-frontend` and `/check-backend` verify code within a single layer. But most bugs don't come from lack of technical skill - they come from "didn't think of it":
|
|
215
|
+
- Changed a constant in one place, missed 5 other places using it
|
|
216
|
+
- Modified database schema, forgot to update the API layer
|
|
217
|
+
- Created a new utility function, but similar one already exists
|
|
218
|
+
- Fixed a bug in one component, but 3 other components have the same bug
|
|
219
|
+
|
|
220
|
+
**THE CORE INSIGHT**:
|
|
221
|
+
Real-world changes have multiple "dimensions" that need checking:
|
|
222
|
+
1. **Cross-layer data flow**: Does data flow correctly from UI -> API -> Service -> Database and back?
|
|
223
|
+
2. **Code reuse**: Are there duplicate definitions? Should this be a shared constant?
|
|
224
|
+
3. **Consistency**: Is the same concept displayed the same way in different places?
|
|
225
|
+
4. **Impact scope**: Did you check ALL files affected by this change?
|
|
226
|
+
|
|
227
|
+
**WHAT IT ACTUALLY DOES**:
|
|
228
|
+
1. Identifies which dimensions your change involves
|
|
229
|
+
2. For each dimension, runs targeted checks:
|
|
230
|
+
|
|
231
|
+
**Dimension A - Cross-Layer Data Flow** (when changes touch 3+ layers):
|
|
232
|
+
- Trace read flow: Database -> Service -> API -> Hook -> Component
|
|
233
|
+
- Trace write flow: Component -> Hook -> API -> Service -> Database
|
|
234
|
+
- Check types passed correctly between layers
|
|
235
|
+
- Check errors propagated to UI
|
|
236
|
+
- Check loading states at each layer
|
|
237
|
+
|
|
238
|
+
**Dimension B - Code Reuse** (when modifying constants/config):
|
|
239
|
+
- Search: How many places define this value?
|
|
240
|
+
- If 2+ places -> Should extract to shared constant
|
|
241
|
+
- After modification, all usage sites updated?
|
|
242
|
+
|
|
243
|
+
**Dimension B2 - New Utilities** (when creating helper functions):
|
|
244
|
+
- Search for existing similar utilities first
|
|
245
|
+
- If similar exists, extend instead of duplicate
|
|
246
|
+
- If new, is it in the right location?
|
|
247
|
+
|
|
248
|
+
**Dimension B3 - Batch Modifications** (after fixing multiple files):
|
|
249
|
+
- Did you check ALL files with similar patterns?
|
|
250
|
+
- Any files missed?
|
|
251
|
+
- Should this pattern be abstracted?
|
|
252
|
+
|
|
253
|
+
**Dimension C - Import Paths** (when creating new files):
|
|
254
|
+
- Using correct path aliases?
|
|
255
|
+
- No circular imports?
|
|
256
|
+
- Consistent with project convention?
|
|
257
|
+
|
|
258
|
+
**Dimension D - Same-Layer Consistency** (when modifying display logic):
|
|
259
|
+
- Search for other components using same concept
|
|
260
|
+
- Are displays consistent?
|
|
261
|
+
- Should they share configuration?
|
|
262
|
+
|
|
263
|
+
**WHY THIS MATTERS**:
|
|
264
|
+
- Without check-cross-layer: You fix one bug, but miss 5 related places. You create a utility that already exists. You change a constant but miss half the usages.
|
|
265
|
+
- With check-cross-layer: Systematic verification across all dimensions. No "didn't think of it" bugs.
|
|
266
|
+
|
|
267
|
+
**ANALOGY**: Like a pre-flight checklist for pilots. Not because pilots don't know how to fly, but because complex systems have many dimensions that are easy to overlook.
|
|
268
|
+
|
|
269
|
+
**RELATED DOCUMENTS** (referenced by this command):
|
|
270
|
+
- `workflow/structure/flows/pre-implementation-checklist.md` - Questions BEFORE coding
|
|
271
|
+
- `workflow/structure/flows/code-reuse-thinking-guide.md` - Pattern recognition
|
|
272
|
+
- `workflow/structure/flows/cross-layer-thinking-guide.md` - Data flow analysis
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
142
276
|
### /finish-work - Holistic Pre-Commit Review
|
|
143
277
|
|
|
144
278
|
**WHY IT EXISTS**:
|