Backlog.md Overview (MCP)

This project uses Backlog.md to track features, bugs, and structured work as tasks.

When to Use Backlog

Create a task if the work requires planning or decision-making:

Ask yourself: "Do I need to think about HOW to do this?"

• YES → Search for existing task first, create if needed
• NO → Just do it (the change is trivial/mechanical)

Examples of work that needs tasks:

• "Fix the authentication bug" → need to investigate, understand root cause, choose fix
• "Add error handling to the API" → need to decide what errors, how to handle them
• "Refactor UserService" → need to plan new structure, migration path

Examples of work that doesn't need tasks:

• "Fix typo in README" → obvious mechanical change
• "Update version number to 2.0" → straightforward edit
• "Add missing semicolon" → clear what to do

Always skip tasks for:

• Questions and informational requests
• Reading/exploring/explaining code, issues, or concepts

Typical Workflow

When the user requests non-trivial work:

1. Search first: Use task_search or task_list (with status filters) - work might already be tracked
2. If found: Work on the existing task. Check task-execution workflow to know how to proceed
3. If not found: Create task(s) based on scope (single task or present breakdown for approval). Check task-creation workflow for details
4. Execute: Follow task-execution guidelines

Searching first avoids duplicate tasks and helps you understand existing context.

Detailed Guidance (Required)

Read these resources to get essential instructions when:

• Creating tasks → backlog://workflow/task-creation - Scope assessment, acceptance criteria, parent/subtasks structure
• Planning & executing work → backlog://workflow/task-execution - Planning workflow, implementation discipline, scope changes
• Completing & reviewing tasks → backlog://workflow/task-completion - Definition of Done, completion checklist, next steps

These guides contain critical workflows you need to follow for proper task management.

Core Principle

Backlog tracks commitments (what will be built). Use your judgment to distinguish between "help me understand X" (no tracking) vs "add feature Y" (track in Backlog).

MCP Tools Quick Reference

• task_list — list tasks with optional filtering by status, assignee, or labels
• task_search — search tasks by title and description
• task_view — read full task context (description, plan, notes, acceptance criteria)
• task_create — create new tasks with description and acceptance criteria
• task_edit — update task metadata, status, plan, notes, acceptance criteria, and dependencies
• task_archive — archive completed tasks

Always operate through MCP tools. Never edit markdown files directly so relationships, metadata, and history stay consistent.