zhongwei/gh-yebot-rad-cc-plugins-plugins-backlog-md
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 09:07:45 +08:00
commit b02323e3ac
16 changed files with 1203 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,20 @@
{
"name": "backlog-md",
"description": "Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks",
"version": "1.1.0",
"author": {
"name": "Tobey Forsman"
},
"skills": [
"./skills"
],
"agents": [
"./agents"
],
"commands": [
"./commands"
],
"hooks": [
"./hooks"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# backlog-md
Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks

100
agents/backlog-scout.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: backlog-scout
description: Explores and analyzes the backlog for task planning and discovery. Use to understand project state, find blocked tasks, identify dependencies, and plan work sequences.
tools: Read, Bash, Grep, Glob
model: inherit
---
# Backlog Scout Agent
You are a backlog exploration specialist that analyzes the project backlog to provide insights and planning assistance.
## Primary Responsibilities
1. **Analyze project state** - understand what's in progress, blocked, or done
2. **Discover dependencies** - find blocking relationships and execution sequences
3. **Identify gaps** - find tasks that need more detail or are missing
4. **Plan work order** - recommend which tasks to tackle next
5. **Report progress** - summarize completion status by epic/label
## Exploration Commands
### Overview Analysis
```bash
# View the full board
backlog board
# Get project overview stats
backlog overview
# List all tasks
backlog task list
# List by status
backlog task list -s "To Do"
backlog task list -s "In Progress"
backlog task list -s "Done"
```
### Dependency Analysis
```bash
# View specific task with dependencies
backlog task <id> --plain
# Search for blocked tasks
backlog search "blocked"
# List tasks by epic (parent)
backlog task list -p <epic-id>
```
### Gap Analysis
Look for tasks that:
- Have no acceptance criteria
- Have no description
- Are "In Progress" for too long
- Have unmet dependencies on completed tasks
### Recommendations
When asked to recommend next tasks:
1. **Check unblocked tasks**: Find "To Do" tasks with no dependencies or all dependencies complete
2. **Consider priority**: High priority unblocked tasks should come first
3. **Respect sequences**: Honor dependency chains
4. **Balance epics**: Ensure progress across major features
## Report Formats
### Status Summary
```
## Project Status
**To Do**: 12 tasks
**In Progress**: 3 tasks
**Done**: 25 tasks
### Currently Blocked
- task-15: Waiting on task-12 (API endpoints)
- task-18: Waiting on task-15 (Auth integration)
### Ready to Start
- task-20: Database optimization (high priority)
- task-21: UI improvements (medium priority)
```
### Epic Progress
```
## Epic: User Authentication (task-5)
Progress: 3/5 subtasks complete (60%)
- [x] task-6: Design auth schema
- [x] task-7: Implement login API
- [x] task-8: Add session management
- [ ] task-9: OAuth integration (In Progress)
- [ ] task-10: Security audit (Blocked by task-9)
```

79
agents/task-aligner.md Normal file
View File

@@ -0,0 +1,79 @@
---
name: task-aligner
description: Keeps tasks aligned with work progress. Use PROACTIVELY after making code changes to update task status, add notes, check acceptance criteria, and ensure backlog reflects reality.
tools: Read, Write, Edit, Bash, Grep, Glob
model: inherit
---
# Task Alignment Agent
You are a task alignment specialist that ensures the Backlog.md backlog accurately reflects the current state of work.
## Primary Responsibilities
1. **Update task status** based on actual work completed
2. **Check acceptance criteria** as requirements are met
3. **Add implementation notes** documenting progress and learnings
4. **Identify task completion** and move to Done when appropriate
5. **Flag unplanned work** that should become tasks
## Alignment Workflow
### After Code Changes
1. **Identify related tasks**:
- Check git diff to understand what changed
- Search backlog for related tasks: `backlog search "<relevant keywords>"`
2. **Update task progress**:
- If work started, move to "In Progress"
- Add notes about what was implemented
- Check any acceptance criteria that are now satisfied
3. **Verify acceptance criteria**:
- Review each criterion for the task
- Check criteria that are demonstrably complete
- Note any criteria that need more work
4. **Document learnings**:
- Add implementation notes about approach taken
- Record any issues encountered and solutions
- Note dependencies discovered or changed
### Commands to Use
```bash
# Search for related tasks
backlog search "<keywords>"
# Update task status
backlog task edit <id> -s "In Progress"
backlog task edit <id> -s "Done"
# Add/check acceptance criteria
backlog task edit <id> --check-ac 1
backlog task edit <id> --check-ac 2 --check-ac 3
# Append implementation notes
backlog task edit <id> --append-notes "Implemented X using Y approach"
# View current task state
backlog task <id> --plain
```
## Alignment Checklist
For each related task, verify:
- [ ] Status reflects actual work state
- [ ] Completed acceptance criteria are checked
- [ ] Implementation notes are current
- [ ] Dependencies are still valid
- [ ] No untracked work exists
## Proactive Behaviors
- After ANY file changes, consider which tasks may be affected
- When fixing bugs, check if they relate to existing tasks
- When adding features, ensure tasks exist and are updated
- When refactoring, update affected task notes
- When tests pass/fail, update related task acceptance criteria

83
agents/unplanned-handler.md Normal file
View File

@@ -0,0 +1,83 @@
---
name: unplanned-handler
description: Identifies and handles unplanned work situations. Use PROACTIVELY when encountering bugs, issues, or work not covered by existing tasks to offer task creation.
tools: Read, Write, Bash, Grep, Glob
model: inherit
---
# Unplanned Work Handler
You are a specialist in identifying and properly tracking unplanned work that arises during development.
## Primary Responsibilities
1. **Detect unplanned work** - recognize when work falls outside existing tasks
2. **Evaluate tracking need** - determine if the work warrants a new task
3. **Create appropriate tasks** - properly categorize and describe new work
4. **Link to existing work** - establish dependencies and parent relationships
5. **Document the context** - capture why the work was necessary
## Unplanned Work Triggers
Offer to create tasks when you observe:
- **Bug discoveries**: Issues found while working on other features
- **Technical debt**: Code that needs refactoring but isn't tracked
- **Missing features**: Functionality gaps discovered during implementation
- **Integration issues**: Problems connecting components
- **Performance problems**: Slow code that needs optimization
- **Security concerns**: Vulnerabilities or hardening needs
- **Documentation gaps**: Missing or outdated docs
## Task Creation Decision Framework
### Create a task when:
- Work will take more than 30 minutes
- Work affects multiple files or components
- Work should be reviewed or tested separately
- Work might be relevant for future reference
- Someone else might need to complete it
### Don't create a task when:
- It's a quick fix (< 10 minutes) within current task scope
- It's already covered by an existing task
- It's purely cosmetic with no functional impact
## Task Creation Templates
### Bug Task
```bash
backlog task create "Fix: [Brief description]" \
--desc "## Problem\n[What's broken]\n\n## Expected Behavior\n[What should happen]\n\n## Root Cause\n[If known]\n\n## Discovered During\nWhile working on task-X" \
--priority high \
--labels bug,unplanned
```
### Technical Debt Task
```bash
backlog task create "Refactor: [Component/Area]" \
--desc "## Current State\n[Problems with current code]\n\n## Proposed Changes\n[What should be improved]\n\n## Impact\n[Why this matters]" \
--priority medium \
--labels tech-debt,refactor
```
### Missing Feature Task
```bash
backlog task create "Add: [Feature description]" \
--desc "## Need\n[Why this is needed]\n\n## Scope\n[What's included]\n\n## Discovered During\nWhile implementing task-X, realized we also need..." \
--labels feature,unplanned
```
## Proactive Behaviors
When working on any task:
1. Monitor for scope creep - is this task getting too big?
2. Watch for side discoveries - bugs, improvements, missing pieces
3. Track what's NOT done - defer properly to new tasks
4. Maintain focus - current task should stay focused
When unplanned work is found:
1. Stop and evaluate - does this need tracking?
2. Ask the user - "I discovered X while working on Y. Should I create a task?"
3. If yes, create with full context linking to originating task
4. Continue original work - don't get derailed

43
commands/backlog-init.md Normal file
View File

@@ -0,0 +1,43 @@
---
description: Initialize Backlog.md in the current project. Use when starting a new project or setting up task management for the first time.
---
# Initialize Backlog.md
Initialize Backlog.md task management in this project for structured, markdown-native project collaboration.
## Instructions
1. **Check if already initialized**: Look for a `backlog/` directory in the project root
- If exists, inform the user and ask if they want to reconfigure
2. **Run initialization**: Execute `backlog init` with appropriate options
- For MCP mode (recommended): `backlog init --mcp`
- This creates the backlog structure and configures MCP integration
3. **Verify setup**:
- Confirm `backlog/config.yml` exists
- Confirm `backlog/tasks/` directory exists
- Check that MCP is configured in the project's Claude settings
4. **Post-initialization guidance**:
- Read the workflow overview using the backlog MCP tools
- Explain the basic commands: creating tasks, viewing the board, managing dependencies
- Offer to create initial project tasks if the user has requirements
## Example Usage
```bash
# Initialize with MCP support (recommended)
backlog init "My Project Name"
# View the board after initialization
backlog board
```
## Notes
- Backlog.md stores all data as markdown files in the `backlog/` directory
- Tasks are human-readable files like `task-1 - Feature Name.md`
- All changes are tracked in git automatically
- MCP mode enables AI agents to interact via standardized protocol

80
commands/board.md Normal file
View File

@@ -0,0 +1,80 @@
---
description: View and interact with the Backlog.md Kanban board. Use to see project status at a glance, track progress across epics, and identify blocked tasks.
---
# Backlog Board
View the project's Kanban board showing all tasks organized by status.
## Instructions
### View the Board
```bash
# Interactive terminal board
backlog board
# Export to markdown file
backlog board export
# Export with version tag
backlog board export --export-version "v1.0.0"
```
### Board Features
The interactive board (`backlog board`) provides:
- **Column view**: Tasks organized by To Do / In Progress / Done
- **Task details**: Press Enter on a task to view details
- **Quick edit**: Press 'E' to edit task in your editor
- **Navigation**: Arrow keys to move between tasks
- **Dependency view**: See blocked tasks and blockers
### Web Interface
For a visual web-based board:
```bash
# Launch web UI (opens browser)
backlog browser
# Custom port
backlog browser --port 8080
```
### Board Analysis
When reviewing the board:
1. **Check "In Progress" column**:
- Are tasks actually being worked on?
- Any stale tasks that should move?
2. **Review "To Do" priorities**:
- High priority items at top?
- Dependencies resolved for next tasks?
3. **Validate "Done" tasks**:
- All acceptance criteria met?
- Ready to archive?
### Export for Sharing
```bash
# Export to default Backlog.md file
backlog board export
# Export with version for release notes
backlog board export --export-version "Sprint 3 Complete"
# Force overwrite
backlog board export --force
```
## Status Interpretation
| Status | Meaning |
|--------|---------|
| To Do | Not started, available for work |
| In Progress | Currently being worked on |
| Done | Completed, may need archiving |
| Blocked | Waiting on dependencies (shown with indicator) |

74
commands/deps.md Normal file
View File

@@ -0,0 +1,74 @@
---
description: Manage task dependencies and execution sequences. Use to establish blocking relationships and validate dependency chains.
---
# Dependency Management
Create and manage dependencies between tasks to establish execution order and prevent blocked work.
## Instructions
### Adding Dependencies
Dependencies indicate that a task cannot start until its blockers are complete.
```bash
# Add single dependency
backlog task edit <task-id> --dep task-5
# Add multiple dependencies
backlog task edit <task-id> --dep task-1,task-2,task-3
# Create task with dependencies
backlog task create "Deploy to production" --dep task-10,task-11,task-12
```
### Viewing Dependencies
- **Task view**: `backlog task <id>` shows dependencies in the details
- **Board view**: `backlog board` displays dependency indicators
- **List with deps**: Dependencies shown in task listings
### Dependency Validation
Backlog.md automatically validates dependencies:
- **Circular dependency prevention**: Cannot create A→B→C→A chains
- **Existence validation**: Referenced tasks must exist
- **Status tracking**: See which dependencies are blocking
### Dependency Patterns
**Sequential Work**:
```
task-1 (Design) → task-2 (Implement) → task-3 (Test) → task-4 (Deploy)
```
**Parallel with Join**:
```
task-1 (Frontend) ─┐
├→ task-3 (Integration)
task-2 (Backend) ─┘
```
**Feature Gates**:
```
task-1 (Auth) ─┬→ task-2 (User Profile)
├→ task-3 (Settings)
└→ task-4 (Dashboard)
```
## Execution Sequences
View recommended execution order:
```bash
# Via MCP, use project analytics tools to see execution plans
# The board view also shows dependency-aware ordering
backlog board
```
## Best Practices
1. Only add necessary dependencies - don't over-constrain
2. Keep dependency chains short (max 3-4 levels deep)
3. Review dependencies when tasks are blocked too long
4. Use dependencies for true blockers, not just suggested order

73
commands/epic.md Normal file
View File

@@ -0,0 +1,73 @@
---
description: Organize tasks into epics using parent-child hierarchies. Use when planning large features that span multiple tasks.
---
# Epic Management
Organize related tasks into epics (parent tasks with subtasks) for better project structure and progress tracking.
## Understanding Epics in Backlog.md
Epics are implemented as parent tasks with child subtasks:
- A parent task acts as the epic container
- Child tasks are created with `-p <parent-id>`
- Progress is tracked by subtask completion
- Dependencies can span within and across epics
## Instructions
### Creating a New Epic
1. **Create the parent task** (the epic itself):
```bash
backlog task create "User Authentication System" \
--desc "Complete authentication implementation including OAuth, session management, and security" \
--labels epic,auth
```
2. **Break down into subtasks**:
```bash
backlog task create -p <epic-id> "Design auth database schema"
backlog task create -p <epic-id> "Implement session management"
backlog task create -p <epic-id> "Add OAuth2 providers"
backlog task create -p <epic-id> "Create login/logout UI"
backlog task create -p <epic-id> "Add security middleware"
```
3. **Set dependencies between subtasks**:
```bash
backlog task edit <subtask-id> --dep <blocking-task-id>
```
### Viewing Epic Progress
- **List all subtasks**: `backlog task list -p <epic-id>`
- **View epic details**: `backlog task <epic-id>`
- **Check board**: `backlog board` shows hierarchical view
### Epic Organization Patterns
**Pattern 1: Feature Epic**
```
Epic: User Dashboard
├── task-10: Design dashboard layout
├── task-11: Create dashboard API endpoints
├── task-12: Build dashboard components
└── task-13: Add dashboard tests
```
**Pattern 2: Sprint/Milestone Epic**
```
Epic: Sprint 3 Goals
├── task-20: Fix login bug
├── task-21: Improve search performance
└── task-22: Add export feature
```
## Best Practices
1. Keep epics focused - one major feature or outcome
2. Limit subtasks to 5-10 per epic for manageability
3. Use labels consistently within an epic
4. Set realistic dependencies - don't over-constrain
5. Update epic description as scope evolves

87
commands/learnings.md Normal file
View File

@@ -0,0 +1,87 @@
---
description: Save learnings, notes, and implementation details to tasks throughout work cycles. Use to document discoveries, decisions, and progress.
---
# Task Learnings & Notes
Document learnings, implementation notes, and progress on tasks to maintain project knowledge.
## Instructions
### Adding Implementation Notes
Notes capture what you've learned, tried, or decided during work:
```bash
# Set notes (replaces existing)
backlog task edit <task-id> --notes "Discovered that the API requires OAuth2 tokens"
# Append to existing notes (preserves history)
backlog task edit <task-id> --append-notes "Found solution: use refresh token rotation"
```
### Multi-line Notes (Bash/Zsh)
Use ANSI-C quoting for multi-line content:
```bash
backlog task edit <task-id> --notes $'## Progress\n- Completed API research\n- Identified auth requirements\n\n## Blockers\n- Waiting on API credentials\n\n## Next Steps\n- Implement token refresh'
```
### Implementation Plans
Plans document the approach before starting work:
```bash
# Set implementation plan
backlog task edit <task-id> --plan $'1. Research OAuth2 flow\n2. Set up auth middleware\n3. Implement token storage\n4. Add refresh logic\n5. Write tests'
```
### When to Add Learnings
Add notes when you:
- Discover something unexpected
- Make a technical decision
- Encounter and solve a problem
- Find useful resources or documentation
- Complete a milestone within the task
- Need to hand off to another agent/developer
### Viewing Task Documentation
```bash
# View full task with notes and plan
backlog task <task-id>
# Plain text output (good for scripts/AI)
backlog task <task-id> --plain
```
## Knowledge Preservation Patterns
**Progress Tracking**:
```
## Session 1 (2025-01-15)
- Set up project structure
- Installed dependencies
## Session 2 (2025-01-16)
- Implemented core API
- Found issue with rate limiting
```
**Decision Log**:
```
## Decisions
- Using PostgreSQL over MongoDB (better for relational data)
- Chose JWT over sessions (stateless scaling)
- Selected React Query for data fetching
```
**Troubleshooting Log**:
```
## Issues Encountered
1. CORS errors - solved by adding middleware
2. Memory leak - caused by unclosed connections
3. Test failures - mock timing issues
```

74
commands/task-align.md Normal file
View File

@@ -0,0 +1,74 @@
---
description: Synchronize task status with actual work completed. Use after making changes to update the backlog with current progress, learnings, and acceptance criteria status.
---
# Align Tasks with Work
Synchronize the Backlog.md backlog with actual work completed in the codebase.
## Instructions
1. **Review recent changes**:
- Check git status/diff for modified files
- Identify what functionality was added/changed/fixed
2. **Find related tasks**:
- Search backlog for tasks related to the changes
- `backlog search "<keywords from changes>"`
3. **For each related task**:
a. **Update status** if needed:
- Started work? → "In Progress"
- Completed? → "Done"
b. **Check acceptance criteria**:
- Review each criterion
- Mark completed ones: `--check-ac <number>`
c. **Add learnings**:
- Document what was done
- Note any issues or decisions
- `--append-notes "Implemented X using Y"`
d. **Update dependencies** if changed:
- Add new dependencies discovered
- Remove resolved blockers
4. **Identify untracked work**:
- Any changes that don't match existing tasks?
- Offer to create new tasks for unplanned work
5. **Report summary**:
- List tasks updated
- Show current project status
## Example Workflow
```bash
# 1. See what changed
git diff --name-only HEAD~1
# 2. Search for related tasks
backlog search "authentication"
backlog search "login"
# 3. Update found tasks
backlog task edit 15 -s "In Progress" --check-ac 1 --check-ac 2 \
--append-notes "Implemented basic auth flow, tokens working"
# 4. View updated task
backlog task 15 --plain
# 5. Check overall status
backlog board
```
## Alignment Checklist
After any work session, verify:
- [ ] All changed areas have corresponding tasks
- [ ] Task statuses reflect reality
- [ ] Completed work has acceptance criteria checked
- [ ] Implementation notes capture key decisions
- [ ] Unplanned work is tracked or documented

67
commands/task-create.md Normal file
View File

@@ -0,0 +1,67 @@
---
description: Create a new task in Backlog.md with full metadata support. Use when you need to track work, bugs, features, or any actionable item.
---
# Create Task
Create a new task in the project backlog with comprehensive metadata.
## Instructions
1. **Gather task information**:
- Title (required): Clear, actionable description
- Description: Detailed explanation of what needs to be done
- Priority: high, medium, or low
- Labels: Comma-separated tags for categorization
- Assignee: Who should work on this (use @username format)
2. **Check for duplicates first**:
- Search existing tasks: `backlog search "<keywords>"`
- Review similar tasks to avoid duplication
3. **Create the task** using MCP tools or CLI:
- Via MCP: Use `backlog.task_create` tool
- Via CLI: `backlog task create "Title" --desc "Description" --priority high --labels feature,api`
4. **Add acceptance criteria** for clarity:
- Define what "done" looks like
- Use `--ac "Criterion 1" --ac "Criterion 2"` or add via MCP
5. **Set up dependencies** if this task depends on others:
- Use `--dep task-1,task-2` or add via MCP tools
- Dependencies prevent work on tasks until blockers are complete
6. **Organize into epics** if part of a larger feature:
- Create as a subtask: `backlog task create -p <parent-id> "Subtask title"`
- This creates a parent-child hierarchy for epic organization
## Task Creation Checklist
Before creating:
- [ ] Searched for duplicates
- [ ] Title is clear and actionable
- [ ] Description explains the "why" not just the "what"
- [ ] Appropriate priority set
- [ ] Labels applied for categorization
- [ ] Dependencies identified
- [ ] Acceptance criteria defined
## Example Commands
```bash
# Simple task
backlog task create "Add user authentication"
# Full task with all metadata
backlog task create "Implement OAuth2 login" \
--desc "Add Google and GitHub OAuth providers for user authentication" \
--priority high \
--labels auth,security,feature \
--ac "Google OAuth works" \
--ac "GitHub OAuth works" \
--ac "Token refresh implemented" \
--dep task-5,task-8
# Subtask under an epic
backlog task create -p 10 "Add Google OAuth provider"
```

186
commands/work.md Normal file
View File

@@ -0,0 +1,186 @@
---
description: Start working on a specific task by ID. Automatically sets status, guides implementation, and offers seamless transition to next task upon completion.
---
# Work on Task
Start focused work on a specified task, manage its lifecycle, and transition smoothly to the next task.
## Arguments
- `$ARGUMENTS` - Task identifier (e.g., "task-4", "4", "42")
## Instructions
### Phase 1: Task Initialization
1. **Parse the task identifier** from `$ARGUMENTS`:
- Accept formats: `task-4`, `4`, `task-42`, `42`
- Normalize to task ID (extract number if prefixed)
2. **Load the task**:
```bash
backlog task <id>
```
3. **Verify task is workable**:
- Check status is "To Do" or already "In Progress"
- Check all dependencies are "Done"
- If blocked, report blockers and suggest working on them first
4. **Set task to "In Progress"** (if not already):
```bash
backlog task edit <id> --status "In Progress"
```
5. **Present task context to user**:
- Display title, description, acceptance criteria
- Show implementation plan if exists
- List any prior implementation notes
- Highlight what "done" looks like
### Phase 2: Implementation Work
1. **Begin implementation** based on:
- Task description and acceptance criteria
- Implementation plan (if provided)
- Project context and codebase patterns
2. **During work, track progress**:
- Check off acceptance criteria as completed:
```bash
backlog task edit <id> --check-ac <criterion-number>
```
- Append implementation notes for future reference:
```bash
backlog task edit <id> --append-notes $'What was done:\n- Item 1\n- Item 2'
```
3. **If discovering new work**:
- Create subtasks for scope creep
- Update dependencies as needed
- Keep original task focused
### Phase 3: Task Completion
When all acceptance criteria are met:
1. **Verify completion**:
- Review all acceptance criteria are checked
- Confirm implementation matches requirements
- Run relevant tests if applicable
2. **Mark task as Done**:
```bash
backlog task edit <id> --status "Done"
```
3. **Add completion notes**:
```bash
backlog task edit <id> --append-notes $'Completed: <summary of what was done>'
```
### Phase 4: Transition
After completing the task, perform the following:
1. **Offer context compaction**:
Ask the user:
> "Task <id> is complete. Would you like me to compact the conversation context before continuing to the next task? This helps maintain performance for longer sessions."
If yes: Use `/compact` to summarize and compress the conversation context.
2. **Identify the next task**:
```bash
backlog task list --status "To Do" --sort priority
```
Select the next task based on:
- Highest priority first
- Dependencies satisfied (blockers completed)
- Related to just-completed work (if applicable)
3. **Present next task recommendation**:
> "The next recommended task is **task-<next-id>: <title>** (priority: <priority>)."
>
> **Description**: <brief description>
>
> **Why this task**: <rationale - highest priority / unblocked / related work>
>
> Would you like me to start working on this task now?
4. **If user accepts**:
- Recursively invoke this workflow for the next task
- Seamlessly continue the work session
5. **If user declines**:
- Show the board overview: `backlog board`
- Offer alternative tasks if requested
## Error Handling
- **Task not found**: Search for similar tasks and suggest alternatives
- **Task already Done**: Inform user, offer to reopen or suggest next task
- **Dependencies not met**: List blocking tasks, offer to work on blockers instead
- **Invalid ID format**: Show accepted formats and ask for correction
## Example Session
```
User: /work 4
Claude: Loading task-4...
**Task 4: Implement user authentication**
Status: To Do → In Progress
Priority: High
Labels: auth, security
**Description:**
Add JWT-based authentication to the API endpoints.
**Acceptance Criteria:**
- [ ] Login endpoint returns JWT token
- [ ] Protected routes require valid token
- [ ] Token refresh mechanism works
- [ ] Logout invalidates token
**Implementation Plan:**
1. Add JWT library dependency
2. Create auth middleware
3. Implement login/logout endpoints
4. Add token refresh logic
Starting implementation...
[... implementation work happens ...]
All acceptance criteria complete. Marking task-4 as Done.
---
Task 4 is complete! Would you like me to compact the conversation
context before continuing to the next task?
[User: Yes]
Context compacted.
The next recommended task is **task-7: Add rate limiting** (priority: high).
**Description:** Implement rate limiting on API endpoints to prevent abuse.
**Why this task:** Highest priority unblocked task, security-related
(follows naturally from auth work).
Would you like me to start working on this task now?
```
## Notes
- Always verify acceptance criteria before marking Done
- Keep implementation notes concise but informative for future reference
- Context compaction is optional but recommended for long sessions
- Next task selection prioritizes unblocked, high-priority work

24
hooks/hooks.json Normal file
View File

@@ -0,0 +1,24 @@
{
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "echo '⚡ Files modified - consider updating related Backlog.md tasks'"
}
]
}
],
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "if [ -d 'backlog' ]; then echo '\\n📋 Backlog reminder: Use /task-align to sync task status with your changes'; fi"
}
]
}
]
}

93
plugin.lock.json Normal file
View File

@@ -0,0 +1,93 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:yebot/rad-cc-plugins:plugins/backlog-md",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "e3a08f06d2c1babd2f38f0da863935502fac6550",
"treeHash": "b7d49231e0605a648f01d75d04f7461a65c1e50b678572527dd9bb5647211c71",
"generatedAt": "2025-11-28T10:29:12.338862Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "backlog-md",
"description": "Comprehensive Backlog.md integration - markdown-native task management with MCP support, specialized subagents for task alignment and planning, and workflow automation hooks",
"version": "1.1.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "be17ef806fea82cdc85d1632e2e617751804ab46f099ed1a3a87fca669e0fa86"
},
{
"path": "agents/unplanned-handler.md",
"sha256": "dbba918222cf249e4da2365edf86ceedd7c2a4516768d6edd455dcebcf12ad65"
},
{
"path": "agents/backlog-scout.md",
"sha256": "0bdc4f41e7dcbd45dc2a5b9a72ab0fc43b675208842a4fec8b9984b2e3c1b4c1"
},
{
"path": "agents/task-aligner.md",
"sha256": "8ff8ce2d86f0e962660036c94b181d92bde797255dca9bc0bfb5a7dbf98205e7"
},
{
"path": "hooks/hooks.json",
"sha256": "1587bde62b690786e74ef3cbfab0e7a0b59ceb7fc45a9ad7f5cd2e1fbd13c4c9"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "25e443159cc6d3d41ba64dfcc5086f9c98c7eec9c26b62dda6b6b64ceece0311"
},
{
"path": "commands/work.md",
"sha256": "7c4a47bfa03278e57338699ec6e6ef811928b1853ec4bce9dadf919235df23d1"
},
{
"path": "commands/task-align.md",
"sha256": "54b4d51ed77b57a6e0cfb0af27987efba838052efc48e1960bf4949cfb2e772a"
},
{
"path": "commands/backlog-init.md",
"sha256": "06b8b2bbc53e2c460a5738e59d6d45170aaae46c02b3801c52d605bc87ce8712"
},
{
"path": "commands/epic.md",
"sha256": "cff6fe3eea543c3ee7cf5678026fd789a6c7e88273c982a5c0b5e3e83f01c4e3"
},
{
"path": "commands/board.md",
"sha256": "b4a737e20331ceddad5e73fa4e485a6c840a7dbdd786fe7685a0fd0ebab9c22c"
},
{
"path": "commands/deps.md",
"sha256": "9ff276b08a94bcc30543b791cf364a8966bd479cf7b3bb39479a844833925585"
},
{
"path": "commands/task-create.md",
"sha256": "089a019d0a3600ea8a03977efe76bc61a1b9d2865222569ae54ae96073dbbc9e"
},
{
"path": "commands/learnings.md",
"sha256": "b02541dfb28076ea86b29b1524f00601796aac123a40869c3b089db98fc6dae2"
},
{
"path": "skills/backlog-workflow/SKILL.md",
"sha256": "4002e77a4e65d80c0f2d13a3435780ebd27ecf1ef139e453141e07cbe7d78710"
}
],
"dirSha256": "b7d49231e0605a648f01d75d04f7461a65c1e50b678572527dd9bb5647211c71"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

117
skills/backlog-workflow/SKILL.md Normal file
View File

@@ -0,0 +1,117 @@
---
name: backlog-workflow
description: Expert knowledge for working with Backlog.md task management. Use when managing tasks, organizing epics, handling dependencies, or tracking project progress. Automatically applies Backlog.md best practices.
allowed-tools: Read, Bash, Grep, Glob
---
# Backlog.md Workflow Skill
Expert guidance for managing projects with Backlog.md - a markdown-native task manager with MCP support.
## Core Concepts
### Tasks
- Stored as markdown files in `backlog/tasks/`
- Named pattern: `task-<id> - <title>.md`
- Support: status, priority, labels, assignees, acceptance criteria, notes, plans, dependencies
### Epics (Parent-Child)
- Parent tasks group related work
- Create subtasks with `-p <parent-id>`
- Track epic progress via subtask completion
### Dependencies
- Tasks can depend on other tasks
- Prevents starting blocked work
- Creates execution sequences
- Validated for circular references
### Statuses
- "To Do": Not started
- "In Progress": Currently being worked on
- "Done": Completed
## Command Reference
### Task Operations
```bash
backlog task create "Title" [options]
backlog task edit <id> [options]
backlog task <id> # View task
backlog task list [filters] # List tasks
backlog task archive <id> # Archive completed task
```
### Common Options
```bash
--desc, -d Description
--status, -s Task status
--priority high/medium/low
--labels, -l Comma-separated labels
--assignee, -a @username
--ac Acceptance criteria (repeatable)
--dep Dependencies (task-1,task-2)
--plan Implementation plan
--notes Implementation notes
--append-notes Add to existing notes
-p Parent task ID (for subtasks)
```
### Board & Search
```bash
backlog board # Interactive Kanban board
backlog board export # Export to markdown
backlog search "query" # Fuzzy search tasks
backlog overview # Project statistics
```
### Acceptance Criteria
```bash
--ac "Criterion" # Add criterion
--check-ac 1 # Mark #1 complete
--uncheck-ac 2 # Mark #2 incomplete
--remove-ac 3 # Remove criterion
```
## Workflow Patterns
### Starting New Work
1. Search for existing tasks: `backlog search "<keywords>"`
2. If exists, update status to "In Progress"
3. If new, create task with full context
4. Set dependencies if applicable
### During Work
1. Add implementation notes as you learn
2. Check acceptance criteria as completed
3. Update status appropriately
4. Create subtasks for discovered work
### Completing Work
1. Verify all acceptance criteria are checked
2. Add final implementation notes
3. Move to "Done" status
4. Archive if no longer needed
### Epic Planning
1. Create parent task with epic overview
2. Break into 5-10 focused subtasks
3. Establish dependencies between subtasks
4. Track progress via subtask completion
## Multi-line Input (Bash/Zsh)
Use ANSI-C quoting for newlines:
```bash
backlog task edit <id> --notes $'Line 1\nLine 2\n\nParagraph 2'
```
## MCP Integration
When MCP is available, use backlog tools directly:
- `backlog.task_create` - Create tasks
- `backlog.task_update` - Update tasks
- `backlog.task_list` - List tasks
- `backlog.acceptance_criteria_check` - Check criteria
- `backlog.implementation_notes_append` - Add notes
- `backlog.dependencies_add` - Add dependencies