backlog.md-linux-x64 1.35.7 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +91 -358
  2. package/backlog +0 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -10,14 +10,15 @@
10
10
 
11
11
  ---
12
12
 
13
- > **Backlog.md** turns any folder with a Git repo into a **self‑contained project board**
13
+ > **Backlog.md** turns any folder with a Git repo into a **self‑contained project board**
14
14
  > powered by plain Markdown files and a zero‑config CLI.
15
+ > Built for **spec‑driven AI development** — structure your tasks so AI agents deliver predictable results.
15
16
 
16
17
  ## Features
17
18
 
18
19
  * 📝 **Markdown-native tasks** -- manage every issue as a plain `.md` file
19
20
 
20
- * 🤖 **AI-Ready** -- Works with Claude Code, Gemini CLI, Codex & any other MCP or CLI compatible AI assistants
21
+ * 🤖 **AI-Ready** -- Works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistants
21
22
 
22
23
  * 📊 **Instant terminal Kanban** -- `backlog board` paints a live board in your shell
23
24
 
@@ -39,38 +40,80 @@
39
40
 
40
41
  ---
41
42
 
42
- ## <img src="./.github/5-minute-tour-256.png" alt="5-minute tour" width="28" height="28" align="center"> Five‑minute tour
43
+ ## <img src="./.github/5-minute-tour-256.png" alt="Getting started" width="28" height="28" align="center"> Getting started
44
+
43
45
  ```bash
44
- # 1. Make sure you have Backlog.md installed (global installation recommended)
45
- bun i -g backlog.md
46
- or
47
- npm i -g backlog.md
48
- or
49
- brew install backlog-md
50
-
51
- # 2. Bootstrap a repo + backlog and choose the AI Agent integration mode (MCP, CLI, or skip)
46
+ # Install
47
+ bun i -g backlog.md
48
+ # or: npm i -g backlog.md
49
+ # or: brew install backlog-md
50
+
51
+ # Initialize in any git repo
52
52
  backlog init "My Awesome Project"
53
+ ```
53
54
 
54
- # 3. Create tasks manually
55
- backlog task create "Render markdown as kanban"
55
+ The init wizard will ask how you want to connect AI tools:
56
+ - **MCP connector** (recommended) — auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor and adds workflow instructions for your agents.
57
+ - **CLI commands** — creates instruction files (CLAUDE.md, AGENTS.md, etc.) so agents use Backlog via CLI.
58
+ - **Skip** — no AI setup; use Backlog.md purely as a task manager.
59
+
60
+ All data is saved under the `backlog` folder as human-readable Markdown files (e.g. `task-10 - Add core search functionality.md`).
61
+
62
+ ---
63
+
64
+ ### Working with AI agents
65
+
66
+ This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools — following the **spec‑driven AI development** approach.
67
+ After running `backlog init` and choosing the MCP or CLI integration, work in this loop:
68
+
69
+ **Step 1 — Describe your idea.** Tell the agent what you want to build and ask it to split the work into small tasks with clear descriptions and acceptance criteria.
70
+
71
+ **🤖 Ask your AI Agent:**
72
+ > I want to add a search feature to the web view that searches tasks, docs, and decisions. Please decompose this into small Backlog.md tasks.
73
+
74
+ > [!NOTE]
75
+ > **Review checkpoint #1** — read the task descriptions and acceptance criteria.
76
+
77
+ **Step 2 — One task at a time.** Work on a single task per agent session, one PR per task. Good task splitting means each session can work independently without conflicts. Make sure each task is small enough to complete in a single conversation. You want to avoid running out of context window.
78
+
79
+ **Step 3 — Plan before coding.** Ask the agent to research and write an implementation plan in the task. Do this right before implementation so the plan reflects the current state of the codebase.
80
+
81
+ **🤖 Ask your AI Agent:**
82
+ > Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.
83
+
84
+ > [!NOTE]
85
+ > **Review checkpoint #2** — read the plan. Does the approach make sense? Approve it or ask the agent to revise.
86
+
87
+ **Step 4 — Implement and verify.** Let the agent implement the task.
88
+
89
+ > [!NOTE]
90
+ > **Review checkpoint #3** — review the code, run tests, check linting, and verify the results match your expectations.
91
+
92
+ If the output is not good enough: clear the plan/notes/final summary, refine the task description and acceptance criteria, and run the task again in a fresh session.
93
+
94
+ ---
56
95
 
57
- # 4. Or ask AI to create them: Claude Code, Gemini CLI, or Codex (Agents automatically use Backlog.md via MCP or CLI)
58
- Claude I would like to build a search functionality in the web view that searches for:
59
- * tasks
60
- * docs
61
- * decisions
62
- Please create relevant tasks to tackle this request.
96
+ ### Working without AI agents
63
97
 
64
- # 5. See where you stand
65
- backlog board view or backlog browser
98
+ Use Backlog.md as a standalone task manager from the terminal or browser.
66
99
 
67
- # 6. Assign tasks to AI (Backlog.md instructions tell agents how to work with tasks)
68
- Claude please implement all tasks related to the web search functionality (task-10, task-11, task-12)
69
- * before starting to write code use 'ultrathink mode' to prepare and add an implementation plan to the task
70
- * use multiple sub-agents when possible and dependencies allow
100
+ ```bash
101
+ # Create and refine tasks
102
+ backlog task create "Render markdown as kanban"
103
+ backlog task edit BACK-1 -d "Detailed context" --ac "Clear acceptance criteria"
104
+
105
+ # Track work
106
+ backlog task list -s "To Do"
107
+ backlog search "kanban"
108
+ backlog board
109
+
110
+ # Work visually in the browser
111
+ backlog browser
71
112
  ```
72
113
 
73
- All data is saved under `backlog` folder as human‑readable Markdown with the following format `task-<task-id> - <task-title>.md` (e.g. `task-10 - Add core search functionality.md`).
114
+ You can switch between AI-assisted and manual workflows at any time — both operate on the same Markdown task files. It is recommended to modify tasks via Backlog.md commands (CLI/MCP/Web) rather than editing task files manually, so field types and metadata stay consistent.
115
+
116
+ **Learn more:** [CLI reference](CLI-INSTRUCTIONS.md) | [Advanced configuration](ADVANCED-CONFIG.md)
74
117
 
75
118
  ---
76
119
 
@@ -104,16 +147,11 @@ backlog browser --no-open
104
147
 
105
148
  ## 🔧 MCP Integration (Model Context Protocol)
106
149
 
107
- The easiest way to connect Backlog.md to AI coding assistants like Claude Code, Codex, and Gemini CLI is via the MCP protocol.
150
+ The easiest way to connect Backlog.md to AI coding assistants like Claude Code, Codex, Gemini CLI and Kiro is via the MCP protocol.
108
151
  You can run `backlog init` (even if you already initialized Backlog.md) to set up MCP integration automatically, or follow the manual steps below.
109
152
 
110
153
  ### Client guides
111
154
 
112
- > [!IMPORTANT]
113
- > When adding the MCP server manually, you should add some extra instructions in your CLAUDE.md/AGENTS.md files to inform the agent about Backlog.md.
114
- > This step is not required when using `backlog init` as it adds these instructions automatically.
115
- > Backlog.md's instructions for agents are available at [`/src/guidelines/mcp/agent-nudge.md`](/src/guidelines/mcp/agent-nudge.md).
116
-
117
155
  <details>
118
156
  <summary><strong>Claude Code</strong></summary>
119
157
 
@@ -141,6 +179,15 @@ You can run `backlog init` (even if you already initialized Backlog.md) to set u
141
179
 
142
180
  </details>
143
181
 
182
+ <details>
183
+ <summary><strong>Kiro</strong></summary>
184
+
185
+ ```bash
186
+ kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start
187
+ ```
188
+
189
+ </details>
190
+
144
191
  Use the shared `backlog` server name everywhere – the MCP server auto-detects whether the current directory is initialized and falls back to `backlog://init-required` when needed.
145
192
 
146
193
  ### Manual config
@@ -156,189 +203,22 @@ Use the shared `backlog` server name everywhere – the MCP server auto-detects
156
203
  }
157
204
  ```
158
205
 
206
+ > [!IMPORTANT]
207
+ > When adding the MCP server manually, you should add some extra instructions in your CLAUDE.md/AGENTS.md files to inform the agent about Backlog.md.
208
+ > This step is not required when using `backlog init` as it adds these instructions automatically.
209
+ > Backlog.md's instructions for agents are available at [`/src/guidelines/mcp/agent-nudge.md`](/src/guidelines/mcp/agent-nudge.md).
210
+
211
+
159
212
  Once connected, agents can read the Backlog.md workflow instructions via the resource `backlog://docs/task-workflow`.
160
- Use `/mcp` command in your AI tool (Claude Code, Codex) to verify if the connection is working.
213
+ Use `/mcp` command in your AI tool (Claude Code, Codex, Kiro) to verify if the connection is working.
161
214
 
162
215
  ---
163
216
 
164
217
  ## <img src="./.github/cli-reference-256.png" alt="CLI Reference" width="28" height="28" align="center"> CLI reference
165
218
 
166
- ### Project Setup
167
-
168
- | Action | Example |
169
- |-------------|------------------------------------------------------|
170
- | Initialize project | `backlog init [project-name]` (creates backlog structure with a minimal interactive flow) |
171
- | Re-initialize | `backlog init` (preserves existing config, allows updates) |
172
- | Advanced settings wizard | `backlog config` (no args) — launches the full interactive configuration flow |
173
-
174
- `backlog init` keeps first-run setup focused on the essentials:
175
- - **Project name** – identifier for your backlog (defaults to the current directory on re-run).
176
- - **Integration choice** – decide whether your AI tools connect through the **MCP connector** (recommended) or stick with **CLI commands (legacy)**.
177
- - **Instruction files (CLI path only)** – when you choose the legacy CLI flow, pick which instruction files to create (CLAUDE.md, AGENTS.md, GEMINI.md, Copilot, or skip).
178
- - **Advanced settings prompt** – default answer “No” finishes init immediately; choosing “Yes” jumps straight into the advanced wizard documented in [Configuration](#configuration).
179
-
180
- You can rerun the wizard anytime with `backlog config`. All existing CLI flags (for example `--defaults`, `--agent-instructions`, or `--install-claude-agent true`) continue to provide fully non-interactive setups, so existing scripts keep working without change.
181
-
182
- ### Documentation
183
-
184
- - Document IDs are global across all subdirectories under `backlog/docs`. You can organize files in nested folders (e.g., `backlog/docs/guides/`), and `backlog doc list` and `backlog doc view <id>` work across the entire tree. Example: `backlog doc create -p guides "New Guide"`.
185
-
186
- ### Task Management
187
-
188
- | Action | Example |
189
- |-------------|------------------------------------------------------|
190
- | Create task | `backlog task create "Add OAuth System"` |
191
- | Create with description | `backlog task create "Feature" -d "Add authentication system"` |
192
- | Create with assignee | `backlog task create "Feature" -a @sara` |
193
- | Create with status | `backlog task create "Feature" -s "In Progress"` |
194
- | Create with labels | `backlog task create "Feature" -l auth,backend` |
195
- | Create with priority | `backlog task create "Feature" --priority high` |
196
- | Create with plan | `backlog task create "Feature" --plan "1. Research\n2. Implement"` |
197
- | Create with AC | `backlog task create "Feature" --ac "Must work,Must be tested"` |
198
- | Add DoD items on create | `backlog task create "Feature" --dod "Run tests"` |
199
- | Create without DoD defaults | `backlog task create "Feature" --no-dod-defaults` |
200
- | Create with notes | `backlog task create "Feature" --notes "Started initial research"` |
201
- | Create with final summary | `backlog task create "Feature" --final-summary "PR-style summary"` |
202
- | Create with deps | `backlog task create "Feature" --dep task-1,task-2` |
203
- | Create with refs | `backlog task create "Feature" --ref https://docs.example.com --ref src/api.ts` |
204
- | Create with docs | `backlog task create "Feature" --doc https://design-docs.example.com --doc docs/spec.md` |
205
- | Create sub task | `backlog task create -p 14 "Add Login with Google"`|
206
- | Create (all options) | `backlog task create "Feature" -d "Description" -a @sara -s "To Do" -l auth --priority high --ac "Must work" --notes "Initial setup done" --dep task-1 --ref src/api.ts --doc docs/spec.md -p 14` |
207
- | List tasks | `backlog task list [-s <status>] [-a <assignee>] [-p <parent>]` |
208
- | List by parent | `backlog task list --parent 42` or `backlog task list -p task-42` |
209
- | View detail | `backlog task 7` (interactive UI, press 'E' to edit in editor) |
210
- | View (AI mode) | `backlog task 7 --plain` |
211
- | Edit | `backlog task edit 7 -a @sara -l auth,backend` |
212
- | Add plan | `backlog task edit 7 --plan "Implementation approach"` |
213
- | Add AC | `backlog task edit 7 --ac "New criterion" --ac "Another one"` |
214
- | Add DoD | `backlog task edit 7 --dod "Ship notes"` |
215
- | Remove AC | `backlog task edit 7 --remove-ac 2` (removes AC #2) |
216
- | Remove multiple ACs | `backlog task edit 7 --remove-ac 2 --remove-ac 4` (removes AC #2 and #4) |
217
- | Check AC | `backlog task edit 7 --check-ac 1` (marks AC #1 as done) |
218
- | Check DoD | `backlog task edit 7 --check-dod 1` (marks DoD #1 as done) |
219
- | Check multiple ACs | `backlog task edit 7 --check-ac 1 --check-ac 3` (marks AC #1 and #3 as done) |
220
- | Uncheck AC | `backlog task edit 7 --uncheck-ac 3` (marks AC #3 as not done) |
221
- | Uncheck DoD | `backlog task edit 7 --uncheck-dod 3` (marks DoD #3 as not done) |
222
- | Mixed AC operations | `backlog task edit 7 --check-ac 1 --uncheck-ac 2 --remove-ac 4` |
223
- | Mixed DoD operations | `backlog task edit 7 --check-dod 1 --uncheck-dod 2 --remove-dod 4` |
224
- | Add notes | `backlog task edit 7 --notes "Completed X, working on Y"` (replaces existing) |
225
- | Append notes | `backlog task edit 7 --append-notes "New findings"` |
226
- | Add final summary | `backlog task edit 7 --final-summary "PR-style summary"` |
227
- | Append final summary | `backlog task edit 7 --append-final-summary "More details"` |
228
- | Clear final summary | `backlog task edit 7 --clear-final-summary` |
229
- | Add deps | `backlog task edit 7 --dep task-1 --dep task-2` |
230
- | Archive | `backlog task archive 7` |
231
-
232
- #### Multi‑line input (description/plan/notes/final summary)
233
-
234
- The CLI preserves input literally; `\n` sequences are not auto‑converted. Use one of the following to insert real newlines:
235
-
236
- - **Bash/Zsh (ANSI‑C quoting)**
237
- - Description: `backlog task create "Feature" --desc $'Line1\nLine2\n\nFinal paragraph'`
238
- - Plan: `backlog task edit 7 --plan $'1. Research\n2. Implement'`
239
- - Notes: `backlog task edit 7 --notes $'Completed A\nWorking on B'`
240
- - Append notes: `backlog task edit 7 --append-notes $'Added X\nAdded Y'`
241
- - Final summary: `backlog task edit 7 --final-summary $'Shipped A\nAdded B'`
242
- - Append final summary: `backlog task edit 7 --append-final-summary $'Added X\nAdded Y'`
243
- - **POSIX sh (printf)**
244
- - `backlog task create "Feature" --desc "$(printf 'Line1\nLine2\n\nFinal paragraph')"`
245
- - **PowerShell (backtick)**
246
- - `backlog task create "Feature" --desc "Line1`nLine2`n`nFinal paragraph"`
247
-
248
- Tip: Help text shows Bash examples with escaped `\\n` for readability; when typing, `$'\n'` expands to a newline.
249
-
250
- ### Search
251
-
252
- Find tasks, documents, and decisions across your entire backlog with fuzzy search:
253
-
254
- | Action | Example |
255
- |--------------------|------------------------------------------------------|
256
- | Search tasks | `backlog search "auth"` |
257
- | Filter by status | `backlog search "api" --status "In Progress"` |
258
- | Filter by priority | `backlog search "bug" --priority high` |
259
- | Combine filters | `backlog search "web" --status "To Do" --priority medium` |
260
- | Plain text output | `backlog search "feature" --plain` (for scripts/AI) |
261
-
262
- **Search features:**
263
- - **Fuzzy matching** -- finds "authentication" when searching for "auth"
264
- - **Interactive filters** -- refine your search in real-time with the TUI
265
- - **Live filtering** -- see results update as you type (no Enter needed)
266
-
267
- ### Draft Workflow
268
-
269
- | Action | Example |
270
- |-------------|------------------------------------------------------|
271
- | Create draft | `backlog task create "Feature" --draft` |
272
- | Draft flow | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
273
- | Demote to draft| `backlog task demote <id>` |
274
-
275
- ### Dependency Management
276
-
277
- Manage task dependencies to create execution sequences and prevent circular relationships:
278
-
279
- | Action | Example |
280
- |-------------|------------------------------------------------------|
281
- | Add dependencies | `backlog task edit 7 --dep task-1 --dep task-2` |
282
- | Add multiple deps | `backlog task edit 7 --dep task-1,task-5,task-9` |
283
- | Create with deps | `backlog task create "Feature" --dep task-1,task-2` |
284
- | View dependencies | `backlog task 7` (shows dependencies in task view) |
285
- | Validate dependencies | Use task commands to automatically validate dependencies |
286
-
287
- **Dependency Features:**
288
- - **Automatic validation**: Prevents circular dependencies and validates task existence
289
- - **Flexible formats**: Use `task-1`, `1`, or comma-separated lists like `1,2,3`
290
- - **Visual sequences**: Dependencies create visual execution sequences in board view
291
- - **Completion tracking**: See which dependencies are blocking task progress
292
-
293
- ### Board Operations
294
-
295
- | Action | Example |
296
- |-------------|------------------------------------------------------|
297
- | Kanban board | `backlog board` (interactive UI, press 'E' to edit in editor) |
298
- | Export board | `backlog board export [file]` (exports Kanban board to markdown) |
299
- | Export with version | `backlog board export --export-version "v1.0.0"` (includes version in export) |
300
-
301
- ### Statistics & Overview
302
-
303
- | Action | Example |
304
- |-------------|------------------------------------------------------|
305
- | Project overview | `backlog overview` (interactive TUI showing project statistics) |
306
-
307
- ### Web Interface
308
-
309
- | Action | Example |
310
- |-------------|------------------------------------------------------|
311
- | Web interface | `backlog browser` (launches web UI on port 6420) |
312
- | Web custom port | `backlog browser --port 8080 --no-open` |
313
-
314
- ### Documentation
315
-
316
- | Action | Example |
317
- |-------------|------------------------------------------------------|
318
- | Create doc | `backlog doc create "API Guidelines"` |
319
- | Create with path | `backlog doc create "Setup Guide" -p guides/setup` |
320
- | Create with type | `backlog doc create "Architecture" -t technical` |
321
- | List docs | `backlog doc list` |
322
- | View doc | `backlog doc view doc-1` |
323
-
324
- ### Decisions
325
-
326
- | Action | Example |
327
- |-------------|------------------------------------------------------|
328
- | Create decision | `backlog decision create "Use PostgreSQL for primary database"` |
329
- | Create with status | `backlog decision create "Migrate to TypeScript" -s proposed` |
330
-
331
- ### Agent Instructions
332
-
333
- | Action | Example |
334
- |-------------|------------------------------------------------------|
335
- | Update agent files | `backlog agents --update-instructions` (updates CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md) |
219
+ Full command reference — task management, search, board, docs, decisions, and more: **[CLI-INSTRUCTIONS.md](CLI-INSTRUCTIONS.md)**
336
220
 
337
- ### Maintenance
338
-
339
- | Action | Example |
340
- |-------------|------------------------------------------------------|
341
- | Cleanup done tasks | `backlog cleanup` (move old completed tasks to completed folder) |
221
+ Quick examples: `backlog task create`, `backlog task list`, `backlog task edit`, `backlog search`, `backlog board`, `backlog browser`.
342
222
 
343
223
  Full help: `backlog --help`
344
224
 
@@ -346,25 +226,13 @@ Full help: `backlog --help`
346
226
 
347
227
  ## <img src="./.github/configuration-256.png" alt="Configuration" width="28" height="28" align="center"> Configuration
348
228
 
349
- Backlog.md merges the following layers (highest → lowest):
229
+ Backlog.md merges the following layers (highest → lowest):
350
230
 
351
231
  1. CLI flags
352
232
  2. `backlog/config.yml` (per‑project)
353
233
  3. `~/backlog/user` (per‑user)
354
234
  4. Built‑ins
355
235
 
356
- ### Configuration Commands
357
-
358
- | Action | Example |
359
- |-------------|------------------------------------------------------|
360
- | View all configs | `backlog config list` |
361
- | Get specific config | `backlog config get defaultEditor` |
362
- | Set config value | `backlog config set defaultEditor "code --wait"` |
363
- | Enable auto-commit | `backlog config set autoCommit true` |
364
- | Bypass git hooks | `backlog config set bypassGitHooks true` |
365
- | Enable cross-branch check | `backlog config set checkActiveBranches true` |
366
- | Set active branch days | `backlog config set activeBranchDays 30` |
367
-
368
236
  ### Interactive wizard (`backlog config`)
369
237
 
370
238
  Run `backlog config` with no arguments to launch the full interactive wizard. This is the same experience triggered from `backlog init` when you opt into advanced settings, and it walks through the complete configuration surface:
@@ -374,7 +242,7 @@ Run `backlog config` with no arguments to launch the full interactive wizard. Th
374
242
  - Editor integration: pick a `defaultEditor` with availability checks.
375
243
  - Web UI defaults: choose `defaultPort` and whether `autoOpenBrowser` should run.
376
244
 
377
- Skipping the wizard (answering “No” during init) applies the safe defaults that ship with Backlog.md:
245
+ Skipping the wizard (answering "No" during init) applies the safe defaults that ship with Backlog.md:
378
246
  - `checkActiveBranches=true`, `remoteOperations=true`, `activeBranchDays=30`.
379
247
  - `autoCommit=false`, `bypassGitHooks=false`.
380
248
  - `zeroPaddedIds` disabled.
@@ -383,41 +251,6 @@ Skipping the wizard (answering “No” during init) applies the safe defaults t
383
251
 
384
252
  Whenever you revisit `backlog init` or rerun `backlog config`, the wizard pre-populates prompts with your current values so you can adjust only what changed.
385
253
 
386
- ### Available Configuration Options
387
-
388
- | Key | Purpose | Default |
389
- |-------------------|--------------------|-------------------------------|
390
- | `defaultAssignee` | Pre‑fill assignee | `[]` |
391
- | `defaultStatus` | First column | `To Do` |
392
- | `definition_of_done` | Default DoD checklist items for new tasks | `(not set)` |
393
- | `statuses` | Board columns | `[To Do, In Progress, Done]` |
394
- | `dateFormat` | Date/time format | `yyyy-mm-dd hh:mm` |
395
- | `includeDatetimeInDates` | Add time to new dates | `true` |
396
- | `defaultEditor` | Editor for 'E' key | Platform default (nano/notepad) |
397
- | `defaultPort` | Web UI port | `6420` |
398
- | `autoOpenBrowser` | Open browser automatically | `true` |
399
- | `remoteOperations`| Enable remote git operations | `true` |
400
- | `autoCommit` | Automatically commit task changes | `false` |
401
- | `bypassGitHooks` | Skip git hooks when committing (uses --no-verify) | `false` |
402
- | `zeroPaddedIds` | Pad all IDs (tasks, docs, etc.) with leading zeros | `(disabled)` |
403
- | `checkActiveBranches` | Check task states across active branches for accuracy | `true` |
404
- | `activeBranchDays` | How many days a branch is considered active | `30` |
405
- | `onStatusChange` | Shell command to run on status change | `(disabled)` |
406
-
407
- > Editor setup guide: See [Configuring VIM and Neovim as Default Editor](backlog/docs/doc-002%20-%20Configuring-VIM-and-Neovim-as-Default-Editor.md) for configuration tips and troubleshooting interactive editors.
408
-
409
- > **Note**: Set `remoteOperations: false` to work offline. This disables git fetch operations and loads tasks from local branches only, useful when working without network connectivity.
410
-
411
- > **Git Control**: By default, `autoCommit` is set to `false`, giving you full control over your git history. Task operations will modify files but won't automatically commit changes. Set `autoCommit: true` if you prefer automatic commits for each task operation.
412
-
413
- > **Git Hooks**: If you have pre-commit hooks (like conventional commits or linters) that interfere with backlog.md's automated commits, set `bypassGitHooks: true` to skip them using the `--no-verify` flag.
414
-
415
- > **Performance**: Cross-branch checking ensures accurate task tracking across all active branches but may impact performance on large repositories. You can disable it by setting `checkActiveBranches: false` for maximum speed, or adjust `activeBranchDays` to control how far back to look for branch activity (lower values = better performance).
416
-
417
- > **Status Change Callbacks**: Set `onStatusChange` to run a shell command whenever a task's status changes. Available variables: `$TASK_ID`, `$OLD_STATUS`, `$NEW_STATUS`, `$TASK_TITLE`. Per-task override via `onStatusChange` in task frontmatter. Example: `'if [ "$NEW_STATUS" = "In Progress" ]; then claude "Task $TASK_ID ($TASK_TITLE) has been assigned to you. Please implement it." & fi'`
418
-
419
- > **Date/Time Support**: Backlog.md now supports datetime precision for all dates. New items automatically include time (YYYY-MM-DD HH:mm format in UTC), while existing date-only entries remain unchanged for backward compatibility. Use the migration script `bun src/scripts/migrate-dates.ts` to optionally add time to existing items.
420
-
421
254
  ### Definition of Done defaults
422
255
 
423
256
  Set project-wide DoD items in the Web UI (Settings → Definition of Done Defaults) or edit `backlog/config.yml` directly:
@@ -431,110 +264,10 @@ definition_of_done:
431
264
 
432
265
  These items are added to every new task by default. You can add more on create with `--dod`, or disable defaults per task with `--no-dod-defaults`. Array values like `definition_of_done` must be edited in the config file or via the Web UI.
433
266
 
434
- ---
435
-
436
- ## 💡 Shell Tab Completion
437
-
438
- Backlog.md includes built-in intelligent tab completion for bash, zsh, and fish shells. Completion scripts are embedded in the binary—no external files needed.
439
-
440
- **Quick Installation:**
441
- ```bash
442
- # Auto-detect and install for your current shell
443
- backlog completion install
444
-
445
- # Or specify shell explicitly
446
- backlog completion install --shell bash
447
- backlog completion install --shell zsh
448
- backlog completion install --shell fish
449
- ```
450
-
451
- **What you get:**
452
- - Command completion: `backlog <TAB>` → shows all commands
453
- - Dynamic task IDs: `backlog task edit <TAB>` → shows actual task IDs from your backlog
454
- - Smart flags: `--status <TAB>` → shows configured status values
455
- - Context-aware suggestions for priorities, labels, and assignees
456
-
457
- 📖 **Full documentation**: See [completions/README.md](completions/README.md) for detailed installation instructions, troubleshooting, and examples.
458
-
459
- ---
460
-
461
- ## <img src="./.github/sharing-export-256.png" alt="Sharing & Export" width="28" height="28" align="center"> Sharing & Export
462
-
463
- ### Board Export
464
-
465
- Export your Kanban board to a clean, shareable markdown file:
466
-
467
- ```bash
468
- # Export to default Backlog.md file
469
- backlog board export
470
-
471
- # Export to custom file
472
- backlog board export project-status.md
473
-
474
- # Force overwrite existing file
475
- backlog board export --force
476
-
477
- # Export to README.md with board markers
478
- backlog board export --readme
479
-
480
- # Include a custom version string in the export
481
- backlog board export --export-version "v1.2.3"
482
- backlog board export --readme --export-version "Release 2024.12.1-beta"
483
- ```
484
-
485
- Perfect for sharing project status, creating reports, or storing snapshots in version control.
267
+ For the full configuration reference (all options, commands, and detailed notes), see **[ADVANCED-CONFIG.md](ADVANCED-CONFIG.md)**.
486
268
 
487
269
  ---
488
270
 
489
- <!-- BOARD_START -->
490
-
491
- ## 📊 Backlog.md Project Status (v1.35.6)
492
-
493
- This board was automatically generated by [Backlog.md](https://backlog.md)
494
-
495
- Generated on: 2026-02-09 20:02:38
496
-
497
- | To Do | In Progress | Done |
498
- | --- | --- | --- |
499
- | **BACK-368** - TUI: Add section-aware navigation for task popup and detail pane [@codex]<br>*#tui #ux #enhancement* | | **BACK-378** - Fix timezone configuration docs and local date display in task modal [@codex]<br>*#bug #web #docs* |
500
- | **BACK-366** - Evaluate and replace prompts library with clack in CLI wizards [@codex] | | **BACK-377** - Prevent web preview crash on angle-bracket type strings [@codex]<br>*#bug #web* |
501
- | └─ **BACK-366.03** - Refactor remaining CLI prompt flows and tests to clack [@codex] | | **BACK-376** - Fix web task creation dropping selected milestone [@codex]<br>*#bug #web #api* |
502
- | └─ **BACK-366.01** - Refactor init wizard prompts to clack [@codex] | | **BACK-375** - Fix inconsistent draft IDs for `task create --draft` [@codex]<br>*#bug #cli* |
503
- | └─ **BACK-366.02** - Refactor advanced config wizard prompts to clack [@codex] | | **BACK-379** - Auto-plain output when stdout is not a TTY [@codex] |
504
- | **BACK-361** - Add label-based filtering to TUI and web UI task list views<br>*#tui #web #enhancement* | | **BACK-374** - Ensure MCP server exits when stdio closes and disposes watchers [@codex] |
505
- | **BACK-355** - Add task type field (bug, feature, enhancement, etc.)<br>*#enhancement #core #cli #mcp #web* | | **BACK-373** - Support Drafts via MCP task tools (no new tools) [@codex]<br>*#mcp #drafts* |
506
- | └─ **BACK-355.06** - Web UI: Display and edit task type<br>*#web* | | **BACK-371** - Investigate flaky CI test failure in PR 494 [@codex] |
507
- | └─ **BACK-355.01** - Core: Add type field to task domain model and persistence<br>*#core* | | **BACK-372** - CI: drop sourcemap in compile-and-smoke-test to avoid InvalidSourceMap flake [@codex] |
508
- | └─ **BACK-355.02** - CLI: Add --type flag to task create and edit commands<br>*#cli* | | **BACK-370** - Release: publish platform binaries before main npm package [@codex] |
509
- | └─ **BACK-355.03** - MCP: Add type parameter to task_create and task_edit tools<br>*#mcp* | | **BACK-369** - Fix web UI acceptance criteria toggle flicker via ContentStore sync [@codex] |
510
- | └─ **BACK-355.04** - Filtering: Add type-based filtering to task list and search<br>*#core #cli #mcp* | | **BACK-367** - Add Final Summary field to tasks for PR-style completion notes [@codex]<br>*#enhancement #core #cli #mcp #workflow* |
511
- | └─ **BACK-355.05** - TUI: Display task type in board and detail views<br>*#tui* | | └─ **BACK-367.5** - Ignore nested section markers when parsing structured sections [@codex]<br>*#bug #markdown #parser #tui* |
512
- | **BACK-349** - Publish Backlog.md as an Agent Skill with bundled guidance (no MCP resources required for instructions) [@codex]<br>*#agent-skills #mcp #docs #distribution* | | └─ **BACK-367.01** - CLI and plain text formatter integration for Final Summary field [@codex]<br>*#cli #enhancement* |
513
- | └─ **BACK-24.02** - CLI TUI: Add milestone swimlanes to interactive board view<br>*#cli #tui #enhancement* | | └─ **BACK-367.02** - MCP tools and schemas integration for Final Summary field [@codex]<br>*#mcp #enhancement* |
514
- | **BACK-239** - Feature: Auto-link tasks to documents/decisions + backlinks [@codex]<br>*#web #enhancement #docs* | | └─ **BACK-367.03** - Web UI integration for Final Summary field [@codex]<br>*#web #enhancement* |
515
- | **BACK-347** - Add milestone editing in Web UI<br>*#milestones #web-ui #enhancement* | | └─ **BACK-367.04** - TUI task viewer integration for Final Summary field [@codex]<br>*#tui #enhancement* |
516
- | **BACK-348** - Redesign All Tasks page with table layout<br>*#web-ui #design #enhancement #ux* | | **BACK-354** - Project Definition of Done defaults [@codex] |
517
- | **BACK-310** - Strengthen Backlog workflow overview emphasis on reading detailed guides [@codex] | | └─ **BACK-354.01** - Core: Definition of Done defaults and persistence [@codex] |
518
- | **BACK-270** - Prevent command substitution in task creation inputs [@codex] | | └─ **BACK-354.02** - CLI + MCP: DoD create options and outputs [@codex] |
519
- | **BACK-267** - Add agent instruction version metadata [@codex] | | └─ **BACK-354.03** - Web UI: DoD in task modal and create flow [@codex] |
520
- | **BACK-268** - Show agent instruction version status [@codex] | | └─ **BACK-354.04** - TUI: DoD in task detail and kanban popup [@codex] |
521
- | **BACK-260** - Web UI: Add filtering to All Tasks view [@codex]<br>*#web-ui #filters #ui* | | └─ **BACK-354.05** - Web UI: edit Definition of Done defaults in Settings [@codex] |
522
- | **BACK-259** - Add task list filters for Status and Priority<br>*#tui #filters #ui* | | **BACK-346** - Add milestone completion/archival workflow [@codex]<br>*#milestones #enhancement #ux* |
523
- | **BACK-257** - Deep link URLs for tasks in board and list views | | **BACK-352** - Include subtask list in plain task output (CLI + MCP) [@codex] |
524
- | **BACK-200** - Add Claude Code integration with workflow commands during init<br>*#enhancement #developer-experience* | | **BACK-353** - Add documentation field to task domain object [@codex] |
525
- | **BACK-218** - Update documentation and tests for sequences<br>*#sequences #documentation #testing* | | **BACK-356** - Add references field to task domain object [@codex] |
526
- | **BACK-217** - Create web UI for sequences with drag-and-drop<br>*#sequences #web-ui #frontend* | | **BACK-351** - Strengthen MCP task creation guidance for standalone tasks [@codex] |
527
- | └─ **BACK-217.03** - Sequences web UI: move tasks and update dependencies<br>*#sequences* | | **BACK-362** - Include completed tasks in MCP task_search results [@codex]<br>*#mcp #enhancement* |
528
- | └─ **BACK-217.04** - Sequences web UI: tests<br>*#sequences* | | **BACK-358** - Rename Task Completion Guide to Task Finalization Guide [@codex]<br>*#documentation #workflow* |
529
- | └─ **BACK-217.02** - Sequences web UI: list sequences<br>*#sequences* | | **BACK-365** - Fix acceptance criteria insertion adding blank lines [@codex] |
530
- | **BACK-240** - Improve binary resolution on Apple Silicon (Rosetta/arch mismatch) [@codex]<br>*#packaging #bug #macos* | | **BACK-364** - Fix getTask() to use configured prefix for numeric ID lookups [@codex]<br>*#bug #mcp* |
531
- | **BACK-222** - Improve task and subtask visualization in web UI | | **BACK-363** - Fix localById case mismatch in cross-branch task loading [@codex]<br>*#core #bug* |
532
- | **BACK-208** - Add paste-as-markdown support in Web UI<br>*#web-ui #enhancement #markdown* | | **BACK-360** - Fix cross-branch index case mismatch for custom prefixes [@codex]<br>*#bug #cross-branch #prefix-config* |
533
- | | | **BACK-359** - Pass configured task prefix to cross-branch loading functions [@codex]<br>*#bug #cross-branch #prefix-config* |
534
- | | | └─ **BACK-345.10** - Fix ID generation bugs and cleanup prefix-config leftovers [@codex]<br>*#bug #refactor #tdd* |
535
-
536
- <!-- BOARD_END -->
537
-
538
271
  ### License
539
272
 
540
273
  Backlog.md is released under the **MIT License** – do anything, just give credit. See [LICENSE](LICENSE).
package/backlog CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "backlog.md-linux-x64",
3
- "version": "1.35.7",
3
+ "version": "1.37.0",
4
4
  "os": ["linux"],
5
5
  "cpu": ["x64"],
6
6
  "files": ["backlog","package.json","LICENSE"],