backlog.md 0.1.0 → 0.1.3

package/.cursorrules

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

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

package/.github/ISSUE_TEMPLATE/bug_report.md

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

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

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

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

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

package/AGENTS.md

@@ -1,65 +0,0 @@
-# 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.  

package/CLAUDE.md

@@ -1,87 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Commands
-
-### Development
-- `bun install` - Install dependencies 
-- `bun test` - Run tests
-- `bun run format` - Format code with Biome
-- `bun run lint` - Lint and auto-fix with Biome  
-- `bun run check` - Run all Biome checks (format + lint)
-
-### Testing
-- `bun test` - Run all tests
-- `bun test <filename>` - Run specific test file
-
-## Project Architecture
-
-This is the **Backlog.md** project - a lightweight git + markdown project management tool for human-AI collaboration.
-
-### Core Structure
-- **CLI Tool**: Built with Bun and TypeScript as a global npm package (`@backlog.md`)
-- **Source Code**: Located in `/src` directory with modular TypeScript structure
-- **Task Management**: Uses markdown files in `.backlog/` directory structure
-- **Workflow**: Git-integrated with task IDs referenced in commits and PRs
-
-### Key Components
-- **Task System**: Tasks stored as `task-<id> - <title>.md` files with decimal subtasks (e.g., `task-4.1`)
-- **Configuration**: Uses `config.yml` for project settings
-- **Status Workflow**: Draft → Active → Archive progression
-
-### AI Agent Integration
-- Reference task IDs in commit messages and PR titles when implementing features
-- Use `.backlog/tasks/` markdown files to understand implementation requirements
-- Include a `## Description` section and a `## Acceptance Criteria` checklist in every task file
-- Write relevant tests when implementing new functionality or fixing bugs
-- Follow decimal numbering for subtasks
-- Maintain clean git status before commits
-- Use task-descriptive branch names: `<task-id> feature description`
-- When you start working on a task, update its status to `In Progress`, assign yourself as the assignee, and push the change.
-- After testing a task, mark it **Done** with:
-
-```bash
-backlog task edit <task-id> --status Done
-```
-
-### Code Standards
-- **Runtime**: Bun with TypeScript 5
-- **Formatting**: Biome with tab indentation and double quotes
-- **Linting**: Biome recommended rules
-- **Testing**: Bun's built-in test runner
-- **Pre-commit**: Husky + lint-staged automatically runs Biome checks before commits
-
-The pre-commit hook automatically runs `biome check --write` on staged files to ensure code quality. If linting errors are found, the commit will be blocked until fixed.
-
-## 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.  

package/CONTRIBUTING.md

@@ -1,19 +0,0 @@
-# Contributing to Backlog.md
-
-Thank you for your interest in contributing to Backlog.md. This project is managed using the Backlog.md workflow and we welcome community involvement.
-
-## Opening Issues
-
-- Search existing issues before creating a new one.
-- Provide a clear description of the problem or proposal.
-- Reference the related task ID when applicable.
-
-## Pull Requests
-
-1. Fork the repository and create a branch named after the task ID and a short description (e.g. `task-27-contributing-guidelines`).
-2. Make your changes and commit them with the task ID in the message.
-3. Run tests with `bun test` and ensure they pass.
-4. Format and lint the code using `npx biome check .`.
-5. Open a pull request referencing the issue or task it addresses.
-
-Please read [AGENTS.md](AGENTS.md) for detailed rules that apply to contributors and AI agents.

package/DEVELOPMENT.md

@@ -1,37 +0,0 @@
-## Local Development
-
-Run these commands to bootstrap the project:
-
-```bash
-bun install
-```
-
-Run tests:
-
-```bash
-bun test
-```
-
-Format and lint:
-
-```bash
-npx biome check .
-```
-
-For contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
-
-## Release
-
-To publish a new version to npm:
-
-1. Update the `version` field in `package.json`.
-2. Commit the change and create a git tag matching the version, e.g. `v0.1.0`.
-   ```bash
-   git tag v<version>
-   git push origin v<version>
-   ```
-3. Push the tag to trigger the GitHub Actions workflow. It will build, test and
-   publish the package to npm using the repository `NPM_TOKEN` secret.
-
-[← Back to README](README.md)
-

package/biome.json

@@ -1,31 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-	"vcs": {
-		"enabled": false,
-		"clientKind": "git",
-		"useIgnoreFile": false
-	},
-	"files": {
-		"ignoreUnknown": false,
-		"ignore": ["cli/"]
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab",
-		"lineWidth": 120
-	},
-	"organizeImports": {
-		"enabled": true
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true
-		}
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "double"
-		}
-	}
-}