.cursorrules (deprecated)

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 &quot;Implementation complete&quot;  # Add notes
91backlog task edit 7 -s &quot;In Progress&quot; -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 &quot;Task title&quot; -d &quot;Description&quot; --ac &quot;First criterion&quot; --ac &quot;Second criterion&quot;
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 &quot;User can login&quot; --ac &quot;Session persists&quot;
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 &quot;In Progress&quot; -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 &quot;1. Research codebase for references\n2Research on internet for similar cases\n3. Implement\n4. Test&quot;
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 &quot;Implemented using pattern X because Reason Y, modified files Z and W&quot;
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 &quot;To Do&quot; --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 &quot;In Progress&quot; -a @myself
324 
325# 4. Add implementation plan
326backlog task edit 42 --plan &quot;1. Analyze\n2. Refactor\n3. Test&quot;
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 &quot;Refactored using strategy pattern, updated tests&quot;
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