backlog.md-windows-x64 1.47.0 → 1.48.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.
- package/README.md +136 -69
- package/backlog.exe +0 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,20 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="./.github/backlog-logo.png" alt="Backlog.md logo" width="120">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
<h1 align="center">Backlog.md</h1>
|
|
2
|
-
<p align="center">Markdown‑native Task Manager & Kanban visualizer for any Git repository</p>
|
|
6
|
+
<p align="center"><strong>Markdown‑native Task Manager & Kanban visualizer for any Git repository</strong></p>
|
|
7
|
+
<p align="center">AI agents write the code. You review the tasks: before, during, and after.</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://www.npmjs.com/package/backlog.md"><img src="https://img.shields.io/npm/v/backlog.md?color=brightgreen" alt="npm version"></a>
|
|
11
|
+
<a href="https://www.npmjs.com/package/backlog.md"><img src="https://img.shields.io/npm/dm/backlog.md" alt="npm downloads"></a>
|
|
12
|
+
<a href="https://github.com/MrLesk/Backlog.md/blob/main/LICENSE"><img src="https://img.shields.io/github/license/MrLesk/Backlog.md" alt="MIT license"></a>
|
|
13
|
+
<a href="https://github.com/MrLesk/Backlog.md"><img src="https://img.shields.io/github/stars/MrLesk/Backlog.md?style=social" alt="GitHub stars"></a>
|
|
14
|
+
</p>
|
|
3
15
|
|
|
4
16
|
<p align="center">
|
|
5
|
-
<code>npm i -g backlog.md</code>
|
|
17
|
+
<code>npm i -g backlog.md</code>
|
|
6
18
|
</p>
|
|
7
19
|
|
|
8
20
|
|
|
@@ -10,32 +22,53 @@
|
|
|
10
22
|
|
|
11
23
|
---
|
|
12
24
|
|
|
13
|
-
> **Backlog.md** turns any folder
|
|
25
|
+
> **Backlog.md** turns any folder into a **self‑contained project board**
|
|
14
26
|
> 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.
|
|
16
27
|
|
|
17
|
-
##
|
|
28
|
+
## Why Backlog.md in the AI era
|
|
29
|
+
|
|
30
|
+
AI agents can now produce more plausible code in an hour than you can carefully read in a day.
|
|
31
|
+
The bottleneck is no longer writing code. It's your attention. You can't meaningfully review
|
|
32
|
+
15,000 generated lines in one sitting, but you can read a screenful of task specs with acceptance
|
|
33
|
+
criteria before any code exists, and push back while a misunderstanding is still one sentence,
|
|
34
|
+
not a rebuilt feature.
|
|
35
|
+
|
|
36
|
+
Backlog.md structures agent work around **three review checkpoints**:
|
|
18
37
|
|
|
19
|
-
|
|
38
|
+
1. **Review the spec:** the agent decomposes your idea into tasks with descriptions, acceptance
|
|
39
|
+
criteria, and milestones before implementation starts.
|
|
40
|
+
2. **Review the plan:** the agent researches your codebase and writes its implementation plan
|
|
41
|
+
into the task. Approve it or steer before any code is written.
|
|
42
|
+
3. **Review the code:** one task = one context window = one PR. Diffs stay a size a human can
|
|
43
|
+
actually read.
|
|
20
44
|
|
|
21
|
-
|
|
45
|
+
Afterwards, the completed tasks remain in Git as a permanent record of what was attempted and why,
|
|
46
|
+
legible to you, your team, and the next agent.
|
|
22
47
|
|
|
23
|
-
|
|
48
|
+
**Dogfooded:** nearly all of Backlog.md's own code is written by AI agents working through
|
|
49
|
+
Backlog.md itself. The full task ledger lives in this repo's [backlog folder](backlog/tasks).
|
|
50
|
+
|
|
51
|
+
📺 **See it in action:** [Devoxx Belgium 2025](https://www.youtube.com/watch?v=LSoDQU_9MMA) · [AI Engineer Code Summit 2025](https://www.youtube.com/watch?v=zMXKhhwiCIc)
|
|
52
|
+
|
|
53
|
+
## Features
|
|
24
54
|
|
|
25
|
-
*
|
|
55
|
+
* 🤖 **AI-ready** -- works with Claude Code, Gemini CLI, Codex, Kiro & any other MCP or CLI compatible AI assistant
|
|
26
56
|
|
|
27
|
-
*
|
|
57
|
+
* 📝 **Markdown-native tasks** -- every task is a plain `.md` file in your repo
|
|
28
58
|
|
|
29
|
-
*
|
|
30
|
-
* ✅ **Definition of Done defaults** -- add a reusable checklist to every new task
|
|
59
|
+
* ✅ **Acceptance criteria & Definition of Done** -- verifiable scope per task, plus a reusable DoD checklist for every new task
|
|
31
60
|
|
|
32
|
-
*
|
|
61
|
+
* 🎯 **Milestones & dependencies** -- structure bigger efforts and make execution order reviewable
|
|
33
62
|
|
|
34
|
-
*
|
|
63
|
+
* 📊 **Terminal Kanban** -- `backlog board` paints a live board in your shell; `backlog board export` creates shareable markdown reports
|
|
35
64
|
|
|
36
|
-
*
|
|
65
|
+
* 🌐 **Web UI** -- `backlog browser` serves a local Kanban board with drag-and-drop and task editing forms
|
|
37
66
|
|
|
38
|
-
*
|
|
67
|
+
* 🔍 **Search** -- fuzzy search across tasks, docs & decisions with `backlog search`
|
|
68
|
+
|
|
69
|
+
* 🔒 **Local-first** -- no server, no account, no telemetry; tasks are plain files in your repo, and remote Git operations are optional
|
|
70
|
+
|
|
71
|
+
* 💻 Cross-platform (macOS, Linux, Windows) · 🆓 MIT-licensed & open-source
|
|
39
72
|
|
|
40
73
|
|
|
41
74
|
---
|
|
@@ -44,9 +77,10 @@
|
|
|
44
77
|
|
|
45
78
|
```bash
|
|
46
79
|
# Install
|
|
47
|
-
|
|
48
|
-
# or:
|
|
80
|
+
npm i -g backlog.md
|
|
81
|
+
# or: bun add -g backlog.md
|
|
49
82
|
# or: brew install backlog-md
|
|
83
|
+
# or: nix run github:MrLesk/Backlog.md
|
|
50
84
|
|
|
51
85
|
# Initialize in any Git repo
|
|
52
86
|
backlog init "My Awesome Project"
|
|
@@ -55,48 +89,53 @@ backlog init "My Awesome Project"
|
|
|
55
89
|
backlog init "Personal Planning" --no-git
|
|
56
90
|
```
|
|
57
91
|
|
|
92
|
+
> [!TIP]
|
|
93
|
+
> **Running one-off with `npx`?** This tool's npm package is named `backlog.md`, so use the full name: `npx backlog.md init "My Project"`, `npx backlog.md board`.
|
|
94
|
+
> Without an install, `npx backlog` resolves to an unrelated third-party npm package — not this tool.
|
|
95
|
+
> (With `backlog.md` installed as a project dependency, `npx backlog` runs the local binary as usual.)
|
|
96
|
+
|
|
58
97
|
The init wizard will ask how you want to connect AI tools:
|
|
59
|
-
- **CLI instructions** (recommended)
|
|
60
|
-
- **MCP connector
|
|
61
|
-
- **Skip
|
|
98
|
+
- **CLI instructions** (recommended): creates a short instruction file that tells agents to run `backlog instructions overview`.
|
|
99
|
+
- **MCP connector**: optionally auto-configures Claude Code, Codex, Gemini CLI, Kiro or Cursor for teams that prefer MCP.
|
|
100
|
+
- **Skip**: no AI setup; use Backlog.md purely as a task manager.
|
|
62
101
|
|
|
63
|
-
|
|
102
|
+
Everything is stored as human-readable Markdown in a project-local backlog folder such as `backlog/`, `.backlog/`, or a custom project-relative path configured through `backlog.config.yml` (e.g. `task-10 - Add core search functionality.md`). Task IDs use a configurable prefix (`backlog init --task-prefix`): the default produces `TASK-1`-style IDs, while this repository uses `back`, so examples below show `BACK-1`-style IDs. Git is optional: `backlog init --no-git` creates a filesystem-only project.
|
|
64
103
|
|
|
65
104
|
---
|
|
66
105
|
|
|
67
|
-
|
|
106
|
+
## Working with AI agents
|
|
68
107
|
|
|
69
|
-
This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools
|
|
108
|
+
This is the recommended flow for Claude Code, Codex, Gemini CLI, Kiro and similar tools, following the **spec‑driven AI development** approach.
|
|
70
109
|
After running `backlog init`, agents should start by running `backlog instructions overview`. Work in this loop:
|
|
71
110
|
|
|
72
|
-
**Step 1
|
|
111
|
+
**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.
|
|
73
112
|
|
|
74
113
|
**🤖 Ask your AI Agent:**
|
|
75
114
|
> 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.
|
|
76
115
|
|
|
77
116
|
> [!NOTE]
|
|
78
|
-
> **Review checkpoint #1
|
|
117
|
+
> **Review checkpoint #1:** read the task descriptions and acceptance criteria.
|
|
79
118
|
|
|
80
|
-
**Step 2
|
|
119
|
+
**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.
|
|
81
120
|
|
|
82
|
-
**Step 3
|
|
121
|
+
**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.
|
|
83
122
|
|
|
84
123
|
**🤖 Ask your AI Agent:**
|
|
85
124
|
> Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding.
|
|
86
125
|
|
|
87
126
|
> [!NOTE]
|
|
88
|
-
> **Review checkpoint #2
|
|
127
|
+
> **Review checkpoint #2:** read the plan. Does the approach make sense? Approve it or ask the agent to revise.
|
|
89
128
|
|
|
90
|
-
**Step 4
|
|
129
|
+
**Step 4: Implement and verify.** Let the agent implement the task.
|
|
91
130
|
|
|
92
131
|
> [!NOTE]
|
|
93
|
-
> **Review checkpoint #3
|
|
132
|
+
> **Review checkpoint #3:** review the code, run tests, check linting, and verify the results match your expectations.
|
|
94
133
|
|
|
95
134
|
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.
|
|
96
135
|
|
|
97
136
|
---
|
|
98
137
|
|
|
99
|
-
|
|
138
|
+
## Working without AI agents
|
|
100
139
|
|
|
101
140
|
Use Backlog.md as a standalone task manager from the terminal or browser.
|
|
102
141
|
|
|
@@ -115,7 +154,7 @@ backlog board
|
|
|
115
154
|
backlog browser
|
|
116
155
|
```
|
|
117
156
|
|
|
118
|
-
You can switch between AI-assisted and manual workflows at any time
|
|
157
|
+
You can switch between AI-assisted and manual workflows at any time; both operate on the same Markdown task files. Just prefer Backlog.md commands (CLI/MCP/Web) over hand-editing task files, so field types and metadata stay consistent.
|
|
119
158
|
|
|
120
159
|
**Learn more:** [CLI reference](CLI-INSTRUCTIONS.md) | [Advanced configuration](ADVANCED-CONFIG.md)
|
|
121
160
|
|
|
@@ -123,7 +162,7 @@ You can switch between AI-assisted and manual workflows at any time — both ope
|
|
|
123
162
|
|
|
124
163
|
## <img src="./.github/web-interface-256.png" alt="Web Interface" width="28" height="28" align="center"> Web Interface
|
|
125
164
|
|
|
126
|
-
Launch a
|
|
165
|
+
Launch a local web interface for visual task management:
|
|
127
166
|
|
|
128
167
|
```bash
|
|
129
168
|
# Start the web server (opens browser automatically)
|
|
@@ -138,7 +177,7 @@ backlog browser --no-open
|
|
|
138
177
|
|
|
139
178
|
**Features:**
|
|
140
179
|
- Interactive Kanban board with drag-and-drop
|
|
141
|
-
- Task creation and editing with
|
|
180
|
+
- Task creation and editing with forms
|
|
142
181
|
- Interactive acceptance criteria editor with checklists
|
|
143
182
|
- Real-time updates across all views
|
|
144
183
|
- Responsive design for desktop and mobile
|
|
@@ -194,9 +233,17 @@ You can run `backlog init` (even if you already initialized Backlog.md) and choo
|
|
|
194
233
|
|
|
195
234
|
</details>
|
|
196
235
|
|
|
197
|
-
|
|
236
|
+
<details>
|
|
237
|
+
<summary><strong>Cursor / other MCP clients</strong></summary>
|
|
238
|
+
|
|
239
|
+
Use the manual JSON config below in your client's MCP settings.
|
|
198
240
|
|
|
199
|
-
|
|
241
|
+
</details>
|
|
242
|
+
|
|
243
|
+
Use the shared `backlog` server name everywhere. The server finds the active project from your client's MCP roots, and re-resolves when you switch workspace or worktree. A single user-scope server covers every repo.
|
|
244
|
+
|
|
245
|
+
<details>
|
|
246
|
+
<summary><strong>Manual config</strong></summary>
|
|
200
247
|
|
|
201
248
|
```json
|
|
202
249
|
{
|
|
@@ -212,8 +259,11 @@ Use the shared `backlog` server name everywhere – the MCP server auto-detects
|
|
|
212
259
|
}
|
|
213
260
|
```
|
|
214
261
|
|
|
215
|
-
|
|
262
|
+
Set `BACKLOG_CWD` to pin the server to one project and stop workspace following. Use it to always target the same backlog, or when your client can't report MCP roots.
|
|
216
263
|
If your IDE supports custom args but not env vars, you can also use `["mcp", "start", "--cwd", "/absolute/path/to/your/project"]`.
|
|
264
|
+
Until the server finds an initialized project, it serves `backlog://init-required`.
|
|
265
|
+
|
|
266
|
+
</details>
|
|
217
267
|
|
|
218
268
|
> [!IMPORTANT]
|
|
219
269
|
> When adding the MCP server manually, add a short instruction to your CLAUDE.md/AGENTS.md files telling agents to read `backlog://workflow/overview`.
|
|
@@ -228,7 +278,7 @@ Use `/mcp` command in your AI tool (Claude Code, Codex, Kiro) to verify if the c
|
|
|
228
278
|
|
|
229
279
|
## <img src="./.github/cli-reference-256.png" alt="CLI Reference" width="28" height="28" align="center"> CLI reference
|
|
230
280
|
|
|
231
|
-
Full command reference
|
|
281
|
+
Full command reference covering task management, search, board, docs, decisions, and more: **[CLI-INSTRUCTIONS.md](CLI-INSTRUCTIONS.md)**
|
|
232
282
|
|
|
233
283
|
Quick examples: `backlog`, `backlog instructions`, `backlog task create`, `backlog task list`, `backlog task edit`, `backlog milestone add`, `backlog milestone rename`, `backlog milestone remove`, `backlog search`, `backlog board`, `backlog browser`.
|
|
234
284
|
|
|
@@ -238,34 +288,11 @@ Full help: `backlog --help`
|
|
|
238
288
|
|
|
239
289
|
## <img src="./.github/configuration-256.png" alt="Configuration" width="28" height="28" align="center"> Configuration
|
|
240
290
|
|
|
241
|
-
Backlog.md
|
|
291
|
+
Backlog.md works with zero configuration. Settings merge from CLI flags, then the project config file (`backlog.config.yml` when present, otherwise `backlog/config.yml` or `.backlog/config.yml`), then built‑in defaults.
|
|
242
292
|
|
|
243
|
-
|
|
244
|
-
2. Project config file:
|
|
245
|
-
- `backlog.config.yml` when present
|
|
246
|
-
- otherwise `backlog/config.yml` or `.backlog/config.yml`
|
|
247
|
-
3. Built‑ins
|
|
293
|
+
Run `backlog config` with no arguments to launch the interactive wizard (the same experience triggered from `backlog init` advanced setup). It walks through cross-branch accuracy (`checkActiveBranches`, `remoteOperations`, `activeBranchDays`), Git workflow (`autoCommit`, `bypassGitHooks`), ID formatting (`zeroPaddedIds`), editor integration (`defaultEditor`), Definition of Done defaults, and Web UI defaults (`defaultPort`, `autoOpenBrowser`). Skipping the wizard applies the safe built-in defaults, and rerunning `backlog init` or `backlog config` pre-populates prompts with your current values.
|
|
248
294
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
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:
|
|
252
|
-
- Cross-branch accuracy: `checkActiveBranches`, `remoteOperations`, and `activeBranchDays`.
|
|
253
|
-
- Git workflow: `autoCommit` and `bypassGitHooks`.
|
|
254
|
-
- ID formatting: enable or size `zeroPaddedIds`.
|
|
255
|
-
- Editor integration: pick a `defaultEditor` with availability checks.
|
|
256
|
-
- Definition of Done defaults: interactively add/remove/reorder/clear project-level `definition_of_done` checklist items.
|
|
257
|
-
- Web UI defaults: choose `defaultPort` and whether `autoOpenBrowser` should run.
|
|
258
|
-
|
|
259
|
-
Skipping the wizard (answering "No" during init) applies the safe defaults that ship with Backlog.md:
|
|
260
|
-
- `checkActiveBranches=true`, `remoteOperations=true`, `activeBranchDays=30`.
|
|
261
|
-
- `autoCommit=false`, `bypassGitHooks=false`.
|
|
262
|
-
- `zeroPaddedIds` disabled.
|
|
263
|
-
- `defaultEditor` unset (falls back to your environment).
|
|
264
|
-
- `defaultPort=6420`, `autoOpenBrowser=true`.
|
|
265
|
-
|
|
266
|
-
For filesystem-only projects, run `backlog init --no-git`. Backlog.md will not run `git init`, and the saved config forces `checkActiveBranches=false`, `remoteOperations=false`, and `autoCommit=false` so CLI, Web, and MCP local-file workflows do not depend on a Git repository.
|
|
267
|
-
|
|
268
|
-
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.
|
|
295
|
+
For filesystem-only projects (`backlog init --no-git`), the saved config forces `checkActiveBranches=false`, `remoteOperations=false`, and `autoCommit=false` so CLI, Web, and MCP local-file workflows do not depend on a Git repository.
|
|
269
296
|
|
|
270
297
|
### Definition of Done defaults
|
|
271
298
|
|
|
@@ -282,16 +309,56 @@ When a project uses root config discovery, edit `backlog.config.yml` instead of
|
|
|
282
309
|
|
|
283
310
|
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`.
|
|
284
311
|
|
|
285
|
-
For the full configuration reference (all options, commands, and detailed notes), see **[ADVANCED-CONFIG.md](ADVANCED-CONFIG.md)**.
|
|
312
|
+
For the full configuration reference (all options, default values, commands, and detailed notes), see **[ADVANCED-CONFIG.md](ADVANCED-CONFIG.md)**.
|
|
286
313
|
|
|
287
314
|
---
|
|
288
315
|
|
|
289
|
-
##
|
|
316
|
+
## Troubleshooting
|
|
317
|
+
|
|
318
|
+
### Apple Silicon (macOS)
|
|
319
|
+
|
|
320
|
+
On M-series Macs, `backlog` can fail with `illegal hardware instruction` or `Binary package not installed for darwin-...` when Node, Bun, or Homebrew run under Rosetta (x64 emulation) and install the Intel binary instead of the arm64 one — or the other way around. The launcher runs whichever darwin variant (arm64 or x64) is actually installed, but a clean native-arch install is the reliable fix.
|
|
321
|
+
|
|
322
|
+
Check what your tools report:
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
uname -m # arm64 = Apple Silicon hardware; x86_64 = Intel or a Rosetta shell
|
|
326
|
+
node -p process.arch # architecture of your Node/Bun runtime
|
|
327
|
+
sysctl -in sysctl.proc_translated # 1 = current shell runs under Rosetta
|
|
328
|
+
which brew # /opt/homebrew = arm64 brew, /usr/local = Intel brew
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
If the architectures disagree, reinstall with the native one:
|
|
332
|
+
|
|
333
|
+
```bash
|
|
334
|
+
# Homebrew: make sure `which brew` prints /opt/homebrew, then
|
|
335
|
+
brew reinstall backlog-md
|
|
336
|
+
|
|
337
|
+
# npm
|
|
338
|
+
arch -arm64 npm i -g backlog.md
|
|
339
|
+
|
|
340
|
+
# Bun
|
|
341
|
+
arch -arm64 bun add -g backlog.md
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
Running an x64 Node under Rosetta on purpose also works: `backlog` falls back to whichever `backlog.md-darwin-*` package is present.
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
## 📺 Talks & Community
|
|
349
|
+
|
|
350
|
+
Watch Backlog.md in action:
|
|
351
|
+
|
|
352
|
+
- **Devoxx Belgium 2025**: [the spec-driven agent workflow behind Backlog.md, live on stage](https://www.youtube.com/watch?v=LSoDQU_9MMA)
|
|
353
|
+
- **AI Engineer Code Summit 2025**: [Backlog.md: task management for AI agents](https://www.youtube.com/watch?v=zMXKhhwiCIc)
|
|
354
|
+
- Slides from these and more talks: [mrlesk.com/talks](https://mrlesk.com/talks)
|
|
355
|
+
|
|
356
|
+
### Community tools
|
|
290
357
|
|
|
291
358
|
- **[vscode-backlog-md](https://marketplace.visualstudio.com/items?itemName=ysamlan.vscode-backlog-md)** - VS Code extension with issues panel, kanban view, and editing. ([ysamlan/vscode-backlog-md](https://github.com/ysamlan/vscode-backlog-md))
|
|
292
359
|
|
|
293
360
|
---
|
|
294
361
|
|
|
295
|
-
|
|
362
|
+
## License
|
|
296
363
|
|
|
297
|
-
Backlog.md is released under the **MIT License
|
|
364
|
+
Backlog.md is released under the **MIT License**: do anything, just give credit. See [LICENSE](LICENSE).
|
package/backlog.exe
CHANGED
|
Binary file
|