backlog.md 0.1.0

package/.backlog/tasks/task-20 - add-agent-guideline-to-mark-tasks-in-progress-on-start.md

@@ -0,0 +1,32 @@
+---
+id: task-20
+title: Add agent guideline to mark tasks In Progress on start
+status: Done
+assignee: []
+reporter: '@MrLesk'
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - agents
+dependencies: []
+---
+
+## Description
+
+Update the AI agent guideline files to ensure that whenever an agent starts working on a task they immediately mark the task as **In Progress**, assign it to themselves, and push the change.
+
+## Acceptance Criteria
+
+- [x] `AGENTS.md` mentions setting status to `In Progress`, assigning the task, and pushing.
+- [x] `CLAUDE.md` mentions the same instruction.
+- [x] `.cursorrules` mentions the same instruction.
+- [x] Task committed to repository.
+
+## Implementation Notes
+
+* Added new guideline bullet in `AGENTS.md` instructing agents to set the task to `In Progress`, assign themselves, and push when beginning work.
+* Mirrored the same instruction in `CLAUDE.md:41` under **AI Agent Integration** section.
+* Updated `.cursorrules` within the Project-Specific Rules section to include the requirement.
+* All three files now consistently instruct agents to mark tasks as "In Progress" and assign themselves when starting work.
+* This ensures proper task tracking and prevents multiple agents from working on the same task simultaneously.
+* Implementation follows the established pattern of maintaining consistency across all agent instruction files.

package/.backlog/tasks/task-21 - kanban-board-vertical-layout.md

@@ -0,0 +1,31 @@
+---
+id: task-21
+title: Kanban board vertical layout
+status: Done
+assignee: []
+reporter: '@MrLesk'
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+completed_date: '2025-06-09'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Add a visualization to the Kanban board where all status columns are displayed vertically in a single column. Include both `--layout vertical` and a shortcut `--vertical` option for convenience.
+
+## Acceptance Criteria
+
+- [x] Vertical Kanban view with all statuses in a single column
+- [x] Support `--layout vertical` option for `backlog board view` command
+- [x] Support `--vertical` shortcut option for `backlog board view` command
+- [x] Documentation updated if necessary
+
+## Implementation Notes
+
+- Added `BoardLayout` type and support for `vertical` layout in `generateKanbanBoard`.
+- Introduced `--layout` option for `backlog board view` command.
+- Added `--vertical` shortcut flag that overrides `--layout` when specified.
+- Updated logic to prioritize `--vertical` flag over `--layout` option.
+- Updated tests and documentation to cover the new layout options.

package/.backlog/tasks/task-22 - cli-prevent-double-dash-in-task-filenames.md

@@ -0,0 +1,24 @@
+---
+id: task-22
+title: 'CLI: Prevent double dash in task filenames'
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Ensure generated task filenames never contain consecutive dashes
+
+## Acceptance Criteria
+- [x] Filenames generated by the CLI do not contain consecutive dashes
+- [x] Task committed to the repository
+
+## Implementation Notes
+- Updated `sanitizeFilename` utility to collapse repeated dashes and trim leading
+  or trailing dashes.
+- Added regression test ensuring filenames created for tasks never contain
+  consecutive dashes.

package/.backlog/tasks/task-23 - cli-kanban-board-order-tasks-by-id-asc.md

@@ -0,0 +1,30 @@
+---
+id: task-23
+title: 'CLI: Kanban board order tasks by ID ASC'
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+completed_date: '2025-06-09'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Sort tasks within each status column by numeric task ID in ascending order when rendering the board.
+
+## Acceptance Criteria
+
+- [x] Tasks in each status column are sorted by numeric task ID ascending.
+- [x] Sorting occurs after collecting tasks from all sources (local or remote, if implemented).
+- [x] Board output consistently displays tasks in ascending order regardless of branch order.
+
+## Implementation Notes
+
+- Added `idSegments` helper function to parse task IDs into numeric segments for proper sorting.
+- Implemented `compareIds` function that compares tasks by their numeric ID segments, handling both simple IDs (task-1, task-2) and complex decimal IDs (task-4.1, task-4.2).
+- Tasks are sorted using `list.slice().sort(compareIds)` within each status column in the `generateKanbanBoard` function.
+- Sorting works correctly with both horizontal and vertical board layouts.
+- Added comprehensive test "sorts tasks by numeric id within each status" to verify task-2 appears before task-10.
+- Successfully resolved merge conflicts with vertical layout and export functionality while preserving all features.

package/.backlog/tasks/task-24 - handle-subtasks-in-the-kanban-view.md

@@ -0,0 +1,38 @@
+---
+id: task-24
+title: Handle subtasks in the Kanban view
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+completed_date: '2025-06-09'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Display subtasks indented with pipes | and em dashes — under their parent task. Subtask IDs show the pipe prefix while titles are cleanly spaced. Includes configurable column width settings for optimal display formatting.
+
+## Acceptance Criteria
+
+- [x] Subtasks appear under their parent task in the Kanban board
+- [x] Pipes and em dashes visually indent subtasks for clarity
+- [x] Subtask IDs prefixed with `  |—` (2 spaces + pipe + em dash)
+- [x] Subtask titles indented with 6 spaces total for optimal alignment
+- [x] Column width configurable via `max_column_width` in config.yml
+
+## Implementation Notes
+
+* Updated `generateKanbanBoard()` in `src/board.ts` to group subtasks under
+  their parent when both share the same status.
+* Subtasks use enhanced formatting: IDs prefixed with `  |—` (2 spaces + pipe + em dash), 
+  titles indented with 6 spaces total for optimal visual alignment.
+* Added configurable column width via `maxColumnWidth` parameter and `max_column_width` 
+  in config.yml (default: 20 for terminal, 80 for export).
+* Added new unit test `nests subtasks under their parent when statuses match`
+  in `src/test/board.test.ts`.
+* Successfully integrated subtask functionality with ID sorting (task 23), vertical layout (task 21), and export features (task 25).
+* Enhanced sorting to use `compareIds` for both parent tasks and subtasks, ensuring proper numeric ordering.
+* Subtask functionality works seamlessly across all board layouts (horizontal/vertical) and export operations.
+* Board export supports both terminal and markdown formats with proper column width constraints.

package/.backlog/tasks/task-24.1 - cli-kanban-board-milestone-view.md

@@ -0,0 +1,19 @@
+---
+id: task-24.1
+title: 'CLI: Kanban board milestone view'
+status: In Progress
+assignee: @codex
+created_date: '2025-06-09'
+labels: []
+dependencies: []
+parent_task_id: task-24
+---
+
+## Description
+
+Add a backlog board view --milestones or -m to view the board based on milestones
+
+## Acceptance Criteria
+
+- [ ] `backlog board view --milestones` or `-m` groups tasks by milestone
+- [ ] Documentation updated if necessary

package/.backlog/tasks/task-25 - cli-export-kanban-board-to-readme.md

@@ -0,0 +1,28 @@
+---
+id: task-25
+title: 'CLI: Export Kanban board to README'
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Implement new command backlog board export to append the board to README.md or specified output file.
+
+## Acceptance Criteria
+
+- [x] `backlog board export` writes the kanban board to `readme.md` if it exists.
+- [x] Provide `--output <path>` option to save board to another file.
+- [x] Automatically create the file if the specified path does not exist.
+- [x] Appended content preserves existing file contents and adds the board at the end.
+
+## Implementation Notes
+
+- Added `exportKanbanBoardToFile()` in `src/board.ts` to handle writing the board to a file.
+- New `board export` command in `src/cli.ts` gathers tasks (including remote) and uses this helper.
+- Supports `--output` option and defaults to `readme.md`.
+- Ensures output file exists and appends the board while preserving content.

package/.backlog/tasks/task-27 - add-contributing-guidelines.md

@@ -0,0 +1,27 @@
+---
+id: task-27
+title: Add CONTRIBUTING guidelines
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - docs
+  - github
+dependencies: []
+---
+
+## Description
+
+Create CONTRIBUTING.md with guidelines for contributing to Backlog.md.
+
+## Acceptance Criteria
+- [x] CONTRIBUTING.md explains how to open issues and PRs
+- [x] Describes running tests and linting
+- [x] Task committed to repository
+
+## Implementation Notes
+- Added `CONTRIBUTING.md` with sections on opening issues and submitting
+  pull requests.
+- Documented test and lint commands (`bun test` and `npx biome check .`).
+- Linked to the new guidelines from `readme.md`.

package/.backlog/tasks/task-29 - add-github-templates.md

@@ -0,0 +1,28 @@
+---
+id: task-29
+title: Add GitHub templates
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - github
+  - docs
+dependencies: []
+---
+
+## Description
+
+Create issue and pull request templates under .github/.
+
+## Acceptance Criteria
+- [x] Bug report and feature request templates added
+- [x] Pull request template added referencing task IDs
+- [x] Task committed to repository
+
+## Implementation Notes
+
+- Added `.github/ISSUE_TEMPLATE` with bug and feature request templates.
+- Created `PULL_REQUEST_TEMPLATE.md` requesting Backlog task references.
+- Documented templates in `readme.md`.
+

package/.backlog/tasks/task-3 - cli-implement-backlog-init.md

@@ -0,0 +1,63 @@
+---
+id: task-3
+title: "CLI: Implement `backlog init` Command"
+status: Done
+assignee: @MrLesk
+reporter: @MrLesk
+created_date: 2025-06-04
+labels: ["cli", "command"]
+milestone: "M1 - CLI"
+dependencies: ["task-2"]
+---
+
+## Description
+
+Implement the `backlog init <project-name>` command in the CLI. This command will set up the `.backlog` directory structure and a `config.yml` in the current Git repository.
+
+## Acceptance Criteria
+
+- [x] `backlog init <project-name>` command creates all necessary subdirectories within `.backlog`.
+- [x] `backlog init <project-name>` creates an initial commit for the `.backlog` structure.
+- [x] Command provides appropriate user feedback.
+
+## Implementation Summary
+
+✅ **CLI Implementation Recovered & Complete**
+
+### Features Recovered
+- **Command Line Interface**: Built with Commander.js for argument parsing
+- **Git Integration**: Automatically detects git repositories and offers to initialize if missing
+- **Directory Structure**: Creates complete `.backlog` directory hierarchy
+- **Configuration**: Generates `config.yml` with project name and default settings
+- **Git Commit**: Automatically commits the initial backlog structure
+- **User Feedback**: Provides clear success messages and error handling
+
+### Technical Details
+- **Entry Point**: `src/cli.ts` contains the CLI implementation
+- **Build System**: Compiles to `cli/index.js` for distribution
+- **Package Scripts**: 
+  - `bun run cli` - Run CLI from source
+  - `bun run build` - Build distributable CLI
+- **Testing**: Comprehensive test suite with 5 integration tests
+- **Dependencies**: Added `commander@14.0.0` for CLI parsing
+
+### Usage
+```bash
+# From source
+bun src/cli.ts init "My Project"
+
+# Built version  
+./cli/index.js init "My Project"
+
+# Help
+bun src/cli.ts --help
+```
+
+### Test Coverage
+- ✅ Initializes backlog project in existing git repo
+- ✅ Creates all required directories
+- ✅ Handles project names with special characters  
+- ✅ Works when git repo exists
+- ✅ Creates initial commit with backlog structure
+
+All **62 tests passing** including 5 CLI integration tests.

package/.backlog/tasks/task-31 - update-readme-for-open-source.md

@@ -0,0 +1,26 @@
+---
+id: task-31
+title: Update README for open source
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - docs
+dependencies: []
+---
+
+## Description
+
+Add installation badges, link to license and contributing guide. Document global install and example usage.
+
+## Acceptance Criteria
+- [x] README highlights MIT license and contribution guidelines
+- [x] Includes npm and bun install badges
+- [x] Provides quick start example
+- [x] Task committed to repository
+
+## Implementation Notes
+- Added npm and bun badge images with links in `readme.md`.
+- Inserted license and contribution links near the top of the README.
+- Added new Quick Start section showing global install and example commands.

package/.backlog/tasks/task-32 - cli-hide-empty-'no-status'-column.md

@@ -0,0 +1,31 @@
+---
+id: task-32
+title: 'CLI: Hide empty ''No Status'' column'
+status: Done
+assignee: []
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - cli
+  - bug
+dependencies: []
+---
+
+## Description
+
+When viewing the kanban board with `backlog board view`, an empty **No Status** column is always displayed even if no tasks lack a status. The board should only include this column when there are tasks without a defined status.
+
+## Acceptance Criteria
+
+- [x] The board does not render the **No Status** column when there are no tasks missing a status.
+- [x] Regression test verifies the column is hidden when unused.
+- [x] Task committed to the repository.
+
+## Implementation Notes
+
+* The functionality was already implemented in `generateKanbanBoard()` in `src/board.ts:71-78`.
+* The code filters out empty status groups using `(groups.get(s)?.length ?? 0) > 0` condition.
+* This ensures only status columns with actual tasks are displayed in both horizontal and vertical layouts.
+* Regression test `omits 'No Status' column when all tasks have status` exists in `src/test/board.test.ts:77-93`.
+* The implementation works for both terminal and markdown export formats.
+* All existing functionality is preserved while improving the UI by hiding unnecessary empty columns.

package/.backlog/tasks/task-33 - cli-export-milestones-board-as-roadmap.md

@@ -0,0 +1,20 @@
+---
+id: task-33
+title: 'CLI: Export milestones board as roadmap'
+status: To Do
+assignee: []
+created_date: '2025-06-10'
+labels: []
+dependencies: []
+milestone: "M2 - CLI Kanban Board"
+---
+
+## Description
+
+Implement board export for milestones, enabling an overview of tasks by milestone as a roadmap. Add --title / -t option to set a custom title.
+
+## Acceptance Criteria
+
+- [ ] `backlog board export --milestones` exports tasks grouped by milestone as a roadmap
+- [ ] Add `--title` or `-t` option to specify a custom heading in the exported file
+- [ ] Documentation updated with usage examples

package/.backlog/tasks/task-34 - split-readme.md-for-users-and-contributors.md

@@ -0,0 +1,26 @@
+---
+id: task-34
+title: Split readme.md for users and contributors
+status: Done
+assignee:
+  - "@codex"
+created_date: '2025-06-09'
+labels:
+  - docs
+dependencies: []
+---
+
+## Description
+
+Split the current README.md into two separate files: one focused on how to use the Backlog.md CLI, and another covering how to run the project locally for contributors.
+
+## Acceptance Criteria
+- [x] README for users explains how to install and use Backlog.md CLI
+- [x] Separate documentation describes how to run the project locally for contributors
+- [x] Both docs link to each other from the repository root
+- [x] Task committed to repository
+
+## Implementation Notes
+- Created `DEVELOPMENT.md` with instructions for running and testing the project locally.
+- Removed development sections from `readme.md` and added a link to the new document.
+- Added reciprocal link back to `readme.md` from `DEVELOPMENT.md`.

package/.backlog/tasks/task-35 - finalize-package.json-metadata-for-publishing.md

@@ -0,0 +1,24 @@
+---
+id: task-35
+title: Finalize package.json metadata for publishing
+status: Done
+assignee:
+  - '@codex'
+created_date: '2025-06-09'
+updated_date: '2025-06-10'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Add full author and repository information to package.json for npm publishing.
+
+## Acceptance Criteria
+- [x] `author` field defined
+- [x] `repository` URL set
+- [x] `bugs` URL set
+- [x] `homepage` field set
+- [x] `keywords` array includes relevant terms
+- [x] `license` field confirmed
+- [x] `npm publish --dry-run` succeeds with no warnings

package/.backlog/tasks/task-36 - cli-prompt-for-project-name-in-init.md

@@ -0,0 +1,24 @@
+---
+id: task-36
+title: 'CLI: Prompt for project name in init'
+status: Done
+assignee:
+  - '@codex'
+created_date: '2025-06-10'
+updated_date: '2025-06-10'
+labels: []
+dependencies: []
+---
+
+## Description
+
+Allow `backlog init` to run without specifying a project name. When omitted, the CLI should prompt for the name before proceeding.
+
+## Acceptance Criteria
+- [x] `backlog init` works without project name parameter
+- [x] When project name is missing, CLI prompts for it before initialization
+- [x] Task committed to repository
+
+## Implementation Notes
+- Updated `src/cli.ts` to accept optional project name and prompt when omitted.
+- Added integration test covering prompt behavior in `src/test/cli.test.ts`.

package/.backlog/tasks/task-37 - cli-board-view-open-tasks-in-ide.md

@@ -0,0 +1,19 @@
+---
+id: task-37
+title: 'CLI: Board view open tasks in IDE'
+status: In Progress
+assignee:
+  - '@AI'
+created_date: '2025-06-10'
+labels: []
+dependencies: []
+---
+
+
+## Description
+
+Add clickable links to each task id in the board view that open the task file in the user's default IDE.
+
+## Acceptance Criteria
+- [ ] Every task id displayed in the board is a hyperlink that opens the task file in the configured IDE when clicked.
+- [ ] Provide a --no-links option to disable hyperlink generation.

package/.backlog/tasks/task-38 - cli-improved-agent-selection-for-init.md

@@ -0,0 +1,25 @@
+---
+id: task-38
+title: 'CLI: Improved Agent Selection for Init'
+status: Done
+assignee:
+  - '@AI'
+created_date: '2025-06-10'
+updated_date: '2025-06-10'
+labels: []
+dependencies: []
+---
+
+## Description
+Implement interactive checkbox-style selection for agents during 'backlog init'. Users should select one or multiple agents using space or enter, similar to modern CLI tools.
+
+## Acceptance Criteria
+- [x] Interactive checkbox UI replaces current agent selection
+- [x] Users can select one or multiple agents using space and confirm with enter
+- [x] Works consistently across Node and Bun runtimes
+- [x] Task committed to repository
+
+## Implementation Notes
+- Added `prompts` dependency for interactive CLI prompts.
+- Replaced numeric input with `multiselect` checkbox prompt in `src/cli.ts`.
+- Supports selecting multiple agent instruction files with space/enter.

package/.backlog/tasks/task-39 - cli-fix-empty-agent-instruction-files-on-init.md

@@ -0,0 +1,31 @@
+---
+id: task-39
+title: 'CLI: fix empty agent instruction files on init'
+status: Done
+assignee:
+  - '@codex'
+reporter: '@MrLesk'
+created_date: '2025-06-10'
+updated_date: '2025-06-10'
+labels:
+  - cli
+  - bug
+dependencies: []
+---
+
+## Description
+
+Backlog init should populate selected agent instruction files with default content instead of creating empty files.
+
+## Acceptance Criteria
+
+- [x] Selected agent instruction files contain default guideline text after running `backlog init`
+- [x] Automated test verifies non-empty content is written to each created file
+
+## Implementation Notes
+
+- Imported guideline constants may resolve to file paths when bundled. Added
+  `_loadAgentGuideline` helper to read file contents when needed.
+- `addAgentInstructions` now loads guideline text before writing files, ensuring
+  non-empty content in `AGENTS.md`, `CLAUDE.md`, and `.cursorrules`.
+- Updated CLI and tests to verify content length instead of specific words.

package/.backlog/tasks/task-4 - cli-task-management-commands.md

@@ -0,0 +1,28 @@
+---
+id: task-4
+title: 'CLI: Task Management Commands'
+status: Done
+assignee: []
+reporter: '@MrLesk'
+created_date: '2025-06-04'
+updated_date: '2025-06-09'
+completed_date: '2025-06-09'
+labels:
+  - cli
+  - command
+milestone: M1 - CLI
+dependencies:
+  - task-3
+---
+
+## Description
+
+Implement comprehensive task management functionality including creation, listing, viewing, editing, and archiving of tasks and drafts. This encompasses all user-facing CLI commands for task lifecycle management.
+
+## Implementation Notes
+
+- Subtasks **task-4.1** through **task-4.13** introduced complete CLI support for task and draft management.
+- Commands include `task create`, `task list`, `task view`, `task edit`, `task archive`, `task demote`, and draft variants.
+- Tasks can be created as subtasks using the `--parent` option and moved between draft and active states.
+- Metadata updates such as status and labels persist correctly through the `edit` command.
+- Extensive tests and documentation were added in each subtask to ensure reliability.

package/.backlog/tasks/task-4.1 - cli-task-create.md

@@ -0,0 +1,27 @@
+---
+id: task-4.1
+title: "CLI: Task Creation Commands"
+status: Done
+assignee: @MrLesk
+reporter: @MrLesk
+created_date: 2025-06-04
+labels: ["cli", "command"]
+milestone: "M1 - CLI"
+dependencies: ["task-3"]
+parent_task_id: task-4
+---
+
+## Description
+
+Implement commands for creating tasks, drafts, and subtasks:
+
+- `backlog task create` to add active tasks.
+- `backlog draft create` to create tasks in draft mode.
+- `backlog task create --parent <task-id>` to create a subtask under an existing task.
+
+## Acceptance Criteria
+
+- [x] Commands create Markdown files in the correct directories.
+- [x] Required metadata is captured from flags or prompts.
+- [x] Subtasks are saved using decimal IDs under `.backlog/tasks/`.
+- [x] Changes are committed with a descriptive message.

package/.backlog/tasks/task-4.10 - use-cli-to-mark-tasks-done.md

@@ -0,0 +1,51 @@
+---
+id: task-4.10
+title: 'CLI: enforce Agents to use backlog CLI to mark tasks Done'
+status: Done
+assignee: []
+reporter: @MrLesk
+created_date: '2025-06-08'
+updated_date: '2025-06-09'
+labels:
+  - cli
+  - agents
+dependencies: []
+parent_task_id: task-4
+---
+
+## Description
+
+Update agent guidelines so that after implementing and testing a task, they use the backlog CLI to set the task status to **Done**.
+
+## Acceptance Criteria
+- [x] Documentation instructs agents to run `backlog task edit <task-id> --status Done` after testing.
+- [x] Example usage included in AGENTS.md, CLAUDE.md and .cursorrules files
+
+## Implementation Notes
+
+**Task 4.10 Implementation Summary:**
+
+1. **Review Found Complete Implementation:**
+   - All agent guidance files already included the CLI command instruction
+   - Implementation was found to be complete during merge conflict resolution
+
+2. **Documentation Updates Applied:**
+   - **AGENTS.md**: Added CLI command instruction in guidelines section and Definition of Done
+   - **CLAUDE.md**: Added CLI command instruction in AI Agent Integration section  
+   - **.cursorrules**: Added CLI command instruction in Task Management section
+
+3. **Consistent Command Format:**
+   - All files now include the same command: `backlog task edit <task-id> --status Done`
+   - Command is presented in code blocks for clarity
+   - Instructions emphasize using this after implementing and testing tasks
+
+4. **Merge Conflict Resolution:**
+   - Resolved conflict in AGENTS.md by combining task 4.10 implementation with Definition of Done from main
+   - Ensured CLI command appears both in guidelines and Definition of Done for consistency
+
+5. **Quality Assurance:**
+   - All 105 tests pass
+   - Code passes all Biome linting and formatting checks  
+   - All agent guidance files now consistently instruct using the Backlog CLI
+
+All AI agents working with this project are now properly guided to mark tasks as Done using the CLI command, ensuring consistent workflow and proper task status management.