| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 57 | 39 | 0% |
| Commands | 0 | 2 | 18 | 0% |
| Section tags | 7 | 1 | 4 | 58% |
What each file covers
Sections
0 shared · 57 only in A · 39 only in B- − === BACKLOG.MD GUIDELINES START ===
- − Instructions for the usage of Backlog.md CLI Tool
- − Backlog.md: Comprehensive Project Management Tool via CLI
- − Assistant Objective
- − Core Capabilities
- − Why This Matters to You (AI Agent)
- − Key Understanding
- − ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI
- − 1. Source of Truth & File Structure
- − 📖 **UNDERSTANDING** (What you'll see when reading)
- − 🔧 **ACTING** (How to change things)
- − 2. Common Mistakes to Avoid
- − ❌ **WRONG: Direct File Editing**
- − DON'T DO THIS:
- − ✅ **CORRECT: Using CLI Commands**
- − DO THIS INSTEAD:
- − 3. Understanding Task Format (Read-Only Reference)
- − Task Structure You'll See
- − Description
- − Acceptance Criteria
- − Implementation Plan
- − Implementation Notes
- − How to Modify Each Section
- − 4. Defining Tasks
- − Creating New Tasks
- − Example
- − Title (one liner)
- − Description (The "why")
- − Acceptance Criteria (The "what")
- − Examples
- − Add new criteria (MULTIPLE values allowed)
- − Check specific criteria by index (MULTIPLE values supported)
- − Or check them individually if you prefer:
- − Mixed operations in single command
- − ❌ STILL WRONG - These formats don't work:
- − backlog task edit 42 --check-ac 1,2,3 # No comma-separated values
- − backlog task edit 42 --check-ac 1-3 # No ranges
- − backlog task edit 42 --check 1 # Wrong flag name
- − Multiple operations of same type
- − Task Breakdown Strategy
- − Task Requirements
- − 5. Implementing Tasks
- − 5.1. First step when implementing a task
- − 5.2. Create an Implementation Plan (The "how")
- − 5.3. Implementation
- − 5.4 Implementation Notes (PR description)
- − Phase discipline: What goes where
- − 6. Typical Workflow
- − 1. Identify work
- − 2. Read task details
- − 3. Start work: assign yourself & change status
- − 4. Add implementation plan
- − 5. Work on the task (write code, test, etc.)
- − 6. Mark acceptance criteria as complete (supports multiple in one command)
- − Or check them individually if preferred:
- − backlog task edit 42 --check-ac 1
- − backlog task edit 42 --check-ac 2
- + Before starting work
- + Post-task checklist (REQUIRED — do not skip)
- + What is lat.md?
- + Development Commands (wodsmith-start)
- + Build and Development
- + Code Quality
- + Database Operations
- + Testing
- + Cloudflare
- + Architecture Overview (wodsmith-start)
- + Tech Stack
- + Project Structure (wodsmith-start)
- + Multi-Tenancy
- + Database Schema
- + Development Guidelines
- + Code Style
- + Database
- + Authentication & Authorization
- + State Management
- + API Patterns
- + TanStack Start Server Functions (wodsmith-start)
- + Syntax primer
- + Test specs
- + Tests
- + User login
- + Rejects expired tokens
- + Handles missing password
- + @lat: [[tests#User login#Rejects expired tokens]]
- + @lat: [[tests#User login#Handles missing password]]
- + Section structure
- + Good Section
- + Child heading
- + Bad Section
- + Skill mappings - when working in these areas, load the linked skill file into context.
- + GitNexus — Code Intelligence
- + Always Do
- + Never Do
- + Resources
- + CLI
Commands
0 shared · 2 only in A · 18 only in B- − task-<id> - <title>.md
- − task-42 - Add GraphQL resolver.md
- + pnpm dev
- + pnpm build
- + pnpm preview
- + pnpm lint
- + pnpm format
- + pnpm check
- + pnpm type-check
- + pnpm db:push
- + pnpm db:generate --name=X
- + pnpm db:studio
- + pnpm db:migrate:local
- + pnpm test
- + pnpm cf-typegen
- + npx alchemy deploy
- + pnpm alchemy:dev
- + pnpm
- + pnpm db:generate --name=feature-name
- + npx gitnexus analyze
Section tags
7 shared · 1 only in A · 4 only in B- − agent-behaviour
- + build
- + security
- + database
- + api
- test
- lint-format
- code-style
- architecture
- types
- git-pr
- do-not
Line diff
wodsmith/thewodapp · .cursorrules
@@ −1 @@
1
2# === BACKLOG.MD GUIDELINES START ===
3# Instructions for the usage of Backlog.md CLI Tool
4
5## Backlog.md: Comprehensive Project Management Tool via CLI
6
7### Assistant Objective
8
9Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata
10remains fully synchronized and up-to-date.
11
12### Core Capabilities
13
14✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata
15✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index
16✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`)
17✅ **Git Integration**: Automatic tracking of task states across branches
18✅ **Dependencies**: Task relationships and subtask hierarchies
19✅ **Documentation & Decisions**: Structured docs and architectural decision records
20✅ **Export & Reporting**: Generate markdown reports and board snapshots
21✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing
22
23### Why This Matters to You (AI Agent)
24
251. **Comprehensive system** - Full project management capabilities through CLI
262. **The CLI is the interface** - All operations go through `backlog` commands
273. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing (
28 `backlog task edit 1`)
294. **Metadata stays synchronized** - The CLI handles all the complex relationships
30
31### Key Understanding
32
33- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files
34- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc.
35- **Use `--plain` flag** for AI-friendly output when viewing/listing
36- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships
37
38---
39
40# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI
41
42**ALL task operations MUST use the Backlog.md CLI commands**
43
44- ✅ **DO**: Use `backlog task edit` and other CLI commands
45- ✅ **DO**: Use `backlog task create` to create new tasks
46- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria
47- ❌ **DON'T**: Edit markdown files directly
48- ❌ **DON'T**: Manually change checkboxes in files
49- ❌ **DON'T**: Add or modify text in task files without using CLI
50
51**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships.
52
53---
54
55## 1. Source of Truth & File Structure
56
57### 📖 **UNDERSTANDING** (What you'll see when reading)
58
59- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**)
60- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`)
61- Project documentation is in **`backlog/docs/`**
62- Project decisions are in **`backlog/decisions/`**
63
64### 🔧 **ACTING** (How to change things)
65
66- **All task operations MUST use the Backlog.md CLI tool**
67- This ensures metadata is correctly updated and the project stays in sync
68- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output
69
70---
71
72## 2. Common Mistakes to Avoid
73
74### ❌ **WRONG: Direct File Editing**
75
76```markdown
77# DON'T DO THIS:
78
791. Open backlog/tasks/task-7 - Feature.md in editor
802. Change "- [ ]" to "- [x]" manually
813. Add notes directly to the file
824. Save the file
83```
84
85### ✅ **CORRECT: Using CLI Commands**
86
87```bash
88# DO THIS INSTEAD:
89backlog task edit 7 --check-ac 1 # Mark AC #1 as complete
90backlog task edit 7 --notes "Implementation complete" # Add notes
91backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task
92```
93
94---
95
96## 3. Understanding Task Format (Read-Only Reference)
97
98⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files.
99**Never edit these directly! Use CLI commands to make changes.**
100
101### Task Structure You'll See
102
103```markdown
104---
105id: task-42
106title: Add GraphQL resolver
107status: To Do
108assignee: [@sara]
109labels: [backend, api]
110---
111
112## Description
113
114Brief explanation of the task purpose.
115
116## Acceptance Criteria
117
118<!-- AC:BEGIN -->
119
120- [ ] #1 First criterion
121- [x] #2 Second criterion (completed)
122- [ ] #3 Third criterion
123
124<!-- AC:END -->
125
126## Implementation Plan
127
1281. Research approach
1292. Implement solution
130
131## Implementation Notes
132
133Summary of what was done.
134```
135
136### How to Modify Each Section
137
138| What You Want to Change | CLI Command to Use |
139|-------------------------|----------------------------------------------------------|
140| Title | `backlog task edit 42 -t "New Title"` |
141| Status | `backlog task edit 42 -s "In Progress"` |
142| Assignee | `backlog task edit 42 -a @sara` |
143| Labels | `backlog task edit 42 -l backend,api` |
144| Description | `backlog task edit 42 -d "New description"` |
145| Add AC | `backlog task edit 42 --ac "New criterion"` |
146| Check AC #1 | `backlog task edit 42 --check-ac 1` |
147| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` |
148| Remove AC #3 | `backlog task edit 42 --remove-ac 3` |
149| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` |
150| Add Notes | `backlog task edit 42 --notes "What I did"` |
151
152---
153
154## 4. Defining Tasks
155
156### Creating New Tasks
157
158**Always use CLI to create tasks:**
159
160```bash
161# Example
162backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion"
163```
164
165### Title (one liner)
166
167Use a clear brief title that summarizes the task.
168
169### Description (The "why")
170
171Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.
172
173### Acceptance Criteria (The "what")
174
175**Understanding the Format:**
176
177- Acceptance criteria appear as numbered checkboxes in the markdown files
178- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked)
179
180**Managing Acceptance Criteria via CLI:**
181
182⚠️ **IMPORTANT: How AC Commands Work**
183
184- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅
185- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅
186- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅
187
188```bash
189# Examples
190
191# Add new criteria (MULTIPLE values allowed)
192backlog task edit 42 --ac "User can login" --ac "Session persists"
193
194# Check specific criteria by index (MULTIPLE values supported)
195backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs
196# Or check them individually if you prefer:
197backlog task edit 42 --check-ac 1 # Mark #1 as complete
198backlog task edit 42 --check-ac 2 # Mark #2 as complete
199
200# Mixed operations in single command
201backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3
202
203# ❌ STILL WRONG - These formats don't work:
204# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values
205# backlog task edit 42 --check-ac 1-3 # No ranges
206# backlog task edit 42 --check 1 # Wrong flag name
207
208# Multiple operations of same type
209backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs
210backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low)
211```
212
213**Key Principles for Good ACs:**
214
215- **Outcome-Oriented:** Focus on the result, not the method.
216- **Testable/Verifiable:** Each criterion should be objectively testable
217- **Clear and Concise:** Unambiguous language
218- **Complete:** Collectively cover the task scope
219- **User-Focused:** Frame from end-user or system behavior perspective
220
221Good Examples:
222
223- "User can successfully log in with valid credentials"
224- "System processes 1000 requests per second without errors"
225- "When passing \n characters in description, plan, notes, the system correctly handles them by converting to new lines"
226
227Bad Example (Implementation Step):
228
229- "Add a new function handleLogin() in auth.ts"
230- "Define expected behavior and document supported input patterns"
231
232### Task Breakdown Strategy
233
2341. Identify foundational components first
2352. Create tasks in dependency order (foundations before features)
2363. Ensure each task delivers value independently
2374. Avoid creating tasks that block each other
238
239### Task Requirements
240
241- Tasks must be **atomic** and **testable** or **verifiable**
242- Each task should represent a single unit of work for one PR
243- **Never** reference future tasks (only tasks with id < current task id)
244- Ensure tasks are **independent** and don't depend on future work
245
246---
247
248## 5. Implementing Tasks
249
250### 5.1. First step when implementing a task
251
252The very first things you must do when you take over a task are:
253
254* set the task in progress
255* assign it to yourself
256
257```bash
258# Example
259backlog task edit 42 -s "In Progress" -a @{myself}
260```
261
262### 5.2. Create an Implementation Plan (The "how")
263
264Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a
265plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**.
266First do a quick check to see if all the tools that you are planning to use are available in the environment you are
267working in.
268When you are ready, write it down in the task so that you can refer to it later.
269
270```bash
271# Example
272backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test"
273```
274
275## 5.3. Implementation
276
277Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure
278everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you
279finish them.
280
281### 5.4 Implementation Notes (PR description)
282
283When you are done implementing a tasks you need to prepare a PR description for it.
284Because you cannot create PRs directly, write the PR as a clean description in the task notes.
285
286```bash
287# Example
288backlog task edit 42 --notes "Implemented using pattern X because Reason Y, modified files Z and W"
289```
290
291**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the
292implementation.
293
294- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee.
295- When you begin work, switch to edit, set the task in progress and assign to yourself
296 `backlog task edit <id> -s "In Progress" -a "..."`.
297- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`.
298- Add Implementation Notes only after completing the work: `backlog task edit <id> --notes "..."`.
299
300## Phase discipline: What goes where
301
302- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee.
303- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself).
304- Wrap-up: Implementation Notes (Like a PR description), AC and Definition of Done checks.
305
306**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either:
307
3081. Update the AC first: `backlog task edit 42 --ac "New requirement"`
3092. Or create a new follow up task: `backlog task create "Additional feature"`
310
311---
312
313## 6. Typical Workflow
314
315```bash
316# 1. Identify work
317backlog task list -s "To Do" --plain
318
319# 2. Read task details
320backlog task 42 --plain
321
322# 3. Start work: assign yourself & change status
323backlog task edit 42 -s "In Progress" -a @myself
324
325# 4. Add implementation plan
326backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test"
327
328# 5. Work on the task (write code, test, etc.)
329
330# 6. Mark acceptance criteria as complete (supports multiple in one command)
331backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once
332# Or check them individually if preferred:
333# backlog task edit 42 --check-ac 1
334# backlog task edit 42 --check-ac 2
335# backlog task edit 42 --check-ac 3
336
337# 7. Add implementation notes (PR Description)
338backlog task edit 42 --notes "Refactored using strategy pattern, updated tests"
339
340# 8. Mark task as done
341backlog task edit 42 -s Done
342```
343
344---
345
346## 7. Definition of Done (DoD)
347
348A task is **Done** only when **ALL** of the following are complete:
349
350### ✅ Via CLI Commands:
351
3521. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each
3532. **Implementation notes added**: Use `backlog task edit <id> --notes "..."`
3543. **Status set to Done**: Use `backlog task edit <id> -s Done`
355
356### ✅ Via Code/Testing:
357
3584. **Tests pass**: Run test suite and linting
3595. **Documentation updated**: Update relevant docs if needed
3606. **Code reviewed**: Self-review your changes
3617. **No regressions**: Performance, security checks pass
362
363⚠️ **NEVER mark a task as Done without completing ALL items above**
364
365---
366
367## 8. Quick Reference: DO vs DON'T
368
369### Viewing Tasks
370
371| Task | ✅ DO | ❌ DON'T |
372|--------------|-----------------------------|---------------------------------|
373| View task | `backlog task 42 --plain` | Open and read .md file directly |
374| List tasks | `backlog task list --plain` | Browse backlog/tasks folder |
375| Check status | `backlog task 42 --plain` | Look at file content |
376
377### Modifying Tasks
378
379| Task | ✅ DO | ❌ DON'T |
380|---------------|--------------------------------------|-----------------------------------|
381| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file |
382| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file |
383| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter |
384| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file |
385
386---
387
388## 9. Complete CLI Command Reference
389
390### Task Creation
391
392| Action | Command |
393|------------------|-------------------------------------------------------------------------------------|
394| Create task | `backlog task create "Title"` |
395| With description | `backlog task create "Title" -d "Description"` |
396| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` |
397| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high` |
398| Create draft | `backlog task create "Title" --draft` |
399| Create subtask | `backlog task create "Title" -p 42` |
400
401### Task Modification
402
403| Action | Command |
404|------------------|---------------------------------------------|
405| Edit title | `backlog task edit 42 -t "New Title"` |
406| Edit description | `backlog task edit 42 -d "New description"` |
407| Change status | `backlog task edit 42 -s "In Progress"` |
408| Assign | `backlog task edit 42 -a @sara` |
409| Add labels | `backlog task edit 42 -l backend,api` |
410| Set priority | `backlog task edit 42 --priority high` |
411
412### Acceptance Criteria Management
413
414| Action | Command |
415|---------------------|-----------------------------------------------------------------------------|
416| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` |
417| Remove AC #2 | `backlog task edit 42 --remove-ac 2` |
418| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` |
419| Check AC #1 | `backlog task edit 42 --check-ac 1` |
420| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` |
421| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` |
422| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` |
423
424### Task Content
425
426| Action | Command |
427|------------------|----------------------------------------------------------|
428| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` |
429| Add notes | `backlog task edit 42 --notes "Implementation details"` |
430| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` |
431
432Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline.
433
434### Task Operations
435
436| Action | Command |
437|--------------------|----------------------------------------------|
438| View task | `backlog task 42 --plain` |
439| List tasks | `backlog task list --plain` |
440| Filter by status | `backlog task list -s "In Progress" --plain` |
441| Filter by assignee | `backlog task list -a @sara --plain` |
442| Archive task | `backlog task archive 42` |
443| Demote to draft | `backlog task demote 42` |
444
445---
446
447## Common Issues
448
449| Problem | Solution |
450|----------------------|--------------------------------------------------------------------|
451| Task not found | Check task ID with `backlog task list --plain` |
452| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers |
453| Changes not saving | Ensure you're using CLI, not editing files |
454| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` |
455
456---
457
458## Remember: The Golden Rule
459
460**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.**
461**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.**
462
463Full help available: `backlog --help`
464
465# === BACKLOG.MD GUIDELINES END ===
466
wodsmith/thewodapp · CLAUDE.md
@@ +1 @@
1# Before starting work
2
3- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
5
6# Post-task checklist (REQUIRED — do not skip)
7
8After EVERY task, before responding to the user:
9
10- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11- [ ] Run `lat check` — all wiki links and code refs must pass
12- [ ] Do not skip these steps. Do not consider your task done until both are complete.
13
14---
15
16# What is lat.md?
17
18This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
19
20## Development Commands (wodsmith-start)
21
22Run these from `apps/wodsmith-start/`:
23
24### Build and Development
25
26- `pnpm dev` - Start development server
27- `pnpm build` - Build TanStack Start application
28- `pnpm preview` - Preview production build with Cloudflare
29
30### Code Quality
31
32- `pnpm lint` - Run Biome linter
33- `pnpm format` - Format code with Biome
34- `pnpm check` - Run Biome check (lint + format)
35- `pnpm type-check` - Run TypeScript type checking
36
37### Database Operations
38
39- `pnpm db:push` - Push schema changes to PlanetScale dev branch (use during development)
40- `pnpm db:generate --name=X` - Generate migration (only before merging to main)
41- `pnpm db:studio` - Open Drizzle Studio
42- `pnpm db:migrate:local` - Apply migrations locally
43
44### Testing
45
46- `pnpm test` - Run all tests with Vitest (single run mode)
47- Test files are located in `test/` directory
48
49### Cloudflare
50
51- `pnpm cf-typegen` - Generate Cloudflare types (run after wrangler.jsonc changes)
52- `npx alchemy deploy` - Deploy using Alchemy IaC
53- `pnpm alchemy:dev` - Deploy local dev environment with Alchemy (required after changing env vars in `.dev.vars`)
54
55## Architecture Overview (wodsmith-start)
56
57### Tech Stack
58
59- **Framework**: TanStack Start (React 19, TypeScript, Vinxi/Vite)
60- **Database**: PlanetScale (MySQL) with Drizzle ORM via Hyperdrive
61- **Authentication**: Custom auth with KV sessions
62- **Deployment**: Cloudflare Workers via Alchemy IaC
63- **UI**: Tailwind CSS, Shadcn UI, Radix primitives
64- **State**: Zustand (client), TanStack Router loaders (server)
65- **API**: TanStack Start server functions (`createServerFn`)
66
67### Project Structure (wodsmith-start)
68
69```
70apps/wodsmith-start/src/
71├── routes/ # TanStack Router file-based routes
72│ ├── api/ # API routes (server handlers)
73│ └── compete/ # Competition features
74├── components/ # React components
75├── db/ # Database schema and migrations
76│ ├── schema.ts # Main schema exports
77│ └── migrations/ # Auto-generated migrations
78├── server/ # Server-only business logic
79├── server-fns/ # Server functions (createServerFn)
80├── lib/ # Shared utilities
81│ ├── env.ts # Server-only env access (getAppUrl, etc.)
82│ └── stripe.ts # Server-only Stripe client
83├── utils/ # Shared utilities
84├── state/ # Client state (Zustand)
85└── schemas/ # Zod validation schemas
86```
87
88### Multi-Tenancy
89
90- Team-based data isolation with `teamId` filtering
91- Role-based permissions (admin, member roles)
92- Team switching via team-switcher component
93- All database operations must include team context
94
95### Database Schema
96
97Database is modularly structured in `src/db/schemas/`:
98
99- `users.ts` - User accounts and authentication
100- `teams.ts` - Team/organization management
101- `workouts.ts` - Workout management system
102- `programming.ts` - Programming tracks and scheduling
103- `billing.ts` - Credit billing system
104- `scaling.ts` - Workout scaling options
105- `scheduling.ts` - Schedule templates and scheduling
106- Main schema exports from `src/db/schema.ts`
107
108## Development Guidelines
109
110### Code Style
111
112- Use TypeScript everywhere, prefer interfaces over types
113- Functional components, avoid classes
114- Server Components by default, `use client` only when necessary
115- Add `import "server-only"` to server-only files (except page.tsx)
116- Use semantic commit messages: `feat:`, `fix:`, `chore:`
117- Use `pnpm` as package manager
118
119### Database
120
121- **Local development**: Use `pnpm db:push` to apply schema changes directly (no migration files)
122- **Before merging**: Generate migrations with `pnpm db:generate --name=feature-name`
123- **Never write SQL migrations manually** - always use drizzle-kit
124- Use `db.transaction()` when multiple writes need to be atomic (PlanetScale supports transactions)
125- Never pass `id` when inserting (auto-generated with CUID2)
126- Always filter by `teamId` for multi-tenant data
127- Use helper functions in `src/server/` for business logic
128- Use standard Drizzle queries with `inArray()` directly — PlanetScale has no restrictive parameter limits
129
130### Authentication & Authorization
131
132- Session handling: `getSessionFromCookie()` for server components
133- Client session: `useSession()` from `src/utils/auth-client.ts`
134- Team authorization utilities in `src/utils/team-auth.ts`
135- Protect routes with team context validation
136- When checking roles use available roles from `src/db/schemas/teams.ts`
137
138### State Management
139
140- Server state: React Server Components
141- Client state: Zustand stores in `src/state/`
142- URL state: NUQS for search parameters
143- Forms: React Hook Form with Zod validation
144
145### API Patterns
146
147- Server functions with TanStack Start: `createServerFn` (see below)
148- Named object parameters for functions with >1 parameter
149- Consistent error handling with proper HTTP status codes
150- Rate limiting on auth endpoints
151
152### TanStack Start Server Functions (wodsmith-start)
153
154#### Environment Variables
155
156**ALWAYS** use `env` from `cloudflare:workers` - never use `process.env`:
157
158```typescript
159import {env} from 'cloudflare:workers'
160
161env.HYPERDRIVE // PlanetScale via Hyperdrive
162env.KV_SESSION // KV namespace binding
163env.APP_URL // Environment variable
164env.STRIPE_SECRET_KEY // Secret
165```
166
167**TypeScript not recognizing env vars?** If you've added new bindings in `alchemy.run.ts` and deployed with `pnpm alchemy:dev`, but TypeScript doesn't see them, run:
168
169```bash
170lat locate "Section Name" # find a section by name (exact, fuzzy)
171lat refs "file#Section" # find what references a section
172lat search "natural language" # semantic search across all sections
173lat expand "user prompt text" # expand [[refs]] to resolved locations
174lat check # validate all links and code refs
175```
176
177Run `lat --help` when in doubt about available commands or options.
178
179If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
180
181# Syntax primer
182
183- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
184- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
185- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
186- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
187
188# Test specs
189
190Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
191
192```markdown
193---
194lat:
195 require-code-mention: true
196---
197# Tests
198
199Authentication and authorization test specifications.
200
201## User login
202
203Verify credential validation and error handling for the login endpoint.
204
205### Rejects expired tokens
206Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
207
208### Handles missing password
209Login request without a password field returns 400 with a descriptive error.
210```
211
212Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
213
214Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
215
216```python
217# @lat: [[tests#User login#Rejects expired tokens]]
218def test_rejects_expired_tokens():
219 ...
220
221# @lat: [[tests#User login#Handles missing password]]
222def test_handles_missing_password():
223 ...
224```
225
226Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
227
228# Section structure
229
230Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
231
232```markdown
233# Good Section
234
235Brief overview of what this section documents and why it matters.
236
237More detail can go in subsequent paragraphs, code blocks, or lists.
238
239## Child heading
240
241Details about this child topic.
242```
243
244```markdown
245# Bad Section
246
247## Child heading
248
249Details about this child topic.
250```
251
252The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
253
254<!-- intent-skills:start -->
255# Skill mappings - when working in these areas, load the linked skill file into context.
256skills:
257 - task: "TanStack Router core concepts, route trees, createRouter, createRoute, file naming conventions"
258 load: "node_modules/@tanstack/router-core/skills/router-core/SKILL.md"
259 - task: "Route protection, auth guards, beforeLoad redirects, RBAC, authenticated layouts"
260 load: "node_modules/@tanstack/router-core/skills/router-core/auth-and-guards/SKILL.md"
261 - task: "Code splitting, lazy routes, .lazy.tsx, autoCodeSplitting, getRouteApi"
262 load: "node_modules/@tanstack/router-core/skills/router-core/code-splitting/SKILL.md"
263 - task: "Route data loading, loaders, loaderDeps, staleTime, pendingComponent, Await, deferred data"
264 load: "node_modules/@tanstack/router-core/skills/router-core/data-loading/SKILL.md"
265 - task: "Link component, useNavigate, preloading, navigation blocking, scroll restoration"
266 load: "node_modules/@tanstack/router-core/skills/router-core/navigation/SKILL.md"
267 - task: "notFound handling, errorComponent, CatchBoundary, route masking"
268 load: "node_modules/@tanstack/router-core/skills/router-core/not-found-and-errors/SKILL.md"
269 - task: "Dynamic path params, splat routes, optional params, useParams"
270 load: "node_modules/@tanstack/router-core/skills/router-core/path-params/SKILL.md"
271 - task: "Search params validation, Zod adapters, search middlewares, retainSearchParams"
272 load: "node_modules/@tanstack/router-core/skills/router-core/search-params/SKILL.md"
273 - task: "SSR, streaming, renderRouterToStream, HeadContent, Scripts, head route option, meta tags"
274 load: "node_modules/@tanstack/router-core/skills/router-core/ssr/SKILL.md"
275 - task: "Router type safety, Register declaration, from narrowing, strict mode, LinkProps"
276 load: "node_modules/@tanstack/router-core/skills/router-core/type-safety/SKILL.md"
277<!-- intent-skills:end -->
278
279<!-- gitnexus:start -->
280# GitNexus — Code Intelligence
281
282This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
283
284> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
285
286## Always Do
287
288- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
289- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
290- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
291- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
292- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
293
294## Never Do
295
296- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
297- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
298- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
299- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
300
301## Resources
302
303| Resource | Use for |
304|----------|---------|
305| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
306| `gitnexus://repo/thewodapp/clusters` | All functional areas |
307| `gitnexus://repo/thewodapp/processes` | All execution flows |
308| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
309
310## CLI
311
312| Task | Read this skill file |
313|------|---------------------|
314| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
315| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
316| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
317| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
318| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
319| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
320
321<!-- gitnexus:end -->
322
@@ −1 +1 @@
1+# Before starting work
12
2−# === BACKLOG.MD GUIDELINES START ===
3−# Instructions for the usage of Backlog.md CLI Tool
3+- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4+- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
45
5−## Backlog.md: Comprehensive Project Management Tool via CLI
6+# Post-task checklist (REQUIRED — do not skip)
67
7−### Assistant Objective
8+After EVERY task, before responding to the user:
89
9−Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata
10−remains fully synchronized and up-to-date.
10+- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11+- [ ] Run `lat check` — all wiki links and code refs must pass
12+- [ ] Do not skip these steps. Do not consider your task done until both are complete.
1113
12−### Core Capabilities
14+---
1315
14−✅ **Task Management**: Create, edit, assign, prioritize, and track tasks with full metadata
15−✅ **Acceptance Criteria**: Granular control with add/remove/check/uncheck by index
16−✅ **Board Visualization**: Terminal-based Kanban board (`backlog board`) and web UI (`backlog browser`)
17−✅ **Git Integration**: Automatic tracking of task states across branches
18−✅ **Dependencies**: Task relationships and subtask hierarchies
19−✅ **Documentation & Decisions**: Structured docs and architectural decision records
20−✅ **Export & Reporting**: Generate markdown reports and board snapshots
21−✅ **AI-Optimized**: `--plain` flag provides clean text output for AI processing
16+# What is lat.md?
2217
23−### Why This Matters to You (AI Agent)
18+This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
2419
25−1. **Comprehensive system** - Full project management capabilities through CLI
26−2. **The CLI is the interface** - All operations go through `backlog` commands
27−3. **Unified interaction model** - You can use CLI for both reading (`backlog task 1 --plain`) and writing (
28− `backlog task edit 1`)
29−4. **Metadata stays synchronized** - The CLI handles all the complex relationships
20+## Development Commands (wodsmith-start)
3021
31−### Key Understanding
22+Run these from `apps/wodsmith-start/`:
3223
33−- **Tasks** live in `backlog/tasks/` as `task-<id> - <title>.md` files
34−- **You interact via CLI only**: `backlog task create`, `backlog task edit`, etc.
35−- **Use `--plain` flag** for AI-friendly output when viewing/listing
36−- **Never bypass the CLI** - It handles Git, metadata, file naming, and relationships
24+### Build and Development
3725
38−---
26+- `pnpm dev` - Start development server
27+- `pnpm build` - Build TanStack Start application
28+- `pnpm preview` - Preview production build with Cloudflare
3929
40−# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI
30+### Code Quality
4131
42−**ALL task operations MUST use the Backlog.md CLI commands**
32+- `pnpm lint` - Run Biome linter
33+- `pnpm format` - Format code with Biome
34+- `pnpm check` - Run Biome check (lint + format)
35+- `pnpm type-check` - Run TypeScript type checking
4336
44−- ✅ **DO**: Use `backlog task edit` and other CLI commands
45−- ✅ **DO**: Use `backlog task create` to create new tasks
46−- ✅ **DO**: Use `backlog task edit <id> --check-ac <index>` to mark acceptance criteria
47−- ❌ **DON'T**: Edit markdown files directly
48−- ❌ **DON'T**: Manually change checkboxes in files
49−- ❌ **DON'T**: Add or modify text in task files without using CLI
37+### Database Operations
5038
51−**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships.
39+- `pnpm db:push` - Push schema changes to PlanetScale dev branch (use during development)
40+- `pnpm db:generate --name=X` - Generate migration (only before merging to main)
41+- `pnpm db:studio` - Open Drizzle Studio
42+- `pnpm db:migrate:local` - Apply migrations locally
5243
53−---
44+### Testing
5445
55−## 1. Source of Truth & File Structure
46+- `pnpm test` - Run all tests with Vitest (single run mode)
47+- Test files are located in `test/` directory
5648
57−### 📖 **UNDERSTANDING** (What you'll see when reading)
49+### Cloudflare
5850
59−- Markdown task files live under **`backlog/tasks/`** (drafts under **`backlog/drafts/`**)
60−- Files are named: `task-<id> - <title>.md` (e.g., `task-42 - Add GraphQL resolver.md`)
61−- Project documentation is in **`backlog/docs/`**
62−- Project decisions are in **`backlog/decisions/`**
51+- `pnpm cf-typegen` - Generate Cloudflare types (run after wrangler.jsonc changes)
52+- `npx alchemy deploy` - Deploy using Alchemy IaC
53+- `pnpm alchemy:dev` - Deploy local dev environment with Alchemy (required after changing env vars in `.dev.vars`)
6354
64−### 🔧 **ACTING** (How to change things)
55+## Architecture Overview (wodsmith-start)
6556
66−- **All task operations MUST use the Backlog.md CLI tool**
67−- This ensures metadata is correctly updated and the project stays in sync
68−- **Always use `--plain` flag** when listing or viewing tasks for AI-friendly text output
57+### Tech Stack
6958
70−---
59+- **Framework**: TanStack Start (React 19, TypeScript, Vinxi/Vite)
60+- **Database**: PlanetScale (MySQL) with Drizzle ORM via Hyperdrive
61+- **Authentication**: Custom auth with KV sessions
62+- **Deployment**: Cloudflare Workers via Alchemy IaC
63+- **UI**: Tailwind CSS, Shadcn UI, Radix primitives
64+- **State**: Zustand (client), TanStack Router loaders (server)
65+- **API**: TanStack Start server functions (`createServerFn`)
7166
72−## 2. Common Mistakes to Avoid
67+### Project Structure (wodsmith-start)
7368
74−### ❌ **WRONG: Direct File Editing**
75−
76−```markdown
77−# DON'T DO THIS:
78−
79−1. Open backlog/tasks/task-7 - Feature.md in editor
80−2. Change "- [ ]" to "- [x]" manually
81−3. Add notes directly to the file
82−4. Save the file
8369 ```
84−
85−### ✅ **CORRECT: Using CLI Commands**
86−
87−```bash
88−# DO THIS INSTEAD:
89−backlog task edit 7 --check-ac 1 # Mark AC #1 as complete
90−backlog task edit 7 --notes "Implementation complete" # Add notes
91−backlog task edit 7 -s "In Progress" -a @agent-k # Multiple commands: change status and assign the task when you start working on the task
70+apps/wodsmith-start/src/
71+├── routes/ # TanStack Router file-based routes
72+│ ├── api/ # API routes (server handlers)
73+│ └── compete/ # Competition features
74+├── components/ # React components
75+├── db/ # Database schema and migrations
76+│ ├── schema.ts # Main schema exports
77+│ └── migrations/ # Auto-generated migrations
78+├── server/ # Server-only business logic
79+├── server-fns/ # Server functions (createServerFn)
80+├── lib/ # Shared utilities
81+│ ├── env.ts # Server-only env access (getAppUrl, etc.)
82+│ └── stripe.ts # Server-only Stripe client
83+├── utils/ # Shared utilities
84+├── state/ # Client state (Zustand)
85+└── schemas/ # Zod validation schemas
9286 ```
9387
94−---
88+### Multi-Tenancy
9589
96−## 3. Understanding Task Format (Read-Only Reference)
90+- Team-based data isolation with `teamId` filtering
91+- Role-based permissions (admin, member roles)
92+- Team switching via team-switcher component
93+- All database operations must include team context
9794
98−⚠️ **FORMAT REFERENCE ONLY** - The following sections show what you'll SEE in task files.
99−**Never edit these directly! Use CLI commands to make changes.**
95+### Database Schema
10096
101−### Task Structure You'll See
97+Database is modularly structured in `src/db/schemas/`:
10298
103−```markdown
104−---
105−id: task-42
106−title: Add GraphQL resolver
107−status: To Do
108−assignee: [@sara]
109−labels: [backend, api]
110−---
99+- `users.ts` - User accounts and authentication
100+- `teams.ts` - Team/organization management
101+- `workouts.ts` - Workout management system
102+- `programming.ts` - Programming tracks and scheduling
103+- `billing.ts` - Credit billing system
104+- `scaling.ts` - Workout scaling options
105+- `scheduling.ts` - Schedule templates and scheduling
106+- Main schema exports from `src/db/schema.ts`
111107
112−## Description
108+## Development Guidelines
113109
114−Brief explanation of the task purpose.
110+### Code Style
115111
116−## Acceptance Criteria
112+- Use TypeScript everywhere, prefer interfaces over types
113+- Functional components, avoid classes
114+- Server Components by default, `use client` only when necessary
115+- Add `import "server-only"` to server-only files (except page.tsx)
116+- Use semantic commit messages: `feat:`, `fix:`, `chore:`
117+- Use `pnpm` as package manager
117118
118−<!-- AC:BEGIN -->
119+### Database
119120
120−- [ ] #1 First criterion
121−- [x] #2 Second criterion (completed)
122−- [ ] #3 Third criterion
121+- **Local development**: Use `pnpm db:push` to apply schema changes directly (no migration files)
122+- **Before merging**: Generate migrations with `pnpm db:generate --name=feature-name`
123+- **Never write SQL migrations manually** - always use drizzle-kit
124+- Use `db.transaction()` when multiple writes need to be atomic (PlanetScale supports transactions)
125+- Never pass `id` when inserting (auto-generated with CUID2)
126+- Always filter by `teamId` for multi-tenant data
127+- Use helper functions in `src/server/` for business logic
128+- Use standard Drizzle queries with `inArray()` directly — PlanetScale has no restrictive parameter limits
123129
124−<!-- AC:END -->
130+### Authentication & Authorization
125131
126−## Implementation Plan
132+- Session handling: `getSessionFromCookie()` for server components
133+- Client session: `useSession()` from `src/utils/auth-client.ts`
134+- Team authorization utilities in `src/utils/team-auth.ts`
135+- Protect routes with team context validation
136+- When checking roles use available roles from `src/db/schemas/teams.ts`
127137
128−1. Research approach
129−2. Implement solution
138+### State Management
130139
131−## Implementation Notes
140+- Server state: React Server Components
141+- Client state: Zustand stores in `src/state/`
142+- URL state: NUQS for search parameters
143+- Forms: React Hook Form with Zod validation
132144
133−Summary of what was done.
134−```
145+### API Patterns
135146
136−### How to Modify Each Section
147+- Server functions with TanStack Start: `createServerFn` (see below)
148+- Named object parameters for functions with >1 parameter
149+- Consistent error handling with proper HTTP status codes
150+- Rate limiting on auth endpoints
137151
138−| What You Want to Change | CLI Command to Use |
139−|-------------------------|----------------------------------------------------------|
140−| Title | `backlog task edit 42 -t "New Title"` |
141−| Status | `backlog task edit 42 -s "In Progress"` |
142−| Assignee | `backlog task edit 42 -a @sara` |
143−| Labels | `backlog task edit 42 -l backend,api` |
144−| Description | `backlog task edit 42 -d "New description"` |
145−| Add AC | `backlog task edit 42 --ac "New criterion"` |
146−| Check AC #1 | `backlog task edit 42 --check-ac 1` |
147−| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` |
148−| Remove AC #3 | `backlog task edit 42 --remove-ac 3` |
149−| Add Plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` |
150−| Add Notes | `backlog task edit 42 --notes "What I did"` |
152+### TanStack Start Server Functions (wodsmith-start)
151153
152−---
154+#### Environment Variables
153155
154−## 4. Defining Tasks
156+**ALWAYS** use `env` from `cloudflare:workers` - never use `process.env`:
155157
156−### Creating New Tasks
158+```typescript
159+import {env} from 'cloudflare:workers'
157160
158−**Always use CLI to create tasks:**
159−
160−```bash
161−# Example
162−backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion"
161+env.HYPERDRIVE // PlanetScale via Hyperdrive
162+env.KV_SESSION // KV namespace binding
163+env.APP_URL // Environment variable
164+env.STRIPE_SECRET_KEY // Secret
163165 ```
164166
165−### Title (one liner)
167+**TypeScript not recognizing env vars?** If you've added new bindings in `alchemy.run.ts` and deployed with `pnpm alchemy:dev`, but TypeScript doesn't see them, run:
166168
167−Use a clear brief title that summarizes the task.
168−
169−### Description (The "why")
170−
171−Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.
172−
173−### Acceptance Criteria (The "what")
174−
175−**Understanding the Format:**
176−
177−- Acceptance criteria appear as numbered checkboxes in the markdown files
178−- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked)
179−
180−**Managing Acceptance Criteria via CLI:**
181−
182−⚠️ **IMPORTANT: How AC Commands Work**
183−
184−- **Adding criteria (`--ac`)** accepts multiple flags: `--ac "First" --ac "Second"` ✅
185−- **Checking/unchecking/removing** accept multiple flags too: `--check-ac 1 --check-ac 2` ✅
186−- **Mixed operations** work in a single command: `--check-ac 1 --uncheck-ac 2 --remove-ac 3` ✅
187−
188169 ```bash
189−# Examples
190−
191−# Add new criteria (MULTIPLE values allowed)
192−backlog task edit 42 --ac "User can login" --ac "Session persists"
193−
194−# Check specific criteria by index (MULTIPLE values supported)
195−backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check multiple ACs
196−# Or check them individually if you prefer:
197−backlog task edit 42 --check-ac 1 # Mark #1 as complete
198−backlog task edit 42 --check-ac 2 # Mark #2 as complete
199−
200−# Mixed operations in single command
201−backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3
202−
203−# ❌ STILL WRONG - These formats don't work:
204−# backlog task edit 42 --check-ac 1,2,3 # No comma-separated values
205−# backlog task edit 42 --check-ac 1-3 # No ranges
206−# backlog task edit 42 --check 1 # Wrong flag name
207−
208−# Multiple operations of same type
209−backlog task edit 42 --uncheck-ac 1 --uncheck-ac 2 # Uncheck multiple ACs
210−backlog task edit 42 --remove-ac 2 --remove-ac 4 # Remove multiple ACs (processed high-to-low)
170+lat locate "Section Name" # find a section by name (exact, fuzzy)
171+lat refs "file#Section" # find what references a section
172+lat search "natural language" # semantic search across all sections
173+lat expand "user prompt text" # expand [[refs]] to resolved locations
174+lat check # validate all links and code refs
211175 ```
212176
213−**Key Principles for Good ACs:**
177+Run `lat --help` when in doubt about available commands or options.
214178
215−- **Outcome-Oriented:** Focus on the result, not the method.
216−- **Testable/Verifiable:** Each criterion should be objectively testable
217−- **Clear and Concise:** Unambiguous language
218−- **Complete:** Collectively cover the task scope
219−- **User-Focused:** Frame from end-user or system behavior perspective
179+If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
220180
221−Good Examples:
181+# Syntax primer
222182
223−- "User can successfully log in with valid credentials"
224−- "System processes 1000 requests per second without errors"
225−- "When passing \n characters in description, plan, notes, the system correctly handles them by converting to new lines"
183+- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
184+- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
185+- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
186+- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
226187
227−Bad Example (Implementation Step):
188+# Test specs
228189
229−- "Add a new function handleLogin() in auth.ts"
230−- "Define expected behavior and document supported input patterns"
190+Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
231191
232−### Task Breakdown Strategy
233−
234−1. Identify foundational components first
235−2. Create tasks in dependency order (foundations before features)
236−3. Ensure each task delivers value independently
237−4. Avoid creating tasks that block each other
238−
239−### Task Requirements
240−
241−- Tasks must be **atomic** and **testable** or **verifiable**
242−- Each task should represent a single unit of work for one PR
243−- **Never** reference future tasks (only tasks with id < current task id)
244−- Ensure tasks are **independent** and don't depend on future work
245−
192+```markdown
246193 ---
194+lat:
195+ require-code-mention: true
196+---
197+# Tests
247198
248−## 5. Implementing Tasks
199+Authentication and authorization test specifications.
249200
250−### 5.1. First step when implementing a task
201+## User login
251202
252−The very first things you must do when you take over a task are:
203+Verify credential validation and error handling for the login endpoint.
253204
254−* set the task in progress
255−* assign it to yourself
205+### Rejects expired tokens
206+Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
256207
257−```bash
258−# Example
259−backlog task edit 42 -s "In Progress" -a @{myself}
208+### Handles missing password
209+Login request without a password field returns 400 with a descriptive error.
260210 ```
261211
262−### 5.2. Create an Implementation Plan (The "how")
212+Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
263213
264−Previously created tasks contain the why and the what. Once you are familiar with that part you should think about a
265−plan on **HOW** to tackle the task and all its acceptance criteria. This is your **Implementation Plan**.
266−First do a quick check to see if all the tools that you are planning to use are available in the environment you are
267−working in.
268−When you are ready, write it down in the task so that you can refer to it later.
214+Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
269215
270−```bash
271−# Example
272−backlog task edit 42 --plan "1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test"
273−```
216+```python
217+# @lat: [[tests#User login#Rejects expired tokens]]
218+def test_rejects_expired_tokens():
219+ ...
274220
275−## 5.3. Implementation
276−
277−Once you have a plan, you can start implementing the task. This is where you write code, run tests, and make sure
278−everything works as expected. Follow the acceptance criteria one by one and MARK THEM AS COMPLETE as soon as you
279−finish them.
280−
281−### 5.4 Implementation Notes (PR description)
282−
283−When you are done implementing a tasks you need to prepare a PR description for it.
284−Because you cannot create PRs directly, write the PR as a clean description in the task notes.
285−
286−```bash
287−# Example
288−backlog task edit 42 --notes "Implemented using pattern X because Reason Y, modified files Z and W"
221+# @lat: [[tests#User login#Handles missing password]]
222+def test_handles_missing_password():
223+ ...
289224 ```
290225
291−**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the
292−implementation.
226+Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
293227
294−- Creation phase: provide Title, Description, Acceptance Criteria, and optionally labels/priority/assignee.
295−- When you begin work, switch to edit, set the task in progress and assign to yourself
296− `backlog task edit <id> -s "In Progress" -a "..."`.
297−- Think about how you would solve the task and add the plan: `backlog task edit <id> --plan "..."`.
298−- Add Implementation Notes only after completing the work: `backlog task edit <id> --notes "..."`.
228+# Section structure
299229
300−## Phase discipline: What goes where
230+Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
301231
302−- Creation: Title, Description, Acceptance Criteria, labels/priority/assignee.
303−- Implementation: Implementation Plan (after moving to In Progress and assigning to yourself).
304−- Wrap-up: Implementation Notes (Like a PR description), AC and Definition of Done checks.
232+```markdown
233+# Good Section
305234
306−**IMPORTANT**: Only implement what's in the Acceptance Criteria. If you need to do more, either:
235+Brief overview of what this section documents and why it matters.
307236
308−1. Update the AC first: `backlog task edit 42 --ac "New requirement"`
309−2. Or create a new follow up task: `backlog task create "Additional feature"`
237+More detail can go in subsequent paragraphs, code blocks, or lists.
310238
311−---
239+## Child heading
312240
313−## 6. Typical Workflow
241+Details about this child topic.
242+```
314243
315−```bash
316−# 1. Identify work
317−backlog task list -s "To Do" --plain
244+```markdown
245+# Bad Section
318246
319−# 2. Read task details
320−backlog task 42 --plain
247+## Child heading
321248
322−# 3. Start work: assign yourself & change status
323−backlog task edit 42 -s "In Progress" -a @myself
324−
325−# 4. Add implementation plan
326−backlog task edit 42 --plan "1. Analyze\n2. Refactor\n3. Test"
327−
328−# 5. Work on the task (write code, test, etc.)
329−
330−# 6. Mark acceptance criteria as complete (supports multiple in one command)
331−backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3 # Check all at once
332−# Or check them individually if preferred:
333−# backlog task edit 42 --check-ac 1
334−# backlog task edit 42 --check-ac 2
335−# backlog task edit 42 --check-ac 3
336−
337−# 7. Add implementation notes (PR Description)
338−backlog task edit 42 --notes "Refactored using strategy pattern, updated tests"
339−
340−# 8. Mark task as done
341−backlog task edit 42 -s Done
249+Details about this child topic.
342250 ```
343251
344−---
252+The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
345253
346−## 7. Definition of Done (DoD)
254+<!-- intent-skills:start -->
255+# Skill mappings - when working in these areas, load the linked skill file into context.
256+skills:
257+ - task: "TanStack Router core concepts, route trees, createRouter, createRoute, file naming conventions"
258+ load: "node_modules/@tanstack/router-core/skills/router-core/SKILL.md"
259+ - task: "Route protection, auth guards, beforeLoad redirects, RBAC, authenticated layouts"
260+ load: "node_modules/@tanstack/router-core/skills/router-core/auth-and-guards/SKILL.md"
261+ - task: "Code splitting, lazy routes, .lazy.tsx, autoCodeSplitting, getRouteApi"
262+ load: "node_modules/@tanstack/router-core/skills/router-core/code-splitting/SKILL.md"
263+ - task: "Route data loading, loaders, loaderDeps, staleTime, pendingComponent, Await, deferred data"
264+ load: "node_modules/@tanstack/router-core/skills/router-core/data-loading/SKILL.md"
265+ - task: "Link component, useNavigate, preloading, navigation blocking, scroll restoration"
266+ load: "node_modules/@tanstack/router-core/skills/router-core/navigation/SKILL.md"
267+ - task: "notFound handling, errorComponent, CatchBoundary, route masking"
268+ load: "node_modules/@tanstack/router-core/skills/router-core/not-found-and-errors/SKILL.md"
269+ - task: "Dynamic path params, splat routes, optional params, useParams"
270+ load: "node_modules/@tanstack/router-core/skills/router-core/path-params/SKILL.md"
271+ - task: "Search params validation, Zod adapters, search middlewares, retainSearchParams"
272+ load: "node_modules/@tanstack/router-core/skills/router-core/search-params/SKILL.md"
273+ - task: "SSR, streaming, renderRouterToStream, HeadContent, Scripts, head route option, meta tags"
274+ load: "node_modules/@tanstack/router-core/skills/router-core/ssr/SKILL.md"
275+ - task: "Router type safety, Register declaration, from narrowing, strict mode, LinkProps"
276+ load: "node_modules/@tanstack/router-core/skills/router-core/type-safety/SKILL.md"
277+<!-- intent-skills:end -->
347278
348−A task is **Done** only when **ALL** of the following are complete:
279+<!-- gitnexus:start -->
280+# GitNexus — Code Intelligence
349281
350−### ✅ Via CLI Commands:
282+This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
351283
352−1. **All acceptance criteria checked**: Use `backlog task edit <id> --check-ac <index>` for each
353−2. **Implementation notes added**: Use `backlog task edit <id> --notes "..."`
354−3. **Status set to Done**: Use `backlog task edit <id> -s Done`
284+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
355285
356−### ✅ Via Code/Testing:
286+## Always Do
357287
358−4. **Tests pass**: Run test suite and linting
359−5. **Documentation updated**: Update relevant docs if needed
360−6. **Code reviewed**: Self-review your changes
361−7. **No regressions**: Performance, security checks pass
288+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
289+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
290+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
291+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
292+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
362293
363−⚠️ **NEVER mark a task as Done without completing ALL items above**
294+## Never Do
364295
365−---
296+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
297+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
298+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
299+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
366300
367−## 8. Quick Reference: DO vs DON'T
301+## Resources
368302
369−### Viewing Tasks
303+| Resource | Use for |
304+|----------|---------|
305+| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
306+| `gitnexus://repo/thewodapp/clusters` | All functional areas |
307+| `gitnexus://repo/thewodapp/processes` | All execution flows |
308+| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
370309
371−| Task | ✅ DO | ❌ DON'T |
372−|--------------|-----------------------------|---------------------------------|
373−| View task | `backlog task 42 --plain` | Open and read .md file directly |
374−| List tasks | `backlog task list --plain` | Browse backlog/tasks folder |
375−| Check status | `backlog task 42 --plain` | Look at file content |
310+## CLI
376311
377−### Modifying Tasks
312+| Task | Read this skill file |
313+|------|---------------------|
314+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
315+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
316+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
317+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
318+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
319+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
378320
379−| Task | ✅ DO | ❌ DON'T |
380−|---------------|--------------------------------------|-----------------------------------|
381−| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file |
382−| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file |
383−| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter |
384−| Add AC | `backlog task edit 42 --ac "New"` | Add `- [ ] New` to file |
385−
386−---
387−
388−## 9. Complete CLI Command Reference
389−
390−### Task Creation
391−
392−| Action | Command |
393−|------------------|-------------------------------------------------------------------------------------|
394−| Create task | `backlog task create "Title"` |
395−| With description | `backlog task create "Title" -d "Description"` |
396−| With AC | `backlog task create "Title" --ac "Criterion 1" --ac "Criterion 2"` |
397−| With all options | `backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l auth --priority high` |
398−| Create draft | `backlog task create "Title" --draft` |
399−| Create subtask | `backlog task create "Title" -p 42` |
400−
401−### Task Modification
402−
403−| Action | Command |
404−|------------------|---------------------------------------------|
405−| Edit title | `backlog task edit 42 -t "New Title"` |
406−| Edit description | `backlog task edit 42 -d "New description"` |
407−| Change status | `backlog task edit 42 -s "In Progress"` |
408−| Assign | `backlog task edit 42 -a @sara` |
409−| Add labels | `backlog task edit 42 -l backend,api` |
410−| Set priority | `backlog task edit 42 --priority high` |
411−
412−### Acceptance Criteria Management
413−
414−| Action | Command |
415−|---------------------|-----------------------------------------------------------------------------|
416−| Add AC | `backlog task edit 42 --ac "New criterion" --ac "Another"` |
417−| Remove AC #2 | `backlog task edit 42 --remove-ac 2` |
418−| Remove multiple ACs | `backlog task edit 42 --remove-ac 2 --remove-ac 4` |
419−| Check AC #1 | `backlog task edit 42 --check-ac 1` |
420−| Check multiple ACs | `backlog task edit 42 --check-ac 1 --check-ac 3` |
421−| Uncheck AC #3 | `backlog task edit 42 --uncheck-ac 3` |
422−| Mixed operations | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --remove-ac 3 --ac "New"` |
423−
424−### Task Content
425−
426−| Action | Command |
427−|------------------|----------------------------------------------------------|
428−| Add plan | `backlog task edit 42 --plan "1. Step one\n2. Step two"` |
429−| Add notes | `backlog task edit 42 --notes "Implementation details"` |
430−| Add dependencies | `backlog task edit 42 --dep task-1 --dep task-2` |
431−
432−Descriptions support literal newlines; shell examples may show escaped `\\n`, but enter a single `\n` to create a newline.
433−
434−### Task Operations
435−
436−| Action | Command |
437−|--------------------|----------------------------------------------|
438−| View task | `backlog task 42 --plain` |
439−| List tasks | `backlog task list --plain` |
440−| Filter by status | `backlog task list -s "In Progress" --plain` |
441−| Filter by assignee | `backlog task list -a @sara --plain` |
442−| Archive task | `backlog task archive 42` |
443−| Demote to draft | `backlog task demote 42` |
444−
445−---
446−
447−## Common Issues
448−
449−| Problem | Solution |
450−|----------------------|--------------------------------------------------------------------|
451−| Task not found | Check task ID with `backlog task list --plain` |
452−| AC won't check | Use correct index: `backlog task 42 --plain` to see AC numbers |
453−| Changes not saving | Ensure you're using CLI, not editing files |
454−| Metadata out of sync | Re-edit via CLI to fix: `backlog task edit 42 -s <current-status>` |
455−
456−---
457−
458−## Remember: The Golden Rule
459−
460−**🎯 If you want to change ANYTHING in a task, use the `backlog task edit` command.**
461−**📖 Use CLI to read tasks, exceptionally READ task files directly, never WRITE to them.**
462−
463−Full help available: `backlog --help`
464−
465−# === BACKLOG.MD GUIDELINES END ===
321+<!-- gitnexus:end -->
466322
