Backlog.md Development Assistant

You are an AI assistant helping with the Backlog.md project - a tool for managing project collaboration between humans and AI agents in a git ecosystem.

Required Reading

Before making any changes, you MUST:

1. Read the `README.md` file to understand the project overview and architecture

2. Read the `src/guidelines/agent-guidelines.md` file to understand agent-specific development guidelines

Project Overview

Backlog.md is a CLI tool built with Bun and TypeScript that manages tasks using markdown files in a `backlog/` directory structure. It integrates with Git workflows where task IDs are referenced in commits and PRs.

Development Commands

Setup & Build

`bun i` - Install dependencies

`bun run build` - Build the CLI tool

`bun run cli` - Run the CLI tool directly

Code Quality

`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

Configuration

`bun run cli config list` - View all configuration values

`bun run cli config get <key>` - Get a specific config value

`bun run cli config set <key> <value>` - Set a config value with validation

Code Standards

Follow these standards strictly:

1. **Runtime**: Bun with TypeScript 5

2. **Code Style**:

- Use Biome for formatting and linting

- Tab indentation (not spaces)

- Double quotes (not single quotes)

3. **Code Quality**:

- Follow Biome recommended rules

- All code must pass `bun run check` before committing

4. **Testing**:

- Use Bun's built-in test runner

- Write tests for new features

5. **Pre-commit**:

- Husky + lint-staged automatically runs Biome checks

- If linting errors are found, commits will be blocked

Git Workflow

Branching Strategy

Use feature branches for tasks: `tasks/task-123-feature-name`

Branch from main/develop as appropriate

Keep branches focused on single tasks

Commit Format

Use this exact format for all commits:

```

TASK-123 - Title of the task

```

Example:

```

TASK-456 - Add user authentication feature

```

Pull Requests

Reference task IDs in PR descriptions

Ensure all checks pass before requesting review

Link related tasks and issues

Project Structure

`/src` - Source code (modular TypeScript structure)

`/backlog` - Task markdown files directory

Tests use Bun's built-in test runner

CLI is designed to be installed globally: `npm i -g backlog.md`

Workflow Steps

When working on a task:

1. **Read guidelines**: Check README.md and agent-guidelines.md first

2. **Create branch**: `git checkout -b tasks/task-ID-feature-name`

3. **Make changes**: Follow code standards above

4. **Run checks**: `bun run check` to validate format and lint

5. **Test**: `bun test` to ensure tests pass

6. **Commit**: Use format `TASK-ID - Description`

7. **Pre-commit hook**: Biome checks run automatically

8. **Push**: Push branch and create PR

Important Notes

The pre-commit hook runs `biome check --write` on staged files automatically

Commits will be blocked if linting errors are found - fix them before committing

Always validate configuration changes using the CLI config commands

Task management uses markdown files - understand the backlog structure before modifying task-related code

This is a CLI tool - consider UX for command-line users when making changes

Configuration Management

The CLI supports runtime configuration. When working with config:

Use `config list` to see all available settings

Use `config get <key>` to check current values

Use `config set <key> <value>` to update (includes validation)

Common config keys: `defaultEditor`, project paths, etc.

Backlog.md Development