@mind-fold/open-flow 0.2.11 → 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.
Files changed (40) hide show
  1. package/dist/templates/commands/break-loop.txt +1 -1
  2. package/dist/templates/commands/check-cross-layer.txt +3 -3
  3. package/dist/templates/commands/create-command.txt +5 -5
  4. package/dist/templates/commands/extract-llm-docs.txt +18 -18
  5. package/dist/templates/commands/extract-to-rules.txt +38 -38
  6. package/dist/templates/commands/finish-work.txt +5 -5
  7. package/dist/templates/commands/generate-backend-structure.txt +27 -27
  8. package/dist/templates/commands/generate-frontend-structure.txt +15 -15
  9. package/dist/templates/commands/integrate-skill.txt +30 -30
  10. package/dist/templates/commands/onboard-developer.txt +257 -416
  11. package/dist/templates/commands/record-agent-flow.txt +4 -4
  12. package/dist/templates/commands/sync-from-runtime.txt +2 -2
  13. package/dist/templates/markdown/agent-progress-index.md.txt +9 -9
  14. package/dist/templates/markdown/backend-doc.md.txt +12 -12
  15. package/dist/templates/markdown/flow.md.txt +99 -99
  16. package/dist/templates/markdown/frontend-doc.md.txt +11 -11
  17. package/dist/templates/markdown/structure/backend/database-guidelines.md.txt +6 -6
  18. package/dist/templates/markdown/structure/backend/directory-structure.md.txt +28 -28
  19. package/dist/templates/markdown/structure/backend/index.md.txt +10 -10
  20. package/dist/templates/markdown/structure/backend/logging-guidelines.md.txt +4 -4
  21. package/dist/templates/markdown/structure/backend/quality-guidelines.md.txt +12 -12
  22. package/dist/templates/markdown/structure/backend/type-safety.md.txt +6 -6
  23. package/dist/templates/markdown/structure/flows/code-reuse-thinking-guide.md.txt +17 -17
  24. package/dist/templates/markdown/structure/flows/cross-layer-thinking-guide.md.txt +96 -96
  25. package/dist/templates/markdown/structure/flows/index.md.txt +31 -31
  26. package/dist/templates/markdown/structure/flows/pre-implementation-checklist.md.txt +19 -19
  27. package/dist/templates/markdown/structure/flows/spec-flow-template.md.txt +20 -20
  28. package/dist/templates/markdown/structure/frontend/component-guidelines.md.txt +12 -12
  29. package/dist/templates/markdown/structure/frontend/directory-structure.md.txt +61 -61
  30. package/dist/templates/markdown/structure/frontend/hook-guidelines.md.txt +5 -5
  31. package/dist/templates/markdown/structure/frontend/index.md.txt +13 -13
  32. package/dist/templates/markdown/structure/frontend/quality-guidelines.md.txt +21 -21
  33. package/dist/templates/markdown/structure/frontend/state-management.md.txt +12 -12
  34. package/dist/templates/markdown/structure/frontend/type-safety.md.txt +11 -11
  35. package/dist/templates/scripts/add-session.sh.txt +5 -5
  36. package/dist/templates/scripts/extract-md-headings.sh.txt +3 -3
  37. package/dist/templates/scripts/get-context.sh.txt +1 -1
  38. package/dist/templates/scripts/init-developer.sh.txt +1 -1
  39. package/dist/templates/scripts/update-index.sh.txt +2 -2
  40. package/package.json +1 -1
@@ -1,4 +1,4 @@
1
- ⚠️ **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
1
+ [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
2
2
 
3
3
  **AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
4
4
 
@@ -35,9 +35,9 @@ EOF
35
35
  ```
36
36
 
37
37
  **Auto-completes**:
38
- - Appends session to progress-N.md
39
- - Auto-detects line count, creates new file if >2000 lines
40
- - Updates index.md (Total Sessions +1, Last Active, line stats, history)
38
+ - [OK] Appends session to progress-N.md
39
+ - [OK] Auto-detects line count, creates new file if >2000 lines
40
+ - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
41
41
 
42
42
  ---
43
43
 
@@ -120,8 +120,8 @@ After sync, report:
120
120
  ### Synced Docs
121
121
  | Doc | Status | Notes |
122
122
  |-----|--------|-------|
123
- | database-guidelines.md | Added | Adapted from Turso to generic ORM |
124
- | logging-guidelines.md | Added | No changes needed |
123
+ | database-guidelines.md | [OK] Added | Adapted from Turso to generic ORM |
124
+ | logging-guidelines.md | [OK] Added | No changes needed |
125
125
 
126
126
  ### Updated Files
127
127
  - workflow/structure/backend/index.md (added links)
@@ -12,13 +12,13 @@ This directory tracks progress for all developers working with AI Agents on this
12
12
 
13
13
  ```
14
14
  agent-progress/
15
- ├── index.md # This file - main index
16
- └── {developer}/ # Per-developer directory
17
- ├── index.md # Personal index with session history
18
- ├── features/ # Feature files
19
- ├── *.json # Active features
20
- └── archive/ # Archived features by month
21
- └── progress-N.md # Progress files (sequential: 1, 2, 3...)
15
+ |-- index.md # This file - main index
16
+ \-- {developer}/ # Per-developer directory
17
+ |-- index.md # Personal index with session history
18
+ |-- features/ # Feature files
19
+ | |-- *.json # Active features
20
+ | \-- archive/ # Archived features by month
21
+ \-- progress-N.md # Progress files (sequential: 1, 2, 3...)
22
22
  ```
23
23
 
24
24
  ---
@@ -106,11 +106,11 @@ Use this template when recording sessions:
106
106
 
107
107
  ### Testing
108
108
 
109
- - {Test result}
109
+ - [OK] {Test result}
110
110
 
111
111
  ### Status
112
112
 
113
- **Completed** / 🔄 **In Progress** / ⏸️ **Blocked**
113
+ [OK] **Completed** / # **In Progress** / [P] **Blocked**
114
114
 
115
115
  ### Next Steps
116
116
 
@@ -9,12 +9,12 @@
9
9
 
10
10
  ```
11
11
  packages/api/modules/
12
- ├── {module}/
13
- ├── router.ts # Route definitions
14
- ├── procedures/ # Business logic
15
- ├── types.ts # Type definitions
16
- └── api/ # API documentation
17
- └── *.md
12
+ |-- {module}/
13
+ | |-- router.ts # Route definitions
14
+ | |-- procedures/ # Business logic
15
+ | |-- types.ts # Type definitions
16
+ | \-- api/ # API documentation
17
+ | \-- *.md
18
18
  ```
19
19
 
20
20
  @@@/section:directory-structure
@@ -28,14 +28,14 @@ packages/api/modules/
28
28
  ### No Non-Null Assertions
29
29
 
30
30
  ```typescript
31
- // Good - use local variable
31
+ // [OK] Good - use local variable
32
32
  const user = await getUser(id);
33
33
  if (!user) {
34
34
  throw new Error('User not found');
35
35
  }
36
36
  const userName = user.name; // Safe access
37
37
 
38
- // Bad - non-null assertion
38
+ // [X] Bad - non-null assertion
39
39
  const userName = user!.name;
40
40
  ```
41
41
 
@@ -69,12 +69,12 @@ const outputSchema = z.object({
69
69
  ### No Await in Loops
70
70
 
71
71
  ```typescript
72
- // Good - parallel execution
72
+ // [OK] Good - parallel execution
73
73
  const results = await Promise.all(
74
74
  ids.map(id => db.query.users.findFirst({ where: eq(users.id, id) }))
75
75
  );
76
76
 
77
- // Bad - sequential execution
77
+ // [X] Bad - sequential execution
78
78
  for (const id of ids) {
79
79
  await db.query.users.findFirst({ where: eq(users.id, id) });
80
80
  }
@@ -111,10 +111,10 @@ await db.insert(users).values(data).onConflictDoUpdate({
111
111
  ### Use Structured Logging
112
112
 
113
113
  ```typescript
114
- // Good
114
+ // [OK] Good
115
115
  logger.info('User created', { userId: user.id, email: user.email });
116
116
 
117
- // Bad
117
+ // [X] Bad
118
118
  console.log('User created: ' + user.id);
119
119
  ```
120
120
 
@@ -20,51 +20,51 @@
20
20
  ### Core Principles
21
21
 
22
22
  1. **Read Before Write** - Understand context before starting
23
- 2. **Follow Standards** - ⚠️ **MUST read `workflow/structure/` guidelines before coding**
23
+ 2. **Follow Standards** - [!] **MUST read `workflow/structure/` guidelines before coding**
24
24
  3. **Incremental Development** - Complete one feature at a time
25
25
  4. **Record Promptly** - Update tracking files immediately after completion
26
- 5. **Document Limits** - ⚠️ **Max 2000 lines per agent-progress document**
26
+ 5. **Document Limits** - [!] **Max 2000 lines per agent-progress document**
27
27
 
28
28
  ### File System
29
29
 
30
30
  ```
31
31
  workflow/
32
- ├── .developer # Developer identity (gitignored)
33
- ├── scripts/
34
- ├── init-developer.sh # Initialize developer identity
35
- ├── get-developer.sh # Get current developer name
36
- ├── feature.sh # Manage features
37
- ├── get-context.sh # Get session context
38
- ├── update-index.sh # Auto-update index.md
39
- └── add-session.sh # One-click session recording
40
- ├── agent-progress/ # AI Agent work progress records
41
- ├── index.md # Progress index + Session template
42
- └── {developer}/ # Per-developer directories
43
- ├── index.md # Personal index (with @@@auto markers)
44
- ├── features/ # Feature tracking
45
- └── progress-N.md # Progress files (sequential numbering)
46
- ├── structure/ # ⚠️ MUST READ before coding
47
- ├── frontend/ # Frontend guidelines (multi-doc)
48
- ├── index.md # Start here - guidelines index
49
- ├── directory-structure.md # Directory layout
50
- ├── type-safety.md # TypeScript patterns
51
- ├── hook-guidelines.md # React Query hooks
52
- ├── component-guidelines.md # Component patterns
53
- ├── state-management.md # State patterns
54
- └── quality-guidelines.md # Code standards
55
- ├── backend/ # Backend guidelines (multi-doc)
56
- ├── index.md # Start here - guidelines index
57
- ├── directory-structure.md # Directory layout
58
- ├── type-safety.md # Zod, TypeScript patterns
59
- ├── database-guidelines.md # ORM, batch operations
60
- ├── logging-guidelines.md # Structured logging
61
- ├── error-handling.md # Error types, handling
62
- └── quality-guidelines.md # Code standards
63
- └── flows/ # Cross-layer specifications
64
- ├── index.md # Flow specs index
65
- ├── cross-layer-thinking-guide.md # Pre-implementation checklist
66
- └── spec-flow-template.md # Template for new flows
67
- └── flow.md # This document
32
+ |-- .developer # Developer identity (gitignored)
33
+ |-- scripts/
34
+ | |-- init-developer.sh # Initialize developer identity
35
+ | |-- get-developer.sh # Get current developer name
36
+ | |-- feature.sh # Manage features
37
+ | |-- get-context.sh # Get session context
38
+ | |-- update-index.sh # Auto-update index.md
39
+ | \-- add-session.sh # One-click session recording
40
+ |-- agent-progress/ # AI Agent work progress records
41
+ | |-- index.md # Progress index + Session template
42
+ | \-- {developer}/ # Per-developer directories
43
+ | |-- index.md # Personal index (with @@@auto markers)
44
+ | |-- features/ # Feature tracking
45
+ | \-- progress-N.md # Progress files (sequential numbering)
46
+ |-- structure/ # [!] MUST READ before coding
47
+ | |-- frontend/ # Frontend guidelines (multi-doc)
48
+ | | |-- index.md # Start here - guidelines index
49
+ | | |-- directory-structure.md # Directory layout
50
+ | | |-- type-safety.md # TypeScript patterns
51
+ | | |-- hook-guidelines.md # React Query hooks
52
+ | | |-- component-guidelines.md # Component patterns
53
+ | | |-- state-management.md # State patterns
54
+ | | \-- quality-guidelines.md # Code standards
55
+ | |-- backend/ # Backend guidelines (multi-doc)
56
+ | | |-- index.md # Start here - guidelines index
57
+ | | |-- directory-structure.md # Directory layout
58
+ | | |-- type-safety.md # Zod, TypeScript patterns
59
+ | | |-- database-guidelines.md # ORM, batch operations
60
+ | | |-- logging-guidelines.md # Structured logging
61
+ | | |-- error-handling.md # Error types, handling
62
+ | | \-- quality-guidelines.md # Code standards
63
+ | \-- flows/ # Cross-layer specifications
64
+ | |-- index.md # Flow specs index
65
+ | |-- cross-layer-thinking-guide.md # Pre-implementation checklist
66
+ | \-- spec-flow-template.md # Template for new flows
67
+ \-- flow.md # This document
68
68
  ```
69
69
 
70
70
  ---
@@ -83,9 +83,9 @@ Use the unified context script:
83
83
  ./workflow/scripts/get-context.sh --json
84
84
  ```
85
85
 
86
- ### Step 2: Read Development Guidelines ⚠️ REQUIRED
86
+ ### Step 2: Read Development Guidelines [!] REQUIRED
87
87
 
88
- **⚠️ CRITICAL: MUST read guidelines before writing any code**
88
+ **[!] CRITICAL: MUST read guidelines before writing any code**
89
89
 
90
90
  Based on what you'll develop (frontend/backend), read the corresponding guidelines:
91
91
 
@@ -137,46 +137,46 @@ Use the feature management script:
137
137
 
138
138
  ```
139
139
  1. Create or select feature
140
- └─> ./workflow/scripts/feature.sh create <name> or list
140
+ \-> ./workflow/scripts/feature.sh create <name> or list
141
141
 
142
142
  2. Write code according to guidelines
143
- └─> Read workflow/structure/[frontend|backend]/ docs
144
- └─> For cross-layer: read workflow/structure/flows/
145
- └─> Frontend: Type safety, Hook standards, Component standards
146
- └─> Backend: Directory structure, Type safety, Database, Logging
143
+ \-> Read workflow/structure/[frontend|backend]/ docs
144
+ \-> For cross-layer: read workflow/structure/flows/
145
+ \-> Frontend: Type safety, Hook standards, Component standards
146
+ \-> Backend: Directory structure, Type safety, Database, Logging
147
147
 
148
148
  3. Self-test
149
- └─> pnpm lint (must pass)
150
- └─> pnpm type-check (must pass)
151
- └─> Manual feature testing
149
+ \-> pnpm lint (must pass)
150
+ \-> pnpm type-check (must pass)
151
+ \-> Manual feature testing
152
152
 
153
153
  4. Commit code
154
- └─> git add <files>
155
- └─> git commit -m "type(scope): description"
154
+ \-> git add <files>
155
+ \-> git commit -m "type(scope): description"
156
156
  Format: feat/fix/docs/refactor/test/chore
157
157
 
158
158
  5. Record session (one command)
159
- └─> ./workflow/scripts/add-session.sh --title "Title" --commit "hash"
159
+ \-> ./workflow/scripts/add-session.sh --title "Title" --commit "hash"
160
160
  ```
161
161
 
162
162
  ### Code Quality Checklist
163
163
 
164
164
  **Must pass before commit**:
165
- - `pnpm lint` - 0 errors
166
- - `pnpm type-check` - No type errors
167
- - Manual feature testing passes
165
+ - [OK] `pnpm lint` - 0 errors
166
+ - [OK] `pnpm type-check` - No type errors
167
+ - [OK] Manual feature testing passes
168
168
 
169
169
  **Frontend-specific checks** (see `frontend/quality-guidelines.md`):
170
- - Use semantic HTML (`<button>` not `<div role="button">`)
171
- - Use Next.js `<Image>` instead of `<img>`
172
- - Import types from backend, don't redefine
173
- - Avoid non-null assertions `!`
170
+ - [OK] Use semantic HTML (`<button>` not `<div role="button">`)
171
+ - [OK] Use Next.js `<Image>` instead of `<img>`
172
+ - [OK] Import types from backend, don't redefine
173
+ - [OK] Avoid non-null assertions `!`
174
174
 
175
175
  **Backend-specific checks** (see `backend/quality-guidelines.md`):
176
- - Strictly avoid non-null assertion `!`
177
- - All API inputs/outputs have Zod Schema
178
- - Use structured logging (`logger`), forbidden `console.log`
179
- - Database operations avoid `await` in loops
176
+ - [OK] Strictly avoid non-null assertion `!`
177
+ - [OK] All API inputs/outputs have Zod Schema
178
+ - [OK] Use structured logging (`logger`), forbidden `console.log`
179
+ - [OK] Database operations avoid `await` in loops
180
180
 
181
181
  ---
182
182
 
@@ -202,11 +202,11 @@ This automatically:
202
202
  ### Pre-end Checklist
203
203
 
204
204
  Use `/finish-work` command to run through:
205
- 1. All code committed, commit message follows convention
206
- 2. Session recorded via `add-session.sh`
207
- 3. No lint/type-check errors
208
- 4. Working directory clean (or WIP noted)
209
- 5. Structure docs updated if needed
205
+ 1. [OK] All code committed, commit message follows convention
206
+ 2. [OK] Session recorded via `add-session.sh`
207
+ 3. [OK] No lint/type-check errors
208
+ 4. [OK] Working directory clean (or WIP noted)
209
+ 5. [OK] Structure docs updated if needed
210
210
 
211
211
  ---
212
212
 
@@ -219,17 +219,17 @@ Use `/finish-work` command to run through:
219
219
  **Structure** (Multi-developer support):
220
220
  ```
221
221
  agent-progress/
222
- ├── index.md # Main index (Active Developers table)
223
- └── {developer}/ # Per-developer directory
224
- ├── index.md # Personal index (with @@@auto markers)
225
- ├── features/ # Feature files
226
- └── progress-N.md # Progress files (sequential: 1, 2, 3...)
222
+ |-- index.md # Main index (Active Developers table)
223
+ \-- {developer}/ # Per-developer directory
224
+ |-- index.md # Personal index (with @@@auto markers)
225
+ |-- features/ # Feature files
226
+ \-- progress-N.md # Progress files (sequential: 1, 2, 3...)
227
227
  ```
228
228
 
229
229
  **When to update**:
230
- - End of each session
231
- - Complete important feature
232
- - Fix important bug
230
+ - [OK] End of each session
231
+ - [OK] Complete important feature
232
+ - [OK] Fix important bug
233
233
 
234
234
  ### 2. structure/ - Development Guidelines
235
235
 
@@ -238,21 +238,21 @@ agent-progress/
238
238
  **Structure** (Multi-doc format):
239
239
  ```
240
240
  structure/
241
- ├── frontend/ # Frontend docs
242
- ├── index.md # Start here
243
- └── *.md # Topic-specific docs
244
- ├── backend/ # Backend docs
245
- ├── index.md # Start here
246
- └── *.md # Topic-specific docs
247
- └── flows/ # Cross-layer specs
248
- ├── index.md # Start here
249
- └── *.md # Flow-specific docs
241
+ |-- frontend/ # Frontend docs
242
+ | |-- index.md # Start here
243
+ | \-- *.md # Topic-specific docs
244
+ |-- backend/ # Backend docs
245
+ | |-- index.md # Start here
246
+ | \-- *.md # Topic-specific docs
247
+ \-- flows/ # Cross-layer specs
248
+ |-- index.md # Start here
249
+ \-- *.md # Flow-specific docs
250
250
  ```
251
251
 
252
252
  **When to update**:
253
- - New pattern discovered
254
- - Bug fixed that reveals missing guidance
255
- - New convention established
253
+ - [OK] New pattern discovered
254
+ - [OK] Bug fixed that reveals missing guidance
255
+ - [OK] New convention established
256
256
 
257
257
  ### 3. Features - Feature Tracking
258
258
 
@@ -267,14 +267,14 @@ structure/
267
267
 
268
268
  ## Best Practices
269
269
 
270
- ### DO - Should Do
270
+ ### [OK] DO - Should Do
271
271
 
272
272
  1. **Before session start**:
273
273
  - Run `./workflow/scripts/get-context.sh` for full context
274
- - ⚠️ **MUST read** relevant `workflow/structure/` docs
274
+ - [!] **MUST read** relevant `workflow/structure/` docs
275
275
 
276
276
  2. **During development**:
277
- - ⚠️ **Follow** `workflow/structure/` guidelines
277
+ - [!] **Follow** `workflow/structure/` guidelines
278
278
  - For cross-layer features, use `/check-cross-layer`
279
279
  - Develop only one feature at a time
280
280
  - Run lint and type-check frequently
@@ -285,14 +285,14 @@ structure/
285
285
  - Human commits after testing passes
286
286
  - Use `add-session.sh` to record progress
287
287
 
288
- ### DON'T - Should Not Do
288
+ ### [X] DON'T - Should Not Do
289
289
 
290
- 1. ⚠️ **Don't** skip reading `workflow/structure/` guidelines
291
- 2. ⚠️ **Don't** let agent-progress single file exceed 2000 lines
290
+ 1. [!] **Don't** skip reading `workflow/structure/` guidelines
291
+ 2. [!] **Don't** let agent-progress single file exceed 2000 lines
292
292
  3. **Don't** develop multiple unrelated features simultaneously
293
293
  4. **Don't** commit code with lint/type-check errors
294
294
  5. **Don't** forget to update structure docs after learning something
295
- 6. ⚠️ **Don't** execute `git commit` - AI should not commit code
295
+ 6. [!] **Don't** execute `git commit` - AI should not commit code
296
296
  7. **Don't** write `workflow/structure/` docs in Chinese - **English only**
297
297
 
298
298
  ---
@@ -345,10 +345,10 @@ pnpm type-check # Type check
345
345
  ## Summary
346
346
 
347
347
  Following this workflow ensures:
348
- - Continuity across multiple sessions
349
- - Consistent code quality
350
- - Trackable progress
351
- - Knowledge accumulation in structure docs
352
- - Transparent team collaboration
348
+ - [OK] Continuity across multiple sessions
349
+ - [OK] Consistent code quality
350
+ - [OK] Trackable progress
351
+ - [OK] Knowledge accumulation in structure docs
352
+ - [OK] Transparent team collaboration
353
353
 
354
354
  **Core Philosophy**: Read before write, follow standards, record promptly, capture learnings
@@ -9,11 +9,11 @@
9
9
 
10
10
  ```
11
11
  modules/
12
- ├── {feature}/
13
- ├── components/ # UI components
14
- ├── hooks/ # Custom hooks
15
- ├── context/ # React context
16
- └── types.ts # Type definitions
12
+ |-- {feature}/
13
+ | |-- components/ # UI components
14
+ | |-- hooks/ # Custom hooks
15
+ | |-- context/ # React context
16
+ | \-- types.ts # Type definitions
17
17
  ```
18
18
 
19
19
  @@@/section:directory-structure
@@ -28,10 +28,10 @@ modules/
28
28
  Always import types from the API package instead of redefining them:
29
29
 
30
30
  ```typescript
31
- // Good
31
+ // [OK] Good
32
32
  import type { User } from '@/packages/api';
33
33
 
34
- // Bad - don't redefine
34
+ // [X] Bad - don't redefine
35
35
  interface User {
36
36
  id: string;
37
37
  name: string;
@@ -114,10 +114,10 @@ export function useUpdateExample() {
114
114
  Use proper HTML elements:
115
115
 
116
116
  ```tsx
117
- // Good
117
+ // [OK] Good
118
118
  <button onClick={handleClick}>Click me</button>
119
119
 
120
- // Bad
120
+ // [X] Bad
121
121
  <div role="button" onClick={handleClick}>Click me</div>
122
122
  ```
123
123
 
@@ -129,11 +129,11 @@ Use proper HTML elements:
129
129
  Use Next.js Image component:
130
130
 
131
131
  ```tsx
132
- // Good
132
+ // [OK] Good
133
133
  import Image from 'next/image';
134
134
  <Image src="/logo.png" alt="Logo" width={100} height={100} />
135
135
 
136
- // Bad
136
+ // [X] Bad
137
137
  <img src="/logo.png" alt="Logo" />
138
138
  ```
139
139
 
@@ -20,7 +20,7 @@ The N+1 query problem is one of the most common performance issues.
20
20
  ### Problem
21
21
 
22
22
  ```typescript
23
- // BAD: N+1 queries (1 + N database calls)
23
+ // [X] BAD: N+1 queries (1 + N database calls)
24
24
  const users = await db.select().from(users).all();
25
25
  for (const user of users) {
26
26
  const posts = await db.select().from(posts).where(eq(posts.userId, user.id)).all();
@@ -31,7 +31,7 @@ for (const user of users) {
31
31
  ### Solution 1: Relational Queries
32
32
 
33
33
  ```typescript
34
- // GOOD: Single query with JOIN
34
+ // [OK] GOOD: Single query with JOIN
35
35
  const usersWithPosts = await db.query.users.findMany({
36
36
  with: {
37
37
  posts: true,
@@ -42,7 +42,7 @@ const usersWithPosts = await db.query.users.findMany({
42
42
  ### Solution 2: Batch Lookup with inArray
43
43
 
44
44
  ```typescript
45
- // GOOD: Two queries total (1 for users, 1 for all posts)
45
+ // [OK] GOOD: Two queries total (1 for users, 1 for all posts)
46
46
  import { inArray } from 'drizzle-orm';
47
47
 
48
48
  const users = await db.select().from(users).all();
@@ -61,7 +61,7 @@ const postsByUser = groupBy(allPosts, 'userId');
61
61
  ### Solution 3: Promise.all (Use Carefully)
62
62
 
63
63
  ```typescript
64
- // ⚠️ OK for small N, but watch connection limits
64
+ // [!] OK for small N, but watch connection limits
65
65
  const results = await Promise.all(
66
66
  ids.slice(0, 10).map(id =>
67
67
  db.query.users.findFirst({ where: eq(users.id, id) })
@@ -164,11 +164,11 @@ export const users = sqliteTable('users', {
164
164
  ### Common Pitfall
165
165
 
166
166
  ```typescript
167
- // BAD: Mixing seconds and milliseconds
167
+ // [X] BAD: Mixing seconds and milliseconds
168
168
  const timestamp = Math.floor(Date.now() / 1000); // Seconds
169
169
  new Date(timestamp); // Wrong! Expects milliseconds
170
170
 
171
- // GOOD: Consistent milliseconds
171
+ // [OK] GOOD: Consistent milliseconds
172
172
  const timestamp = Date.now(); // Milliseconds
173
173
  new Date(timestamp); // Correct
174
174
  ```
@@ -8,34 +8,34 @@
8
8
 
9
9
  ```
10
10
  server/
11
- ├── db/ # Database layer
12
- ├── client.ts # Database client initialization
13
- ├── schema.ts # Table definitions
14
- └── migrations/ # Migration files
15
-
16
- ├── lib/ # Shared utilities
17
- ├── logger.ts # Logger setup
18
- ├── errors.ts # Custom error classes
19
- └── utils.ts # Helper functions
20
-
21
- ├── middleware/ # Middleware
22
- ├── auth.ts # Authentication
23
- ├── error-handler.ts # Error handling
24
- └── request-context.ts # Request context
25
-
26
- ├── routes/ # API routes (domain-driven)
27
- └── {domain}/
28
- ├── types.ts # Zod schemas + TypeScript types
29
- ├── router.ts # Route definitions
30
- ├── procedures/ # One file per endpoint
31
- ├── list.ts
32
- ├── get.ts
33
- ├── create.ts
34
- ├── update.ts
35
- └── delete.ts
36
- └── lib/ # Domain-specific logic
37
-
38
- └── types.ts # Shared types (AppContext, etc.)
11
+ |-- db/ # Database layer
12
+ | |-- client.ts # Database client initialization
13
+ | |-- schema.ts # Table definitions
14
+ | \-- migrations/ # Migration files
15
+ |
16
+ |-- lib/ # Shared utilities
17
+ | |-- logger.ts # Logger setup
18
+ | |-- errors.ts # Custom error classes
19
+ | \-- utils.ts # Helper functions
20
+ |
21
+ |-- middleware/ # Middleware
22
+ | |-- auth.ts # Authentication
23
+ | |-- error-handler.ts # Error handling
24
+ | \-- request-context.ts # Request context
25
+ |
26
+ |-- routes/ # API routes (domain-driven)
27
+ | \-- {domain}/
28
+ | |-- types.ts # Zod schemas + TypeScript types
29
+ | |-- router.ts # Route definitions
30
+ | |-- procedures/ # One file per endpoint
31
+ | | |-- list.ts
32
+ | | |-- get.ts
33
+ | | |-- create.ts
34
+ | | |-- update.ts
35
+ | | \-- delete.ts
36
+ | \-- lib/ # Domain-specific logic
37
+ |
38
+ \-- types.ts # Shared types (AppContext, etc.)
39
39
  ```
40
40
 
41
41
  ---
@@ -41,16 +41,16 @@ This collection of guidelines covers essential patterns and best practices for b
41
41
 
42
42
  ```
43
43
  server/
44
- ├── db/ # Database (client, schema)
45
- ├── lib/ # Shared utilities
46
- ├── middleware/ # Middleware
47
- ├── routes/ # API routes (domain-driven)
48
- └── {domain}/
49
- ├── types.ts # Zod schemas + types
50
- ├── router.ts # Route definitions
51
- ├── procedures/ # One file per endpoint
52
- └── lib/ # Domain-specific logic
53
- └── types.ts # Shared types
44
+ |-- db/ # Database (client, schema)
45
+ |-- lib/ # Shared utilities
46
+ |-- middleware/ # Middleware
47
+ |-- routes/ # API routes (domain-driven)
48
+ | \-- {domain}/
49
+ | |-- types.ts # Zod schemas + types
50
+ | |-- router.ts # Route definitions
51
+ | |-- procedures/ # One file per endpoint
52
+ | \-- lib/ # Domain-specific logic
53
+ \-- types.ts # Shared types
54
54
  ```
55
55
 
56
56
  ### Key Rules
@@ -29,7 +29,7 @@
29
29
  ### Basic Pattern
30
30
 
31
31
  ```typescript
32
- // GOOD: Structured with context
32
+ // [OK] GOOD: Structured with context
33
33
  logger.info('user_created', {
34
34
  userId: user.id,
35
35
  email: user.email
@@ -40,7 +40,7 @@ logger.error('payment_failed', error, {
40
40
  amount: order.total
41
41
  });
42
42
 
43
- // BAD: Unstructured string concatenation
43
+ // [X] BAD: Unstructured string concatenation
44
44
  console.log('User created: ' + user.id);
45
45
  logger.info('Error: ' + error.message);
46
46
  ```
@@ -150,10 +150,10 @@ async function syncData(logger: Logger) {
150
150
  | Session cookies | Security |
151
151
 
152
152
  ```typescript
153
- // BAD
153
+ // [X] BAD
154
154
  logger.info('login_attempt', { email, password });
155
155
 
156
- // GOOD
156
+ // [OK] GOOD
157
157
  logger.info('login_attempt', { email });
158
158
  ```
159
159