Initial commit

2025-11-30 09:07:45 +08:00
commit b02323e3ac
16 changed files with 1203 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -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"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -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
--- a/agents/backlog-scout.md
+++ b/agents/backlog-scout.md
@@ -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)
+```
--- a/agents/task-aligner.md
+++ b/agents/task-aligner.md
@@ -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
--- a/agents/unplanned-handler.md
+++ b/agents/unplanned-handler.md
@@ -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
--- a/commands/backlog-init.md
+++ b/commands/backlog-init.md
@@ -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
--- a/commands/board.md
+++ b/commands/board.md
@@ -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) |
--- a/commands/deps.md
+++ b/commands/deps.md
@@ -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
--- a/commands/epic.md
+++ b/commands/epic.md
@@ -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
--- a/commands/learnings.md
+++ b/commands/learnings.md
@@ -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
+```
--- a/commands/task-align.md
+++ b/commands/task-align.md
@@ -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
--- a/commands/task-create.md
+++ b/commands/task-create.md
@@ -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"
+```
--- a/commands/work.md
+++ b/commands/work.md
@@ -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
--- a/hooks/hooks.json
+++ b/hooks/hooks.json
@@ -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"
+        }
+      ]
+    }
+  ]
+}
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -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": []
+  }
+}
--- a/skills/backlog-workflow/SKILL.md
+++ b/skills/backlog-workflow/SKILL.md
@@ -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