| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 24 | 57 | 0% |
| Commands | 0 | 1 | 2 | 0% |
| Section tags | 5 | 0 | 3 | 63% |
What each file covers
Sections
0 shared · 24 only in A · 57 only in B- − Before starting work
- − Post-task checklist (REQUIRED — do not skip)
- − What is lat.md?
- − Commands
- − Syntax primer
- − Test specs
- − Tests
- − User login
- − Rejects expired tokens
- − Handles missing password
- − @lat: [[tests#User login#Rejects expired tokens]]
- − @lat: [[tests#User login#Handles missing password]]
- − Section structure
- − Good Section
- − Child heading
- − Bad Section
- − CRM Agent APIs
- − Discover Capabilities
- − Upload CRM Documents
- − GitNexus — Code Intelligence
- − Always Do
- − Never Do
- − Resources
- − CLI
- + === 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 · 1 only in A · 2 only in B- − npx gitnexus analyze
- + task-<id> - <title>.md
- + task-42 - Add GraphQL resolver.md
Section tags
5 shared · 0 only in A · 3 only in B- + lint-format
- + types
- + git-pr
- test
- code-style
- architecture
- do-not
- agent-behaviour
Line diff
wodsmith/thewodapp · AGENTS.md
@@ −1 @@
1# Before starting work
2
3- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
5
6# Post-task checklist (REQUIRED — do not skip)
7
8After EVERY task, before responding to the user:
9
10- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11- [ ] Run `lat check` — all wiki links and code refs must pass
12- [ ] Do not skip these steps. Do not consider your task done until both are complete.
13
14---
15
16# What is lat.md?
17
18This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
19
20# Commands
21
22```bash
23lat locate "Section Name" # find a section by name (exact, fuzzy)
24lat refs "file#Section" # find what references a section
25lat search "natural language" # semantic search across all sections
26lat expand "user prompt text" # expand [[refs]] to resolved locations
27lat check # validate all links and code refs
28```
29
30Run `lat --help` when in doubt about available commands or options.
31
32If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
33
34# Syntax primer
35
36- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
37- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
38- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
39- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
40
41# Test specs
42
43Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
44
45```markdown
46---
47lat:
48 require-code-mention: true
49---
50# Tests
51
52Authentication and authorization test specifications.
53
54## User login
55
56Verify credential validation and error handling for the login endpoint.
57
58### Rejects expired tokens
59Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
60
61### Handles missing password
62Login request without a password field returns 400 with a descriptive error.
63```
64
65Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
66
67Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
68
69```python
70# @lat: [[tests#User login#Rejects expired tokens]]
71def test_rejects_expired_tokens():
72 ...
73
74# @lat: [[tests#User login#Handles missing password]]
75def test_handles_missing_password():
76 ...
77```
78
79Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
80
81# Section structure
82
83Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
84
85```markdown
86# Good Section
87
88Brief overview of what this section documents and why it matters.
89
90More detail can go in subsequent paragraphs, code blocks, or lists.
91
92## Child heading
93
94Details about this child topic.
95```
96
97```markdown
98# Bad Section
99
100## Child heading
101
102Details about this child topic.
103```
104
105The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
106
107## CRM Agent APIs
108
109The CRM exposes authenticated JSON endpoints for automation. Agents should prefer these endpoints over native browser file-picker automation.
110
111### Discover Capabilities
112
113`GET /api/crm/agent-capabilities`
114
115Requires an authenticated CRM session cookie. Returns machine-readable capabilities, including the document upload endpoint and request body shape.
116
117### Upload CRM Documents
118
119`POST /api/crm/documents`
120
121Requires an authenticated CRM session cookie. Use this endpoint to attach local files to CRM entries, especially transcript files referenced in interaction notes.
122
123Body:
124
125- `entryId`: CRM entry id, such as an interaction id.
126- `fileName`: original file name.
127- `fileBase64`: base64-encoded file contents.
128- `fileSize`: byte size.
129- `contentType`: MIME type, usually `text/markdown` for transcripts.
130- `title`: optional display label.
131
132Example:
133
134```json
135{
136 "entryId": "meet_nathan_cff_20260403_000",
137 "fileName": "2026-04-03-nathan-crossfit-fullerton.md",
138 "fileBase64": "...",
139 "fileSize": 50732,
140 "contentType": "text/markdown",
141 "title": "2026-04-03 Nathan CrossFit Fullerton transcript"
142}
143```
144
145The CRM document panel also exposes DOM hints:
146
147- `data-agent-capabilities="/api/crm/agent-capabilities"`
148- `data-agent-document-upload-api="/api/crm/documents"`
149- `data-agent-entry-id="<current entry id>"`
150- `data-agent-preferred-action="uploadCrmDocument"` on the upload form.
151- `data-agent-api="/api/crm/documents"` on the upload form.
152
153<!-- gitnexus:start -->
154# GitNexus — Code Intelligence
155
156This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
157
158> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
159
160## Always Do
161
162- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
163- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
164- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
165- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
166- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
167
168## Never Do
169
170- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
171- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
172- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
173- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
174
175## Resources
176
177| Resource | Use for |
178|----------|---------|
179| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
180| `gitnexus://repo/thewodapp/clusters` | All functional areas |
181| `gitnexus://repo/thewodapp/processes` | All execution flows |
182| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
183
184## CLI
185
186| Task | Read this skill file |
187|------|---------------------|
188| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
189| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
190| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
191| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
192| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
193| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
194
195<!-- gitnexus:end -->
196
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
@@ −1 +1 @@
1−# Before starting work
21
3−- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4−- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
2+# === BACKLOG.MD GUIDELINES START ===
3+# Instructions for the usage of Backlog.md CLI Tool
54
6−# Post-task checklist (REQUIRED — do not skip)
5+## Backlog.md: Comprehensive Project Management Tool via CLI
76
8−After EVERY task, before responding to the user:
7+### Assistant Objective
98
10−- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11−- [ ] Run `lat check` — all wiki links and code refs must pass
12−- [ ] Do not skip these steps. Do not consider your task done until both are complete.
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.
1311
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+
1438 ---
1539
16−# What is lat.md?
40+# ⚠️ CRITICAL: NEVER EDIT TASK FILES DIRECTLY. Edit Only via CLI
1741
18−This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
42+**ALL task operations MUST use the Backlog.md CLI commands**
1943
20−# 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
2150
22−```bash
23−lat locate "Section Name" # find a section by name (exact, fuzzy)
24−lat refs "file#Section" # find what references a section
25−lat search "natural language" # semantic search across all sections
26−lat expand "user prompt text" # expand [[refs]] to resolved locations
27−lat check # validate all links and code refs
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+
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
2883 ```
2984
30−Run `lat --help` when in doubt about available commands or options.
85+### ✅ **CORRECT: Using CLI Commands**
3186
32−If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
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+```
3393
34−# Syntax primer
94+---
3595
36−- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
37−- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
38−- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
39−- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
96+## 3. Understanding Task Format (Read-Only Reference)
4097
41−# Test specs
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.**
42100
43−Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
101+### Task Structure You'll See
44102
45103 ```markdown
46104 ---
47−lat:
48− require-code-mention: true
105+id: task-42
106+title: Add GraphQL resolver
107+status: To Do
108+assignee: [@sara]
109+labels: [backend, api]
49110 ---
50−# Tests
51111
52−Authentication and authorization test specifications.
112+## Description
53113
54−## User login
114+Brief explanation of the task purpose.
55115
56−Verify credential validation and error handling for the login endpoint.
116+## Acceptance Criteria
57117
58−### Rejects expired tokens
59−Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
118+<!-- AC:BEGIN -->
60119
61−### Handles missing password
62−Login request without a password field returns 400 with a descriptive error.
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.
63134 ```
64135
65−Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
136+### How to Modify Each Section
66137
67−Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
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"` |
68151
69−```python
70−# @lat: [[tests#User login#Rejects expired tokens]]
71−def test_rejects_expired_tokens():
72− ...
152+---
73153
74−# @lat: [[tests#User login#Handles missing password]]
75−def test_handles_missing_password():
76− ...
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"
77163 ```
78164
79−Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
165+### Title (one liner)
80166
81−# Section structure
167+Use a clear brief title that summarizes the task.
82168
83−Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
169+### Description (The "why")
84170
85−```markdown
86−# Good Section
171+Provide a concise summary of the task purpose and its goal. Explains the context without implementation details.
87172
88−Brief overview of what this section documents and why it matters.
173+### Acceptance Criteria (The "what")
89174
90−More detail can go in subsequent paragraphs, code blocks, or lists.
175+**Understanding the Format:**
91176
92−## Child heading
177+- Acceptance criteria appear as numbered checkboxes in the markdown files
178+- Format: `- [ ] #1 Criterion text` (unchecked) or `- [x] #1 Criterion text` (checked)
93179
94−Details about this child topic.
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)
95211 ```
96212
97−```markdown
98−# Bad Section
213+**Key Principles for Good ACs:**
99214
100−## Child heading
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
101220
102−Details about this child topic.
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}
103260 ```
104261
105−The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
262+### 5.2. Create an Implementation Plan (The "how")
106263
107−## CRM Agent APIs
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.
108269
109−The CRM exposes authenticated JSON endpoints for automation. Agents should prefer these endpoints over native browser file-picker automation.
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+```
110274
111−### Discover Capabilities
275+## 5.3. Implementation
112276
113−`GET /api/crm/agent-capabilities`
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.
114280
115−Requires an authenticated CRM session cookie. Returns machine-readable capabilities, including the document upload endpoint and request body shape.
281+### 5.4 Implementation Notes (PR description)
116282
117−### Upload CRM Documents
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.
118285
119−`POST /api/crm/documents`
286+```bash
287+# Example
288+backlog task edit 42 --notes "Implemented using pattern X because Reason Y, modified files Z and W"
289+```
120290
121−Requires an authenticated CRM session cookie. Use this endpoint to attach local files to CRM entries, especially transcript files referenced in interaction notes.
291+**IMPORTANT**: Do NOT include an Implementation Plan when creating a task. The plan is added only after you start the
292+implementation.
122293
123−Body:
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 "..."`.
124299
125−- `entryId`: CRM entry id, such as an interaction id.
126−- `fileName`: original file name.
127−- `fileBase64`: base64-encoded file contents.
128−- `fileSize`: byte size.
129−- `contentType`: MIME type, usually `text/markdown` for transcripts.
130−- `title`: optional display label.
300+## Phase discipline: What goes where
131301
132−Example:
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.
133305
134−```json
135−{
136− "entryId": "meet_nathan_cff_20260403_000",
137− "fileName": "2026-04-03-nathan-crossfit-fullerton.md",
138− "fileBase64": "...",
139− "fileSize": 50732,
140− "contentType": "text/markdown",
141− "title": "2026-04-03 Nathan CrossFit Fullerton transcript"
142−}
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
143342 ```
144343
145−The CRM document panel also exposes DOM hints:
344+---
146345
147−- `data-agent-capabilities="/api/crm/agent-capabilities"`
148−- `data-agent-document-upload-api="/api/crm/documents"`
149−- `data-agent-entry-id="<current entry id>"`
150−- `data-agent-preferred-action="uploadCrmDocument"` on the upload form.
151−- `data-agent-api="/api/crm/documents"` on the upload form.
346+## 7. Definition of Done (DoD)
152347
153−<!-- gitnexus:start -->
154−# GitNexus — Code Intelligence
348+A task is **Done** only when **ALL** of the following are complete:
155349
156−This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
350+### ✅ Via CLI Commands:
157351
158−> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
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`
159355
160−## Always Do
356+### ✅ Via Code/Testing:
161357
162−- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
163−- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
164−- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
165−- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
166−- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
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
167362
168−## Never Do
363+⚠️ **NEVER mark a task as Done without completing ALL items above**
169364
170−- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
171−- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
172−- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
173−- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
365+---
174366
175−## Resources
367+## 8. Quick Reference: DO vs DON'T
176368
177−| Resource | Use for |
178−|----------|---------|
179−| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
180−| `gitnexus://repo/thewodapp/clusters` | All functional areas |
181−| `gitnexus://repo/thewodapp/processes` | All execution flows |
182−| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
369+### Viewing Tasks
183370
184−## CLI
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 |
185376
186−| Task | Read this skill file |
187−|------|---------------------|
188−| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
189−| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
190−| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
191−| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
192−| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
193−| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
377+### Modifying Tasks
194378
195−<!-- gitnexus:end -->
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 ===
196466
