Initial commit
This commit is contained in:
Zhongwei Li
257
skills/backlog-quick-reference/SKILL.md
Normal file
257
skills/backlog-quick-reference/SKILL.md
Normal file
@@ -0,0 +1,257 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user