backlog.md 0.1.0

package/.backlog/tasks/task-6.1 - cli-local-installation-support-for-bunx-npx.md

@@ -0,0 +1,49 @@
+---
+id: task-6.1
+title: 'CLI: Local installation support for bunx/npx'
+status: Done
+assignee: []
+reporter: @MrLesk
+created_date: '2025-06-08'
+updated_date: '2025-06-09'
+labels:
+  - cli
+dependencies: []
+parent_task_id: task-6
+---
+
+## Description
+
+Allow installing Backlog.md locally in JS projects so agents can run bunx/npx backlog create when global install isn't available.
+
+## Acceptance Criteria
+
+- [x] Remove `"private": true` from package.json to allow publishing
+- [x] Configure proper package name/scope for npm registry
+- [x] Test and verify `npx backlog` and `bunx backlog` work from any project directory
+- [x] Update documentation with local installation instructions
+
+## Implementation Notes
+
+**Package Configuration:**
+- `package.json` configured for npm publishing with proper `name`, `version` (0.1.0), and `bin` entry
+- `bin` field points to `./cli/index.js` enabling global CLI access after installation
+- Build script creates both Node.js bundle and compiled binary for distribution flexibility
+
+**Local Installation Support:**
+- Package installable via `npm install backlog.md --save-dev` or `bun add -d backlog.md`
+- CLI accessible through `npx backlog` and `bunx backlog` commands
+- Works from any directory within the project after local installation
+
+**Documentation:**
+- `readme.md` includes comprehensive local installation section (lines 15-30)
+- Documents both npm and bun installation methods
+- Provides clear usage examples for npx/bunx execution
+
+**Test Coverage:**
+- `local-install.test.ts` automatically tests both execution methods
+- Creates temporary project, builds tarball, installs locally, and verifies CLI functionality
+- Tests confirm `--help` output contains expected "Backlog project management CLI" text
+- Both npx and bunx execution paths validated in isolated environment
+
+The implementation ensures seamless local installation for projects where global CLI installation isn't available, particularly useful for AI agents working in constrained environments.

package/.backlog/tasks/task-6.2 - cli-github-actions-for-build-&-publish.md

@@ -0,0 +1,64 @@
+---
+id: task-6.2
+title: 'CLI: GitHub Actions for Build & Publish'
+status: Done
+assignee: []
+reporter: '@MrLesk'
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels:
+  - ci
+dependencies: []
+parent_task_id: task-6
+---
+
+## Description
+
+Set up continuous integration for the CLI. Use GitHub Actions to build the project with Bun, run tests, and publish the package to npm (and by extension Yarn) when a release tag is pushed.
+
+## Acceptance Criteria
+
+- [x] Workflow builds the CLI with `bun build` and runs tests
+- [x] Publishing step deploys to npm using `NODE_AUTH_TOKEN`
+- [x] Trigger on version tags like `v*.*.*`
+- [x] Documentation updated with release instructions
+
+## Implementation Notes
+
+**GitHub Actions Workflow (.github/workflows/ci.yml):**
+- Created comprehensive CI/CD pipeline with name "Build and Publish"
+- **Triggers**: Main branch pushes, pull requests, and version tags matching `v*.*.*` pattern
+- **Environment**: Runs on `ubuntu-latest` with Bun runtime setup via `oven-sh/setup-bun@v1`
+- **Build Process**: Executes `bun install`, `bun run build`, and `bun test` in sequence
+- **Publishing**: Conditional publishing to npm only when tags are pushed (`startsWith(github.ref, 'refs/tags/')`)
+
+**Build & Test Pipeline:**
+- **Dependencies**: `bun install` installs all project dependencies
+- **Build**: `bun run build` executes complex build script creating both Node.js bundle and compiled binary
+- **Testing**: `bun test` runs entire test suite (122+ tests) to ensure quality before publishing
+- **Build Artifacts**: Creates `cli/index.js` (Node.js entry point) and `cli/backlog` (standalone binary)
+
+**NPM Publishing Configuration:**
+- Uses `npm publish --access public` for publishing to npm registry
+- Authenticates via `NODE_AUTH_TOKEN` environment variable from GitHub secrets
+- Package configured with `"name": "backlog.md"` and proper `bin` entry pointing to `./cli/index.js`
+- Version controlled via `package.json` version field (currently 0.1.0)
+
+**Documentation & Release Process (readme.md:245-257):**
+- Added comprehensive "Release" section with step-by-step instructions
+- **Process**: Update version in package.json → Commit changes → Create git tag → Push tag
+- **Automation**: Git tag push automatically triggers GitHub Actions workflow
+- **Security**: Workflow uses repository `NODE_AUTH_TOKEN` secret for secure npm publishing
+
+**Quality Assurance:**
+- Workflow validates build process before any publishing attempt
+- All tests must pass before package publication
+- Conditional publishing prevents accidental releases from non-tag pushes
+- Multi-trigger setup enables CI validation on PRs and main branch changes
+
+**Future Considerations:**
+- Workflow ready for production use with proper security practices
+- Supports semantic versioning via git tags (v1.0.0, v2.1.3, etc.)
+- Can be enhanced with version consistency validation and artifact retention if needed
+
+The implementation provides a complete automated CI/CD pipeline that builds, tests, and publishes the Backlog.md CLI package to npm whenever a version tag is pushed, ensuring quality releases with minimal manual intervention.

package/.backlog/tasks/task-7 - cli-kanban-view.md

@@ -0,0 +1,60 @@
+---
+id: task-7
+title: "Kanban Board: Implement CLI Text-Based Kanban Board View"
+status: Done
+assignee: []
+reporter: "@MrLesk"
+created_date: 2025-06-04
+updated_date: 2025-06-09
+completed_date: 2025-06-09
+labels: ["cli", "command"]
+milestone: "M2 - CLI Kanban Board"
+dependencies: ["task-3"]
+---
+
+## Description
+
+Design and implement a CLI command (`backlog board view` or similar) that reads tasks from `.backlog/tasks/` and displays them in a simple text-based Kanban board format in the terminal. Columns should be derived from task statuses.
+
+## Acceptance Criteria
+
+- [x] Command parses task files and groups them by status.
+- [x] Output is a readable text-based representation of the Kanban board.
+- [x] Columns are dynamically generated.
+
+## Implementation Notes
+
+**Core Implementation (src/board.ts):**
+- `generateKanbanBoard()` function creates text-based kanban board from task array
+- Dynamically groups tasks by status using Map for efficient lookup
+- Respects configured status order from project config (`config.yml`)
+- Auto-adjusts column widths based on longest content (status name or task title)
+- Handles empty task lists by showing configured status columns
+- Supports tasks with missing/empty status under "No Status" column
+
+**CLI Integration (src/cli.ts:380-399):**
+- Added `backlog board view` command with proper help documentation
+- Loads tasks from filesystem and project configuration
+- Gracefully handles empty projects with "No tasks found" message
+- Integrates with existing Core/FileSystem infrastructure
+
+**Algorithm Features:**
+- Column-based layout with proper padding and separators
+- Maintains visual alignment with calculated column widths
+- Status ordering: configured statuses first, then any unrecognized statuses
+- Clean table format: header row, separator line, task rows
+- Multi-line task display: task ID on first line, title on second line
+- Empty rows between tasks for improved readability
+- Screen-friendly format that accommodates long task titles
+
+**Test Coverage (src/test/board.test.ts + src/test/cli.test.ts):**
+- Unit tests for core board generation function (5 test cases)
+- Integration tests for CLI board command (2 test cases)
+- Edge cases: empty tasks, no status, long titles, status ordering
+- Comprehensive verification of board structure and content
+
+**Export Integration (src/index.ts:25):**
+- Function exported for reuse in other modules
+- Follows project's modular architecture pattern
+
+The implementation provides a professional text-based kanban view that works seamlessly with the existing CLI infrastructure and maintains visual consistency across different terminal widths.

package/.backlog/tasks/task-7.1 - cli-kanban-board-detect-remote-task-status.md

@@ -0,0 +1,62 @@
+---
+id: task-7.1
+title: 'CLI: Kanban board detect remote task status'
+status: Done
+assignee: []
+reporter: @MrLesk
+created_date: '2025-06-09'
+updated_date: '2025-06-09'
+labels: []
+dependencies: []
+parent_task_id: task-7
+---
+
+## Description
+
+Improve the Kanban board command so it checks all branches on the `origin`
+remote for task updates before rendering the board. Use `git fetch` to get the
+latest references and then iterate through each branch to collect task files
+using `git ls-tree`. Retrieve each task file with `git show` and merge the most
+recent status into the board view. If multiple branches contain the same task,
+adopt the frontmatter from the task that supplies the latest status so fields
+like `title` and `assignee` remain current.
+
+Status conflicts can occur when the same task has different status values in
+multiple branches. In that case always display the last status found in the
+iteration order and respect the status sequence defined in `config.yml`.
+All frontmatter fields should also come from the task file that provided the
+chosen status.
+
+## Acceptance Criteria
+
+- [x] `backlog board view` fetches and scans every branch under `origin` for task files.
+- [x] The displayed status for each task reflects the most recent entry across all branches.
+- [x] Status columns follow the configured order and fall back to the last seen status on conflicts, copying the full frontmatter from the task that provided the displayed status.
+
+## Implementation Notes
+
+Added remote task status detection to the CLI kanban board view. Key technical details:
+
+**Git Operations Enhanced:**
+- Added `fetchRemote()`, `listRemoteBranches()`, `listFilesInTree()`, and `showFile()` methods to `GitOperations` class in `src/git/operations.ts`
+- These methods use git commands: `fetch`, `branch -r`, `ls-tree -r --name-only`, and `show` respectively
+
+**Board View Logic (src/cli.ts:428-454):**
+- Fetches latest remote references using `core.gitOps.fetchRemote()`
+- Iterates through all remote branches from `core.gitOps.listRemoteBranches()`
+- For each branch, scans `.backlog/tasks` directory using `core.gitOps.listFilesInTree()`
+- Retrieves and parses task files using `core.gitOps.showFile()` and `parseTask()`
+- Merges task status based on configured status order - later statuses override earlier ones
+- Preserves all frontmatter (title, assignee, etc.) from the task providing the winning status
+- Gracefully handles remote access errors (offline scenarios, missing remotes)
+
+**Status Conflict Resolution:**
+- Uses `statuses.indexOf()` to determine status progression order from config.yml
+- Condition `newIdx > currentIdx || currentIdx === -1 || newIdx === currentIdx` ensures the most advanced status wins
+- When status indices are equal, the last seen task (iteration order) takes precedence
+- Entire task object is replaced (not just status) to maintain frontmatter consistency
+
+**Testing:**
+- Comprehensive test in `src/test/cli.test.ts` verifies remote status merging with bare git repositories
+- Test creates a feature branch with updated task status and verifies main branch picks up the advanced status
+

package/.backlog/tasks/task-8 - gui-project-setup.md

@@ -0,0 +1,21 @@
+---
+id: task-8
+title: "GUI: Setup GUI Project Structure"
+status: "To Do"
+assignee: []
+reporter: @MrLesk
+created_date: 2025-06-04
+labels: ["gui", "setup"]
+milestone: "M3 - GUI"
+dependencies: ["task-7"]
+---
+
+## Description
+
+Initialize the GUI project using Tauri. Integrate the core logic library. Set up basic window layout and navigation placeholders.
+
+## Acceptance Criteria
+
+- [ ] GUI project created with Tauri.
+- [ ] Core logic library successfully imported and usable.
+- [ ] Basic application window opens.

package/.backlog/tasks/task-9 - gui-task-crud.md

@@ -0,0 +1,24 @@
+---
+id: task-9
+title: "GUI: Implement GUI Task Creation/Editing Forms"
+status: "To Do"
+assignee: []
+reporter: @MrLesk
+created_date: 2025-06-04
+labels: ["gui"]
+milestone: "M3 - GUI"
+dependencies: ["task-8"]
+---
+
+## Description
+
+Create forms/modals in the GUI for:
+
+- Creating new tasks (as active tasks or draft).
+- Editing existing tasks (all fields from frontmatter and description).
+- All operations should use the core logic library to update Markdown files and commit.
+
+## Acceptance Criteria
+
+- [ ] Task creation form works and saves new tasks.
+- [ ] Task editing form loads existing task data and saves changes.

package/.cursorrules

@@ -0,0 +1,223 @@
+# Cursor Agent Rules for Backlog.md Project
+# These rules are designed to ensure high-quality contributions and maintain project consistency
+
+## Table of Contents
+1. Project Structure and Navigation
+2. Task Management
+3. Documentation
+4. Code Quality and Testing
+5. Git Workflow
+6. AI Agent Guidelines
+7. Configuration Management
+8. Review and Communication
+9. Error Handling and Logging
+10. Performance and Security
+11. Maintenance and Dependencies
+12. Accessibility and Internationalization
+13. Version Control and Releases
+14. Emergency Procedures
+15. Project-Specific Rules
+16. Definition of Done
+17. Glossary
+18. Templates and Examples
+
+---
+
+## 1. Project Structure and Navigation
+1.1 Always check the project structure in `AGENTS.md` before making changes
+1.2 Follow the directory structure under `.backlog/` (see [Project Structure](./AGENTS.md#structure))
+- Never modify files outside the designated project directories
+- Always verify file locations before making changes
+
+## 2. Task Management
+- Always check .backlog/tasks/ for current tasks before starting work
+- Reference task IDs in all commit messages and PR titles
+- Follow the task status workflow defined in config.yml
+- Never modify task files directly - use the backlog CLI commands
+- When creating new tasks, ensure they follow the established format
+- Subtasks must use decimal numbering (e.g., task-4.1) to indicate their parentage.
+- Subtasks are created using the CLI with the --parent <task-id> flag; the next decimal ID is assigned automatically.
+- Always reference subtasks by their full decimal ID in commit messages, PR titles, and documentation.
+- Subtasks are stored in the same .backlog/tasks/ directory as main tasks.
+- After completing and testing a task, set its status to Done via CLI:
+
+```bash
+backlog task edit <task-id> --status Done
+```
+
+## 3. Documentation
+3.1 All documentation must be in Markdown format
+3.2 Update relevant `readme.md` files when making changes
+3.3 Document architectural decisions in `.backlog/decisions/`
+3.4 Maintain clear and concise documentation
+3.5 Include examples in documentation where appropriate 
+
+## 4. Code Quality and Testing
+- Ensure all code changes are properly tested
+- Follow the project's coding style and conventions
+- Write clear, self-documenting code
+- Include appropriate error handling
+- Add comments for complex logic
+
+## 5. Git Workflow
+- Always check git status before committing
+- Use branch names that reflect the task being worked on (tasks/<task-id> feature description)
+- Keep commits atomic and focused
+- Write clear, descriptive commit messages
+- Reference task IDs in commit messages
+
+## 6. AI Agent Guidelines
+6.1 Always verify task requirements before implementation
+6.2 Use semantic search to understand existing code
+6.3 Check for similar implementations before creating new features
+6.4 Document any assumptions in PR descriptions and `.backlog/decisions/`
+6.5 Consider edge cases and error scenarios
+
+## 7. Configuration Management
+- Never modify config.yml directly
+- Use backlog config commands for configuration changes
+- Maintain backward compatibility when possible
+- Document configuration changes in decisions/
+
+## 8. Review and Communication
+- Ensure all changes are properly documented
+- Verify that changes don't break existing functionality
+- Check for potential security implications
+- Consider performance impact of changes
+- Validate against project requirements
+- Use clear and professional language in comments and documentation
+- Document any questions or concerns in task comments
+- Keep commit messages and PR descriptions informative
+- Reference relevant documentation when making changes
+
+## 9. Error Handling and Logging
+- Implement proper error handling for all new features
+- Include appropriate logging
+- Consider user experience in error scenarios
+- Document error cases and recovery procedures
+
+## 10. Performance and Security
+- Consider performance implications of changes
+- Optimize code when necessary
+- Document performance considerations
+- Test with realistic data volumes
+- Follow security best practices
+- Validate all user inputs
+- Consider potential security implications
+- Document security-related decisions
+
+## 11. Maintenance and Dependencies
+- Keep dependencies up to date
+- Remove deprecated code
+- Maintain backward compatibility
+- Document maintenance procedures
+- Document all new dependencies
+- Justify dependency additions
+- Consider impact on project size
+- Check for license compatibility
+
+## 12. Accessibility and Internationalization
+- Ensure all features are accessible
+- Follow accessibility guidelines
+- Test with accessibility tools
+- Document accessibility considerations
+- Support multiple languages where appropriate
+- Use proper character encoding
+- Consider cultural differences
+- Document internationalization requirements
+
+## 13. Version Control and Releases
+- Follow semantic versioning
+- Document breaking changes
+- Maintain changelog
+- Tag releases appropriately
+
+## 14. Emergency Procedures
+- Document emergency procedures
+- Know how to rollback changes
+- Have backup procedures
+- Document recovery steps
+
+## 15. Project-Specific Rules
+- Follow Backlog.md CLI conventions
+- Use proper task status transitions
+- Maintain task history
+- Follow project naming conventions
+- Use appropriate labels for tasks
+- Keep task descriptions clear and complete
+- Include a `## Description` section and `## Acceptance Criteria` checklist in each task
+- Write relevant tests when implementing new functionality or fixing bugs
+- Follow the established workflow
+- When starting work on a task, set its status to `In Progress`, assign yourself, and push the change before continuing
+- Use proper task prioritization
+- Maintain task dependencies
+- Follow project branching strategy
+
+## 16. Definition of Done
+A task is **Done** only when **all** of the following hold:
+
+1. **Acceptance criteria** checklist in the task file is fully checked.  
+2. **Automated tests** (unit + integration) cover new logic and CI passes.  
+3. **Static analysis**: linter & formatter succeed (when available).  
+4. **Documentation**:  
+   - Docs updated.  
+   - Task file appended with a `## Implementation Notes` section summarising approach, trade‑offs and follow‑ups.  
+5. **Review**: code reviewed.  
+6. **Task hygiene**: status set to **Done** via CLI.  
+7. **No regressions**: performance, security and licence checks green.
+
+## 17. Glossary
+- Add a glossary of project-specific terms and acronyms
+- Add "Subtask" entry: decimal numbering, CLI creation, referencing, and storage
+
+## 18. Templates and Examples
+- Add a `docs/` directory for guides (onboarding, semantic search, coding style, etc.)
+- Automate rule enforcement where possible (e.g., with pre-commit hooks, CI checks)
+- Regularly review and update rules to reflect project evolution and lessons learned
+
+# Code Review
+- Review code for:
+  - Functionality
+  - Performance
+  - Security
+  - Maintainability
+  - Documentation
+  - Testing
+  - Accessibility
+  - Internationalization
+
+# Emergency Procedures
+- Document emergency procedures
+- Know how to rollback changes
+- Have backup procedures
+- Document recovery steps
+
+# Project-Specific Rules
+- Follow Backlog.md CLI conventions
+- Use proper task status transitions
+- Maintain task history
+- Follow project naming conventions
+- Use appropriate labels for tasks
+- Keep task descriptions clear and complete
+- Follow the established workflow
+- Use proper task prioritization
+- Maintain task dependencies
+- Follow project branching strategy 
+
+## Backlog.md Tool - CLI usage
+| Purpose | Command |
+|---------|---------|
+| Create task | `backlog task create "Add OAuth"`                    |
+| Create sub task | `backlog task create --parent 14 "Add Google auth"`                    |
+| List tasks  | `backlog task list`                                  |
+| View detail | `backlog task 7`                                     |
+| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
+| Archive     | `backlog task archive 7`                             |
+| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
+| Demote to draft| `backlog task demote <id>` |
+
+## Backlog.md Tool - Tips for AI Agents
+- Keep tasks **small, atomic, and testable**; create subtasks liberally.  
+- Prefer **idempotent** changes so reruns remain safe.  
+- Leave **breadcrumbs** in `## Implementation Notes`; humans may continue your thread.  
+- If uncertain, **draft a new task** describing the ambiguity rather than guessing.  

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug Report
+about: Create a bug report to help us improve
+title: "[Bug]: "
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment**
+- OS: [e.g., Windows 11]
+- Node version: [e.g., 20]
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature Request
+about: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: enhancement
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear description of what problem you want to solve.
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,8 @@
+## Summary
+Briefly explain the purpose of this pull request.
+
+## Related Tasks
+List task IDs this PR closes, e.g. `closes task-29`.
+
+## Testing
+Describe how you tested your changes.

package/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: Build and Publish
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*.*.*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: bun install
+      - run: bun run build
+      - run: bun test
+      
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: bun install
+      - run: bun run build
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

package/.husky/pre-commit

@@ -0,0 +1 @@
+bun lint-staged

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Project structure
+
+backlog.md/ (Root folder for "Backlog.md" project)
+└── .backlog/ ("Backlog.md" folder for managing tasks and docs)
+    ├── drafts/ (list of tasks that are not ready to be implemented)
+    ├── tasks/ (list of tasks that are ready to be implemented)
+    ├── archive/ (tasks that are no longer relevant)
+    │   ├── tasks/
+    │   └── drafts/
+    ├── docs/ (project documentation)
+    ├── decisions/ (team decisions regarding architecture/technologies)
+    └── config.yml ("Backlog.md" configuration file)
+
+Instructions for using the Backlog.md tool are available in the `readme.md` file in the root folder.
+
+Each folder contains a `readme.md` file with instructions on how to use the Backlog.md tool for that specific folder.
+
+## AI Agent Guidelines
+
+- Use the markdown task files under `.backlog/tasks/` to decide what to implement.
+- Reference the task `id` in commit messages and PR titles when closing a task.
+- Subtasks use decimal numbering (e.g., `task-4.1`). Reference these IDs the same way.
+- Each task must include a `## Description` section followed by a `## Acceptance Criteria` checklist.
+- Include relevant tests when implementing new functionality or fixing bugs.
+- Keep all project documentation in Markdown format and update the related `readme.md` files when necessary.
+- Ensure the working tree is clean (`git status`) before committing changes.
+- The branch name should reflect the task being worked on, e.g., `<task-id> feature description`.
+- When beginning work on a task, immediately set its status to `In Progress`, assign yourself as the `assignee`, and push the change.
+- After implementing and testing a task, mark it as **Done** using the CLI:
+
+```bash
+backlog task edit <task-id> --status Done
+```
+
+## Definition of Done
+
+A task is **Done** only when **all** of the following hold:
+
+1. **Acceptance criteria** checklist in the task file is fully checked.  
+2. **Automated tests** (unit + integration) cover new logic and CI passes.  
+3. **Static analysis**: linter & formatter succeed (when available).  
+4. **Documentation**:  
+   - Docs updated.  
+   - Task file appended with a `## Implementation Notes` section summarising approach, trade‑offs and follow‑ups.  
+5. **Review**: code reviewed.  
+6. **Task hygiene**: status set to **Done** via CLI.  
+7. **No regressions**: performance, security and licence checks green.
+
+## Backlog.md Tool - CLI usage
+| Purpose | Command |
+|---------|---------|
+| Create task | `backlog task create "Add OAuth"`                    |
+| Create sub task | `backlog task create --parent 14 "Add Google auth"`                    |
+| List tasks  | `backlog task list`                                  |
+| View detail | `backlog task 7`                                     |
+| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
+| Archive     | `backlog task archive 7`                             |
+| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
+| Demote to draft| `backlog task demote <id>` |
+
+## Backlog.md Tool - Tips for AI Agents
+- Keep tasks **small, atomic, and testable**; create subtasks liberally.  
+- Prefer **idempotent** changes so reruns remain safe.  
+- Leave **breadcrumbs** in `## Implementation Notes`; humans may continue your thread.  
+- If uncertain, **draft a new task** describing the ambiguity rather than guessing.