backlog.md 0.1.0 → 0.1.3

package/.backlog/tasks/task-14 - gui-introduction-screens.md

@@ -1,21 +0,0 @@
----
-id: task-14
-title: 'GUI: introduction screens'
-status: To Do
-assignee: []
-reporter: @MrLesk
-created_date: '2025-06-09'
-labels: ["gui", "feature"]
-milestone: "M3 - GUI"
-dependencies: []
----
-## Description
-
-Two introduction screens should appear:
-1. When launching Backlog for the first time in a folder without initialization.
-2. When launching Backlog again in an already initialized folder.
-
-## Acceptance Criteria
-
-- [ ] Welcome screen for first-time users displays key options when no project is initialized.
-- [ ] Welcome back screen for existing projects shows popular options.

package/.backlog/tasks/task-15 - improve-tasks-readme-with-generic-example-and-cli-reference.md

@@ -1,20 +0,0 @@
----
-id: task-15
-title: "Improve tasks readme with generic example and CLI command reference"
-status: To Do
-assignee: []
-reporter: @MrLesk
-created_date: 2025-06-09
-labels: []
-dependencies: []
----
-
-## Description
-
-Update `.backlog/tasks/readme.md` so the task example demonstrates a generic template rather than the current specific example. Include a section listing all task-related CLI commands with a short description for each.
-
-## Acceptance Criteria
-
-- [ ] Generic task template replaces the old example
-- [ ] `backlog task` commands documented (`create`, `list`, `edit`, `view`, `archive`, `demote`)
-- [ ] Task committed to repository

package/.backlog/tasks/task-16 - improve-docs-readme-with-generic-example-and-cli-reference.md

@@ -1,20 +0,0 @@
----
-id: task-16
-title: "Improve docs readme with generic example and CLI command reference"
-status: To Do
-assignee: []
-reporter: @MrLesk
-created_date: 2025-06-09
-labels: []
-dependencies: []
----
-
-## Description
-
-Refine `.backlog/docs/readme.md` with a generic documentation example. Add a list of all `backlog doc` commands and their purpose.
-
-## Acceptance Criteria
-
-- [ ] Generic document example provided
-- [ ] `backlog doc` command descriptions added (`create`, `list`)
-- [ ] Task committed to repository

package/.backlog/tasks/task-17 - improve-drafts-readme-with-generic-example-and-cli-reference.md

@@ -1,20 +0,0 @@
----
-id: task-17
-title: "Improve drafts readme with generic example and CLI command reference"
-status: To Do
-assignee: []
-reporter: @MrLesk
-created_date: 2025-06-09
-labels: []
-dependencies: []
----
-
-## Description
-
-Update `.backlog/drafts/readme.md` to show a generic draft task example. Document available `backlog draft` commands.
-
-## Acceptance Criteria
-
-- [ ] Generic draft task example added
-- [ ] `backlog draft` command descriptions added (`create`, `archive`, `promote`)
-- [ ] Task committed to repository

package/.backlog/tasks/task-18 - improve-decisions-readme-with-generic-example-and-cli-reference.md

@@ -1,20 +0,0 @@
----
-id: task-18
-title: "Improve decisions readme with generic example and CLI command reference"
-status: To Do
-assignee: []
-reporter: @MrLesk
-created_date: 2025-06-09
-labels: []
-dependencies: []
----
-
-## Description
-
-Refine `.backlog/decisions/readme.md` with a generic decision log example and provide a list of `backlog decision` commands.
-
-## Acceptance Criteria
-
-- [ ] Generic decision example included
-- [ ] `backlog decision` command descriptions added (`create`, `list`)
-- [ ] Task committed to repository

package/.backlog/tasks/task-19 - cli-fix-default-task-status-and-remove-draft-from-statuses.md

@@ -1,55 +0,0 @@
----
-id: task-19
-title: CLI - fix default task status and remove Draft from statuses
-status: Done
-reporter: @MrLesk
-created_date: '2025-06-09'
-labels: []
-dependencies: []
----
-
-## Description
-The CLI currently creates tasks in the "Draft" status by default and includes "Draft" in the list of task statuses. Draft tasks should be handled separately.
-
-## Acceptance Criteria
-- [x] `backlog task create` without options creates a task in `.backlog/tasks` with status `To Do`.
-- [x] `backlog task create --draft` creates a draft task in `.backlog/drafts` with status `Draft`.
-- [x] `config.yml` no longer lists `Draft` in the `statuses` array and sets `default_status` to `To Do`.
-- [x] Documentation updated to reflect the new behaviour.
-
-## Implementation Notes
-
-**Constants Updated (src/constants/index.ts:36-41):**
-- Changed `DEFAULT_STATUSES` from `["Draft", "To Do", "In Progress", "Done"]` to `["To Do", "In Progress", "Done"]`
-- Set `FALLBACK_STATUS` to `"To Do"` instead of `"Draft"`
-- Removed "Draft" from the standard workflow statuses
-
-**CLI Command Enhancement (src/cli.ts:191-204):**
-- Added `--draft` option to `backlog task create` command
-- When `--draft` flag is used, task is created in `.backlog/drafts` using `core.createDraft()`
-- Without `--draft` flag, task is created in `.backlog/tasks` using `core.createTask()`
-- Both operations properly handle the status assignment based on context
-
-**Configuration Updates:**
-- Project `config.yml` now shows `statuses: ["To Do", "In Progress", "Done"]` (no Draft)
-- Default status set to `"To Do"` in configuration files
-- Draft tasks are managed separately from the main workflow statuses
-
-**Documentation Updates (readme.md):**
-- Line 74: Added `--draft` option documentation for task creation
-- Line 199: Added explanation that "Draft tasks are stored separately under `.backlog/drafts`"
-- Clear distinction between workflow statuses and draft storage location
-
-**Test Verification:**
-- All 35 CLI integration tests pass
-- All 20 core tests pass
-- Manual testing confirms regular tasks created with "To Do" status in `.backlog/tasks`
-- Manual testing confirms draft tasks created with "Draft" status in `.backlog/drafts`
-
-**Workflow Impact:**
-- Regular task creation: `backlog task create "Title"` → `.backlog/tasks` with status "To Do"
-- Draft task creation: `backlog task create "Title" --draft` → `.backlog/drafts` with status "Draft"
-- Kanban board and listing commands now show only workflow statuses: To Do, In Progress, Done
-- Draft tasks are managed through separate `backlog draft` commands
-
-The implementation successfully separates draft handling from the main task workflow while maintaining backward compatibility and clear user experience.

package/.backlog/tasks/task-2 - cli-core-logic-library.md

@@ -1,28 +0,0 @@
----
-id: task-2
-title: "CLI: Design & Implement Core Logic Library"
-status: Done
-assignee: @MrLesk
-reporter: @MrLesk
-created_date: 2025-06-03
-labels: ["cli", "core-logic", "architecture"]
-milestone: "M1 - CLI"
-dependencies: ["task-1"]
----
-
-## Description
-
-Develop the central TypeScript library that handles:
-
-- File system operations within the `.backlog` directory.
-- Markdown parsing (reading frontmatter and content).
-- Markdown serialization (writing task files).
-- Basic Git interaction wrappers (e.g., add, commit specific files).
-- Defining data structures for tasks, docs, decisions.
-
-## Acceptance Criteria
-
-- [x] Clear interface for file operations.
-- [x] Robust Markdown parsing/serialization for Backlog task files.
-- [x] Wrapper functions for essential Git commands (e.g., commit changes to a task file).
-- [x] Core data models (Task, DecisionLog, Document) defined.

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

@@ -1,32 +0,0 @@
----
-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

@@ -1,31 +0,0 @@
----
-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

@@ -1,24 +0,0 @@
----
-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

@@ -1,30 +0,0 @@
----
-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

@@ -1,38 +0,0 @@
----
-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

@@ -1,19 +0,0 @@
----
-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

@@ -1,28 +0,0 @@
----
-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

@@ -1,27 +0,0 @@
----
-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

@@ -1,28 +0,0 @@
----
-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

@@ -1,63 +0,0 @@
----
-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

@@ -1,26 +0,0 @@
----
-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

@@ -1,31 +0,0 @@
----
-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

@@ -1,20 +0,0 @@
----
-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

@@ -1,26 +0,0 @@
----
-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

@@ -1,24 +0,0 @@
----
-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