258 lines
7.5 KiB
Markdown
258 lines
7.5 KiB
Markdown
---
|
|
description: Quick reference for Backlog.md CLI with critical file naming rules and workflow patterns
|
|
disable-model-invocation: false
|
|
---
|
|
|
|
# Backlog.md CLI Quick Reference Skill
|
|
|
|
## 🚨 CRITICAL: File Naming Convention
|
|
|
|
**Sacred Pattern**: `task-{id} - {title}.md`
|
|
|
|
### Examples
|
|
✅ `task-1 - Initial setup.md`
|
|
✅ `task-42 - Add authentication.md`
|
|
✅ `task-137 - Refactor API endpoints.md`
|
|
|
|
❌ `task-42-Add authentication.md` (missing spaces)
|
|
❌ `task42 - Title.md` (missing hyphen)
|
|
❌ `Add authentication.md` (missing task ID)
|
|
❌ `task-42.md` (missing title)
|
|
|
|
### Why This Matters
|
|
|
|
- CLI parses filenames to extract task ID and title
|
|
- Git tracking relies on consistent naming
|
|
- Metadata synchronization depends on format
|
|
- Breaking this format breaks Backlog.md functionality
|
|
|
|
### Golden Rule
|
|
|
|
**NEVER** manually create, rename, or edit task files.
|
|
**ALWAYS** use `backlog task create` and `backlog task edit`.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Backlog.md is a comprehensive CLI tool for managing project tasks, acceptance criteria, and documentation. All task modifications MUST use CLI commands.
|
|
|
|
**Reference Guide**: For complete documentation, see `docs/backlog-md-cli-usage.md` in this plugin
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Viewing Tasks
|
|
```bash
|
|
backlog task list --plain # List all tasks
|
|
backlog task 42 --plain # View specific task
|
|
backlog search "keyword" --plain # Search for tasks
|
|
```
|
|
|
|
### Creating Tasks
|
|
```bash
|
|
# Basic task
|
|
backlog task create "Task title" -d "Description"
|
|
|
|
# With acceptance criteria
|
|
backlog task create "Title" -d "Desc" --ac "AC 1" --ac "AC 2"
|
|
|
|
# With all options
|
|
backlog task create "Title" -d "Desc" -a @sara -s "To Do" -l backend,api --priority high
|
|
```
|
|
|
|
### Working on a Task
|
|
```bash
|
|
# Start working on a task
|
|
backlog task edit 42 -s "In Progress" -a @myself
|
|
|
|
# Add implementation plan
|
|
backlog task edit 42 --plan $'1. Research\n2. Implement\n3. Test'
|
|
|
|
# Mark acceptance criteria complete (supports multiple)
|
|
backlog task edit 42 --check-ac 1 --check-ac 2 --check-ac 3
|
|
|
|
# Add implementation notes
|
|
backlog task edit 42 --notes "Implemented using pattern X because Y"
|
|
|
|
# Mark as done
|
|
backlog task edit 42 -s Done
|
|
```
|
|
|
|
---
|
|
|
|
## Essential Commands
|
|
|
|
### Editing Tasks
|
|
|
|
| What | Command |
|
|
|---------------------|---------|
|
|
| Change status | `backlog task edit 42 -s "In Progress"` |
|
|
| Assign task | `backlog task edit 42 -a @sara` |
|
|
| Edit description | `backlog task edit 42 -d "New description"` |
|
|
| Edit title | `backlog task edit 42 -t "New Title"` |
|
|
| Add labels | `backlog task edit 42 -l backend,api` |
|
|
| Set priority | `backlog task edit 42 --priority high` |
|
|
|
|
### Acceptance Criteria (AC)
|
|
|
|
| What | Command |
|
|
|---------------------|---------|
|
|
| Add AC | `backlog task edit 42 --ac "New criterion"` |
|
|
| Add multiple AC | `backlog task edit 42 --ac "First" --ac "Second"` |
|
|
| Check AC #1 | `backlog task edit 42 --check-ac 1` |
|
|
| Check multiple AC | `backlog task edit 42 --check-ac 1 --check-ac 2` |
|
|
| Uncheck AC #2 | `backlog task edit 42 --uncheck-ac 2` |
|
|
| Remove AC #3 | `backlog task edit 42 --remove-ac 3` |
|
|
| Mixed ops | `backlog task edit 42 --check-ac 1 --uncheck-ac 2 --ac "New"` |
|
|
|
|
### Implementation Planning & Notes
|
|
|
|
| What | Command |
|
|
|---------------------|---------|
|
|
| Add plan | `backlog task edit 42 --plan $'1. Step 1\n2. Step 2'` |
|
|
| Add notes | `backlog task edit 42 --notes "Implementation details"` |
|
|
| Append notes | `backlog task edit 42 --append-notes "Additional note"` |
|
|
|
|
### Searching & Filtering
|
|
|
|
| What | Command |
|
|
|---------------------|---------|
|
|
| Search tasks | `backlog search "auth" --plain` |
|
|
| Filter by status | `backlog task list -s "To Do" --plain` |
|
|
| Filter by assignee | `backlog task list -a @sara --plain` |
|
|
| Search type filter | `backlog search "api" --type task --plain` |
|
|
|
|
---
|
|
|
|
## Multi-line Input Tips
|
|
|
|
For descriptions, plans, and notes with multiple lines, use Bash ANSI-C quoting:
|
|
|
|
```bash
|
|
# Example with newlines
|
|
backlog task edit 42 --plan $'1. Research\n2. Implement\n3. Test'
|
|
|
|
# Multi-paragraph notes
|
|
backlog task edit 42 --notes $'Implemented feature X\n\nAdded comprehensive tests\nUpdated documentation'
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow Example
|
|
|
|
```bash
|
|
# 1. Create a task
|
|
backlog task create "Add user authentication" \
|
|
-d "Implement login/logout functionality" \
|
|
--ac "Login with valid credentials" \
|
|
--ac "Session persists across page reloads" \
|
|
--ac "Logout clears session"
|
|
|
|
# 2. Start working (assuming task ID is 42)
|
|
backlog task edit 42 -s "In Progress" -a @myself
|
|
|
|
# 3. Add implementation plan
|
|
backlog task edit 42 --plan $'1. Research auth patterns\n2. Implement login endpoint\n3. Add session management\n4. Write tests'
|
|
|
|
# 4. During implementation, check off ACs as you complete them
|
|
backlog task edit 42 --check-ac 1
|
|
|
|
# 5. When done, add implementation notes
|
|
backlog task edit 42 --notes "Implemented JWT-based auth with HTTP-only cookies for security"
|
|
|
|
# 6. Mark all remaining ACs complete
|
|
backlog task edit 42 --check-ac 2 --check-ac 3
|
|
|
|
# 7. Mark task as done
|
|
backlog task edit 42 -s Done
|
|
```
|
|
|
|
---
|
|
|
|
## Definition of Done Checklist
|
|
|
|
A task is Done only when ALL of these are complete:
|
|
|
|
- [ ] All acceptance criteria checked via CLI (`--check-ac`)
|
|
- [ ] Implementation notes added via CLI (`--notes`)
|
|
- [ ] Status set to "Done" via CLI (`-s Done`)
|
|
- [ ] Tests pass and linting checks pass
|
|
- [ ] Documentation updated if needed
|
|
- [ ] Code reviewed
|
|
- [ ] No regressions detected
|
|
|
|
---
|
|
|
|
## Golden Rules
|
|
|
|
1. **Never edit task files directly** - Use CLI commands only
|
|
2. **Always use `--plain` flag** when listing/viewing tasks
|
|
3. **Mark ACs as you complete them** - Don't wait until the end
|
|
4. **Share implementation plans with user** before coding
|
|
5. **Use newlines in descriptions/plans/notes** for readability
|
|
6. **Respect the naming pattern** - `task-{id} - {title}.md`
|
|
|
|
---
|
|
|
|
## Task Status Flow
|
|
|
|
- New task → "To Do"
|
|
- Starting work → "In Progress" (+ assign yourself)
|
|
- Work complete → "Done" (all ACs checked, notes added)
|
|
|
|
---
|
|
|
|
## Acceptance Criteria Strategy
|
|
|
|
- **Outcome-focused** - What does the user/system do, not implementation details
|
|
- **Testable** - Can be objectively verified
|
|
- **Independent** - Each AC is a unit of work
|
|
- **Complete** - Together they define the full task scope
|
|
|
|
### Good ACs (outcome-focused)
|
|
- "User can log in with valid credentials"
|
|
- "System returns 404 for non-existent resources"
|
|
|
|
### Bad ACs (implementation-focused)
|
|
- "Add login() function to auth.ts"
|
|
- "Use bcrypt for password hashing"
|
|
|
|
---
|
|
|
|
## Notes Format (PR Description Style)
|
|
|
|
```
|
|
- Outcome: What was implemented
|
|
- Implementation: How it was done and why
|
|
- Testing: What was tested
|
|
- Follow-up: Any next steps or known issues
|
|
```
|
|
|
|
---
|
|
|
|
## Common Patterns
|
|
|
|
### DO vs DON'T
|
|
|
|
| Task | ✅ DO | ❌ DON'T |
|
|
|---------------|--------------------------------------|-----------------------------------|
|
|
| View task | `backlog task 42 --plain` | Read .md file directly |
|
|
| Check AC | `backlog task edit 42 --check-ac 1` | Change `- [ ]` to `- [x]` in file |
|
|
| Add notes | `backlog task edit 42 --notes "..."` | Type notes into .md file |
|
|
| Change status | `backlog task edit 42 -s Done` | Edit status in frontmatter |
|
|
|
|
---
|
|
|
|
## Full Documentation
|
|
|
|
For complete documentation including all options and advanced features:
|
|
```bash
|
|
# Read comprehensive guide
|
|
cat docs/backlog-md-cli-usage.md
|
|
|
|
# CLI help
|
|
backlog --help
|
|
```
|