| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 57 | 3 | 0% |
| Commands | 0 | 2 | 16 | 0% |
| Section tags | 2 | 6 | 1 | 22% |
What each file covers
Sections
0 shared · 57 only in A · 3 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
- + APIs
- + Testing
- + Frontend
Commands
0 shared · 2 only in A · 16 only in B- − task-<id> - <title>.md
- − task-42 - Add GraphQL resolver.md
- + bun <file>
- + node <file>
- + bun test
- + jest
- + vitest
- + bun build <file.html|file.ts|file.css>
- + bun install
- + npm install
- + yarn install
- + pnpm install
- + bun run <script>
- + npm run <script>
- + yarn run <script>
- + pnpm run <script>
- + bun:sqlite
- + node:fs
Section tags
2 shared · 6 only in A · 1 only in B- − lint-format
- − architecture
- − types
- − git-pr
- − do-not
- − agent-behaviour
- + setup
- test
- code-style
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/hooks/CLAUDE.md
@@ +1 @@
1---
2description: Use Bun instead of Node.js, npm, pnpm, or vite.
3globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
4alwaysApply: false
5---
6
7Default to using Bun instead of Node.js.
8
9- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
10- Use `bun test` instead of `jest` or `vitest`
11- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
12- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
13- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
14- Bun automatically loads .env, so don't use dotenv.
15
16## APIs
17
18- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
19- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
20- `Bun.redis` for Redis. Don't use `ioredis`.
21- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
22- `WebSocket` is built-in. Don't use `ws`.
23- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
24- Bun.$`ls` instead of execa.
25
26## Testing
27
28Use `bun test` to run tests.
29
30```ts#index.test.ts
31import { test, expect } from "bun:test";
32
33test("hello world", () => {
34 expect(1).toBe(1);
35});
36```
37
38## Frontend
39
40Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
41
42Server:
43
44```ts#index.ts
45import index from "./index.html"
46
47Bun.serve({
48 routes: {
49 "/": index,
50 "/api/users/:id": {
51 GET: (req) => {
52 return new Response(JSON.stringify({ id: req.params.id }));
53 },
54 },
55 },
56 // optional websocket support
57 websocket: {
58 open: (ws) => {
59 ws.send("Hello, world!");
60 },
61 message: (ws, message) => {
62 ws.send(message);
63 },
64 close: (ws) => {
65 // handle close
66 }
67 },
68 development: {
69 hmr: true,
70 console: true,
71 }
72})
73```
74
75HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
76
77```html#index.html
78<html>
79 <body>
80 <h1>Hello, world!</h1>
81 <script type="module" src="./frontend.tsx"></script>
82 </body>
83</html>
84```
85
86With the following `frontend.tsx`:
87
88```tsx#frontend.tsx
89import React from "react";
90
91// import .css files directly and it works
92import './index.css';
93
94import { createRoot } from "react-dom/client";
95
96const root = createRoot(document.body);
97
98export default function Frontend() {
99 return <h1>Hello, world!</h1>;
100}
101
102root.render(<Frontend />);
103```
104
105Then, run index.ts
106
107```sh
108bun --hot ./index.ts
109```
110
111For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
112
@@ −1 +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−
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.
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−
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
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−
381 ---
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−
2+description: Use Bun instead of Node.js, npm, pnpm, or vite.
3+globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
4+alwaysApply: false
535 ---
546
55−## 1. Source of Truth & File Structure
7+Default to using Bun instead of Node.js.
568
57−### 📖 **UNDERSTANDING** (What you'll see when reading)
9+- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
10+- Use `bun test` instead of `jest` or `vitest`
11+- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
12+- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
13+- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
14+- Bun automatically loads .env, so don't use dotenv.
5815
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/`**
16+## APIs
6317
64−### 🔧 **ACTING** (How to change things)
18+- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
19+- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
20+- `Bun.redis` for Redis. Don't use `ioredis`.
21+- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
22+- `WebSocket` is built-in. Don't use `ws`.
23+- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
24+- Bun.$`ls` instead of execa.
6525
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
26+## Testing
6927
70−---
28+Use `bun test` to run tests.
7129
72−## 2. Common Mistakes to Avoid
30+```ts#index.test.ts
31+import { test, expect } from "bun:test";
7332
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
33+test("hello world", () => {
34+ expect(1).toBe(1);
35+});
8336 ```
8437
85−### ✅ **CORRECT: Using CLI Commands**
38+## Frontend
8639
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
92−```
40+Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
9341
94−---
42+Server:
9543
96−## 3. Understanding Task Format (Read-Only Reference)
44+```ts#index.ts
45+import index from "./index.html"
9746
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−---
105−id: task-42
106−title: Add GraphQL resolver
107−status: To Do
108−assignee: [@sara]
109−labels: [backend, api]
110−---
111−
112−## Description
113−
114−Brief 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−
128−1. Research approach
129−2. Implement solution
130−
131−## Implementation Notes
132−
133−Summary of what was done.
47+Bun.serve({
48+ routes: {
49+ "/": index,
50+ "/api/users/:id": {
51+ GET: (req) => {
52+ return new Response(JSON.stringify({ id: req.params.id }));
53+ },
54+ },
55+ },
56+ // optional websocket support
57+ websocket: {
58+ open: (ws) => {
59+ ws.send("Hello, world!");
60+ },
61+ message: (ws, message) => {
62+ ws.send(message);
63+ },
64+ close: (ws) => {
65+ // handle close
66+ }
67+ },
68+ development: {
69+ hmr: true,
70+ console: true,
71+ }
72+})
13473 ```
13574
136−### How to Modify Each Section
75+HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
13776
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
162−backlog task create "Task title" -d "Description" --ac "First criterion" --ac "Second criterion"
77+```html#index.html
78+<html>
79+ <body>
80+ <h1>Hello, world!</h1>
81+ <script type="module" src="./frontend.tsx"></script>
82+ </body>
83+</html>
16384 ```
16485
165−### Title (one liner)
86+With the following `frontend.tsx`:
16687
167−Use a clear brief title that summarizes the task.
88+```tsx#frontend.tsx
89+import React from "react";
16890
169−### Description (The "why")
91+// import .css files directly and it works
92+import './index.css';
17093
171−Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.
94+import { createRoot } from "react-dom/client";
17295
173−### Acceptance Criteria (The "what")
96+const root = createRoot(document.body);
17497
175−**Understanding the Format:**
98+export default function Frontend() {
99+ return <h1>Hello, world!</h1>;
100+}
176101
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)
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)
102+root.render(<Frontend />);
211103 ```
212104
213−**Key Principles for Good ACs:**
105+Then, run index.ts
214106
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−
221−Good 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−
227−Bad 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−
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−
246−---
247−
248−## 5. Implementing Tasks
249−
250−### 5.1. First step when implementing a task
251−
252−The 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
259−backlog task edit 42 -s "In Progress" -a @{myself}
107+```sh
108+bun --hot ./index.ts
260109 ```
261110
262−### 5.2. Create an Implementation Plan (The "how")
263−
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.
269−
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−```
274−
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"
289−```
290−
291−**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the
292−implementation.
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−
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"`
310−
311−---
312−
313−## 6. Typical Workflow
314−
315−```bash
316−# 1. Identify work
317−backlog task list -s "To Do" --plain
318−
319−# 2. Read task details
320−backlog task 42 --plain
321−
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
342−```
343−
344−---
345−
346−## 7. Definition of Done (DoD)
347−
348−A task is **Done** only when **ALL** of the following are complete:
349−
350−### ✅ Via CLI Commands:
351−
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`
355−
356−### ✅ Via Code/Testing:
357−
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
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−
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 ===
111+For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
466112
