Comparison

A · CLAUDE.md · wodsmith/thewodapp B · .cursorrules · wodsmith/thewodapp

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	3	57	0%
Commands	0	16	2	0%
Section tags	2	1	6	22%

What each file covers

Sections

0 shared · 3 only in A · 57 only in B

− APIs
− Testing
− Frontend
+ === 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

Commands

0 shared · 16 only in A · 2 only in B

− 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
+ task-<id> - <title>.md
+ task-42 - Add GraphQL resolver.md

Section tags

2 shared · 1 only in A · 6 only in B

− setup
+ lint-format
+ architecture
+ types
+ git-pr
+ do-not
+ agent-behaviour
test
code-style

Line diff

+433 added−79 removed33 unchanged7.1% identical

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---

7Default to using Bun instead of Node.js.

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.

16## APIs

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.

26## Testing

28Use `bun test` to run tests.

30```ts#index.test.ts

31import { test, expect } from "bun:test";

33test("hello world", () => {

34 expect(1).toBe(1);

35});

36```

38## Frontend

40Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.

42Server:

44```ts#index.ts

45import index from "./index.html"

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```

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.

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```

86With the following `frontend.tsx`:

88```tsx#frontend.tsx

89import React from "react";

91// import .css files directly and it works

92import './index.css';

94import { createRoot } from "react-dom/client";

96const root = createRoot(document.body);

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

wodsmith/thewodapp · .cursorrules

@@ +1 @@

2# === BACKLOG.MD GUIDELINES START ===

3# Instructions for the usage of Backlog.md CLI Tool

5## Backlog.md: Comprehensive Project Management Tool via CLI

7### Assistant Objective

9Efficiently manage all project tasks, status, and documentation using the Backlog.md CLI, ensuring all project metadata

10remains fully synchronized and up-to-date.

12### Core Capabilities

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

23### Why This Matters to You (AI Agent)

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

31### Key Understanding

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

38---

40# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI

42**ALL task operations MUST use the Backlog.md CLI commands**

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

51**Why?** Direct file editing breaks metadata synchronization, Git tracking, and task relationships.

53---

55## 1. Source of Truth & File Structure

57### 📖 **UNDERSTANDING** (What you'll see when reading)

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/`**

64### 🔧 **ACTING** (How to change things)

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

70---

72## 2. Common Mistakes to Avoid

74### ❌ **WRONG: Direct File Editing**

76```markdown

77# DON'T DO THIS:

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```

85### ✅ **CORRECT: Using CLI Commands**

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```

94---

96## 3. Understanding Task Format (Read-Only Reference)

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

119

120- [ ] #1 First criterion

121- [x] #2 Second criterion (completed)

122- [ ] #3 Third criterion

123

124

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

@@ −1 +1 @@

2+# === BACKLOG.MD GUIDELINES START ===

3+# Instructions for the usage of Backlog.md CLI Tool

5+## Backlog.md: Comprehensive Project Management Tool via CLI

7+### Assistant Objective

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+

138 ---

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

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+

553 ---

654

7−Default to using Bun instead of Node.js.

55+## 1. Source of Truth & File Structure

856

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.

57+### 📖 **UNDERSTANDING** (What you'll see when reading)

1558

16−## APIs

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/`**

1763

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.

64+### 🔧 **ACTING** (How to change things)

2565

26−## Testing

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

2769

28−Use `bun test` to run tests.

70+---

2971

30−```ts#index.test.ts

31−import { test, expect } from "bun:test";

72+## 2. Common Mistakes to Avoid

3273

33−test("hello world", () => {

34− expect(1).toBe(1);

35−});

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

3683 ```

3784

38−## Frontend

85+### ✅ **CORRECT: Using CLI Commands**

3986

40−Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.

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+```

4193

42−Server:

94+---

4395

44−```ts#index.ts

45−import index from "./index.html"

96+## 3. Understanding Task Format (Read-Only Reference)

4697

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−})

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+

119+

120+- [ ] #1 First criterion

121+- [x] #2 Second criterion (completed)

122+- [ ] #3 Third criterion

123+

124+

125+

126+## Implementation Plan

127+

128+1. Research approach

129+2. Implement solution

130+

131+## Implementation Notes

132+

133+Summary of what was done.

73134 ```

74135

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.

136+### How to Modify Each Section

76137

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>

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"

84163 ```

85164

86−With the following `frontend.tsx`:

165+### Title (one liner)

87166

88−```tsx#frontend.tsx

89−import React from "react";

167+Use a clear brief title that summarizes the task.

90168

91−// import .css files directly and it works

92−import './index.css';

169+### Description (The "why")

93170

94−import { createRoot } from "react-dom/client";

171+Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.

95172

96−const root = createRoot(document.body);

173+### Acceptance Criteria (The "what")

97174

98−export default function Frontend() {

99− return <h1>Hello, world!</h1>;

100−}

175+**Understanding the Format:**

101176

102−root.render(<Frontend />);

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)

103211 ```

104212

105−Then, run index.ts

213+**Key Principles for Good ACs:**

106214

107−```sh

108−bun --hot ./index.ts

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}

109260 ```

110261

111−For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.

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 ===

112466