@mind-fold/open-flow 0.2.11 → 0.2.12

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 +24 -24
  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
@@ -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
 
@@ -26,11 +26,11 @@ pnpm test
26
26
  ### Non-Null Assertions
27
27
 
28
28
  ```typescript
29
- // FORBIDDEN
29
+ // [X] FORBIDDEN
30
30
  const name = user!.name;
31
31
  const data = response!.data;
32
32
 
33
- // REQUIRED
33
+ // [OK] REQUIRED
34
34
  const user = await getUser(id);
35
35
  if (!user) {
36
36
  throw new NotFoundError('User not found');
@@ -41,11 +41,11 @@ const name = user.name;
41
41
  ### Console.log
42
42
 
43
43
  ```typescript
44
- // FORBIDDEN
44
+ // [X] FORBIDDEN
45
45
  console.log('Debug:', data);
46
46
  console.error('Error:', error);
47
47
 
48
- // REQUIRED
48
+ // [OK] REQUIRED
49
49
  logger.debug('processing_data', { data });
50
50
  logger.error('operation_failed', error);
51
51
  ```
@@ -53,12 +53,12 @@ logger.error('operation_failed', error);
53
53
  ### Await in Loops
54
54
 
55
55
  ```typescript
56
- // FORBIDDEN
56
+ // [X] FORBIDDEN
57
57
  for (const id of ids) {
58
58
  await db.select().from(users).where(eq(users.id, id));
59
59
  }
60
60
 
61
- // REQUIRED
61
+ // [OK] REQUIRED
62
62
  const results = await db
63
63
  .select()
64
64
  .from(users)
@@ -68,11 +68,11 @@ const results = await db
68
68
  ### Type Assertions Without Validation
69
69
 
70
70
  ```typescript
71
- // FORBIDDEN
71
+ // [X] FORBIDDEN
72
72
  const data = input as UserData;
73
73
  const config = JSON.parse(str) as Config;
74
74
 
75
- // REQUIRED
75
+ // [OK] REQUIRED
76
76
  const data = userDataSchema.parse(input);
77
77
  const config = configSchema.parse(JSON.parse(str));
78
78
  ```
@@ -80,11 +80,11 @@ const config = configSchema.parse(JSON.parse(str));
80
80
  ### Any Type
81
81
 
82
82
  ```typescript
83
- // FORBIDDEN
83
+ // [X] FORBIDDEN
84
84
  function process(data: any) { ... }
85
85
  const result: any = await fetch(...);
86
86
 
87
- // REQUIRED
87
+ // [OK] REQUIRED
88
88
  function process(data: unknown) {
89
89
  const validated = schema.parse(data);
90
90
  ...
@@ -151,11 +151,11 @@ if (!user) {
151
151
  ### Comments
152
152
 
153
153
  ```typescript
154
- // GOOD: Explain WHY, not WHAT
154
+ // [OK] GOOD: Explain WHY, not WHAT
155
155
  // Skip validation for internal calls to avoid performance overhead
156
156
  const data = trustInternalData(input);
157
157
 
158
- // BAD: Obvious comment
158
+ // [X] BAD: Obvious comment
159
159
  // Get user by id
160
160
  const user = await getUser(id);
161
161
  ```
@@ -77,7 +77,7 @@ export const userSummary = userSchema.pick({
77
77
  ### Problem
78
78
 
79
79
  ```typescript
80
- // BAD: Crashes if user is null
80
+ // [X] BAD: Crashes if user is null
81
81
  const user = await getUser(id);
82
82
  const name = user!.name; // TypeScript trusts you, runtime doesn't
83
83
  ```
@@ -85,7 +85,7 @@ const name = user!.name; // TypeScript trusts you, runtime doesn't
85
85
  ### Solution: Guard with Local Variable
86
86
 
87
87
  ```typescript
88
- // GOOD: Explicit null check
88
+ // [OK] GOOD: Explicit null check
89
89
  const user = await getUser(id);
90
90
  if (!user) {
91
91
  throw new NotFoundError('User not found');
@@ -97,7 +97,7 @@ const name = user.name; // Safe access
97
97
  ### Solution: Early Return
98
98
 
99
99
  ```typescript
100
- // GOOD: Early return pattern
100
+ // [OK] GOOD: Early return pattern
101
101
  async function getUserName(id: string): Promise<string> {
102
102
  const user = await getUser(id);
103
103
  if (!user) {
@@ -178,13 +178,13 @@ if (!user) {
178
178
 
179
179
  ```typescript
180
180
  // Trust external data
181
- const data = externalInput as User; //
181
+ const data = externalInput as User; // [X]
182
182
 
183
183
  // Use non-null assertion
184
- const name = user!.name; //
184
+ const name = user!.name; // [X]
185
185
 
186
186
  // Ignore parse errors
187
- const data = userSchema.parse(input); // Throws on invalid
187
+ const data = userSchema.parse(input); // [X] Throws on invalid
188
188
  ```
189
189
 
190
190
  ---